# 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").

```
$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 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").

```
$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 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 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 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> $w = zeroes(byte,2,3); # $w is a 2x3 byte piddle
pdl> $y = ndcoords($w); # $y inherits $w's type
pdl> $c = ndcoords(long,$w->dims); # $c is a long piddle, 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 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

` $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 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 ($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 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.

` $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]
]
```