Provided by: pdl_2.018-1ubuntu4_amd64 bug

NAME

       PDL::Basic -- Basic utility functions for PDL

DESCRIPTION

       This module contains basic utility functions for creating and manipulating piddles. Most
       of these functions are simplified interfaces to the more flexible functions in the modules
       PDL::Primitive and PDL::Slices.

SYNOPSIS

        use PDL::Basic;

FUNCTIONS

   xvals
       Fills a piddle with X index values.  Uses similar specifications to zeroes and
       new_from_specification.

       CAVEAT:

       If you use the single argument piddle form (top row in the usage table) the output will
       have the same type as the input; this may give surprising results if, e.g., you have a
       byte array with a dimension of size greater than 256.  To force a type, use the third
       form.

        $x = xvals($somearray);
        $x = xvals([OPTIONAL TYPE],$nx,$ny,$nz...);
        $x = xvals([OPTIONAL TYPE], $somarray->dims);

       etc. see zeroes.

         pdl> print xvals zeroes(5,10)
         [
          [0 1 2 3 4]
          [0 1 2 3 4]
          [0 1 2 3 4]
          [0 1 2 3 4]
          [0 1 2 3 4]
          [0 1 2 3 4]
          [0 1 2 3 4]
          [0 1 2 3 4]
          [0 1 2 3 4]
          [0 1 2 3 4]
         ]

   yvals
       Fills a piddle with Y index values.  See the CAVEAT for xvals.

        $x = yvals($somearray); yvals(inplace($somearray));
        $x = yvals([OPTIONAL TYPE],$nx,$ny,$nz...);

       etc. see zeroes.

        pdl> print yvals zeroes(5,10)
        [
         [0 0 0 0 0]
         [1 1 1 1 1]
         [2 2 2 2 2]
         [3 3 3 3 3]
         [4 4 4 4 4]
         [5 5 5 5 5]
         [6 6 6 6 6]
         [7 7 7 7 7]
         [8 8 8 8 8]
         [9 9 9 9 9]
        ]

   zvals
       Fills a piddle with Z index values.  See the CAVEAT for xvals.

        $x = zvals($somearray); zvals(inplace($somearray));
        $x = zvals([OPTIONAL TYPE],$nx,$ny,$nz...);

       etc. see zeroes.

        pdl> print zvals zeroes(3,4,2)
        [
         [
          [0 0 0]
          [0 0 0]
          [0 0 0]
          [0 0 0]
         ]
         [
          [1 1 1]
          [1 1 1]
          [1 1 1]
          [1 1 1]
         ]
        ]

   xlinvals
       X axis values between endpoints (see xvals).

        $a = zeroes(100,100);
        $x = $a->xlinvals(0.5,1.5);
        $y = $a->ylinvals(-2,-1);
        # calculate Z for X between 0.5 and 1.5 and
        # Y between -2 and -1.
        $z = f($x,$y);

       "xlinvals", "ylinvals" and "zlinvals" return a piddle with the same shape as their first
       argument and linearly scaled values between the two other arguments along the given axis.

   ylinvals
       Y axis values between endpoints (see yvals).

       See xlinvals for more information.

   zlinvals
       Z axis values between endpoints (see zvals).

       See xlinvals for more information.

   xlogvals
       X axis values logarithmically spaced between endpoints (see xvals).

        $a = zeroes(100,100);
        $x = $a->xlogvals(1e-6,1e-3);
        $y = $a->ylinvals(1e-4,1e3);
        # calculate Z for X between 1e-6 and 1e-3 and
        # Y between 1e-4 and 1e3.
        $z = f($x,$y);

       "xlogvals", "ylogvals" and "zlogvals" return a piddle with the same shape as their first
       argument and logarithmically scaled values between the two other arguments along the given
       axis.

   ylogvals
       Y axis values logarithmically spaced between endpoints (see yvals).

       See xlogvals for more information.

   zlogvals
       Z axis values logarithmically spaced between endpoints (see zvals).

       See xlogvals for more information.

   allaxisvals
       Synonym for ndcoords - enumerates all coordinates in a PDL or dim list, adding an extra
       dim on the front to accommodate the vector coordinate index (the form expected by indexND,
       range, and interpND).  See ndcoords for more detail.

       $indices = allaxisvals($pdl); $indices = allaxisvals(@dimlist); $indices =
       allaxisvals($type,@dimlist);

   ndcoords
       Enumerate pixel coordinates for an N-D piddle

       Returns an enumerated list of coordinates suitable for use in indexND or range: you feed
       in a dimension list and get out a piddle whose 0th dimension runs over dimension index and
       whose 1st through Nth dimensions are the dimensions given in the input.  If you feed in a
       piddle instead of a perl list, then the dimension list is used, as in xvals etc.

       Unlike xvals etc., if you supply a piddle input, you get out a piddle of the default
       piddle type: double.   This causes less surprises than the previous default of keeping the
       data type of the input piddle since that rarely made sense in most usages.

       $indices = ndcoords($pdl); $indices = ndcoords(@dimlist); $indices =
       ndcoords($type,@dimlist);

         pdl> print ndcoords(2,3)

         [
          [
           [0 0]
           [1 0]
          ]
          [
           [0 1]
           [1 1]
          ]
          [
           [0 2]
           [1 2]
          ]
         ]

         pdl> $a = zeroes(byte,2,3);        # $a is a 2x3 byte piddle
         pdl> $b = ndcoords($a);            # $b inherits $a's type
         pdl> $c = ndcoords(long,$a->dims); # $c is a long piddle, same dims as $b
         pdl> help $b;
         This variable is   Byte D [2,2,3]              P            0.01Kb
         pdl> help $c;
         This variable is   Long D [2,2,3]              P            0.05Kb

   hist
       Create histogram of a piddle

        $hist = hist($data);
        ($xvals,$hist) = hist($data);

       or

        $hist = hist($data,$min,$max,$step);
        ($xvals,$hist) = hist($data,[$min,$max,$step]);

       If "hist" is run in list context, $xvals gives the computed bin centres as double values.

       A nice idiom (with PDL::Graphics::PGPLOT) is

        bin hist $data;  # Plot histogram

        pdl> p $y
        [13 10 13 10 9 13 9 12 11 10 10 13 7 6 8 10 11 7 12 9 11 11 12 6 12 7]
        pdl> $h = hist $y,0,20,1; # hist with step 1, min 0 and 20 bins
        pdl> p $h
        [0 0 0 0 0 0 2 3 1 3 5 4 4 4 0 0 0 0 0 0]

   whist
       Create a weighted histogram of a piddle

        $hist = whist($data, $wt, [$min,$max,$step]);
        ($xvals,$hist) = whist($data, $wt, [$min,$max,$step]);

       If requested, $xvals gives the computed bin centres as type double values.  $data and $wt
       should have the same dimensionality and extents.

       A nice idiom (with PDL::Graphics::PGPLOT) is

        bin whist $data, $wt;  # Plot histogram

        pdl> p $y
        [13 10 13 10 9 13 9 12 11 10 10 13 7 6 8 10 11 7 12 9 11 11 12 6 12 7]
        pdl> $wt = grandom($y->nelem)
        pdl> $h = whist $y, $wt, 0, 20, 1 # hist with step 1, min 0 and 20 bins
        pdl> p $h
        [0 0 0 0 0 0 -0.49552342  1.7987439 0.39450696  4.0073722 -2.6255299 -2.5084501  2.6458365  4.1671676 0 0 0 0 0 0]

   sequence
       Create array filled with a sequence of values

        $a = sequence($b); $a = sequence [OPTIONAL TYPE], @dims;

       etc. see zeroes.

        pdl> p sequence(10)
        [0 1 2 3 4 5 6 7 8 9]
        pdl> p sequence(3,4)
        [
         [ 0  1  2]
         [ 3  4  5]
         [ 6  7  8]
         [ 9 10 11]
        ]

   rvals
       Fills a piddle with radial distance values from some centre.

        $r = rvals $piddle,{OPTIONS};
        $r = rvals [OPTIONAL TYPE],$nx,$ny,...{OPTIONS};

        Options:

        Centre => [$x,$y,$z...] # Specify centre
        Center => [$x,$y.$z...] # synonym.

        Squared => 1 # return distance squared (i.e., don't take the square root)

        pdl> print rvals long,7,7,{Centre=>[2,2]}
        [
         [2 2 2 2 2 3 4]
         [2 1 1 1 2 3 4]
         [2 1 0 1 2 3 4]
         [2 1 1 1 2 3 4]
         [2 2 2 2 2 3 4]
         [3 3 3 3 3 4 5]
         [4 4 4 4 4 5 5]
        ]

       If "Center" is not specified, the midpoint for a given dimension of size "N" is given by "
       int(N/2) " so that the midpoint always falls on an exact pixel point in the data.  For
       dimensions of even size, that means the midpoint is shifted by 1/2 pixel from the true
       center of that dimension.

       Also note that the calculation for "rvals" for integer values does not promote the
       datatype so you will have wraparound when the value calculated for " r**2 " is greater
       than the datatype can hold.  If you need exact values, be sure to use large integer or
       floating point datatypes.

       For a more general metric, one can define, e.g.,

        sub distance {
          my ($a,$centre,$f) = @_;
          my ($r) = $a->allaxisvals-$centre;
          $f->($r);
        }
        sub l1 { sumover(abs($_[0])); }
        sub euclid { use PDL::Math 'pow'; pow(sumover(pow($_[0],2)),0.5); }
        sub linfty { maximum(abs($_[0])); }

       so now

        distance($a, $centre, \&euclid);

       will emulate rvals, while "\&l1" and "\&linfty" will generate other well-known norms.

   axisvals
       Fills a piddle with index values on Nth dimension

        $z = axisvals ($piddle, $nth);

       This is the routine, for which xvals, yvals etc are mere shorthands. "axisvals" can be
       used to fill along any dimension, using a parameter.

       See also allaxisvals, which generates all axis values simultaneously in a form useful for
       range, interpND, indexND, etc.

       Note the 'from specification' style (see zeroes) is not available here, for obvious
       reasons.

   transpose
       transpose rows and columns.

        $b = transpose($a);

        pdl> $a = sequence(3,2)
        pdl> p $a
        [
         [0 1 2]
         [3 4 5]
        ]
        pdl> p transpose( $a )
        [
         [0 3]
         [1 4]
         [2 5]
        ]