Basic(3) User Contributed Perl Documentation Basic(3)NAMEPDL::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 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.
allaxisvals
Synonym for ndcoords - enumerates all coordinates in a PDL or dim list,
adding an extra dim on the front to accomodate 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
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. $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]
]
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]
]
perl v5.14.1 2011-03-30 Basic(3)
