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 an ndarray 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->transpose
36 prodover processes bad values. It will set the bad-value flag of all
38 output ndarrays if the flag is set for any of the input ndarrays.
39 cprodover
41 Signature: (a(n); cdouble [o]b())
42 Project via product to N-1 dimensions
44 This function reduces the dimensionality of an ndarray 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->transpose
53 Unlike prodover, the calculations are performed in complex double
55 precision.
56 cprodover processes bad values. It will set the bad-value flag of all
58 output ndarrays if the flag is set for any of the input ndarrays.
59 dprodover
61 Signature: (a(n); double [o]b())
62 Project via product to N-1 dimensions
64 This function reduces the dimensionality of an ndarray by one by taking
66 the product along the 1st dimension.
67 By using xchg etc. it is possible to use any dimension.
69 $y = dprodover($x);
71 $spectrum = dprodover $image->transpose
73 Unlike "prodover", the calculations are performed in double precision.
75 dprodover processes bad values. It will set the bad-value flag of all
77 output ndarrays if the flag is set for any of the input ndarrays.
78 cumuprodover
80 Signature: (a(n); int+ [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->transpose
95 cumuprodover processes bad values. It will set the bad-value flag of
97 all output ndarrays if the flag is set for any of the input ndarrays.
98 dcumuprodover
100 Signature: (a(n); double [o]b(n))
101 Cumulative product
103 This function calculates the cumulative product along the 1st
105 dimension.
106 By using xchg etc. it is possible to use any dimension.
108 The sum is started so that the first element in the cumulative product
110 is the first element of the parameter.
111 $y = cumuprodover($x);
113 $spectrum = cumuprodover $image->transpose
115 Unlike "cumuprodover", the calculations are performed in double
117 precision.
118 dcumuprodover processes bad values. It will set the bad-value flag of
120 all output ndarrays if the flag is set for any of the input ndarrays.
121 sumover
123 Signature: (a(n); int+ [o]b())
124 Project via sum to N-1 dimensions
126 This function reduces the dimensionality of an ndarray by one by taking
128 the sum along the 1st dimension.
129 By using xchg etc. it is possible to use any dimension.
131 $y = sumover($x);
133 $spectrum = sumover $image->transpose
135 sumover processes bad values. It will set the bad-value flag of all
137 output ndarrays if the flag is set for any of the input ndarrays.
138 csumover
140 Signature: (a(n); cdouble [o]b())
141 Project via sum to N-1 dimensions
143 This function reduces the dimensionality of an ndarray by one by taking
145 the sum along the 1st dimension.
146 By using xchg etc. it is possible to use any dimension.
148 $y = dsumover($x);
150 $spectrum = dsumover $image->transpose
152 Unlike sumover, the calculations are performed in complex double
154 precision.
155 csumover processes bad values. It will set the bad-value flag of all
157 output ndarrays if the flag is set for any of the input ndarrays.
158 dsumover
160 Signature: (a(n); double [o]b())
161 Project via sum to N-1 dimensions
163 This function reduces the dimensionality of an ndarray by one by taking
165 the sum along the 1st dimension.
166 By using xchg etc. it is possible to use any dimension.
168 $y = dsumover($x);
170 $spectrum = dsumover $image->transpose
172 Unlike "sumover", the calculations are performed in double precision.
174 dsumover processes bad values. It will set the bad-value flag of all
176 output ndarrays if the flag is set for any of the input ndarrays.
177 cumusumover
179 Signature: (a(n); int+ [o]b(n))
180 Cumulative sum
182 This function calculates the cumulative sum along the 1st dimension.
184 By using xchg etc. it is possible to use any dimension.
186 The sum is started so that the first element in the cumulative sum is
188 the first element of the parameter.
189 $y = cumusumover($x);
191 $spectrum = cumusumover $image->transpose
193 cumusumover processes bad values. It will set the bad-value flag of
195 all output ndarrays if the flag is set for any of the input ndarrays.
196 dcumusumover
198 Signature: (a(n); double [o]b(n))
199 Cumulative sum
201 This function calculates the cumulative sum along the 1st dimension.
203 By using xchg etc. it is possible to use any dimension.
205 The sum is started so that the first element in the cumulative sum is
207 the first element of the parameter.
208 $y = cumusumover($x);
210 $spectrum = cumusumover $image->transpose
212 Unlike "cumusumover", the calculations are performed in double
214 precision.
215 dcumusumover processes bad values. It will set the bad-value flag of
217 all output ndarrays if the flag is set for any of the input ndarrays.
218 andover
220 Signature: (a(n); int+ [o]b())
221 Project via and to N-1 dimensions
223 This function reduces the dimensionality of an ndarray by one by taking
225 the and along the 1st dimension.
226 By using xchg etc. it is possible to use any dimension.
228 $y = andover($x);
230 $spectrum = andover $image->transpose
232 If "a()" contains only bad data (and its bad flag is set), "b()" is set
234 bad. Otherwise "b()" will have its bad flag cleared, as it will not
235 contain any bad values.
236 bandover
238 Signature: (a(n); [o]b())
239 Project via bitwise and to N-1 dimensions
241 This function reduces the dimensionality of an ndarray by one by taking
243 the bitwise and along the 1st dimension.
244 By using xchg etc. it is possible to use any dimension.
246 $y = bandover($x);
248 $spectrum = bandover $image->transpose
250 If "a()" contains only bad data (and its bad flag is set), "b()" is set
252 bad. Otherwise "b()" will have its bad flag cleared, as it will not
253 contain any bad values.
254 borover
256 Signature: (a(n); [o]b())
257 Project via bitwise or to N-1 dimensions
259 This function reduces the dimensionality of an ndarray by one by taking
261 the bitwise or along the 1st dimension.
262 By using xchg etc. it is possible to use any dimension.
264 $y = borover($x);
266 $spectrum = borover $image->transpose
268 If "a()" contains only bad data (and its bad flag is set), "b()" is set
270 bad. Otherwise "b()" will have its bad flag cleared, as it will not
271 contain any bad values.
272 orover
274 Signature: (a(n); int+ [o]b())
275 Project via or to N-1 dimensions
277 This function reduces the dimensionality of an ndarray by one by taking
279 the or along the 1st dimension.
280 By using xchg etc. it is possible to use any dimension.
282 $y = orover($x);
284 $spectrum = orover $image->transpose
286 If "a()" contains only bad data (and its bad flag is set), "b()" is set
288 bad. Otherwise "b()" will have its bad flag cleared, as it will not
289 contain any bad values.
290 zcover
292 Signature: (a(n); int+ [o]b())
293 Project via == 0 to N-1 dimensions
295 This function reduces the dimensionality of an ndarray by one by taking
297 the == 0 along the 1st dimension.
298 By using xchg etc. it is possible to use any dimension.
300 $y = zcover($x);
302 $spectrum = zcover $image->transpose
304 If "a()" contains only bad data (and its bad flag is set), "b()" is set
306 bad. Otherwise "b()" will have its bad flag cleared, as it will not
307 contain any bad values.
308 intover
310 Signature: (a(n); float+ [o]b())
311 Project via integral to N-1 dimensions
313 This function reduces the dimensionality of an ndarray by one by taking
315 the integral along the 1st dimension.
316 By using xchg etc. it is possible to use any dimension.
318 $y = intover($x);
320 $spectrum = intover $image->transpose
322 Notes:
324 "intover" uses a point spacing of one (i.e., delta-h==1). You will
326 need to scale the result to correct for the true point delta).
327 For "n > 3", these are all "O(h^4)" (like Simpson's rule), but are
329 integrals between the end points assuming the pdl gives values just at
330 these centres: for such `functions', sumover is correct to O(h), but is
331 the natural (and correct) choice for binned data, of course.
332 intover ignores the bad-value flag of the input ndarrays. It will set
334 the bad-value flag of all output ndarrays if the flag is set for any of
335 the input ndarrays.
336 average
338 Signature: (a(n); int+ [o]b())
339 Project via average to N-1 dimensions
341 This function reduces the dimensionality of an ndarray by one by taking
343 the average along the 1st dimension.
344 By using xchg etc. it is possible to use any dimension.
346 $y = average($x);
348 $spectrum = average $image->transpose
350 average processes bad values. It will set the bad-value flag of all
352 output ndarrays if the flag is set for any of the input ndarrays.
353 avgover
355 Synonym for average.
356 caverage
358 Signature: (a(n); cdouble [o]b())
359 Project via average to N-1 dimensions
361 This function reduces the dimensionality of an ndarray by one by taking
363 the average along the 1st dimension.
364 By using xchg etc. it is possible to use any dimension.
366 $y = daverage($x);
368 $spectrum = daverage $image->transpose
370 Unlike average, the calculation is performed in complex double
372 precision.
373 caverage processes bad values. It will set the bad-value flag of all
375 output ndarrays if the flag is set for any of the input ndarrays.
376 daverage
378 Signature: (a(n); double [o]b())
379 Project via average to N-1 dimensions
381 This function reduces the dimensionality of an ndarray by one by taking
383 the average along the 1st dimension.
384 By using xchg etc. it is possible to use any dimension.
386 $y = daverage($x);
388 $spectrum = daverage $image->transpose
390 Unlike "average", the calculation is performed in double precision.
392 daverage processes bad values. It will set the bad-value flag of all
394 output ndarrays if the flag is set for any of the input ndarrays.
395 davgover
397 Synonym for daverage.
398 medover
400 Signature: (a(n); [o]b(); [t]tmp(n))
401 Project via median to N-1 dimensions
403 This function reduces the dimensionality of an ndarray by one by taking
405 the median along the 1st dimension.
406 By using xchg etc. it is possible to use any dimension.
408 $y = medover($x);
410 $spectrum = medover $image->transpose
412 medover processes bad values. It will set the bad-value flag of all
414 output ndarrays if the flag is set for any of the input ndarrays.
415 oddmedover
417 Signature: (a(n); [o]b(); [t]tmp(n))
418 Project via oddmedian to N-1 dimensions
420 This function reduces the dimensionality of an ndarray by one by taking
422 the oddmedian along the 1st dimension.
423 By using xchg etc. it is possible to use any dimension.
425 $y = oddmedover($x);
427 $spectrum = oddmedover $image->transpose
429 The median is sometimes not a good choice as if the array has an even
431 number of elements it lies half-way between the two middle values -
432 thus it does not always correspond to a data value. The lower-odd
433 median is just the lower of these two values and so it ALWAYS sits on
434 an actual data value which is useful in some circumstances.
435 oddmedover processes bad values. It will set the bad-value flag of all
437 output ndarrays if the flag is set for any of the input ndarrays.
438 modeover
440 Signature: (data(n); [o]out(); [t]sorted(n))
441 Project via mode to N-1 dimensions
443 This function reduces the dimensionality of an ndarray by one by taking
445 the mode along the 1st dimension.
446 By using xchg etc. it is possible to use any dimension.
448 $y = modeover($x);
450 $spectrum = modeover $image->transpose
452 The mode is the single element most frequently found in a discrete data
454 set.
455 It only makes sense for integer data types, since floating-point types
457 are demoted to integer before the mode is calculated.
458 "modeover" treats BAD the same as any other value: if BAD is the most
460 common element, the returned value is also BAD.
461 modeover does not process bad values. It will set the bad-value flag
463 of all output ndarrays if the flag is set for any of the input
464 ndarrays.
465 pctover
467 Signature: (a(n); p(); [o]b(); [t]tmp(n))
468 Project via percentile to N-1 dimensions
470 This function reduces the dimensionality of an ndarray by one by
472 finding the specified percentile (p) along the 1st dimension. The
473 specified percentile must be between 0.0 and 1.0. When the specified
474 percentile falls between data points, the result is interpolated.
475 Values outside the allowed range are clipped to 0.0 or 1.0
476 respectively. The algorithm implemented here is based on the
477 interpolation variant described at
478 <http://en.wikipedia.org/wiki/Percentile> as used by Microsoft Excel
479 and recommended by NIST.
480 By using xchg etc. it is possible to use any dimension.
482 $y = pctover($x, $p);
484 $spectrum = pctover $image->transpose, $p
486 pctover processes bad values. It will set the bad-value flag of all
488 output ndarrays if the flag is set for any of the input ndarrays.
489 oddpctover
491 Signature: (a(n); p(); [o]b(); [t]tmp(n))
492 Project via percentile to N-1 dimensions
494 This function reduces the dimensionality of an ndarray by one by
496 finding the specified percentile along the 1st dimension. The
497 specified percentile must be between 0.0 and 1.0. When the specified
498 percentile falls between two values, the nearest data value is the
499 result. The algorithm implemented is from the textbook version
500 described first at <http://en.wikipedia.org/wiki/Percentile>.
501 By using xchg etc. it is possible to use any dimension.
503 $y = oddpctover($x, $p);
505 $spectrum = oddpctover $image->transpose, $p
507 oddpctover processes bad values. It will set the bad-value flag of all
509 output ndarrays if the flag is set for any of the input ndarrays.
510 pct
512 Return the specified percentile of all elements in an ndarray. The
513 specified percentile (p) must be between 0.0 and 1.0. When the
514 specified percentile falls between data points, the result is
515 interpolated.
516 $x = pct($data, $pct);
518 oddpct
520 Return the specified percentile of all elements in an ndarray. The
521 specified percentile must be between 0.0 and 1.0. When the specified
522 percentile falls between two values, the nearest data value is the
523 result.
524 $x = oddpct($data, $pct);
526 avg
528 Return the average of all elements in an ndarray.
529 See the documentation for "average" for more information.
531 $x = avg($data);
533 This routine handles bad values.
535 sum
537 Return the sum of all elements in an ndarray.
538 See the documentation for "sumover" for more information.
540 $x = sum($data);
542 This routine handles bad values.
544 prod
546 Return the product of all elements in an ndarray.
547 See the documentation for "prodover" for more information.
549 $x = prod($data);
551 This routine handles bad values.
553 davg
555 Return the average (in double precision) of all elements in an ndarray.
556 See the documentation for "daverage" for more information.
558 $x = davg($data);
560 This routine handles bad values.
562 dsum
564 Return the sum (in double precision) of all elements in an ndarray.
565 See the documentation for "dsumover" for more information.
567 $x = dsum($data);
569 This routine handles bad values.
571 dprod
573 Return the product (in double precision) of all elements in an ndarray.
574 See the documentation for "dprodover" for more information.
576 $x = dprod($data);
578 This routine handles bad values.
580 zcheck
582 Return the check for zero of all elements in an ndarray.
583 See the documentation for "zcover" for more information.
585 $x = zcheck($data);
587 This routine handles bad values.
589 and
591 Return the logical and of all elements in an ndarray.
592 See the documentation for "andover" for more information.
594 $x = and($data);
596 This routine handles bad values.
598 band
600 Return the bitwise and of all elements in an ndarray.
601 See the documentation for "bandover" for more information.
603 $x = band($data);
605 This routine handles bad values.
607 or
609 Return the logical or of all elements in an ndarray.
610 See the documentation for "orover" for more information.
612 $x = or($data);
614 This routine handles bad values.
616 bor
618 Return the bitwise or of all elements in an ndarray.
619 See the documentation for "borover" for more information.
621 $x = bor($data);
623 This routine handles bad values.
625 min
627 Return the minimum of all elements in an ndarray.
628 See the documentation for "minimum" for more information.
630 $x = min($data);
632 This routine handles bad values.
634 max
636 Return the maximum of all elements in an ndarray.
637 See the documentation for "maximum" for more information.
639 $x = max($data);
641 This routine handles bad values.
643 median
645 Return the median of all elements in an ndarray.
646 See the documentation for "medover" for more information.
648 $x = median($data);
650 This routine handles bad values.
652 mode
654 Return the mode of all elements in an ndarray.
655 See the documentation for "modeover" for more information.
657 $x = mode($data);
659 This routine handles bad values.
661 oddmedian
663 Return the oddmedian of all elements in an ndarray.
664 See the documentation for "oddmedover" for more information.
666 $x = oddmedian($data);
668 This routine handles bad values.
670 any
672 Return true if any element in ndarray set
673 Useful in conditional expressions:
675 if (any $x>15) { print "some values are greater than 15\n" }
677 See "or" for comments on what happens when all elements in the check
679 are bad.
680 all
682 Return true if all elements in ndarray set
683 Useful in conditional expressions:
685 if (all $x>15) { print "all values are greater than 15\n" }
687 See "and" for comments on what happens when all elements in the check
689 are bad.
690 minmax
692 Returns a list with minimum and maximum values of an ndarray.
693 ($mn, $mx) = minmax($pdl);
695 This routine does not thread over the dimensions of $pdl; it returns
697 the minimum and maximum values of the whole ndarray. See "minmaximum"
698 if this is not what is required. The two values are returned as Perl
699 scalars similar to min/max, and therefore ignore whether the values are
700 bad.
701 pdl> $x = pdl [1,-2,3,5,0]
703 pdl> ($min, $max) = minmax($x);
704 pdl> p "$min $max\n";
705 -2 5
706 qsort
708 Signature: (a(n); [o]b(n))
709 Quicksort a vector into ascending order.
711 print qsort random(10);
713 Bad values are moved to the end of the array:
715 pdl> p $y
717 [42 47 98 BAD 22 96 74 41 79 76 96 BAD 32 76 25 59 BAD 96 32 BAD]
718 pdl> p qsort($y)
719 [22 25 32 32 41 42 47 59 74 76 76 79 96 96 96 98 BAD BAD BAD BAD]
720 qsorti
722 Signature: (a(n); indx [o]indx(n))
723 Quicksort a vector and return index of elements in ascending order.
725 $ix = qsorti $x;
727 print $x->index($ix); # Sorted list
728 Bad elements are moved to the end of the array:
730 pdl> p $y
732 [42 47 98 BAD 22 96 74 41 79 76 96 BAD 32 76 25 59 BAD 96 32 BAD]
733 pdl> p $y->index( qsorti($y) )
734 [22 25 32 32 41 42 47 59 74 76 76 79 96 96 96 98 BAD BAD BAD BAD]
735 qsortvec
737 Signature: (a(n,m); [o]b(n,m))
738 Sort a list of vectors lexicographically.
740 The 0th dimension of the source ndarray is dimension in the vector; the
742 1st dimension is list order. Higher dimensions are threaded over.
743 print qsortvec pdl([[1,2],[0,500],[2,3],[4,2],[3,4],[3,5]]);
745 [
746 [ 0 500]
747 [ 1 2]
748 [ 2 3]
749 [ 3 4]
750 [ 3 5]
751 [ 4 2]
752 ]
753 Vectors with bad components should be moved to the end of the array:
755 qsortveci
757 Signature: (a(n,m); indx [o]indx(m))
758 Sort a list of vectors lexicographically, returning the indices of the
760 sorted vectors rather than the sorted list itself.
761 As with "qsortvec", the input PDL should be an NxM array containing M
763 separate N-dimensional vectors. The return value is an integer M-PDL
764 containing the M-indices of original array rows, in sorted order.
765 As with "qsortvec", the zeroth element of the vectors runs slowest in
767 the sorted list.
768 Additional dimensions are threaded over: each plane is sorted
770 separately, so qsortveci may be thought of as a collapse operator of
771 sorts (groan).
772 Vectors with bad components should be moved to the end of the array:
774 minimum
776 Signature: (a(n); [o]c())
777 Project via minimum to N-1 dimensions
779 This function reduces the dimensionality of an ndarray by one by taking
781 the minimum along the 1st dimension.
782 By using xchg etc. it is possible to use any dimension.
784 $y = minimum($x);
786 $spectrum = minimum $image->transpose
788 Output is set bad if all elements of the input are bad, otherwise the
790 bad flag is cleared for the output ndarray.
791 Note that "NaNs" are considered to be valid values; see isfinite and
793 badmask for ways of masking NaNs.
794 minimum_ind
796 Signature: (a(n); indx [o] c())
797 Like minimum but returns the index rather than the value
799 Output is set bad if all elements of the input are bad, otherwise the
801 bad flag is cleared for the output ndarray.
802 minimum_n_ind
804 Signature: (a(n); indx [o]c(m))
805 Returns the index of "m" minimum elements
807 Not yet been converted to ignore bad values
809 maximum
811 Signature: (a(n); [o]c())
812 Project via maximum to N-1 dimensions
814 This function reduces the dimensionality of an ndarray by one by taking
816 the maximum along the 1st dimension.
817 By using xchg etc. it is possible to use any dimension.
819 $y = maximum($x);
821 $spectrum = maximum $image->transpose
823 Output is set bad if all elements of the input are bad, otherwise the
825 bad flag is cleared for the output ndarray.
826 Note that "NaNs" are considered to be valid values; see isfinite and
828 badmask for ways of masking NaNs.
829 maximum_ind
831 Signature: (a(n); indx [o] c())
832 Like maximum but returns the index rather than the value
834 Output is set bad if all elements of the input are bad, otherwise the
836 bad flag is cleared for the output ndarray.
837 maximum_n_ind
839 Signature: (a(n); indx [o]c(m))
840 Returns the index of "m" maximum elements
842 Not yet been converted to ignore bad values
844 maxover
846 Synonym for maximum.
847 maxover_ind
849 Synonym for maximum_ind.
850 maxover_n_ind
852 Synonym for maximum_n_ind.
853 minover
855 Synonym for minimum.
856 minover_ind
858 Synonym for minimum_ind.
859 minover_n_ind
861 Synonym for minimum_n_ind
862 minmaximum
864 Signature: (a(n); [o]cmin(); [o] cmax(); indx [o]cmin_ind(); indx [o]cmax_ind())
865 Find minimum and maximum and their indices for a given ndarray;
867 pdl> $x=pdl [[-2,3,4],[1,0,3]]
869 pdl> ($min, $max, $min_ind, $max_ind)=minmaximum($x)
870 pdl> p $min, $max, $min_ind, $max_ind
871 [-2 0] [4 3] [0 1] [2 2]
872 See also "minmax", which clumps the ndarray together.
874 If "a()" contains only bad data, then the output ndarrays will be set
876 bad, along with their bad flag. Otherwise they will have their bad
877 flags cleared, since they will not contain any bad values.
878 minmaxover
880 Synonym for minmaximum.
881
883 Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu).
884 Contributions by Christian Soeller (c.soeller@auckland.ac.nz) and Karl
885 Glazebrook (kgb@aaoepp.aao.gov.au). All rights reserved. There is no
886 warranty. You are allowed to redistribute this software / documentation
887 under certain conditions. For details, see the file COPYING in the PDL
888 distribution. If this file is separated from the PDL distribution, the
889 copyright notice should be included in the file.
890perl v5.34.0 2021-08-16 Ufunc(3)