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 precision.
174 dcumusumover processes bad values. It will set the bad-value flag of
176 all output piddles if the flag is set for any of the input piddles.
177 andover
179 Signature: (a(n); int+ [o]b())
180 Project via and to N-1 dimensions
182 This function reduces the dimensionality of a piddle by one by taking
184 the and along the 1st dimension.
185 By using xchg etc. it is possible to use any dimension.
187 $y = andover($x);
189 $spectrum = andover $image->xchg(0,1)
191 If "a()" contains only bad data (and its bad flag is set), "b()" is set
193 bad. Otherwise "b()" will have its bad flag cleared, as it will not
194 contain any bad values.
195 bandover
197 Signature: (a(n); [o]b())
198 Project via bitwise and to N-1 dimensions
200 This function reduces the dimensionality of a piddle by one by taking
202 the bitwise and along the 1st dimension.
203 By using xchg etc. it is possible to use any dimension.
205 $y = bandover($x);
207 $spectrum = bandover $image->xchg(0,1)
209 If "a()" contains only bad data (and its bad flag is set), "b()" is set
211 bad. Otherwise "b()" will have its bad flag cleared, as it will not
212 contain any bad values.
213 borover
215 Signature: (a(n); [o]b())
216 Project via bitwise or to N-1 dimensions
218 This function reduces the dimensionality of a piddle by one by taking
220 the bitwise or along the 1st dimension.
221 By using xchg etc. it is possible to use any dimension.
223 $y = borover($x);
225 $spectrum = borover $image->xchg(0,1)
227 If "a()" contains only bad data (and its bad flag is set), "b()" is set
229 bad. Otherwise "b()" will have its bad flag cleared, as it will not
230 contain any bad values.
231 orover
233 Signature: (a(n); int+ [o]b())
234 Project via or to N-1 dimensions
236 This function reduces the dimensionality of a piddle by one by taking
238 the or along the 1st dimension.
239 By using xchg etc. it is possible to use any dimension.
241 $y = orover($x);
243 $spectrum = orover $image->xchg(0,1)
245 If "a()" contains only bad data (and its bad flag is set), "b()" is set
247 bad. Otherwise "b()" will have its bad flag cleared, as it will not
248 contain any bad values.
249 zcover
251 Signature: (a(n); int+ [o]b())
252 Project via == 0 to N-1 dimensions
254 This function reduces the dimensionality of a piddle by one by taking
256 the == 0 along the 1st dimension.
257 By using xchg etc. it is possible to use any dimension.
259 $y = zcover($x);
261 $spectrum = zcover $image->xchg(0,1)
263 If "a()" contains only bad data (and its bad flag is set), "b()" is set
265 bad. Otherwise "b()" will have its bad flag cleared, as it will not
266 contain any bad values.
267 intover
269 Signature: (a(n); float+ [o]b())
270 Project via integral to N-1 dimensions
272 This function reduces the dimensionality of a piddle by one by taking
274 the integral along the 1st dimension.
275 By using xchg etc. it is possible to use any dimension.
277 $y = intover($x);
279 $spectrum = intover $image->xchg(0,1)
281 Notes:
283 "intover" uses a point spacing of one (i.e., delta-h==1). You will
285 need to scale the result to correct for the true point delta).
286 For "n > 3", these are all "O(h^4)" (like Simpson's rule), but are
288 integrals between the end points assuming the pdl gives values just at
289 these centres: for such `functions', sumover is correct to O(h), but is
290 the natural (and correct) choice for binned data, of course.
291 intover ignores the bad-value flag of the input piddles. It will set
293 the bad-value flag of all output piddles if the flag is set for any of
294 the input piddles.
295 average
297 Signature: (a(n); int+ [o]b())
298 Project via average to N-1 dimensions
300 This function reduces the dimensionality of a piddle by one by taking
302 the average along the 1st dimension.
303 By using xchg etc. it is possible to use any dimension.
305 $y = average($x);
307 $spectrum = average $image->xchg(0,1)
309 average processes bad values. It will set the bad-value flag of all
311 output piddles if the flag is set for any of the input piddles.
312 avgover
314 Synonym for average.
315 daverage
317 Signature: (a(n); double [o]b())
318 Project via average to N-1 dimensions
320 This function reduces the dimensionality of a piddle by one by taking
322 the average along the 1st dimension.
323 By using xchg etc. it is possible to use any dimension.
325 $y = daverage($x);
327 $spectrum = daverage $image->xchg(0,1)
329 Unlike average, the calculation is performed in double precision.
331 daverage processes bad values. It will set the bad-value flag of all
333 output piddles if the flag is set for any of the input piddles.
334 davgover
336 Synonym for daverage.
337 medover
339 Signature: (a(n); [o]b(); [t]tmp(n))
340 Project via median to N-1 dimensions
342 This function reduces the dimensionality of a piddle by one by taking
344 the median along the 1st dimension.
345 By using xchg etc. it is possible to use any dimension.
347 $y = medover($x);
349 $spectrum = medover $image->xchg(0,1)
351 medover processes bad values. It will set the bad-value flag of all
353 output piddles if the flag is set for any of the input piddles.
354 oddmedover
356 Signature: (a(n); [o]b(); [t]tmp(n))
357 Project via oddmedian to N-1 dimensions
359 This function reduces the dimensionality of a piddle by one by taking
361 the oddmedian along the 1st dimension.
362 By using xchg etc. it is possible to use any dimension.
364 $y = oddmedover($x);
366 $spectrum = oddmedover $image->xchg(0,1)
368 The median is sometimes not a good choice as if the array has an even
370 number of elements it lies half-way between the two middle values -
371 thus it does not always correspond to a data value. The lower-odd
372 median is just the lower of these two values and so it ALWAYS sits on
373 an actual data value which is useful in some circumstances.
374 oddmedover processes bad values. It will set the bad-value flag of all
376 output piddles if the flag is set for any of the input piddles.
377 modeover
379 Signature: (data(n); [o]out(); [t]sorted(n))
380 Project via mode to N-1 dimensions
382 This function reduces the dimensionality of a piddle by one by taking
384 the mode along the 1st dimension.
385 By using xchg etc. it is possible to use any dimension.
387 $y = modeover($x);
389 $spectrum = modeover $image->xchg(0,1)
391 The mode is the single element most frequently found in a discrete data
393 set.
394 It only makes sense for integer data types, since floating-point types
396 are demoted to integer before the mode is calculated.
397 "modeover" treats BAD the same as any other value: if BAD is the most
399 common element, the returned value is also BAD.
400 modeover does not process bad values. It will set the bad-value flag
402 of all output piddles if the flag is set for any of the input piddles.
403 pctover
405 Signature: (a(n); p(); [o]b(); [t]tmp(n))
406 Project via percentile to N-1 dimensions
408 This function reduces the dimensionality of a piddle by one by finding
410 the specified percentile (p) along the 1st dimension. The specified
411 percentile must be between 0.0 and 1.0. When the specified percentile
412 falls between data points, the result is interpolated. Values outside
413 the allowed range are clipped to 0.0 or 1.0 respectively. The
414 algorithm implemented here is based on the interpolation variant
415 described at <http://en.wikipedia.org/wiki/Percentile> as used by
416 Microsoft Excel and recommended by NIST.
417 By using xchg etc. it is possible to use any dimension.
419 $y = pctover($x, $p);
421 $spectrum = pctover $image->xchg(0,1), $p
423 pctover processes bad values. It will set the bad-value flag of all
425 output piddles if the flag is set for any of the input piddles.
426 oddpctover
428 Signature: (a(n); p(); [o]b(); [t]tmp(n))
429 Project via percentile to N-1 dimensions
431 This function reduces the dimensionality of a piddle by one by finding
433 the specified percentile along the 1st dimension. The specified
434 percentile must be between 0.0 and 1.0. When the specified percentile
435 falls between two values, the nearest data value is the result. The
436 algorithm implemented is from the textbook version described first at
437 <http://en.wikipedia.org/wiki/Percentile>.
438 By using xchg etc. it is possible to use any dimension.
440 $y = oddpctover($x, $p);
442 $spectrum = oddpctover $image->xchg(0,1), $p
444 oddpctover processes bad values. It will set the bad-value flag of all
446 output piddles if the flag is set for any of the input piddles.
447 pct
449 Return the specified percentile of all elements in a piddle. The
450 specified percentile (p) must be between 0.0 and 1.0. When the
451 specified percentile falls between data points, the result is
452 interpolated.
453 $x = pct($data, $pct);
455 oddpct
457 Return the specified percentile of all elements in a piddle. The
458 specified percentile must be between 0.0 and 1.0. When the specified
459 percentile falls between two values, the nearest data value is the
460 result.
461 $x = oddpct($data, $pct);
463 avg
465 Return the average of all elements in a piddle.
466 See the documentation for average for more information.
468 $x = avg($data);
470 This routine handles bad values.
472 sum
474 Return the sum of all elements in a piddle.
475 See the documentation for sumover for more information.
477 $x = sum($data);
479 This routine handles bad values.
481 prod
483 Return the product of all elements in a piddle.
484 See the documentation for prodover for more information.
486 $x = prod($data);
488 This routine handles bad values.
490 davg
492 Return the average (in double precision) of all elements in a piddle.
493 See the documentation for daverage for more information.
495 $x = davg($data);
497 This routine handles bad values.
499 dsum
501 Return the sum (in double precision) of all elements in a piddle.
502 See the documentation for dsumover for more information.
504 $x = dsum($data);
506 This routine handles bad values.
508 dprod
510 Return the product (in double precision) of all elements in a piddle.
511 See the documentation for dprodover for more information.
513 $x = dprod($data);
515 This routine handles bad values.
517 zcheck
519 Return the check for zero of all elements in a piddle.
520 See the documentation for zcover for more information.
522 $x = zcheck($data);
524 This routine handles bad values.
526 and
528 Return the logical and of all elements in a piddle.
529 See the documentation for andover for more information.
531 $x = and($data);
533 This routine handles bad values.
535 band
537 Return the bitwise and of all elements in a piddle.
538 See the documentation for bandover for more information.
540 $x = band($data);
542 This routine handles bad values.
544 or
546 Return the logical or of all elements in a piddle.
547 See the documentation for orover for more information.
549 $x = or($data);
551 This routine handles bad values.
553 bor
555 Return the bitwise or of all elements in a piddle.
556 See the documentation for borover for more information.
558 $x = bor($data);
560 This routine handles bad values.
562 min
564 Return the minimum of all elements in a piddle.
565 See the documentation for minimum for more information.
567 $x = min($data);
569 This routine handles bad values.
571 max
573 Return the maximum of all elements in a piddle.
574 See the documentation for maximum for more information.
576 $x = max($data);
578 This routine handles bad values.
580 median
582 Return the median of all elements in a piddle.
583 See the documentation for medover for more information.
585 $x = median($data);
587 This routine handles bad values.
589 mode
591 Return the mode of all elements in a piddle.
592 See the documentation for modeover for more information.
594 $x = mode($data);
596 This routine handles bad values.
598 oddmedian
600 Return the oddmedian of all elements in a piddle.
601 See the documentation for oddmedover for more information.
603 $x = oddmedian($data);
605 This routine handles bad values.
607 any
609 Return true if any element in piddle set
610 Useful in conditional expressions:
612 if (any $x>15) { print "some values are greater than 15\n" }
614 See or for comments on what happens when all elements in the check are
616 bad.
617 all
619 Return true if all elements in piddle set
620 Useful in conditional expressions:
622 if (all $x>15) { print "all values are greater than 15\n" }
624 See and for comments on what happens when all elements in the check are
626 bad.
627 minmax
629 Returns an array with minimum and maximum values of a piddle.
630 ($mn, $mx) = minmax($pdl);
632 This routine does not thread over the dimensions of $pdl; it returns
634 the minimum and maximum values of the whole array. See minmaximum if
635 this is not what is required. The two values are returned as Perl
636 scalars similar to min/max.
637 pdl> $x = pdl [1,-2,3,5,0]
639 pdl> ($min, $max) = minmax($x);
640 pdl> p "$min $max\n";
641 -2 5
642 qsort
644 Signature: (a(n); [o]b(n))
645 Quicksort a vector into ascending order.
647 print qsort random(10);
649 Bad values are moved to the end of the array:
651 pdl> p $y
653 [42 47 98 BAD 22 96 74 41 79 76 96 BAD 32 76 25 59 BAD 96 32 BAD]
654 pdl> p qsort($y)
655 [22 25 32 32 41 42 47 59 74 76 76 79 96 96 96 98 BAD BAD BAD BAD]
656 qsorti
658 Signature: (a(n); indx [o]indx(n))
659 Quicksort a vector and return index of elements in ascending order.
661 $ix = qsorti $x;
663 print $x->index($ix); # Sorted list
664 Bad elements are moved to the end of the array:
666 pdl> p $y
668 [42 47 98 BAD 22 96 74 41 79 76 96 BAD 32 76 25 59 BAD 96 32 BAD]
669 pdl> p $y->index( qsorti($y) )
670 [22 25 32 32 41 42 47 59 74 76 76 79 96 96 96 98 BAD BAD BAD BAD]
671 qsortvec
673 Signature: (a(n,m); [o]b(n,m))
674 Sort a list of vectors lexicographically.
676 The 0th dimension of the source piddle is dimension in the vector; the
678 1st dimension is list order. Higher dimensions are threaded over.
679 print qsortvec pdl([[1,2],[0,500],[2,3],[4,2],[3,4],[3,5]]);
681 [
682 [ 0 500]
683 [ 1 2]
684 [ 2 3]
685 [ 3 4]
686 [ 3 5]
687 [ 4 2]
688 ]
689 Vectors with bad components should be moved to the end of the array:
691 qsortveci
693 Signature: (a(n,m); indx [o]indx(m))
694 Sort a list of vectors lexicographically, returning the indices of the
696 sorted vectors rather than the sorted list itself.
697 As with "qsortvec", the input PDL should be an NxM array containing M
699 separate N-dimensional vectors. The return value is an integer M-PDL
700 containing the M-indices of original array rows, in sorted order.
701 As with "qsortvec", the zeroth element of the vectors runs slowest in
703 the sorted list.
704 Additional dimensions are threaded over: each plane is sorted
706 separately, so qsortveci may be thought of as a collapse operator of
707 sorts (groan).
708 Vectors with bad components should be moved to the end of the array:
710 minimum
712 Signature: (a(n); [o]c())
713 Project via minimum to N-1 dimensions
715 This function reduces the dimensionality of a piddle by one by taking
717 the minimum along the 1st dimension.
718 By using xchg etc. it is possible to use any dimension.
720 $y = minimum($x);
722 $spectrum = minimum $image->xchg(0,1)
724 Output is set bad if all elements of the input are bad, otherwise the
726 bad flag is cleared for the output piddle.
727 Note that "NaNs" are considered to be valid values; see isfinite and
729 badmask for ways of masking NaNs.
730 minimum_ind
732 Signature: (a(n); indx [o] c())
733 Like minimum but returns the index rather than the value
735 Output is set bad if all elements of the input are bad, otherwise the
737 bad flag is cleared for the output piddle.
738 minimum_n_ind
740 Signature: (a(n); indx [o]c(m))
741 Returns the index of "m" minimum elements
743 Not yet been converted to ignore bad values
745 maximum
747 Signature: (a(n); [o]c())
748 Project via maximum to N-1 dimensions
750 This function reduces the dimensionality of a piddle by one by taking
752 the maximum along the 1st dimension.
753 By using xchg etc. it is possible to use any dimension.
755 $y = maximum($x);
757 $spectrum = maximum $image->xchg(0,1)
759 Output is set bad if all elements of the input are bad, otherwise the
761 bad flag is cleared for the output piddle.
762 Note that "NaNs" are considered to be valid values; see isfinite and
764 badmask for ways of masking NaNs.
765 maximum_ind
767 Signature: (a(n); indx [o] c())
768 Like maximum but returns the index rather than the value
770 Output is set bad if all elements of the input are bad, otherwise the
772 bad flag is cleared for the output piddle.
773 maximum_n_ind
775 Signature: (a(n); indx [o]c(m))
776 Returns the index of "m" maximum elements
778 Not yet been converted to ignore bad values
780 maxover
782 Synonym for maximum.
783 maxover_ind
785 Synonym for maximum_ind.
786 maxover_n_ind
788 Synonym for maximum_n_ind.
789 minover
791 Synonym for minimum.
792 minover_ind
794 Synonym for minimum_ind.
795 minover_n_ind
797 Synonym for minimum_n_ind
798 minmaximum
800 Signature: (a(n); [o]cmin(); [o] cmax(); indx [o]cmin_ind(); indx [o]cmax_ind())
801 Find minimum and maximum and their indices for a given piddle;
803 pdl> $x=pdl [[-2,3,4],[1,0,3]]
805 pdl> ($min, $max, $min_ind, $max_ind)=minmaximum($x)
806 pdl> p $min, $max, $min_ind, $max_ind
807 [-2 0] [4 3] [0 1] [2 2]
808 See also minmax, which clumps the piddle together.
810 If "a()" contains only bad data, then the output piddles will be set
812 bad, along with their bad flag. Otherwise they will have their bad
813 flags cleared, since they will not contain any bad values.
814 minmaxover
816 Synonym for minmaximum.
817
819 Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu).
820 Contributions by Christian Soeller (c.soeller@auckland.ac.nz) and Karl
821 Glazebrook (kgb@aaoepp.aao.gov.au). All rights reserved. There is no
822 warranty. You are allowed to redistribute this software / documentation
823 under certain conditions. For details, see the file COPYING in the PDL
824 distribution. If this file is separated from the PDL distribution, the
825 copyright notice should be included in the file.
826perl v5.32.0 2020-09-17 Ufunc(3)