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

NAME

6       PDL::Bad - PDL always processes bad values
7

DESCRIPTION

9       This module is loaded when you do "use PDL", "Use PDL::Lite" or
10       "PDL::LiteF".
11
12       Implementation details are given in PDL::BadValues.
13

SYNOPSIS

15        use PDL::Bad;
16        print "\nBad value per PDL support in PDL is turned " .
17            $PDL::Bad::PerPdl ? "on" : "off" . ".\n";
18

VARIABLES

20       $PDL::Bad::UseNaN
21           Set to 0 as of PDL 2.040, as no longer available, though NaN can be
22           used as a badvalue for a given PDL object.
23
24       $PDL::Bad::PerPdl
25           Set to 1 as of PDL 2.040 as always available.
26
27       $PDL::Bad::Status
28           Set to 1 as of PDL 2.035 as always available.
29

FUNCTIONS

31   badflag
32       getter/setter for the bad data flag
33
34         if ( $x->badflag() ) {
35           print "Data may contain bad values.\n";
36         }
37         $x->badflag(1);      # set bad data flag
38         $x->badflag(0);      # unset bad data flag
39
40       When called as a setter, this modifies the ndarray on which it is
41       called. This always returns a Perl scalar with the final value of the
42       bad flag.
43
44       A return value of 1 does not guarantee the presence of bad data in an
45       ndarray; all it does is say that we need to check for the presence of
46       such beasties. To actually find out if there are any bad values present
47       in an ndarray, use the "check_badflag" method.
48
49       This function works with ndarrays that have bad values. It always
50       returns a Perl scalar, so it never returns bad values.
51
52   badvalue
53       returns the value used to indicate a missing (or bad) element for the
54       given ndarray type. You can give it an ndarray, a PDL::Type object, or
55       one of $PDL_B, $PDL_S, etc.
56
57          $badval = badvalue( float );
58          $x = ones(ushort,10);
59          print "The bad data value for ushort is: ",
60             $x->badvalue(), "\n";
61
62       This can act as a setter (e.g. "$x->badvalue(23)"), including with the
63       value "NaN" for floating-point types.  Note that this never touches the
64       data in the ndarray.  That is, if $x already has bad values, they will
65       not be changed to use the given number and if any elements of $x have
66       that value, they will unceremoniously be marked as bad data. See
67       "setvaltobad", "setbadtoval", and "setbadif" for ways to actually
68       modify the data in ndarrays
69
70       It is possible to change the bad value on a per-ndarray basis, so
71
72           $x = sequence (10);
73           $x->badvalue (3); $x->badflag (1);
74           $y = sequence (10);
75           $y->badvalue (4); $y->badflag (1);
76
77       will set $x to be "[0 1 2 BAD 4 5 6 7 8 9]" and $y to be "[0 1 2 3 BAD
78       5 6 7 8 9]".
79
80       This method does not care if you call it on an input ndarray that has
81       bad values. It always returns an ndarray with the current or new bad
82       value.
83
84   orig_badvalue
85       returns the original value used to represent bad values for a given
86       type.
87
88       This routine operates the same as "badvalue", except you can not change
89       the values.
90
91       It also has an awful name.
92
93          $orig_badval = orig_badvalue( float );
94          $x = ones(ushort,10);
95          print "The original bad data value for ushort is: ",
96             $x->orig_badvalue(), "\n";
97
98       This method does not care if you call it on an input ndarray that has
99       bad values. It always returns an ndarray with the original bad value
100       for the associated type.
101
102   check_badflag
103       Clear the badflag of an ndarray if it does not contain any bad values
104
105       Given an ndarray whose bad flag is set, check whether it actually
106       contains any bad values and, if not, clear the flag.  It returns the
107       final state of the badflag.
108
109        print "State of bad flag == ", $pdl->check_badflag;
110
111       This method accepts ndarrays with or without bad values. It returns an
112       ndarray with the final badflag.
113
114   isbad
115         Signature: (a(); int [o]b())
116
117       Returns a binary mask indicating which values of the input are bad
118       values
119
120       Returns a 1 if the value is bad, 0 otherwise.  Similar to isfinite.
121
122        $x = pdl(1,2,3);
123        $x->badflag(1);
124        set($x,1,$x->badvalue);
125        $y = isbad($x);
126        print $y, "\n";
127        [0 1 0]
128
129       This method works with input ndarrays that are bad. The output ndarray
130       will never contain bad values, but its bad value flag will be the same
131       as the input ndarray's flag.
132
133   isgood
134         Signature: (a(); int [o]b())
135
136       Is a value good?
137
138       Returns a 1 if the value is good, 0 otherwise.  Also see isfinite.
139
140        $x = pdl(1,2,3);
141        $x->badflag(1);
142        set($x,1,$x->badvalue);
143        $y = isgood($x);
144        print $y, "\n";
145        [1 0 1]
146
147       This method works with input ndarrays that are bad. The output ndarray
148       will never contain bad values, but its bad value flag will be the same
149       as the input ndarray's flag.
150
151   nbadover
152         Signature: (a(n); indx [o] b())
153
154       Find the number of bad elements along the 1st dimension.
155
156       This function reduces the dimensionality of an ndarray by one by
157       finding the number of bad elements along the 1st dimension. In this
158       sense it shares much in common with the functions defined in
159       PDL::Ufunc. In particular, by using xchg and similar dimension
160       rearranging methods, it is possible to perform this calculation over
161       any dimension.
162
163        $x = nbadover($y);
164
165        $spectrum = nbadover $image->transpose
166
167       nbadover processes input values that are bad. The output ndarray will
168       not have any bad values, but the bad flag will be set if the input
169       ndarray had its bad flag set.
170
171   ngoodover
172         Signature: (a(n); indx [o] b())
173
174       Find the number of good elements along the 1st dimension.
175
176       This function reduces the dimensionality of an ndarray by one by
177       finding the number of good elements along the 1st dimension.
178
179       By using xchg etc. it is possible to use any dimension.
180
181        $x = ngoodover($y);
182
183        $spectrum = ngoodover $image->transpose
184
185       ngoodover processes input values that are bad. The output ndarray will
186       not have any bad values, but the bad flag will be set if the input
187       ndarray had its bad flag set.
188
189   nbad
190       Returns the number of bad values in an ndarray
191
192        $x = nbad($data);
193
194       Accepts good and bad input ndarrays; output is an ndarray and is always
195       good.
196
197   ngood
198       Returns the number of good values in an ndarray
199
200        $x = ngood($data);
201
202       Accepts good and bad input ndarrays; output is an ndarray and is always
203       good.
204
205   setbadat
206       Set the value to bad at a given position.
207
208        setbadat $ndarray, @position
209
210       @position is a coordinate list, of size equal to the number of
211       dimensions in the ndarray.  This is a wrapper around set and is
212       probably mainly useful in test scripts!
213
214        pdl> $x = sequence 3,4
215        pdl> $x->setbadat 2,1
216        pdl> p $x
217        [
218         [  0   1   2]
219         [  3   4 BAD]
220         [  6   7   8]
221         [  9  10  11]
222        ]
223
224       This method can be called on ndarrays that have bad values.  The
225       remainder of the arguments should be Perl scalars indicating the
226       position to set as bad. The output ndarray will have bad values and
227       will have its badflag turned on.
228
229   setbadif
230         Signature: (a(); int mask(); [o]b())
231
232       Set elements bad based on the supplied mask, otherwise copy across the
233       data.
234
235        pdl> $x = sequence(5,5)
236        pdl> $x = $x->setbadif( $x % 2 )
237        pdl> p "a badflag: ", $x->badflag, "\n"
238        a badflag: 1
239        pdl> p "a is\n$x"
240        [
241         [  0 BAD   2 BAD   4]
242         [BAD   6 BAD   8 BAD]
243         [ 10 BAD  12 BAD  14]
244         [BAD  16 BAD  18 BAD]
245         [ 20 BAD  22 BAD  24]
246        ]
247
248       Unfortunately, this routine can not be run inplace, since the current
249       implementation can not handle the same ndarray used as "a" and "mask"
250       (eg "$x->inplace->setbadif($x%2)" fails).  Even more unfortunate: we
251       can't catch this error and tell you.
252
253       The output always has its bad flag set, even if it does not contain any
254       bad values (use "check_badflag" to check whether there are any bad
255       values in the output).  The input ndarray can have bad values: any bad
256       values in the input ndarrays are copied across to the output ndarray.
257
258       Also see "setvaltobad" and "setnantobad".
259
260   setvaltobad
261         Signature: (a(); [o]b(); double value)
262
263       Set bad all those elements which equal the supplied value.
264
265        $x = sequence(10) % 3;
266        $x->inplace->setvaltobad( 0 );
267        print "$x\n";
268        [BAD 1 2 BAD 1 2 BAD 1 2 BAD]
269
270       This is a simpler version of "setbadif", but this function can be done
271       inplace.  See "setnantobad" if you want to convert NaN to the bad
272       value.
273
274       The output always has its bad flag set, even if it does not contain any
275       bad values (use "check_badflag" to check whether there are any bad
276       values in the output).  Any bad values in the input ndarrays are copied
277       across to the output ndarray.
278
279   setnantobad
280         Signature: (a(); [o]b())
281
282       Sets NaN values (for complex, where either is NaN) in the input ndarray
283       bad (only relevant for floating-point ndarrays).  Can be done inplace.
284
285        $y = $x->setnantobad;
286        $x->inplace->setnantobad;
287
288       This method can process ndarrays with bad values: those bad values are
289       propagated into the output ndarray. Any value that is not a number
290       (before version 2.040 the test was for "not finite") is also set to bad
291       in the output ndarray. If all values from the input ndarray are good,
292       the output ndarray will not have its bad flag set.
293
294   setinftobad
295         Signature: (a(); [o]b())
296
297       Sets non-finite values (for complex, where either is non-finite) in the
298       input ndarray bad (only relevant for floating-point ndarrays).  Can be
299       done inplace.
300
301        $y = $x->setinftobad;
302        $x->inplace->setinftobad;
303
304       This method can process ndarrays with bad values: those bad values are
305       propagated into the output ndarray. Any value that is not finite is
306       also set to bad in the output ndarray. If all values from the input
307       ndarray are finite, the output ndarray will not have its bad flag set.
308
309   setnonfinitetobad
310         Signature: (a(); [o]b())
311
312       Sets non-finite values (for complex, where either is non-finite) in the
313       input ndarray bad (only relevant for floating-point ndarrays).  Can be
314       done inplace.
315
316        $y = $x->setnonfinitetobad;
317        $x->inplace->setnonfinitetobad;
318
319       This method can process ndarrays with bad values: those bad values are
320       propagated into the output ndarray. Any value that is not finite is
321       also set to bad in the output ndarray. If all values from the input
322       ndarray are finite, the output ndarray will not have its bad flag set.
323
324   setbadtonan
325         Signature: (a(); [o] b();)
326
327       Sets Bad values to NaN
328
329       This is only relevant for floating-point ndarrays. The input ndarray
330       can be of any type, but if done inplace, the input must be floating
331       point.
332
333        $y = $x->setbadtonan;
334        $x->inplace->setbadtonan;
335
336       This method processes input ndarrays with bad values. The output
337       ndarrays will not contain bad values (insofar as NaN is not Bad as far
338       as PDL is concerned) and the output ndarray does not have its bad flag
339       set. As an inplace operation, it clears the bad flag.
340
341   setbadtoval
342         Signature: (a(); [o]b(); double newval)
343
344       Replace any bad values by a (non-bad) value.
345
346       Can be done inplace. Also see "badmask".
347
348        $x->inplace->setbadtoval(23);
349        print "a badflag: ", $x->badflag, "\n";
350        a badflag: 0
351
352       The output always has its bad flag cleared.  If the input ndarray does
353       not have its bad flag set, then values are copied with no replacement.
354
355   badmask
356         Signature: (a(); b(); [o]c())
357
358       Clears all "infs" and "nans" in $a to the corresponding value in $b.
359
360       badmask can be run with $x inplace:
361
362         badmask($x->inplace,0);
363         $x->inplace->badmask(0);
364
365       If bad values are present, these are also cleared.
366
367   copybad
368         Signature: (a(); mask(); [o]b())
369
370       Copies values from one ndarray to another, setting them bad if they are
371       bad in the supplied mask.
372
373       Can be done inplace.
374
375        $x = byte( [0,1,3] );
376        $mask = byte( [0,0,0] );
377        $mask->badflag(1);
378        set($mask,1,$mask->badvalue);
379        $x->inplace->copybad( $mask );
380        p $x;
381        [0 BAD 3]
382
383       It is equivalent to:
384
385        $c = $x + $mask * 0
386
387       This handles input ndarrays that are bad. If either $x or $mask have
388       bad values, those values will be marked as bad in the output ndarray
389       and the output ndarray will have its bad value flag set to true.
390
391   locf
392         Signature: (a(n); [o]b(n))
393
394       Last Observation Carried Forward - replace every BAD value with the
395       most recent non-BAD value prior to it.  Any leading BADs will be set to
396       0.
397
398       locf processes bad values.  It will set the bad-value flag of all
399       output ndarrays if the flag is set for any of the input ndarrays.
400

AUTHOR

402       Doug Burke (djburke@cpan.org), 2000, 2001, 2003, 2006.
403
404       The per-ndarray bad value support is by Heiko Klein (2006).
405
406       CPAN documentation fixes by David Mertens (2010, 2013).
407
408       All rights reserved. There is no warranty. You are allowed to
409       redistribute this software / documentation under certain conditions.
410       For details, see the file COPYING in the PDL distribution. If this file
411       is separated from the PDL distribution, the copyright notice should be
412       included in the file.
413
414
415
416perl v5.36.0                      2023-01-20                            Bad(3)
Impressum