PDL::Basic -- Basic utility functions for PDL

- NAME
- DESCRIPTION
- SYNOPSIS
- FUNCTIONS

- xvals
- yvals
- zvals
- xlinvals
- ylinvals
- zlinvals
- hist
- whist
- sequence
- rvals
- axisvals
- allaxisvals
- transpose

# 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

     $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.

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