NAME

       PDL::CCS::Utils - Low-level utilities for compressed storage sparse PDLs

SYNOPSIS

        use PDL;
        use PDL::CCS::Utils;

        ##---------------------------------------------------------------------
        ## ... stuff happens

FUNCTIONS

Non-missing Value Counts

   nnz
         Signature: (a(N); int+ [o]nnz())

       Get number of non-zero values in a PDL $a(); For 1d PDLs, should be equivalent to:

        $nnz = nelem(which($a!=0));

       For k>1 dimensional PDLs, projects via number of nonzero elements to N-1 dimensions by
       computing the number of nonzero elements along the the 1st dimension.

       nnz does not process bad values.  It will set the bad-value flag of all output ndarrays if
       the flag is set for any of the input ndarrays.

   nnza
         Signature: (a(N); eps(); int+ [o]nnz())

       Like nnz() using tolerance constant $eps().  For 1d PDLs, should be equivalent to:

        $nnz = nelem(which(!$a->approx(0,$eps)));

       nnza does not process bad values.  It will set the bad-value flag of all output ndarrays
       if the flag is set for any of the input ndarrays.

Encoding Utilities

   ccs_encode_pointers
         Signature: (indx ix(Nnz); indx N(); indx [o]ptr(Nplus1); indx [o]ixix(Nnz))

       General CCS encoding utility.

       Get a compressed storage "pointer" vector $ptr for a dimension of size $N with non-missing
       values at indices $ix.  Also returns a vector $ixix() which may be used as an index for
       $ix() to align its elements with $ptr() along the compressed dimension.

       The induced vector $ix->index($ixix) is guaranteed to be stably sorted along dimension
       $N():

        \forall $i,$j with 1 <= $i < $j <= $Nnz :

         $ix->index($ixix)->at($i) < $ix->index($ixix)->at($j)   ##-- primary sort on $ix()
        or
         $ixix->at($i)             < $ixix->at($j)               ##-- ... stable

       ccs_encode_pointers does not process bad values.  It will set the bad-value flag of all
       output ndarrays if the flag is set for any of the input ndarrays.

Decoding Utilities

   ccs_decode_pointer
         Signature: (indx ptr(Nplus1); indx proj(Nproj); indx [o]projix(NnzProj); indx [o]nzix(NnzProj))

       General CCS decoding utility.

       Project indices $proj() from a compressed storage "pointer" vector $proj().  If
       unspecified, $proj() defaults to:

        sequence($ptr->dim(0))

       ccs_decode_pointer does not process bad values.  It will set the bad-value flag of all
       output ndarrays if the flag is set for any of the input ndarrays.

   ccs_pointerlen
         Signature: (ptr(Nplus1); [o]ptrlen(N))

       Get number of non-missing values for each axis value from a CCS-encoded offset pointer
       vector $ptr().

       ccs_pointerlen does not process bad values.  It will set the bad-value flag of all output
       ndarrays if the flag is set for any of the input ndarrays.

Indexing Utilities

   ccs_xindex1d
         Signature: (which(Ndims,Nnz); a(Na); [o]nzia(NnzA); [o]nnza())

       Compute indices $nzai() along dimension "NNz" of $which() whose initial values
       $which(0,$nzai) match some element of $a().  Appropriate for indexing a sparse encoded PDL
       with non-missing entries at $which() along the 0th dimension, a la dice_axis(0,$a).
       $which((0),) and $a() must be both sorted in ascending order.

       In list context, returns a list ($nzai,$nnza), where $nnza() is the number of indices
       found, and $nzai are those "Nnz" indices.  In scalar context, trims the output vector
       $nzai() to $nnza() elements.

       ccs_xindex1d does not process bad values.  It will set the bad-value flag of all output
       ndarrays if the flag is set for any of the input ndarrays.

   ccs_xindex2d
         Signature: (which(Ndims,Nnz); a(Na); b(Nb); [o]ab(Nab); [o]nab())

       Compute indices along dimension "NNz" of $which() corresponding to any combination of
       values in the Cartesian product of $a() and $b().  Appropriate for indexing a 2d sparse
       encoded PDL with non-missing entries at $which() via the ND-index piddle
       $a->slice("*1,")->cat($b)->clump(2)->xchg(0,1), i.e. all pairs $ai,$bi with $ai in $a()
       and $bi in $b().  $a() and $b() values must be be sorted in ascending order

       In list context, returns a list ($ab,$nab), where $nab() is the number of indices found,
       and $ab are those "Nnz" indices.  In scalar context, trims the output vector $ab() to
       $nab() elements.

       ccs_xindex2d does not process bad values.  It will set the bad-value flag of all output
       ndarrays if the flag is set for any of the input ndarrays.

Debugging Utilities

   ccs_dump_which
         Signature: (indx which(Ndims,Nnz); SV *HANDLE; char *fmt; char *fsep; char *rsep)

       Print a text dump of an index PDL to the filehandle "HANDLE", which default to "STDUT".
       $fmt is a printf() format to use for output, which defaults to "%d".  $fsep and $rsep are
       field-and record separators, which default to a single space and $/, respectively.

       ccs_dump_which does not process bad values.  It will set the bad-value flag of all output
       ndarrays if the flag is set for any of the input ndarrays.

ACKNOWLEDGEMENTS

       Perl by Larry Wall.

       PDL by Karl Glazebrook, Tuomas J. Lukka, Christian Soeller, and others.

KNOWN BUGS

       Probably many.

AUTHOR

       Bryan Jurish <moocow@cpan.org>

   Copyright Policy
       Copyright (C) 2007-2022, Bryan Jurish. All rights reserved.

       This package is free software, and entirely without warranty.  You may redistribute it
       and/or modify it under the same terms as Perl itself.

SEE ALSO

       perl(1), PDL(3perl)