1Ufunc(3) User Contributed Perl Documentation Ufunc(3)
2
6 PDL::Ufunc - primitive ufunc operations for pdl
7
9 This module provides some primitive and useful functions defined using
10 PDL::PP based on functionality of what are sometimes called ufuncs (for
11 example NumPY and Mathematica talk about these). It collects all the
12 functions generally used to "reduce" or "accumulate" along a dimension.
13 These all do their job across the first dimension but by using the
14 slicing functions you can do it on any dimension.
15 The PDL::Reduce module provides an alternative interface to many of the
17 functions in this module.
18
20 use PDL::Ufunc;
21
23 prodover
24 Signature: (a(n); int+ [o]b())
25 Project via product to N-1 dimensions
27 This function reduces the dimensionality of a piddle by one by taking
29 the product along the 1st dimension.
30 By using xchg etc. it is possible to use any dimension.
32 $y = prodover($x);
34 $spectrum = prodover $image->xchg(0,1)
36 prodover processes bad values. It will set the bad-value flag of all
38 output piddles if the flag is set for any of the input piddles.
39 dprodover
41 Signature: (a(n); double [o]b())
42 Project via product to N-1 dimensions
44 This function reduces the dimensionality of a piddle by one by taking
46 the product along the 1st dimension.
47 By using xchg etc. it is possible to use any dimension.
49 $y = dprodover($x);
51 $spectrum = dprodover $image->xchg(0,1)
53 Unlike "prodover", the calculations are performed in double precision.
55 dprodover processes bad values. It will set the bad-value flag of all
57 output piddles if the flag is set for any of the input piddles.
58 cumuprodover
60 Signature: (a(n); int+ [o]b(n))
61 Cumulative product
63 This function calculates the cumulative product along the 1st
65 dimension.
66 By using xchg etc. it is possible to use any dimension.
68 The sum is started so that the first element in the cumulative product
70 is the first element of the parameter.
71 $y = cumuprodover($x);
73 $spectrum = cumuprodover $image->xchg(0,1)
75 cumuprodover processes bad values. It will set the bad-value flag of
77 all output piddles if the flag is set for any of the input piddles.
78 dcumuprodover
80 Signature: (a(n); double [o]b(n))
81 Cumulative product
83 This function calculates the cumulative product along the 1st
85 dimension.
86 By using xchg etc. it is possible to use any dimension.
88 The sum is started so that the first element in the cumulative product
90 is the first element of the parameter.
91 $y = cumuprodover($x);
93 $spectrum = cumuprodover $image->xchg(0,1)
95 Unlike "cumuprodover", the calculations are performed in double
97 precision.
98 dcumuprodover processes bad values. It will set the bad-value flag of
100 all output piddles if the flag is set for any of the input piddles.
101 sumover
103 Signature: (a(n); int+ [o]b())
104 Project via sum to N-1 dimensions
106 This function reduces the dimensionality of a piddle by one by taking
108 the sum along the 1st dimension.
109 By using xchg etc. it is possible to use any dimension.
111 $y = sumover($x);
113 $spectrum = sumover $image->xchg(0,1)
115 sumover processes bad values. It will set the bad-value flag of all
117 output piddles if the flag is set for any of the input piddles.
118 dsumover
120 Signature: (a(n); double [o]b())
121 Project via sum to N-1 dimensions
123 This function reduces the dimensionality of a piddle by one by taking
125 the sum along the 1st dimension.
126 By using xchg etc. it is possible to use any dimension.
128 $y = dsumover($x);
130 $spectrum = dsumover $image->xchg(0,1)
132 Unlike "sumover", the calculations are performed in double precision.
134 dsumover processes bad values. It will set the bad-value flag of all
136 output piddles if the flag is set for any of the input piddles.
137 cumusumover
139 Signature: (a(n); int+ [o]b(n))
140 Cumulative sum
142 This function calculates the cumulative sum along the 1st dimension.
144 By using xchg etc. it is possible to use any dimension.
146 The sum is started so that the first element in the cumulative sum is
148 the first element of the parameter.
149 $y = cumusumover($x);
151 $spectrum = cumusumover $image->xchg(0,1)
153 cumusumover processes bad values. It will set the bad-value flag of
155 all output piddles if the flag is set for any of the input piddles.
156 dcumusumover
158 Signature: (a(n); double [o]b(n))
159 Cumulative sum
161 This function calculates the cumulative sum along the 1st dimension.
163 By using xchg etc. it is possible to use any dimension.
165 The sum is started so that the first element in the cumulative sum is
167 the first element of the parameter.
168 $y = cumusumover($x);
170 $spectrum = cumusumover $image->xchg(0,1)
172 Unlike "cumusumover", the calculations are performed in double
174 precision.
175 dcumusumover processes bad values. It will set the bad-value flag of
177 all output piddles if the flag is set for any of the input piddles.
178 andover
180 Signature: (a(n); int+ [o]b())
181 Project via and to N-1 dimensions
183 This function reduces the dimensionality of a piddle by one by taking
185 the and along the 1st dimension.
186 By using xchg etc. it is possible to use any dimension.
188 $y = andover($x);
190 $spectrum = andover $image->xchg(0,1)
192 If "a()" contains only bad data (and its bad flag is set), "b()" is set
194 bad. Otherwise "b()" will have its bad flag cleared, as it will not
195 contain any bad values.
196 bandover
198 Signature: (a(n); [o]b())
199 Project via bitwise and to N-1 dimensions
201 This function reduces the dimensionality of a piddle by one by taking
203 the bitwise and along the 1st dimension.
204 By using xchg etc. it is possible to use any dimension.
206 $y = bandover($x);
208 $spectrum = bandover $image->xchg(0,1)
210 If "a()" contains only bad data (and its bad flag is set), "b()" is set
212 bad. Otherwise "b()" will have its bad flag cleared, as it will not
213 contain any bad values.
214 borover
216 Signature: (a(n); [o]b())
217 Project via bitwise or to N-1 dimensions
219 This function reduces the dimensionality of a piddle by one by taking
221 the bitwise or along the 1st dimension.
222 By using xchg etc. it is possible to use any dimension.
224 $y = borover($x);
226 $spectrum = borover $image->xchg(0,1)
228 If "a()" contains only bad data (and its bad flag is set), "b()" is set
230 bad. Otherwise "b()" will have its bad flag cleared, as it will not
231 contain any bad values.
232 orover
234 Signature: (a(n); int+ [o]b())
235 Project via or to N-1 dimensions
237 This function reduces the dimensionality of a piddle by one by taking
239 the or along the 1st dimension.
240 By using xchg etc. it is possible to use any dimension.
242 $y = orover($x);
244 $spectrum = orover $image->xchg(0,1)
246 If "a()" contains only bad data (and its bad flag is set), "b()" is set
248 bad. Otherwise "b()" will have its bad flag cleared, as it will not
249 contain any bad values.
250 zcover
252 Signature: (a(n); int+ [o]b())
253 Project via == 0 to N-1 dimensions
255 This function reduces the dimensionality of a piddle by one by taking
257 the == 0 along the 1st dimension.
258 By using xchg etc. it is possible to use any dimension.
260 $y = zcover($x);
262 $spectrum = zcover $image->xchg(0,1)
264 If "a()" contains only bad data (and its bad flag is set), "b()" is set
266 bad. Otherwise "b()" will have its bad flag cleared, as it will not
267 contain any bad values.
268 intover
270 Signature: (a(n); float+ [o]b())
271 Project via integral to N-1 dimensions
273 This function reduces the dimensionality of a piddle by one by taking
275 the integral along the 1st dimension.
276 By using xchg etc. it is possible to use any dimension.
278 $y = intover($x);
280 $spectrum = intover $image->xchg(0,1)
282 Notes:
284 "intover" uses a point spacing of one (i.e., delta-h==1). You will
286 need to scale the result to correct for the true point delta).
287 For "n > 3", these are all "O(h^4)" (like Simpson's rule), but are
289 integrals between the end points assuming the pdl gives values just at
290 these centres: for such `functions', sumover is correct to O(h), but is
291 the natural (and correct) choice for binned data, of course.
292 intover ignores the bad-value flag of the input piddles. It will set
294 the bad-value flag of all output piddles if the flag is set for any of
295 the input piddles.
296 average
298 Signature: (a(n); int+ [o]b())
299 Project via average to N-1 dimensions
301 This function reduces the dimensionality of a piddle by one by taking
303 the average along the 1st dimension.
304 By using xchg etc. it is possible to use any dimension.
306 $y = average($x);
308 $spectrum = average $image->xchg(0,1)
310 average processes bad values. It will set the bad-value flag of all
312 output piddles if the flag is set for any of the input piddles.
313 avgover
315 Synonym for average.
316 daverage
318 Signature: (a(n); double [o]b())
319 Project via average to N-1 dimensions
321 This function reduces the dimensionality of a piddle by one by taking
323 the average along the 1st dimension.
324 By using xchg etc. it is possible to use any dimension.
326 $y = daverage($x);
328 $spectrum = daverage $image->xchg(0,1)
330 Unlike "average", the calculation is performed in double precision.
332 daverage processes bad values. It will set the bad-value flag of all
334 output piddles if the flag is set for any of the input piddles.
335 davgover
337 Synonym for daverage.
338 medover
340 Signature: (a(n); [o]b(); [t]tmp(n))
341 Project via median to N-1 dimensions
343 This function reduces the dimensionality of a piddle by one by taking
345 the median along the 1st dimension.
346 By using xchg etc. it is possible to use any dimension.
348 $y = medover($x);
350 $spectrum = medover $image->xchg(0,1)
352 medover processes bad values. It will set the bad-value flag of all
354 output piddles if the flag is set for any of the input piddles.
355 oddmedover
357 Signature: (a(n); [o]b(); [t]tmp(n))
358 Project via oddmedian to N-1 dimensions
360 This function reduces the dimensionality of a piddle by one by taking
362 the oddmedian along the 1st dimension.
363 By using xchg etc. it is possible to use any dimension.
365 $y = oddmedover($x);
367 $spectrum = oddmedover $image->xchg(0,1)
369 The median is sometimes not a good choice as if the array has an even
371 number of elements it lies half-way between the two middle values -
372 thus it does not always correspond to a data value. The lower-odd
373 median is just the lower of these two values and so it ALWAYS sits on
374 an actual data value which is useful in some circumstances.
375 oddmedover processes bad values. It will set the bad-value flag of all
377 output piddles if the flag is set for any of the input piddles.
378 modeover
380 Signature: (data(n); [o]out(); [t]sorted(n))
381 Project via mode to N-1 dimensions
383 This function reduces the dimensionality of a piddle by one by taking
385 the mode along the 1st dimension.
386 By using xchg etc. it is possible to use any dimension.
388 $y = modeover($x);
390 $spectrum = modeover $image->xchg(0,1)
392 The mode is the single element most frequently found in a discrete data
394 set.
395 It only makes sense for integer data types, since floating-point types
397 are demoted to integer before the mode is calculated.
398 "modeover" treats BAD the same as any other value: if BAD is the most
400 common element, the returned value is also BAD.
401 modeover does not process bad values. It will set the bad-value flag
403 of all output piddles if the flag is set for any of the input piddles.
404 pctover
406 Signature: (a(n); p(); [o]b(); [t]tmp(n))
407 Project via percentile to N-1 dimensions
409 This function reduces the dimensionality of a piddle by one by finding
411 the specified percentile (p) along the 1st dimension. The specified
412 percentile must be between 0.0 and 1.0. When the specified percentile
413 falls between data points, the result is interpolated. Values outside
414 the allowed range are clipped to 0.0 or 1.0 respectively. The
415 algorithm implemented here is based on the interpolation variant
416 described at <http://en.wikipedia.org/wiki/Percentile> as used by
417 Microsoft Excel and recommended by NIST.
418 By using xchg etc. it is possible to use any dimension.
420 $y = pctover($x, $p);
422 $spectrum = pctover $image->xchg(0,1), $p
424 pctover processes bad values. It will set the bad-value flag of all
426 output piddles if the flag is set for any of the input piddles.
427 oddpctover
429 Signature: (a(n); p(); [o]b(); [t]tmp(n))
430 Project via percentile to N-1 dimensions
432 This function reduces the dimensionality of a piddle by one by finding
434 the specified percentile along the 1st dimension. The specified
435 percentile must be between 0.0 and 1.0. When the specified percentile
436 falls between two values, the nearest data value is the result. The
437 algorithm implemented is from the textbook version described first at
438 <http://en.wikipedia.org/wiki/Percentile>.
439 By using xchg etc. it is possible to use any dimension.
441 $y = oddpctover($x, $p);
443 $spectrum = oddpctover $image->xchg(0,1), $p
445 oddpctover processes bad values. It will set the bad-value flag of all
447 output piddles if the flag is set for any of the input piddles.
448 pct
450 Return the specified percentile of all elements in a piddle. The
451 specified percentile (p) must be between 0.0 and 1.0. When the
452 specified percentile falls between data points, the result is
453 interpolated.
454 $x = pct($data, $pct);
456 oddpct
458 Return the specified percentile of all elements in a piddle. The
459 specified percentile must be between 0.0 and 1.0. When the specified
460 percentile falls between two values, the nearest data value is the
461 result.
462 $x = oddpct($data, $pct);
464 avg
466 Return the average of all elements in a piddle.
467 See the documentation for "average" for more information.
469 $x = avg($data);
471 This routine handles bad values.
473 sum
475 Return the sum of all elements in a piddle.
476 See the documentation for "sumover" for more information.
478 $x = sum($data);
480 This routine handles bad values.
482 prod
484 Return the product of all elements in a piddle.
485 See the documentation for "prodover" for more information.
487 $x = prod($data);
489 This routine handles bad values.
491 davg
493 Return the average (in double precision) of all elements in a piddle.
494 See the documentation for "daverage" for more information.
496 $x = davg($data);
498 This routine handles bad values.
500 dsum
502 Return the sum (in double precision) of all elements in a piddle.
503 See the documentation for "dsumover" for more information.
505 $x = dsum($data);
507 This routine handles bad values.
509 dprod
511 Return the product (in double precision) of all elements in a piddle.
512 See the documentation for "dprodover" for more information.
514 $x = dprod($data);
516 This routine handles bad values.
518 zcheck
520 Return the check for zero of all elements in a piddle.
521 See the documentation for "zcover" for more information.
523 $x = zcheck($data);
525 This routine handles bad values.
527 and
529 Return the logical and of all elements in a piddle.
530 See the documentation for "andover" for more information.
532 $x = and($data);
534 This routine handles bad values.
536 band
538 Return the bitwise and of all elements in a piddle.
539 See the documentation for "bandover" for more information.
541 $x = band($data);
543 This routine handles bad values.
545 or
547 Return the logical or of all elements in a piddle.
548 See the documentation for "orover" for more information.
550 $x = or($data);
552 This routine handles bad values.
554 bor
556 Return the bitwise or of all elements in a piddle.
557 See the documentation for "borover" for more information.
559 $x = bor($data);
561 This routine handles bad values.
563 min
565 Return the minimum of all elements in a piddle.
566 See the documentation for "minimum" for more information.
568 $x = min($data);
570 This routine handles bad values.
572 max
574 Return the maximum of all elements in a piddle.
575 See the documentation for "maximum" for more information.
577 $x = max($data);
579 This routine handles bad values.
581 median
583 Return the median of all elements in a piddle.
584 See the documentation for "medover" for more information.
586 $x = median($data);
588 This routine handles bad values.
590 mode
592 Return the mode of all elements in a piddle.
593 See the documentation for "modeover" for more information.
595 $x = mode($data);
597 This routine handles bad values.
599 oddmedian
601 Return the oddmedian of all elements in a piddle.
602 See the documentation for "oddmedover" for more information.
604 $x = oddmedian($data);
606 This routine handles bad values.
608 any
610 Return true if any element in piddle set
611 Useful in conditional expressions:
613 if (any $x>15) { print "some values are greater than 15\n" }
615 See "or" for comments on what happens when all elements in the check
617 are bad.
618 all
620 Return true if all elements in piddle set
621 Useful in conditional expressions:
623 if (all $x>15) { print "all values are greater than 15\n" }
625 See "and" for comments on what happens when all elements in the check
627 are bad.
628 minmax
630 Returns an array with minimum and maximum values of a piddle.
631 ($mn, $mx) = minmax($pdl);
633 This routine does not thread over the dimensions of $pdl; it returns
635 the minimum and maximum values of the whole array. See "minmaximum" if
636 this is not what is required. The two values are returned as Perl
637 scalars similar to min/max.
638 pdl> $x = pdl [1,-2,3,5,0]
640 pdl> ($min, $max) = minmax($x);
641 pdl> p "$min $max\n";
642 -2 5
643 qsort
645 Signature: (a(n); [o]b(n))
646 Quicksort a vector into ascending order.
648 print qsort random(10);
650 Bad values are moved to the end of the array:
652 pdl> p $y
654 [42 47 98 BAD 22 96 74 41 79 76 96 BAD 32 76 25 59 BAD 96 32 BAD]
655 pdl> p qsort($y)
656 [22 25 32 32 41 42 47 59 74 76 76 79 96 96 96 98 BAD BAD BAD BAD]
657 qsorti
659 Signature: (a(n); indx [o]indx(n))
660 Quicksort a vector and return index of elements in ascending order.
662 $ix = qsorti $x;
664 print $x->index($ix); # Sorted list
665 Bad elements are moved to the end of the array:
667 pdl> p $y
669 [42 47 98 BAD 22 96 74 41 79 76 96 BAD 32 76 25 59 BAD 96 32 BAD]
670 pdl> p $y->index( qsorti($y) )
671 [22 25 32 32 41 42 47 59 74 76 76 79 96 96 96 98 BAD BAD BAD BAD]
672 qsortvec
674 Signature: (a(n,m); [o]b(n,m))
675 Sort a list of vectors lexicographically.
677 The 0th dimension of the source piddle is dimension in the vector; the
679 1st dimension is list order. Higher dimensions are threaded over.
680 print qsortvec pdl([[1,2],[0,500],[2,3],[4,2],[3,4],[3,5]]);
682 [
683 [ 0 500]
684 [ 1 2]
685 [ 2 3]
686 [ 3 4]
687 [ 3 5]
688 [ 4 2]
689 ]
690 Vectors with bad components should be moved to the end of the array:
692 qsortveci
694 Signature: (a(n,m); indx [o]indx(m))
695 Sort a list of vectors lexicographically, returning the indices of the
697 sorted vectors rather than the sorted list itself.
698 As with "qsortvec", the input PDL should be an NxM array containing M
700 separate N-dimensional vectors. The return value is an integer M-PDL
701 containing the M-indices of original array rows, in sorted order.
702 As with "qsortvec", the zeroth element of the vectors runs slowest in
704 the sorted list.
705 Additional dimensions are threaded over: each plane is sorted
707 separately, so qsortveci may be thought of as a collapse operator of
708 sorts (groan).
709 Vectors with bad components should be moved to the end of the array:
711 minimum
713 Signature: (a(n); [o]c())
714 Project via minimum to N-1 dimensions
716 This function reduces the dimensionality of a piddle by one by taking
718 the minimum along the 1st dimension.
719 By using xchg etc. it is possible to use any dimension.
721 $y = minimum($x);
723 $spectrum = minimum $image->xchg(0,1)
725 Output is set bad if all elements of the input are bad, otherwise the
727 bad flag is cleared for the output piddle.
728 Note that "NaNs" are considered to be valid values; see isfinite and
730 badmask for ways of masking NaNs.
731 minimum_ind
733 Signature: (a(n); indx [o] c())
734 Like minimum but returns the index rather than the value
736 Output is set bad if all elements of the input are bad, otherwise the
738 bad flag is cleared for the output piddle.
739 minimum_n_ind
741 Signature: (a(n); indx [o]c(m))
742 Returns the index of "m" minimum elements
744 Not yet been converted to ignore bad values
746 maximum
748 Signature: (a(n); [o]c())
749 Project via maximum to N-1 dimensions
751 This function reduces the dimensionality of a piddle by one by taking
753 the maximum along the 1st dimension.
754 By using xchg etc. it is possible to use any dimension.
756 $y = maximum($x);
758 $spectrum = maximum $image->xchg(0,1)
760 Output is set bad if all elements of the input are bad, otherwise the
762 bad flag is cleared for the output piddle.
763 Note that "NaNs" are considered to be valid values; see isfinite and
765 badmask for ways of masking NaNs.
766 maximum_ind
768 Signature: (a(n); indx [o] c())
769 Like maximum but returns the index rather than the value
771 Output is set bad if all elements of the input are bad, otherwise the
773 bad flag is cleared for the output piddle.
774 maximum_n_ind
776 Signature: (a(n); indx [o]c(m))
777 Returns the index of "m" maximum elements
779 Not yet been converted to ignore bad values
781 maxover
783 Synonym for maximum.
784 maxover_ind
786 Synonym for maximum_ind.
787 maxover_n_ind
789 Synonym for maximum_n_ind.
790 minover
792 Synonym for minimum.
793 minover_ind
795 Synonym for minimum_ind.
796 minover_n_ind
798 Synonym for minimum_n_ind
799 minmaximum
801 Signature: (a(n); [o]cmin(); [o] cmax(); indx [o]cmin_ind(); indx [o]cmax_ind())
802 Find minimum and maximum and their indices for a given piddle;
804 pdl> $x=pdl [[-2,3,4],[1,0,3]]
806 pdl> ($min, $max, $min_ind, $max_ind)=minmaximum($x)
807 pdl> p $min, $max, $min_ind, $max_ind
808 [-2 0] [4 3] [0 1] [2 2]
809 See also "minmax", which clumps the piddle together.
811 If "a()" contains only bad data, then the output piddles will be set
813 bad, along with their bad flag. Otherwise they will have their bad
814 flags cleared, since they will not contain any bad values.
815 minmaxover
817 Synonym for minmaximum.
818
820 Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu).
821 Contributions by Christian Soeller (c.soeller@auckland.ac.nz) and Karl
822 Glazebrook (kgb@aaoepp.aao.gov.au). All rights reserved. There is no
823 warranty. You are allowed to redistribute this software / documentation
824 under certain conditions. For details, see the file COPYING in the PDL
825 distribution. If this file is separated from the PDL distribution, the
826 copyright notice should be included in the file.
827perl v5.32.1 2021-02-15 Ufunc(3)