The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
PDL-2.019
River stage three • 93 direct dependents • 101 total dependents
52 ++
/ Basic/Ufunc/ufunc.pd

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

avgover

  Synonym for average.

davgover

  Synonym for daverage.

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.

See the documentation for $func for more information.

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

This routine handles bad values.

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

maxover

  Synonym for maximum.

maxover_ind

  Synonym for maximum_ind.

maxover_n_ind

  Synonym for maximum_n_ind.

minover

  Synonym for minimum.

minover_ind

  Synonym for minimum_ind.

minover_n_ind

  Synonym for minimum_n_ind

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.

minmaxover

  Synonym for minmaximum.

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.