1Ufunc(3)              User Contributed Perl Documentation             Ufunc(3)
2
3
4

NAME

6       PDL::Ufunc - primitive ufunc operations for pdl
7

DESCRIPTION

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
16       The PDL::Reduce module provides an alternative interface to many of the
17       functions in this module.
18

SYNOPSIS

20        use PDL::Ufunc;
21

FUNCTIONS

23   prodover
24         Signature: (a(n); int+ [o]b())
25
26       Project via product to N-1 dimensions
27
28       This function reduces the dimensionality of a piddle by one by taking
29       the product along the 1st dimension.
30
31       By using xchg etc. it is possible to use any dimension.
32
33        $y = prodover($x);
34
35        $spectrum = prodover $image->xchg(0,1)
36
37       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
40   dprodover
41         Signature: (a(n); double [o]b())
42
43       Project via product to N-1 dimensions
44
45       This function reduces the dimensionality of a piddle by one by taking
46       the product along the 1st dimension.
47
48       By using xchg etc. it is possible to use any dimension.
49
50        $y = dprodover($x);
51
52        $spectrum = dprodover $image->xchg(0,1)
53
54       Unlike prodover, the calculations are performed in double precision.
55
56       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
59   cumuprodover
60         Signature: (a(n); int+ [o]b(n))
61
62       Cumulative product
63
64       This function calculates the cumulative product along the 1st
65       dimension.
66
67       By using xchg etc. it is possible to use any dimension.
68
69       The sum is started so that the first element in the cumulative product
70       is the first element of the parameter.
71
72        $y = cumuprodover($x);
73
74        $spectrum = cumuprodover $image->xchg(0,1)
75
76       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
79   dcumuprodover
80         Signature: (a(n); double [o]b(n))
81
82       Cumulative product
83
84       This function calculates the cumulative product along the 1st
85       dimension.
86
87       By using xchg etc. it is possible to use any dimension.
88
89       The sum is started so that the first element in the cumulative product
90       is the first element of the parameter.
91
92        $y = cumuprodover($x);
93
94        $spectrum = cumuprodover $image->xchg(0,1)
95
96       Unlike cumuprodover, the calculations are performed in double
97       precision.
98
99       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
102   sumover
103         Signature: (a(n); int+ [o]b())
104
105       Project via sum to N-1 dimensions
106
107       This function reduces the dimensionality of a piddle by one by taking
108       the sum along the 1st dimension.
109
110       By using xchg etc. it is possible to use any dimension.
111
112        $y = sumover($x);
113
114        $spectrum = sumover $image->xchg(0,1)
115
116       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
119   dsumover
120         Signature: (a(n); double [o]b())
121
122       Project via sum to N-1 dimensions
123
124       This function reduces the dimensionality of a piddle by one by taking
125       the sum along the 1st dimension.
126
127       By using xchg etc. it is possible to use any dimension.
128
129        $y = dsumover($x);
130
131        $spectrum = dsumover $image->xchg(0,1)
132
133       Unlike sumover, the calculations are performed in double precision.
134
135       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
138   cumusumover
139         Signature: (a(n); int+ [o]b(n))
140
141       Cumulative sum
142
143       This function calculates the cumulative sum along the 1st dimension.
144
145       By using xchg etc. it is possible to use any dimension.
146
147       The sum is started so that the first element in the cumulative sum is
148       the first element of the parameter.
149
150        $y = cumusumover($x);
151
152        $spectrum = cumusumover $image->xchg(0,1)
153
154       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
157   dcumusumover
158         Signature: (a(n); double [o]b(n))
159
160       Cumulative sum
161
162       This function calculates the cumulative sum along the 1st dimension.
163
164       By using xchg etc. it is possible to use any dimension.
165
166       The sum is started so that the first element in the cumulative sum is
167       the first element of the parameter.
168
169        $y = cumusumover($x);
170
171        $spectrum = cumusumover $image->xchg(0,1)
172
173       Unlike cumusumover, the calculations are performed in double precision.
174
175       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
178   andover
179         Signature: (a(n); int+ [o]b())
180
181       Project via and to N-1 dimensions
182
183       This function reduces the dimensionality of a piddle by one by taking
184       the and along the 1st dimension.
185
186       By using xchg etc. it is possible to use any dimension.
187
188        $y = andover($x);
189
190        $spectrum = andover $image->xchg(0,1)
191
192       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
196   bandover
197         Signature: (a(n);  [o]b())
198
199       Project via bitwise and to N-1 dimensions
200
201       This function reduces the dimensionality of a piddle by one by taking
202       the bitwise and along the 1st dimension.
203
204       By using xchg etc. it is possible to use any dimension.
205
206        $y = bandover($x);
207
208        $spectrum = bandover $image->xchg(0,1)
209
210       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
214   borover
215         Signature: (a(n);  [o]b())
216
217       Project via bitwise or to N-1 dimensions
218
219       This function reduces the dimensionality of a piddle by one by taking
220       the bitwise or along the 1st dimension.
221
222       By using xchg etc. it is possible to use any dimension.
223
224        $y = borover($x);
225
226        $spectrum = borover $image->xchg(0,1)
227
228       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
232   orover
233         Signature: (a(n); int+ [o]b())
234
235       Project via or to N-1 dimensions
236
237       This function reduces the dimensionality of a piddle by one by taking
238       the or along the 1st dimension.
239
240       By using xchg etc. it is possible to use any dimension.
241
242        $y = orover($x);
243
244        $spectrum = orover $image->xchg(0,1)
245
246       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
250   zcover
251         Signature: (a(n); int+ [o]b())
252
253       Project via == 0 to N-1 dimensions
254
255       This function reduces the dimensionality of a piddle by one by taking
256       the == 0 along the 1st dimension.
257
258       By using xchg etc. it is possible to use any dimension.
259
260        $y = zcover($x);
261
262        $spectrum = zcover $image->xchg(0,1)
263
264       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
268   intover
269         Signature: (a(n); float+ [o]b())
270
271       Project via integral to N-1 dimensions
272
273       This function reduces the dimensionality of a piddle by one by taking
274       the integral along the 1st dimension.
275
276       By using xchg etc. it is possible to use any dimension.
277
278        $y = intover($x);
279
280        $spectrum = intover $image->xchg(0,1)
281
282       Notes:
283
284       "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
287       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
292       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
296   average
297         Signature: (a(n); int+ [o]b())
298
299       Project via average to N-1 dimensions
300
301       This function reduces the dimensionality of a piddle by one by taking
302       the average along the 1st dimension.
303
304       By using xchg etc. it is possible to use any dimension.
305
306        $y = average($x);
307
308        $spectrum = average $image->xchg(0,1)
309
310       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
313   avgover
314         Synonym for average.
315
316   daverage
317         Signature: (a(n); double [o]b())
318
319       Project via average to N-1 dimensions
320
321       This function reduces the dimensionality of a piddle by one by taking
322       the average along the 1st dimension.
323
324       By using xchg etc. it is possible to use any dimension.
325
326        $y = daverage($x);
327
328        $spectrum = daverage $image->xchg(0,1)
329
330       Unlike average, the calculation is performed in double precision.
331
332       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
335   davgover
336         Synonym for daverage.
337
338   medover
339         Signature: (a(n); [o]b(); [t]tmp(n))
340
341       Project via median to N-1 dimensions
342
343       This function reduces the dimensionality of a piddle by one by taking
344       the median along the 1st dimension.
345
346       By using xchg etc. it is possible to use any dimension.
347
348        $y = medover($x);
349
350        $spectrum = medover $image->xchg(0,1)
351
352       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
355   oddmedover
356         Signature: (a(n); [o]b(); [t]tmp(n))
357
358       Project via oddmedian to N-1 dimensions
359
360       This function reduces the dimensionality of a piddle by one by taking
361       the oddmedian along the 1st dimension.
362
363       By using xchg etc. it is possible to use any dimension.
364
365        $y = oddmedover($x);
366
367        $spectrum = oddmedover $image->xchg(0,1)
368
369       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
375       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
378   modeover
379         Signature: (data(n); [o]out(); [t]sorted(n))
380
381       Project via mode to N-1 dimensions
382
383       This function reduces the dimensionality of a piddle by one by taking
384       the mode along the 1st dimension.
385
386       By using xchg etc. it is possible to use any dimension.
387
388        $y = modeover($x);
389
390        $spectrum = modeover $image->xchg(0,1)
391
392       The mode is the single element most frequently found in a discrete data
393       set.
394
395       It only makes sense for integer data types, since floating-point types
396       are demoted to integer before the mode is calculated.
397
398       "modeover" treats BAD the same as any other value:  if BAD is the most
399       common element, the returned value is also BAD.
400
401       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
404   pctover
405         Signature: (a(n); p(); [o]b(); [t]tmp(n))
406
407       Project via percentile to N-1 dimensions
408
409       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
418       By using xchg etc. it is possible to use any dimension.
419
420        $y = pctover($x, $p);
421
422        $spectrum = pctover $image->xchg(0,1), $p
423
424       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
427   oddpctover
428         Signature: (a(n); p(); [o]b(); [t]tmp(n))
429
430       Project via percentile to N-1 dimensions
431
432       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
439       By using xchg etc. it is possible to use any dimension.
440
441        $y = oddpctover($x, $p);
442
443        $spectrum = oddpctover $image->xchg(0,1), $p
444
445       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
448   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
454        $x = pct($data, $pct);
455
456   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
462        $x = oddpct($data, $pct);
463
464   avg
465       Return the average of all elements in a piddle.
466
467       See the documentation for average for more information.
468
469        $x = avg($data);
470
471       This routine handles bad values.
472
473   sum
474       Return the sum of all elements in a piddle.
475
476       See the documentation for sumover for more information.
477
478        $x = sum($data);
479
480       This routine handles bad values.
481
482   prod
483       Return the product of all elements in a piddle.
484
485       See the documentation for prodover for more information.
486
487        $x = prod($data);
488
489       This routine handles bad values.
490
491   davg
492       Return the average (in double precision) of all elements in a piddle.
493
494       See the documentation for daverage for more information.
495
496        $x = davg($data);
497
498       This routine handles bad values.
499
500   dsum
501       Return the sum (in double precision) of all elements in a piddle.
502
503       See the documentation for dsumover for more information.
504
505        $x = dsum($data);
506
507       This routine handles bad values.
508
509   dprod
510       Return the product (in double precision) of all elements in a piddle.
511
512       See the documentation for dprodover for more information.
513
514        $x = dprod($data);
515
516       This routine handles bad values.
517
518   zcheck
519       Return the check for zero of all elements in a piddle.
520
521       See the documentation for zcover for more information.
522
523        $x = zcheck($data);
524
525       This routine handles bad values.
526
527   and
528       Return the logical and of all elements in a piddle.
529
530       See the documentation for andover for more information.
531
532        $x = and($data);
533
534       This routine handles bad values.
535
536   band
537       Return the bitwise and of all elements in a piddle.
538
539       See the documentation for bandover for more information.
540
541        $x = band($data);
542
543       This routine handles bad values.
544
545   or
546       Return the logical or of all elements in a piddle.
547
548       See the documentation for orover for more information.
549
550        $x = or($data);
551
552       This routine handles bad values.
553
554   bor
555       Return the bitwise or of all elements in a piddle.
556
557       See the documentation for borover for more information.
558
559        $x = bor($data);
560
561       This routine handles bad values.
562
563   min
564       Return the minimum of all elements in a piddle.
565
566       See the documentation for minimum for more information.
567
568        $x = min($data);
569
570       This routine handles bad values.
571
572   max
573       Return the maximum of all elements in a piddle.
574
575       See the documentation for maximum for more information.
576
577        $x = max($data);
578
579       This routine handles bad values.
580
581   median
582       Return the median of all elements in a piddle.
583
584       See the documentation for medover for more information.
585
586        $x = median($data);
587
588       This routine handles bad values.
589
590   mode
591       Return the mode of all elements in a piddle.
592
593       See the documentation for modeover for more information.
594
595        $x = mode($data);
596
597       This routine handles bad values.
598
599   oddmedian
600       Return the oddmedian of all elements in a piddle.
601
602       See the documentation for oddmedover for more information.
603
604        $x = oddmedian($data);
605
606       This routine handles bad values.
607
608   any
609       Return true if any element in piddle set
610
611       Useful in conditional expressions:
612
613        if (any $x>15) { print "some values are greater than 15\n" }
614
615       See or for comments on what happens when all elements in the check are
616       bad.
617
618   all
619       Return true if all elements in piddle set
620
621       Useful in conditional expressions:
622
623        if (all $x>15) { print "all values are greater than 15\n" }
624
625       See and for comments on what happens when all elements in the check are
626       bad.
627
628   minmax
629       Returns an array with minimum and maximum values of a piddle.
630
631        ($mn, $mx) = minmax($pdl);
632
633       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
638        pdl> $x = pdl [1,-2,3,5,0]
639        pdl> ($min, $max) = minmax($x);
640        pdl> p "$min $max\n";
641        -2 5
642
643   qsort
644         Signature: (a(n); [o]b(n))
645
646       Quicksort a vector into ascending order.
647
648        print qsort random(10);
649
650       Bad values are moved to the end of the array:
651
652        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
657   qsorti
658         Signature: (a(n); indx [o]indx(n))
659
660       Quicksort a vector and return index of elements in ascending order.
661
662        $ix = qsorti $x;
663        print $x->index($ix); # Sorted list
664
665       Bad elements are moved to the end of the array:
666
667        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
672   qsortvec
673         Signature: (a(n,m); [o]b(n,m))
674
675       Sort a list of vectors lexicographically.
676
677       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
680        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
690       Vectors with bad components should be moved to the end of the array:
691
692   qsortveci
693         Signature: (a(n,m); indx [o]indx(m))
694
695       Sort a list of vectors lexicographically, returning the indices of the
696       sorted vectors rather than the sorted list itself.
697
698       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
702       As with "qsortvec", the zeroth element of the vectors runs slowest in
703       the sorted list.
704
705       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
709       Vectors with bad components should be moved to the end of the array:
710
711   minimum
712         Signature: (a(n); [o]c())
713
714       Project via minimum to N-1 dimensions
715
716       This function reduces the dimensionality of a piddle by one by taking
717       the minimum along the 1st dimension.
718
719       By using xchg etc. it is possible to use any dimension.
720
721        $y = minimum($x);
722
723        $spectrum = minimum $image->xchg(0,1)
724
725       Output is set bad if all elements of the input are bad, otherwise the
726       bad flag is cleared for the output piddle.
727
728       Note that "NaNs" are considered to be valid values; see isfinite and
729       badmask for ways of masking NaNs.
730
731   minimum_ind
732         Signature: (a(n); indx [o] c())
733
734       Like minimum but returns the index rather than the value
735
736       Output is set bad if all elements of the input are bad, otherwise the
737       bad flag is cleared for the output piddle.
738
739   minimum_n_ind
740         Signature: (a(n); indx [o]c(m))
741
742       Returns the index of "m" minimum elements
743
744       Not yet been converted to ignore bad values
745
746   maximum
747         Signature: (a(n); [o]c())
748
749       Project via maximum to N-1 dimensions
750
751       This function reduces the dimensionality of a piddle by one by taking
752       the maximum along the 1st dimension.
753
754       By using xchg etc. it is possible to use any dimension.
755
756        $y = maximum($x);
757
758        $spectrum = maximum $image->xchg(0,1)
759
760       Output is set bad if all elements of the input are bad, otherwise the
761       bad flag is cleared for the output piddle.
762
763       Note that "NaNs" are considered to be valid values; see isfinite and
764       badmask for ways of masking NaNs.
765
766   maximum_ind
767         Signature: (a(n); indx [o] c())
768
769       Like maximum but returns the index rather than the value
770
771       Output is set bad if all elements of the input are bad, otherwise the
772       bad flag is cleared for the output piddle.
773
774   maximum_n_ind
775         Signature: (a(n); indx [o]c(m))
776
777       Returns the index of "m" maximum elements
778
779       Not yet been converted to ignore bad values
780
781   maxover
782         Synonym for maximum.
783
784   maxover_ind
785         Synonym for maximum_ind.
786
787   maxover_n_ind
788         Synonym for maximum_n_ind.
789
790   minover
791         Synonym for minimum.
792
793   minover_ind
794         Synonym for minimum_ind.
795
796   minover_n_ind
797         Synonym for minimum_n_ind
798
799   minmaximum
800         Signature: (a(n); [o]cmin(); [o] cmax(); indx [o]cmin_ind(); indx [o]cmax_ind())
801
802       Find minimum and maximum and their indices for a given piddle;
803
804        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
809       See also minmax, which clumps the piddle together.
810
811       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
815   minmaxover
816         Synonym for minmaximum.
817

AUTHOR

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.
826
827
828
829perl v5.30.2                      2020-04-02                          Ufunc(3)
Impressum