**See also:**How do I search for a function?

# hist

# 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. 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 $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 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., 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 ($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] ]