Provided by: pdl_2.085-1ubuntu1_amd64 
NAME
PDL::Basic -- Basic utility functions for PDL
DESCRIPTION
This module contains basic utility functions for creating and manipulating ndarrays. 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 an ndarray with X index values. Uses similar specifications to "zeroes" and
"new_from_specification".
CAVEAT:
If you use the single argument ndarray form (top row in the usage table) the output will
have the same type as the input, except that as of 2.064, the returned ndarray will
default to at least type "double". As of 2.085, this will respect a given type as in the
second or third form below.
$x = xvals($somearray); # at least type double
$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 an ndarray 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 an ndarray 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").
$w = zeroes(100,100);
$x = $w->xlinvals(0.5,1.5);
$y = $w->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 an ndarray 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").
$w = zeroes(100,100);
$x = $w->xlogvals(1e-6,1e-3);
$y = $w->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 an ndarray 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 ndarray
Returns an enumerated list of coordinates suitable for use in indexND or range: you feed
in a dimension list and get out an ndarray whose 0th dimension runs over dimension index
and whose 1st through Nth dimensions are the dimensions given in the input. If you feed
in an ndarray instead of a perl list, then the dimension list is used, as in "xvals" etc.
Unlike "xvals" etc., if you supply an ndarray input, you get out an ndarray of the default
ndarray type: double. This causes less surprises than the previous default of keeping
the data type of the input ndarray 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> $w = zeroes(byte,2,3); # $w is a 2x3 byte ndarray
pdl> $y = ndcoords($w); # $y inherits $w's type
pdl> $c = ndcoords(long,$w->dims); # $c is a long ndarray, same dims as $y
pdl> help $y;
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 an ndarray
$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 an ndarray
$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
$w = sequence($y); $w = 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 an ndarray with radial distance values from some centre.
$r = rvals $ndarray,{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 ($w,$centre,$f) = @_;
my ($r) = $w->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($w, $centre, \&euclid);
will emulate rvals, while "\&l1" and "\&linfty" will generate other well-known norms.
axisvals
Fills an ndarray with index values on Nth dimension
$z = axisvals ($ndarray, $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.
$y = transpose($w);
pdl> $w = sequence(3,2)
pdl> p $w
[
[0 1 2]
[3 4 5]
]
pdl> p transpose( $w )
[
[0 3]
[1 4]
[2 5]
]