Chris Marshall > PDL-2.006 > PDL::Ufunc
Source   Latest Release: PDL-2.007_03

# NAME

PDL::Ufunc - primitive ufunc operations for pdl

# DESCRIPTION

This module provides some primitive and useful functions defined using PDL::PP based on functionality of what are sometimes called ufuncs (for example NumPY and Mathematica talk about these). It collects all the functions generally used to `reduce` or `accumulate` along a dimension. These all do their job across the first dimension but by using the slicing functions you can do it on any dimension.

The PDL::Reduce module provides an alternative interface to many of the functions in this module.

# SYNOPSIS

` use PDL::Ufunc;`

Project via \$name to N-1 dimensions

This function reduces the dimensionality of a piddle by one by taking the \$name along the 1st dimension.

By using xchg etc. it is possible to use any dimension.

` \\$b = \$op(\\$a);`
` \\$spectrum = \$op \\$image->xchg(0,1)`

\$extras

Cumulative \$name

This function calculates the cumulative \$name along the 1st dimension.

By using xchg etc. it is possible to use any dimension.

The sum is started so that the first element in the cumulative \$name is the first element of the parameter.

` \\$b = \$op(\\$a);`
` \\$spectrum = \$op \\$image->xchg(0,1)`

\$extras

Project via percentile to N-1 dimensions

This function reduces the dimensionality of a piddle by one by finding the specified percentile (p) along the 1st dimension. The specified percentile must be between 0.0 and 1.0. When the specified percentile falls between data points, the result is interpolated. Values outside the allowed range are clipped to 0.0 or 1.0 respectively. The algorithm implemented here is based on the interpolation variant described at http://en.wikipedia.org/wiki/Percentile as used by Microsoft Excel and recommended by NIST.

By using xchg etc. it is possible to use any dimension.

` \$b = pctover(\$a, \$p);`
` \$spectrum = pctover \$image->xchg(0,1), \$p`
` \$b = oddpctover(\$a, \$p);`
` \$spectrum = oddpctover \$image->xchg(0,1), \$p`

## pct

Return the specified percentile of all elements in a piddle. The specified percentile (p) must be between 0.0 and 1.0. When the specified percentile falls between data points, the result is interpolated.

` \\$x = pct(\\$data, \\$pct);`

## oddpct

Return the specified percentile of all elements in a piddle. The specified percentile must be between 0.0 and 1.0. When the specified percentile falls between two values, the nearest data value is the result.

` \\$x = oddpct(\\$data, \\$pct);`

## \$name

Return the \$text of all elements in a piddle

` \\$x = \$name(\\$data);`

This routine handles bad values (see the documentation for \$func). I still need to decide how to handle the case when the return value is a bad value (eg to make sure it has the same type as the input piddle OR perhaps we should die - makes sense for the conditional ops but not things like sum)

## any

Return true if any element in piddle set

Useful in conditional expressions:

` if (any \$a>15) { print "some values are greater than 15\n" }`

See or for comments on what happens when all elements in the check are bad.

## all

Return true if all elements in piddle set

Useful in conditional expressions:

` if (all \$a>15) { print "all values are greater than 15\n" }`

See and for comments on what happens when all elements in the check are bad.

## minmax

Returns an array with minimum and maximum values of a piddle.

` (\$mn, \$mx) = minmax(\$pdl);`

This routine does not thread over the dimensions of `\$pdl`; it returns the minimum and maximum values of the whole array. See minmaximum if this is not what is required. The two values are returned as Perl scalars similar to min/max.

``` pdl> \$x = pdl [1,-2,3,5,0]
pdl> (\$min, \$max) = minmax(\$x);
pdl> p "\$min \$max\n";
-2 5```

Quicksort a vector into ascending order.

` print qsort random(10);`

Quicksort a vector and return index of elements in ascending order.

``` \$ix = qsorti \$a;
print \$a->index(\$ix); # Sorted list```

Sort a list of vectors lexicographically.

The 0th dimension of the source piddle is dimension in the vector; the 1st dimension is list order. Higher dimensions are threaded over.

``` print qsortvec pdl([[1,2],[0,500],[2,3],[4,2],[3,4],[3,5]]);
[
[  0 500]
[  1   2]
[  2   3]
[  3   4]
[  3   5]
[  4   2]
]```

Sort a list of vectors lexicographically, returning the indices of the sorted vectors rather than the sorted list itself.

As with `qsortvec`, the input PDL should be an NxM array containing M separate N-dimensional vectors. The return value is an integer M-PDL containing the M-indices of original array rows, in sorted order.

As with `qsortvec`, the zeroth element of the vectors runs slowest in the sorted list.

Additional dimensions are threaded over: each plane is sorted separately, so qsortveci may be thought of as a collapse operator of sorts (groan).

Find minimum and maximum and their indices for a given piddle;

``` pdl> \$a=pdl [[-2,3,4],[1,0,3]]
pdl> (\$min, \$max, \$min_ind, \$max_ind)=minmaximum(\$a)
pdl> p \$min, \$max, \$min_ind, \$max_ind
[-2 0] [4 3] [0 1] [2 2]```

See also minmax, which clumps the piddle together.

# AUTHOR

Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu). Contributions by Christian Soeller (c.soeller@auckland.ac.nz) and Karl Glazebrook (kgb@aaoepp.aao.gov.au). All rights reserved. There is no warranty. You are allowed to redistribute this software / documentation under certain conditions. For details, see the file COPYING in the PDL distribution. If this file is separated from the PDL distribution, the copyright notice should be included in the file.

syntax highlighting: