PDL::Basic

Basic(3pm)            User Contributed Perl Documentation           Basic(3pm)



NAME
       PDL::Basic -- Basic utility functions for PDL

DESCRIPTION
       This module contains basic utility functions for creating and manipu-
       lating 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

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

       etc. see zeroes.

         perldl> 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

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

       etc. see zeroes.

        perldl> 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

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

       etc. see zeroes.

        perldl> 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 logarithmicly 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 logarithmicly scaled values between
       the two other arguments along the given axis.

       ylogvals

       Y axis values logarithmicly spaced between endpoints (see yvals).

       See xlogvals for more information.

       zlogvals

       Z axis values logarithmicly spaced between endpoints (see zvals).

       See xlogvals for more information.

       ndcoords

       Enumerate pixel coordinates for an N-D piddle

       $indices = ndcoords($pdl) $indices = ndcoords(@dimlist)

       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 dimen-
       sions 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.

         perldl> print ndcoords(2,3)
         [
          [
           [0 0]
           [1 0]
           [2 0]
          ]
          [
           [0 1]
           [1 1]
           [2 1]
          ]
         ]

       hist

       Create histogram of a piddle

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

       If requested, $xvals gives the computed bin centres

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

        bin hist $data;  # Plot histogram

        perldl> 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]
        perldl> $h = hist $y,0,20,1; # hist with step 1, min 0 and 20 bins
        perldl> 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.  $data and $wt
       should have the same dimensionality and extents.

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

        bin whist $data, $wt;  # Plot histogram

        perldl> 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]
        perldl> $wt = grandom($y->nelem)
        perldl> $h = whist $y, $wt, 0, 20, 1 # hist with step 1, min 0 and 20 bins
        perldl> 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.

        perldl> p sequence(10)
        [0 1 2 3 4 5 6 7 8 9]
        perldl> 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)

        perldl> 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]
        ]

       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.

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

       allaxisvals

       Generates a piddle with index values

        $z = allaxisvals ($piddle);

       "allaxisvals" produces an array with axis values along each dimension,
       adding an extra dimension at the start.

       "allaxisvals($piddle)->slice("($nth)")" will produce the same result as
       "axisvals($piddle,$nth)" (although with extra work and not inplace).

       It's useful when all the values will be required, as in the example
       given of a generalized rvals.

       transpose

       transpose rows and columns.

        $b = transpose($a); $b = ~$a;

       Also bound to the "~" unary operator in PDL::Matrix.

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



perl v5.8.8                       2002-05-21                        Basic(3pm)