*Manual Reference Pages - * PDL::BASIC (3)
.ds Aq ’
### NAME
PDL::Basic -- Basic utility functions for PDL
### CONTENTS
### 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 logarithmically 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 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 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 $as 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 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 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
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
`
` `
$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., dont 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 ($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.20.3* | BASIC (3) | *2015-10-03* |
Visit the GSP FreeBSD Man Page Interface. Output converted with manServer 1.07. |