/ 
PDL-2.004
River stage three • 100 direct dependents • 108 total dependents
/ PDL::Basic

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)
Dims:  5,10  DLen:  400

[
 [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)
Dims:  5,10  DLen:  400

[
 [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)
Dims:  3,4,2  DLen:  192

[
 [
  [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, ylinvals, zlinvals

X,Y or Z axis values between endpoints. (see xvals,yvals,zvals)

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

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.

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::PG) 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 10 10 10 13]
perldl> $h = hist $y,0,20,1
hist with step 1, min 0 and 21 bins

perldl> p $h
[0 0 0 0 0 0 2 3 1 3 8 4 4 5 0 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)
Dims:  10  DLen:  80
[0 1 2 3 4 5 6 7 8 9]
perldl> p sequence(3,4)
Dims:  12  DLen:  96

[
 [ 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.
perldl> print rvals long,7,7,{Centre=>[2,2]}
Dims:  7,7  DLen:  196

[
 [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'.