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 $a = prodover($b);
34 $spectrum = prodover $image->xchg(0,1)
36 prodover does handle 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 $a = dprodover($b);
51 $spectrum = dprodover $image->xchg(0,1)
53 Unlike prodover, the calculations are performed in double precision.
55 dprodover does handle bad values. It will set the bad-value flag of
57 all 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 $a = cumuprodover($b);
73 $spectrum = cumuprodover $image->xchg(0,1)
75 cumuprodover does handle 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 $a = cumuprodover($b);
93 $spectrum = cumuprodover $image->xchg(0,1)
95 Unlike cumuprodover, the calculations are performed in double
97 precision.
98 dcumuprodover does handle bad values. It will set the bad-value flag
100 of 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 $a = sumover($b);
113 $spectrum = sumover $image->xchg(0,1)
115 sumover does handle 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 $a = dsumover($b);
130 $spectrum = dsumover $image->xchg(0,1)
132 Unlike sumover, the calculations are performed in double precision.
134 dsumover does handle 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 $a = cumusumover($b);
151 $spectrum = cumusumover $image->xchg(0,1)
153 cumusumover does handle 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 $a = cumusumover($b);
170 $spectrum = cumusumover $image->xchg(0,1)
172 Unlike cumusumover, the calculations are performed in double precision.
174 dcumusumover does handle 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 orover
179 Signature: (a(n); int+ [o]b())
180 Project via or to N-1 dimensions
182 This function reduces the dimensionality of a piddle by one by taking
184 the or along the 1st dimension.
185 By using xchg etc. it is possible to use any dimension.
187 $a = orover($b);
189 $spectrum = orover $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); int+ [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 $a = bandover($b);
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); int+ [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 $a = borover($b);
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 zcover
233 Signature: (a(n); int+ [o]b())
234 Project via == 0 to N-1 dimensions
236 This function reduces the dimensionality of a piddle by one by taking
238 the == 0 along the 1st dimension.
239 By using xchg etc. it is possible to use any dimension.
241 $a = zcover($b);
243 $spectrum = zcover $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 andover
251 Signature: (a(n); int+ [o]b())
252 Project via and to N-1 dimensions
254 This function reduces the dimensionality of a piddle by one by taking
256 the and along the 1st dimension.
257 By using xchg etc. it is possible to use any dimension.
259 $a = andover($b);
261 $spectrum = andover $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); int+ [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 $a = intover($b);
279 $spectrum = intover $image->xchg(0,1)
281 Notes:
283 For "n > 3", these are all "O(h^4)" (like Simpson's rule), but are
285 integrals between the end points assuming the pdl gives values just at
286 these centres: for such `functions', sumover is correct to O(h), but is
287 the natural (and correct) choice for binned data, of course.
288 intover ignores the bad-value flag of the input piddles. It will set
290 the bad-value flag of all output piddles if the flag is set for any of
291 the input piddles.
292 average
294 Signature: (a(n); int+ [o]b())
295 Project via average to N-1 dimensions
297 This function reduces the dimensionality of a piddle by one by taking
299 the average along the 1st dimension.
300 By using xchg etc. it is possible to use any dimension.
302 $a = average($b);
304 $spectrum = average $image->xchg(0,1)
306 average does handle bad values. It will set the bad-value flag of all
308 output piddles if the flag is set for any of the input piddles.
309 daverage
311 Signature: (a(n); double [o]b())
312 Project via average to N-1 dimensions
314 This function reduces the dimensionality of a piddle by one by taking
316 the average along the 1st dimension.
317 By using xchg etc. it is possible to use any dimension.
319 $a = daverage($b);
321 $spectrum = daverage $image->xchg(0,1)
323 Unlike average, the calculation is performed in double precision.
325 daverage does handle bad values. It will set the bad-value flag of all
327 output piddles if the flag is set for any of the input piddles.
328 medover
330 Signature: (a(n); [o]b(); [t]tmp(n))
331 Project via median to N-1 dimensions
333 This function reduces the dimensionality of a piddle by one by taking
335 the median along the 1st dimension.
336 By using xchg etc. it is possible to use any dimension.
338 $a = medover($b);
340 $spectrum = medover $image->xchg(0,1)
342 medover does handle bad values. It will set the bad-value flag of all
344 output piddles if the flag is set for any of the input piddles.
345 oddmedover
347 Signature: (a(n); [o]b(); [t]tmp(n))
348 Project via oddmedian to N-1 dimensions
350 This function reduces the dimensionality of a piddle by one by taking
352 the oddmedian along the 1st dimension.
353 By using xchg etc. it is possible to use any dimension.
355 $a = oddmedover($b);
357 $spectrum = oddmedover $image->xchg(0,1)
359 The median is sometimes not a good choice as if the array has an even
361 number of elements it lies half-way between the two middle values -
362 thus it does not always correspond to a data value. The lower-odd
363 median is just the lower of these two values and so it ALWAYS sits on
364 an actual data value which is useful in some circumstances.
365 oddmedover does handle bad values. It will set the bad-value flag of
367 all output piddles if the flag is set for any of the input piddles.
368 pctover
370 Signature: (a(n); p(); [o]b(); [t]tmp(n))
371 Project via percentile to N-1 dimensions
373 This function reduces the dimensionality of a piddle by one by finding
375 the specified percentile (p) along the 1st dimension. The specified
376 percentile must be between 0.0 and 1.0. When the specified percentile
377 falls between data points, the result is interpolated. Values outside
378 the allowed range are clipped to 0.0 or 1.0 respectively. The
379 algorithm implemented here is based on the interpolation variant
380 described at "/en.wikipedia.org/wiki/Percentile" in http: as used by
381 Microsoft Excel and recommended by NIST.
382 By using xchg etc. it is possible to use any dimension.
384 $a = pctover($b, $p);
386 $spectrum = pctover $image->xchg(0,1) $p
388 pctover does not process bad values. It will set the bad-value flag of
390 all output piddles if the flag is set for any of the input piddles.
391 oddpctover
393 Signature: (a(n); p(); [o]b(); [t]tmp(n))
394 Project via percentile to N-1 dimensions
396 This function reduces the dimensionality of a piddle by one by finding
398 the specified percentile along the 1st dimension. The specified
399 percentile must be between 0.0 and 1.0. When the specified percentile
400 falls between two values, the nearest data value is the result. The
401 algorithm implemented is from the textbook version described first at
402 "/en.wikipedia.org/wiki/Percentile" in http:.
403 By using xchg etc. it is possible to use any dimension.
405 $a = oddpctover($b, $p);
407 $spectrum = oddpctover $image->xchg(0,1) $p
409 oddpctover does not process bad values. It will set the bad-value flag
411 of all output piddles if the flag is set for any of the input piddles.
412 pct
414 Return the specified percentile of all elements in a piddle. The
415 specified percentile (p) must be between 0.0 and 1.0. When the
416 specified percentile falls between data points, the result is
417 interpolated.
418 $x = pct($data, $pct);
420 oddpct
422 Return the specified percentile of all elements in a piddle. The
423 specified percentile must be between 0.0 and 1.0. When the specified
424 percentile falls between two values, the nearest data value is the
425 result.
426 $x = oddpct($data, $pct);
428 avg
430 Return the average of all elements in a piddle
431 $x = avg($data);
433 This routine handles bad values (see the documentation for average). I
435 still need to decide how to handle the case when the return value is a
436 bad value (eg to make sure it has the same type as the input piddle OR
437 perhaps we should die - makes sense for the conditional ops but not
438 things like sum)
439 sum
441 Return the sum of all elements in a piddle
442 $x = sum($data);
444 This routine handles bad values (see the documentation for sumover). I
446 still need to decide how to handle the case when the return value is a
447 bad value (eg to make sure it has the same type as the input piddle OR
448 perhaps we should die - makes sense for the conditional ops but not
449 things like sum)
450 prod
452 Return the product of all elements in a piddle
453 $x = prod($data);
455 This routine handles bad values (see the documentation for prodover).
457 I still need to decide how to handle the case when the return value is
458 a bad value (eg to make sure it has the same type as the input piddle
459 OR perhaps we should die - makes sense for the conditional ops but not
460 things like sum)
461 davg
463 Return the average (in double precision) of all elements in a piddle
464 $x = davg($data);
466 This routine handles bad values (see the documentation for daverage).
468 I still need to decide how to handle the case when the return value is
469 a bad value (eg to make sure it has the same type as the input piddle
470 OR perhaps we should die - makes sense for the conditional ops but not
471 things like sum)
472 dsum
474 Return the sum (in double precision) of all elements in a piddle
475 $x = dsum($data);
477 This routine handles bad values (see the documentation for dsumover).
479 I still need to decide how to handle the case when the return value is
480 a bad value (eg to make sure it has the same type as the input piddle
481 OR perhaps we should die - makes sense for the conditional ops but not
482 things like sum)
483 dprod
485 Return the product (in double precision) of all elements in a piddle
486 $x = dprod($data);
488 This routine handles bad values (see the documentation for dprodover).
490 I still need to decide how to handle the case when the return value is
491 a bad value (eg to make sure it has the same type as the input piddle
492 OR perhaps we should die - makes sense for the conditional ops but not
493 things like sum)
494 zcheck
496 Return the check for zero of all elements in a piddle
497 $x = zcheck($data);
499 This routine handles bad values (see the documentation for zcover). I
501 still need to decide how to handle the case when the return value is a
502 bad value (eg to make sure it has the same type as the input piddle OR
503 perhaps we should die - makes sense for the conditional ops but not
504 things like sum)
505 and
507 Return the logical and of all elements in a piddle
508 $x = and($data);
510 This routine handles bad values (see the documentation for andover). I
512 still need to decide how to handle the case when the return value is a
513 bad value (eg to make sure it has the same type as the input piddle OR
514 perhaps we should die - makes sense for the conditional ops but not
515 things like sum)
516 band
518 Return the bitwise and of all elements in a piddle
519 $x = band($data);
521 This routine handles bad values (see the documentation for bandover).
523 I still need to decide how to handle the case when the return value is
524 a bad value (eg to make sure it has the same type as the input piddle
525 OR perhaps we should die - makes sense for the conditional ops but not
526 things like sum)
527 or
529 Return the logical or of all elements in a piddle
530 $x = or($data);
532 This routine handles bad values (see the documentation for orover). I
534 still need to decide how to handle the case when the return value is a
535 bad value (eg to make sure it has the same type as the input piddle OR
536 perhaps we should die - makes sense for the conditional ops but not
537 things like sum)
538 bor
540 Return the bitwise or of all elements in a piddle
541 $x = bor($data);
543 This routine handles bad values (see the documentation for borover). I
545 still need to decide how to handle the case when the return value is a
546 bad value (eg to make sure it has the same type as the input piddle OR
547 perhaps we should die - makes sense for the conditional ops but not
548 things like sum)
549 min
551 Return the minimum of all elements in a piddle
552 $x = min($data);
554 This routine handles bad values (see the documentation for minimum). I
556 still need to decide how to handle the case when the return value is a
557 bad value (eg to make sure it has the same type as the input piddle OR
558 perhaps we should die - makes sense for the conditional ops but not
559 things like sum)
560 max
562 Return the maximum of all elements in a piddle
563 $x = max($data);
565 This routine handles bad values (see the documentation for maximum). I
567 still need to decide how to handle the case when the return value is a
568 bad value (eg to make sure it has the same type as the input piddle OR
569 perhaps we should die - makes sense for the conditional ops but not
570 things like sum)
571 median
573 Return the median of all elements in a piddle
574 $x = median($data);
576 This routine handles bad values (see the documentation for medover). I
578 still need to decide how to handle the case when the return value is a
579 bad value (eg to make sure it has the same type as the input piddle OR
580 perhaps we should die - makes sense for the conditional ops but not
581 things like sum)
582 oddmedian
584 Return the oddmedian of all elements in a piddle
585 $x = oddmedian($data);
587 This routine handles bad values (see the documentation for oddmedover).
589 I still need to decide how to handle the case when the return value is
590 a bad value (eg to make sure it has the same type as the input piddle
591 OR perhaps we should die - makes sense for the conditional ops but not
592 things like sum)
593 any
595 Return true if any element in piddle set
596 Useful in conditional expressions:
598 if (any $a>15) { print "some values are greater than 15\n" }
600 See or for comments on what happens when all elements in the check are
602 bad.
603 all
605 Return true if all elements in piddle set
606 Useful in conditional expressions:
608 if (all $a>15) { print "all values are greater than 15\n" }
610 See and for comments on what happens when all elements in the check are
612 bad.
613 minmax
615 Returns an array with minimum and maximum values of a piddle.
616 ($mn, $mx) = minmax($pdl);
618 This routine does not thread over the dimensions of $pdl; it returns
620 the minimum and maximum values of the whole array. See minmaximum if
621 this is not what is required. The two values are returned as Perl
622 scalars similar to min/max.
623 perldl> $x = pdl [1,-2,3,5,0]
625 perldl> ($min, $max) = minmax($x);
626 perldl> p "$min $max\n";
627 -2 5
628 qsort
630 Signature: (a(n); [o]b(n))
631 Quicksort a vector into ascending order.
633 print qsort random(10);
635 Bad values are moved to the end of the array:
637 perldl> p $b
639 [42 47 98 BAD 22 96 74 41 79 76 96 BAD 32 76 25 59 BAD 96 32 BAD]
640 perldl> p qsort($b)
641 [22 25 32 32 41 42 47 59 74 76 76 79 96 96 96 98 BAD BAD BAD BAD]
642 qsorti
644 Signature: (a(n); int [o]indx(n))
645 Quicksort a vector and return index of elements in ascending order.
647 $ix = qsorti $a;
649 print $a->index($ix); # Sorted list
650 Bad elements are moved to the end of the array:
652 perldl> p $b
654 [42 47 98 BAD 22 96 74 41 79 76 96 BAD 32 76 25 59 BAD 96 32 BAD]
655 perldl> p $b->index( qsorti($b) )
656 [22 25 32 32 41 42 47 59 74 76 76 79 96 96 96 98 BAD BAD BAD BAD]
657 qsortvec
659 Signature: (a(n,m); [o]b(n,m))
660 Sort a list of vectors lexicographically.
662 The 0th dimension of the source piddle is dimension in the vector; the
664 1st dimension is list order. Higher dimensions are threaded over.
665 print qsortvec pdl([[1,2],[0,500],[2,3],[4,2],[3,4],[3,5]]);
667 [
668 [ 0 500]
669 [ 1 2]
670 [ 2 3]
671 [ 3 4]
672 [ 3 5]
673 [ 4 2]
674 ]
675 Vectors with bad components should be moved to the end of the array:
677 qsortveci
679 Signature: (a(n,m); int [o]indx(m))
680 Sort a list of vectors lexicographically, returning the indices of the
682 sorted vectors rather than the sorted list itself.
683 As with "qsortvec", the input PDL should be an NxM array containing M
685 separate N-dimensional vectors. The return value is an integer M-PDL
686 containing the M-indices of original array rows, in sorted order.
687 As with "qsortvec", the zeroth element of the vectors runs slowest in
689 the sorted list.
690 Additional dimensions are threaded over: each plane is sorted
692 separately, so qsortveci may be thought of as a collapse operator of
693 sorts (groan).
694 Vectors with bad components should be moved to the end of the array:
696 minimum
698 Signature: (a(n); [o]c())
699 Project via minimum to N-1 dimensions
701 This function reduces the dimensionality of a piddle by one by taking
703 the minimum along the 1st dimension.
704 By using xchg etc. it is possible to use any dimension.
706 $a = minimum($b);
708 $spectrum = minimum $image->xchg(0,1)
710 Output is set bad if all elements of the input are bad, otherwise the
712 bad flag is cleared for the output piddle.
713 Note that "NaNs" are considered to be valid values; see isfinite and
715 badmask for ways of masking NaNs.
716 minimum_ind
718 Signature: (a(n); int [o] c())
719 Like minimum but returns the index rather than the value
721 Output is set bad if all elements of the input are bad, otherwise the
723 bad flag is cleared for the output piddle.
724 minimum_n_ind
726 Signature: (a(n); int[o]c(m))
727 Returns the index of "m" minimum elements
729 Not yet been converted to ignore bad values
731 maximum
733 Signature: (a(n); [o]c())
734 Project via maximum to N-1 dimensions
736 This function reduces the dimensionality of a piddle by one by taking
738 the maximum along the 1st dimension.
739 By using xchg etc. it is possible to use any dimension.
741 $a = maximum($b);
743 $spectrum = maximum $image->xchg(0,1)
745 Output is set bad if all elements of the input are bad, otherwise the
747 bad flag is cleared for the output piddle.
748 Note that "NaNs" are considered to be valid values; see isfinite and
750 badmask for ways of masking NaNs.
751 maximum_ind
753 Signature: (a(n); int [o] c())
754 Like maximum but returns the index rather than the value
756 Output is set bad if all elements of the input are bad, otherwise the
758 bad flag is cleared for the output piddle.
759 maximum_n_ind
761 Signature: (a(n); int[o]c(m))
762 Returns the index of "m" maximum elements
764 Not yet been converted to ignore bad values
766 minmaximum
768 Signature: (a(n); [o]cmin(); [o] cmax(); int [o]cmin_ind(); int [o]cmax_ind())
769 Find minimum and maximum and their indices for a given piddle;
771 perldl> $a=pdl [[-2,3,4],[1,0,3]]
773 perldl> ($min, $max, $min_ind, $max_ind)=minmaximum($a)
774 perldl> p $min, $max, $min_ind, $max_ind
775 [-2 0] [4 3] [0 1] [2 2]
776 See also minmax, which clumps the piddle together.
778 If "a()" contains only bad data, then the output piddles will be set
780 bad, along with their bad flag. Otherwise they will have their bad
781 flags cleared, since they will not contain any bad values.
782
784 Copyright (C) Tuomas J. Lukka 1997 (lukka@husc.harvard.edu).
785 Contributions by Christian Soeller (c.soeller@auckland.ac.nz) and Karl
786 Glazebrook (kgb@aaoepp.aao.gov.au). All rights reserved. There is no
787 warranty. You are allowed to redistribute this software / documentation
788 under certain conditions. For details, see the file COPYING in the PDL
789 distribution. If this file is separated from the PDL distribution, the
790 copyright notice should be included in the file.
791perl v5.12.3 2011-03-31 Ufunc(3)