Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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)

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

   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.

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

   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)

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

   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.

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

   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
       contain any bad values.

   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
       contain any bad values.

   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
       contain any bad values.

   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
       contain any bad values.

   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
       contain any bad values.

   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.

       See the documentation for average for more information.

	$x = avg($data);

       This routine handles bad	values.

   sum
       Return the sum of all elements in a piddle.

       See the documentation for sumover for more information.

	$x = sum($data);

       This routine handles bad	values.

   prod
       Return the product of all elements in a piddle.

       See the documentation for prodover for more information.

	$x = prod($data);

       This routine handles bad	values.

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

       See the documentation for daverage for more information.

	$x = davg($data);

       This routine handles bad	values.

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

       See the documentation for dsumover for more information.

	$x = dsum($data);

       This routine handles bad	values.

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

       See the documentation for dprodover for more information.

	$x = dprod($data);

       This routine handles bad	values.

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

       See the documentation for zcover	for more information.

	$x = zcheck($data);

       This routine handles bad	values.

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

       See the documentation for andover for more information.

	$x = and($data);

       This routine handles bad	values.

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

       See the documentation for bandover for more information.

	$x = band($data);

       This routine handles bad	values.

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

       See the documentation for orover	for more information.

	$x = or($data);

       This routine handles bad	values.

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

       See the documentation for borover for more information.

	$x = bor($data);

       This routine handles bad	values.

   min
       Return the minimum of all elements in a piddle.

       See the documentation for minimum for more information.

	$x = min($data);

       This routine handles bad	values.

   max
       Return the maximum of all elements in a piddle.

       See the documentation for maximum for more information.

	$x = max($data);

       This routine handles bad	values.

   median
       Return the median of all	elements in a piddle.

       See the documentation for medover for more information.

	$x = median($data);

       This routine handles bad	values.

   mode
       Return the mode of all elements in a piddle.

       See the documentation for modeover for more information.

	$x = mode($data);

       This routine handles bad	values.

   oddmedian
       Return the oddmedian of all elements in a piddle.

       See the documentation for oddmedover for	more information.

	$x = oddmedian($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

   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
	[42 47 98 BAD 22 96 74 41 79 76	96 BAD 32 76 25	59 BAD 96 32 BAD]
	pdl> p qsort($b)
	[22 25 32 32 41	42 47 59 74 76 76 79 96	96 96 98 BAD BAD BAD BAD]

   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
	[42 47 98 BAD 22 96 74 41 79 76	96 BAD 32 76 25	59 BAD 96 32 BAD]
	pdl> p $b->index( qsorti($b) )
	[22 25 32 32 41	42 47 59 74 76 76 79 96	96 96 98 BAD BAD BAD BAD]

   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.

       Additional dimensions are threaded over:	each plane is sorted
       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
       badmask for ways	of masking NaNs.

   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
       badmask for ways	of masking NaNs.

   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]

       See also	minmax,	which clumps the piddle	together.

       If "a()"	contains only bad data,	then the output	piddles	will be	set
       bad, along with their bad flag.	Otherwise they will have their bad
       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>

home | help