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 = cprodover($x);
51 $spectrum = cprodover $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 = dcumuprodover($x);
113 $spectrum = dcumuprodover $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 = csumover($x);
150 $spectrum = csumover $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 = dcumusumover($x);
210 $spectrum = dcumusumover $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 = caverage($x);
368 $spectrum = caverage $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 cavgover
378 Synonym for caverage.
379 daverage
381 Signature: (a(n); double [o]b())
382 Project via average to N-1 dimensions
384 This function reduces the dimensionality of an ndarray by one by taking
386 the average along the 1st dimension.
387 By using xchg etc. it is possible to use any dimension.
389 $y = daverage($x);
391 $spectrum = daverage $image->transpose
393 Unlike average, the calculation is performed in double precision.
395 daverage processes bad values. It will set the bad-value flag of all
397 output ndarrays if the flag is set for any of the input ndarrays.
398 davgover
400 Synonym for daverage.
401 minimum
403 Signature: (a(n); [o]c())
404 Project via minimum to N-1 dimensions
406 This function reduces the dimensionality of an ndarray by one by taking
408 the minimum along the 1st dimension.
409 By using xchg etc. it is possible to use any dimension.
411 $y = minimum($x);
413 $spectrum = minimum $image->transpose
415 Output is set bad if all elements of the input are bad, otherwise the
417 bad flag is cleared for the output ndarray.
418 Note that "NaNs" are considered to be valid values; see isfinite and
420 badmask for ways of masking NaNs.
421 minover
423 Synonym for minimum.
424 minimum_ind
426 Signature: (a(n); indx [o] c())
427 Like minimum but returns the index rather than the value
429 Output is set bad if all elements of the input are bad, otherwise the
431 bad flag is cleared for the output ndarray.
432 minover_ind
434 Synonym for minimum_ind.
435 minimum_n_ind
437 Signature: (a(n); indx [o]c(m))
438 Returns the index of "m" minimum elements
440 Not yet been converted to ignore bad values
442 minover_n_ind
444 Synonym for minimum_n_ind.
445 maximum
447 Signature: (a(n); [o]c())
448 Project via maximum to N-1 dimensions
450 This function reduces the dimensionality of an ndarray by one by taking
452 the maximum along the 1st dimension.
453 By using xchg etc. it is possible to use any dimension.
455 $y = maximum($x);
457 $spectrum = maximum $image->transpose
459 Output is set bad if all elements of the input are bad, otherwise the
461 bad flag is cleared for the output ndarray.
462 Note that "NaNs" are considered to be valid values; see isfinite and
464 badmask for ways of masking NaNs.
465 maxover
467 Synonym for maximum.
468 maximum_ind
470 Signature: (a(n); indx [o] c())
471 Like maximum but returns the index rather than the value
473 Output is set bad if all elements of the input are bad, otherwise the
475 bad flag is cleared for the output ndarray.
476 maxover_ind
478 Synonym for maximum_ind.
479 maximum_n_ind
481 Signature: (a(n); indx [o]c(m))
482 Returns the index of "m" maximum elements
484 Not yet been converted to ignore bad values
486 maxover_n_ind
488 Synonym for maximum_n_ind.
489 minmaximum
491 Signature: (a(n); [o]cmin(); [o] cmax(); indx [o]cmin_ind(); indx [o]cmax_ind())
492 Find minimum and maximum and their indices for a given ndarray;
494 pdl> $x=pdl [[-2,3,4],[1,0,3]]
496 pdl> ($min, $max, $min_ind, $max_ind)=minmaximum($x)
497 pdl> p $min, $max, $min_ind, $max_ind
498 [-2 0] [4 3] [0 1] [2 2]
499 See also "minmax", which clumps the ndarray together.
501 If "a()" contains only bad data, then the output ndarrays will be set
503 bad, along with their bad flag. Otherwise they will have their bad
504 flags cleared, since they will not contain any bad values.
505 minmaxover
507 Synonym for minmaximum.
508 avg
510 Return the average of all elements in an ndarray.
511 See the documentation for "average" for more information.
513 $x = avg($data);
515 This routine handles bad values.
517 sum
519 Return the sum of all elements in an ndarray.
520 See the documentation for "sumover" for more information.
522 $x = sum($data);
524 This routine handles bad values.
526 prod
528 Return the product of all elements in an ndarray.
529 See the documentation for "prodover" for more information.
531 $x = prod($data);
533 This routine handles bad values.
535 davg
537 Return the average (in double precision) of all elements in an ndarray.
538 See the documentation for "daverage" for more information.
540 $x = davg($data);
542 This routine handles bad values.
544 dsum
546 Return the sum (in double precision) of all elements in an ndarray.
547 See the documentation for "dsumover" for more information.
549 $x = dsum($data);
551 This routine handles bad values.
553 dprod
555 Return the product (in double precision) of all elements in an ndarray.
556 See the documentation for "dprodover" for more information.
558 $x = dprod($data);
560 This routine handles bad values.
562 zcheck
564 Return the check for zero of all elements in an ndarray.
565 See the documentation for "zcover" for more information.
567 $x = zcheck($data);
569 This routine handles bad values.
571 and
573 Return the logical and of all elements in an ndarray.
574 See the documentation for "andover" for more information.
576 $x = and($data);
578 This routine handles bad values.
580 band
582 Return the bitwise and of all elements in an ndarray.
583 See the documentation for "bandover" for more information.
585 $x = band($data);
587 This routine handles bad values.
589 or
591 Return the logical or of all elements in an ndarray.
592 See the documentation for "orover" for more information.
594 $x = or($data);
596 This routine handles bad values.
598 bor
600 Return the bitwise or of all elements in an ndarray.
601 See the documentation for "borover" for more information.
603 $x = bor($data);
605 This routine handles bad values.
607 min
609 Return the minimum of all elements in an ndarray.
610 See the documentation for "minimum" for more information.
612 $x = min($data);
614 This routine handles bad values.
616 max
618 Return the maximum of all elements in an ndarray.
619 See the documentation for "maximum" for more information.
621 $x = max($data);
623 This routine handles bad values.
625 median
627 Return the median of all elements in an ndarray.
628 See the documentation for "medover" for more information.
630 $x = median($data);
632 This routine handles bad values.
634 mode
636 Return the mode of all elements in an ndarray.
637 See the documentation for "modeover" for more information.
639 $x = mode($data);
641 This routine handles bad values.
643 oddmedian
645 Return the oddmedian of all elements in an ndarray.
646 See the documentation for "oddmedover" for more information.
648 $x = oddmedian($data);
650 This routine handles bad values.
652 any
654 Return true if any element in ndarray set
655 Useful in conditional expressions:
657 if (any $x>15) { print "some values are greater than 15\n" }
659 See "or" for comments on what happens when all elements in the check
661 are bad.
662 all
664 Return true if all elements in ndarray set
665 Useful in conditional expressions:
667 if (all $x>15) { print "all values are greater than 15\n" }
669 See "and" for comments on what happens when all elements in the check
671 are bad.
672 minmax
674 Returns a list with minimum and maximum values of an ndarray.
675 ($mn, $mx) = minmax($pdl);
677 This routine does not broadcast over the dimensions of $pdl; it returns
679 the minimum and maximum values of the whole ndarray. See "minmaximum"
680 if this is not what is required. The two values are returned as Perl
681 scalars similar to min/max, and therefore ignore whether the values are
682 bad.
683 pdl> $x = pdl [1,-2,3,5,0]
685 pdl> ($min, $max) = minmax($x);
686 pdl> p "$min $max\n";
687 -2 5
688 medover
690 Signature: (a(n); [o]b(); [t]tmp(n))
691 Project via median to N-1 dimensions
693 This function reduces the dimensionality of an ndarray by one by taking
695 the median along the 1st dimension.
696 By using xchg etc. it is possible to use any dimension.
698 $y = medover($x);
700 $spectrum = medover $image->transpose
702 medover processes bad values. It will set the bad-value flag of all
704 output ndarrays if the flag is set for any of the input ndarrays.
705 oddmedover
707 Signature: (a(n); [o]b(); [t]tmp(n))
708 Project via oddmedian to N-1 dimensions
710 This function reduces the dimensionality of an ndarray by one by taking
712 the oddmedian along the 1st dimension.
713 By using xchg etc. it is possible to use any dimension.
715 $y = oddmedover($x);
717 $spectrum = oddmedover $image->transpose
719 The median is sometimes not a good choice as if the array has an even
721 number of elements it lies half-way between the two middle values -
722 thus it does not always correspond to a data value. The lower-odd
723 median is just the lower of these two values and so it ALWAYS sits on
724 an actual data value which is useful in some circumstances.
725 oddmedover processes bad values. It will set the bad-value flag of all
727 output ndarrays if the flag is set for any of the input ndarrays.
728 modeover
730 Signature: (data(n); [o]out(); [t]sorted(n))
731 Project via mode to N-1 dimensions
733 This function reduces the dimensionality of an ndarray by one by taking
735 the mode along the 1st dimension.
736 By using xchg etc. it is possible to use any dimension.
738 $y = modeover($x);
740 $spectrum = modeover $image->transpose
742 The mode is the single element most frequently found in a discrete data
744 set.
745 It only makes sense for integer data types, since floating-point types
747 are demoted to integer before the mode is calculated.
748 "modeover" treats BAD the same as any other value: if BAD is the most
750 common element, the returned value is also BAD.
751 modeover does not process bad values. It will set the bad-value flag
753 of all output ndarrays if the flag is set for any of the input
754 ndarrays.
755 pctover
757 Signature: (a(n); p(); [o]b(); [t]tmp(n))
758 Project via specified percentile to N-1 dimensions
760 This function reduces the dimensionality of an ndarray by one by taking
762 the specified percentile along the 1st dimension.
763 By using xchg etc. it is possible to use any dimension.
765 $y = pctover($x);
767 $spectrum = pctover $image->transpose
769 The specified percentile must be between 0.0 and 1.0. When the
771 specified percentile falls between data points, the result is
772 interpolated. Values outside the allowed range are clipped to 0.0 or
773 1.0 respectively. The algorithm implemented here is based on the
774 interpolation variant described at
775 <http://en.wikipedia.org/wiki/Percentile> as used by Microsoft Excel
776 and recommended by NIST.
777 pctover processes bad values. It will set the bad-value flag of all
779 output ndarrays if the flag is set for any of the input ndarrays.
780 oddpctover
782 Signature: (a(n); p(); [o]b(); [t]tmp(n))
783 Project via specified percentile to N-1 dimensions
785 This function reduces the dimensionality of an ndarray by one by taking
787 the specified percentile along the 1st dimension.
788 By using xchg etc. it is possible to use any dimension.
790 $y = oddpctover($x);
792 $spectrum = oddpctover $image->transpose
794 The specified percentile must be between 0.0 and 1.0. When the
796 specified percentile falls between two values, the nearest data value
797 is the result. The algorithm implemented is from the textbook version
798 described first at <http://en.wikipedia.org/wiki/Percentile>.
799 oddpctover processes bad values. It will set the bad-value flag of all
801 output ndarrays if the flag is set for any of the input ndarrays.
802 pct
804 Return the specified percentile of all elements in an ndarray. The
805 specified percentile (p) must be between 0.0 and 1.0. When the
806 specified percentile falls between data points, the result is
807 interpolated.
808 $x = pct($data, $pct);
810 oddpct
812 Return the specified percentile of all elements in an ndarray. The
813 specified percentile must be between 0.0 and 1.0. When the specified
814 percentile falls between two values, the nearest data value is the
815 result.
816 $x = oddpct($data, $pct);
818 qsort
820 Signature: (a(n); [o]b(n))
821 Quicksort a vector into ascending order.
823 print qsort random(10);
825 Bad values are moved to the end of the array:
827 pdl> p $y
829 [42 47 98 BAD 22 96 74 41 79 76 96 BAD 32 76 25 59 BAD 96 32 BAD]
830 pdl> p qsort($y)
831 [22 25 32 32 41 42 47 59 74 76 76 79 96 96 96 98 BAD BAD BAD BAD]
832 qsorti
834 Signature: (a(n); indx [o]indx(n))
835 Quicksort a vector and return index of elements in ascending order.
837 $ix = qsorti $x;
839 print $x->index($ix); # Sorted list
840 Bad elements are moved to the end of the array:
842 pdl> p $y
844 [42 47 98 BAD 22 96 74 41 79 76 96 BAD 32 76 25 59 BAD 96 32 BAD]
845 pdl> p $y->index( qsorti($y) )
846 [22 25 32 32 41 42 47 59 74 76 76 79 96 96 96 98 BAD BAD BAD BAD]
847 qsortvec
849 Signature: (a(n,m); [o]b(n,m))
850 Sort a list of vectors lexicographically.
852 The 0th dimension of the source ndarray is dimension in the vector; the
854 1st dimension is list order. Higher dimensions are broadcasted over.
855 print qsortvec pdl([[1,2],[0,500],[2,3],[4,2],[3,4],[3,5]]);
857 [
858 [ 0 500]
859 [ 1 2]
860 [ 2 3]
861 [ 3 4]
862 [ 3 5]
863 [ 4 2]
864 ]
865 Vectors with bad components are moved to the end of the array:
867 pdl> p $p = pdl("[0 0] [-100 0] [BAD 0] [100 0]")->qsortvec
869 [
871 [-100 0]
872 [ 0 0]
873 [ 100 0]
874 [ BAD 0]
875 ]
876 qsortveci
878 Signature: (a(n,m); indx [o]indx(m))
879 Sort a list of vectors lexicographically, returning the indices of the
881 sorted vectors rather than the sorted list itself.
882 As with "qsortvec", the input PDL should be an NxM array containing M
884 separate N-dimensional vectors. The return value is an integer M-PDL
885 containing the M-indices of original array rows, in sorted order.
886 As with "qsortvec", the zeroth element of the vectors runs slowest in
888 the sorted list.
889 Additional dimensions are broadcasted over: each plane is sorted
891 separately, so qsortveci may be thought of as a collapse operator of
892 sorts (groan).
893 Vectors with bad components are moved to the end of the array as for
895 "qsortvec".
896
898 Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu).
899 Contributions by Christian Soeller (c.soeller@auckland.ac.nz) and Karl
900 Glazebrook (kgb@aaoepp.aao.gov.au). All rights reserved. There is no
901 warranty. You are allowed to redistribute this software / documentation
902 under certain conditions. For details, see the file COPYING in the PDL
903 distribution. If this file is separated from the PDL distribution, the
904 copyright notice should be included in the file.
905perl v5.34.0 2022-02-28 Ufunc(3)