# FreeBSD Manual Pages

```Ufunc(3)	      User Contributed Perl Documentation	      Ufunc(3)

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;

FUNCTIONS
prodover
Signature: (a(n); int+	[o]b())

Project via product to N-1 dimensions

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

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

\$b = prodover(\$a);

\$spectrum = prodover \$image->xchg(0,1)

prodover	processes bad values.  It will set the bad-value flag of all
output piddles if the flag is set for any of the	input piddles.

dprodover
Signature: (a(n); double [o]b())

Project via product to N-1 dimensions

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

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

\$b = dprodover(\$a);

\$spectrum = dprodover \$image->xchg(0,1)

Unlike prodover,	the calculations are performed in double precision.

dprodover processes bad values.	It will	set the	bad-value flag of all
output piddles if the flag is set for any of the	input piddles.

cumuprodover
Signature: (a(n); int+	[o]b(n))

Cumulative product

This function calculates	the cumulative product 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 product
is the first element of the parameter.

\$b = cumuprodover(\$a);

\$spectrum = cumuprodover \$image->xchg(0,1)

all output piddles if the flag is set for any of	the input piddles.

dcumuprodover
Signature: (a(n); double [o]b(n))

Cumulative product

This function calculates	the cumulative product 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 product
is the first element of the parameter.

\$b = cumuprodover(\$a);

\$spectrum = cumuprodover \$image->xchg(0,1)

Unlike cumuprodover, the	calculations are performed in double
precision.

all output piddles if the flag is set for any of	the input piddles.

sumover
Signature: (a(n); int+	[o]b())

Project via sum to N-1 dimensions

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

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

\$b = sumover(\$a);

\$spectrum = sumover \$image->xchg(0,1)

sumover processes bad values.  It will set the bad-value	flag of	all
output piddles if the flag is set for any of the	input piddles.

dsumover
Signature: (a(n); double [o]b())

Project via sum to N-1 dimensions

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

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

\$b = dsumover(\$a);

\$spectrum = dsumover \$image->xchg(0,1)

Unlike sumover, the calculations	are performed in double	precision.

dsumover	processes bad values.  It will set the bad-value flag of all
output piddles if the flag is set for any of the	input piddles.

cumusumover
Signature: (a(n); int+	[o]b(n))

Cumulative sum

This function calculates	the cumulative sum 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 sum is
the first element of the	parameter.

\$b = cumusumover(\$a);

\$spectrum = cumusumover	\$image->xchg(0,1)

all output piddles if the flag is set for any of	the input piddles.

dcumusumover
Signature: (a(n); double [o]b(n))

Cumulative sum

This function calculates	the cumulative sum 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 sum is
the first element of the	parameter.

\$b = cumusumover(\$a);

\$spectrum = cumusumover	\$image->xchg(0,1)

Unlike cumusumover, the calculations are	performed in double precision.

all output piddles if the flag is set for any of	the input piddles.

andover
Signature: (a(n); int+	[o]b())

Project via and to N-1 dimensions

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

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

\$b = andover(\$a);

\$spectrum = andover \$image->xchg(0,1)

If "a()"	contains only bad data (and its	bad flag is set), "b()"	is set
bad. Otherwise "b()" will have its bad flag cleared, as it will not

bandover
Signature: (a(n);  [o]b())

Project via bitwise and to N-1 dimensions

This function reduces the dimensionality	of a piddle by one by taking
the bitwise and along the 1st dimension.

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

\$b = bandover(\$a);

\$spectrum = bandover \$image->xchg(0,1)

If "a()"	contains only bad data (and its	bad flag is set), "b()"	is set
bad. Otherwise "b()" will have its bad flag cleared, as it will not

borover
Signature: (a(n);  [o]b())

Project via bitwise or to N-1 dimensions

This function reduces the dimensionality	of a piddle by one by taking
the bitwise or along the	1st dimension.

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

\$b = borover(\$a);

\$spectrum = borover \$image->xchg(0,1)

If "a()"	contains only bad data (and its	bad flag is set), "b()"	is set
bad. Otherwise "b()" will have its bad flag cleared, as it will not

orover
Signature: (a(n); int+	[o]b())

Project via or to N-1 dimensions

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

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

\$b = orover(\$a);

\$spectrum = orover \$image->xchg(0,1)

If "a()"	contains only bad data (and its	bad flag is set), "b()"	is set
bad. Otherwise "b()" will have its bad flag cleared, as it will not

zcover
Signature: (a(n); int+	[o]b())

Project via == 0	to N-1 dimensions

This function reduces the dimensionality	of a piddle by one by taking
the == 0	along the 1st dimension.

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

\$b = zcover(\$a);

\$spectrum = zcover \$image->xchg(0,1)

If "a()"	contains only bad data (and its	bad flag is set), "b()"	is set
bad. Otherwise "b()" will have its bad flag cleared, as it will not

intover
Signature: (a(n); float+ [o]b())

Project via integral to N-1 dimensions

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

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

\$b = intover(\$a);

\$spectrum = intover \$image->xchg(0,1)

Notes:

"intover" uses a	point spacing of one (i.e., delta-h==1).  You will
need to scale the result	to correct for the true	point delta).

For "n >	3", these are all "O(h^4)" (like Simpson's rule), but are
integrals between the end points	assuming the pdl gives values just at
these centres: for such `functions', sumover is correct to O(h),	but is
the natural (and	correct) choice	for binned data, of course.

intover ignores the bad-value flag of the input piddles.	 It will set
the bad-value flag of all output	piddles	if the flag is set for any of
the input piddles.

average
Signature: (a(n); int+	[o]b())

Project via average to N-1 dimensions

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

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

\$b = average(\$a);

\$spectrum = average \$image->xchg(0,1)

average processes bad values.  It will set the bad-value	flag of	all
output piddles if the flag is set for any of the	input piddles.

avgover
Synonym for average.

daverage
Signature: (a(n); double [o]b())

Project via average to N-1 dimensions

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

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

\$b = daverage(\$a);

\$spectrum = daverage \$image->xchg(0,1)

Unlike average, the calculation is performed in double precision.

daverage	processes bad values.  It will set the bad-value flag of all
output piddles if the flag is set for any of the	input piddles.

davgover
Synonym for daverage.

medover
Signature: (a(n); [o]b(); [t]tmp(n))

Project via median to N-1 dimensions

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

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

\$b = medover(\$a);

\$spectrum = medover \$image->xchg(0,1)

medover processes bad values.  It will set the bad-value	flag of	all
output piddles if the flag is set for any of the	input piddles.

oddmedover
Signature: (a(n); [o]b(); [t]tmp(n))

Project via oddmedian to	N-1 dimensions

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

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

\$b = oddmedover(\$a);

\$spectrum = oddmedover \$image->xchg(0,1)

The median is sometimes not a good choice as if the array has an	even
number of elements it lies half-way between the two middle values -
thus it does not	always correspond to a data value. The lower-odd
median is just the lower	of these two values and	so it ALWAYS sits on
an actual data value which is useful in some circumstances.

oddmedover processes bad	values.	 It will set the bad-value flag	of all
output piddles if the flag is set for any of the	input piddles.

modeover
Signature: (data(n); [o]out();	[t]sorted(n))

Project via mode	to N-1 dimensions

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

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

\$b = modeover(\$a);

\$spectrum = modeover \$image->xchg(0,1)

The mode	is the single element most frequently found in a discrete data
set.

It only makes sense for integer data types, since floating-point	types
are demoted to integer before the mode is calculated.

"modeover" treats BAD the same as any other value:  if BAD is the most
common element, the returned value is also BAD.

modeover	does not process bad values.  It will set the bad-value	flag
of all output piddles if	the flag is set	for any	of the input piddles.

pctover
Signature: (a(n); p();	[o]b();	[t]tmp(n))

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

pctover processes bad values.  It will set the bad-value	flag of	all
output piddles if the flag is set for any of the	input piddles.

oddpctover
Signature: (a(n); p();	[o]b();	[t]tmp(n))

Project via percentile to N-1 dimensions

This function reduces the dimensionality	of a piddle by one by finding
the specified percentile	along the 1st dimension.  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.	The
algorithm implemented is	from the textbook version described first at
<http://en.wikipedia.org/wiki/Percentile>.

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

\$b = oddpctover(\$a, \$p);

\$spectrum = oddpctover \$image->xchg(0,1), \$p

oddpctover processes bad	values.	 It will set the bad-value flag	of all
output piddles if the flag is set for any of the	input piddles.

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

avg
Return the average of all elements in a piddle.

\$x = avg(\$data);

sum
Return the sum of all elements in a piddle.

\$x = sum(\$data);

prod
Return the product of all elements in a piddle.

\$x = prod(\$data);

davg
Return the average (in double precision)	of all elements	in a piddle.

\$x = davg(\$data);

dsum
Return the sum (in double precision) of all elements in a piddle.

\$x = dsum(\$data);

dprod
Return the product (in double precision)	of all elements	in a piddle.

\$x = dprod(\$data);

zcheck
Return the check	for zero of all	elements in a piddle.

\$x = zcheck(\$data);

and
Return the logical and of all elements in a piddle.

\$x = and(\$data);

band
Return the bitwise and of all elements in a piddle.

\$x = band(\$data);

or
Return the logical or of	all elements in	a piddle.

\$x = or(\$data);

bor
Return the bitwise or of	all elements in	a piddle.

\$x = bor(\$data);

min
Return the minimum of all elements in a piddle.

\$x = min(\$data);

max
Return the maximum of all elements in a piddle.

\$x = max(\$data);

median
Return the median of all	elements in a piddle.

\$x = median(\$data);

mode
Return the mode of all elements in a piddle.

\$x = mode(\$data);

oddmedian
Return the oddmedian of all elements in a piddle.

\$x = oddmedian(\$data);

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

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

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

qsort
Signature: (a(n); [o]b(n))

Quicksort a vector into ascending order.

print qsort random(10);

Bad values are moved to the end of the array:

pdl> p \$b
pdl> p qsort(\$b)

qsorti
Signature: (a(n); indx	[o]indx(n))

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

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

Bad elements are	moved to the end of the	array:

pdl> p \$b
pdl> p \$b->index( qsorti(\$b) )

qsortvec
Signature: (a(n,m); [o]b(n,m))

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

Vectors with bad	components should be moved to the end of the array:

qsortveci
Signature: (a(n,m); indx [o]indx(m))

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.

separately, so qsortveci	may be thought of as a collapse	operator of
sorts (groan).

Vectors with bad	components should be moved to the end of the array:

minimum
Signature: (a(n); [o]c())

Project via minimum to N-1 dimensions

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

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

\$b = minimum(\$a);

\$spectrum = minimum \$image->xchg(0,1)

Output is set bad if all	elements of the	input are bad, otherwise the
bad flag	is cleared for the output piddle.

Note that "NaNs"	are considered to be valid values; see isfinite	and

minimum_ind
Signature: (a(n); indx	[o] c())

Like minimum but	returns	the index rather than the value

Output is set bad if all	elements of the	input are bad, otherwise the
bad flag	is cleared for the output piddle.

minimum_n_ind
Signature: (a(n); indx	[o]c(m))

Returns the index of "m"	minimum	elements

Not yet been converted to ignore	bad values

maximum
Signature: (a(n); [o]c())

Project via maximum to N-1 dimensions

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

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

\$b = maximum(\$a);

\$spectrum = maximum \$image->xchg(0,1)

Output is set bad if all	elements of the	input are bad, otherwise the
bad flag	is cleared for the output piddle.

Note that "NaNs"	are considered to be valid values; see isfinite	and

maximum_ind
Signature: (a(n); indx	[o] c())

Like maximum but	returns	the index rather than the value

Output is set bad if all	elements of the	input are bad, otherwise the
bad flag	is cleared for the output piddle.

maximum_n_ind
Signature: (a(n); indx	[o]c(m))

Returns the index of "m"	maximum	elements

Not yet been converted to ignore	bad values

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

minmaximum
Signature: (a(n); [o]cmin(); [o] cmax(); indx [o]cmin_ind(); indx [o]cmax_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]

If "a()"	contains only bad data,	then the output	piddles	will be	set
flags cleared, since they will not contain any bad values.

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.

perl v5.24.1			  2017-07-02			      Ufunc(3)
```

NAME | DESCRIPTION | SYNOPSIS | FUNCTIONS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=PDL::Ufunc&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>