1Bad(3) User Contributed Perl Documentation Bad(3)
2
6 PDL::Bad - PDL always processes bad values
7
9 This module is loaded when you do "use PDL", "Use PDL::Lite" or
10 "PDL::LiteF".
11 Implementation details are given in PDL::BadValues.
13
15 use PDL::Bad;
16 print "\nBad value per PDL support in PDL is turned " .
17 $PDL::Bad::PerPdl ? "on" : "off" . ".\n";
18
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 $PDL::Bad::PerPdl
25 Set to 1 as of PDL 2.040 as always available.
26 $PDL::Bad::Status
28 Set to 1 as of PDL 2.035 as always available.
29
31 badflag
32 getter/setter for the bad data flag
33 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 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 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 This function works with ndarrays that have bad values. It always
50 returns a Perl scalar, so it never returns bad values.
51 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 $badval = badvalue( float );
58 $x = ones(ushort,10);
59 print "The bad data value for ushort is: ",
60 $x->badvalue(), "\n";
61 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 It is possible to change the bad value on a per-ndarray basis, so
71 $x = sequence (10);
73 $x->badvalue (3); $x->badflag (1);
74 $y = sequence (10);
75 $y->badvalue (4); $y->badflag (1);
76 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 This method does not care if you call it on an input ndarray that has
81 bad values. It always returns a Perl scalar with the current or new bad
82 value.
83 orig_badvalue
85 returns the original value used to represent bad values for a given
86 type.
87 This routine operates the same as "badvalue", except you can not change
89 the values.
90 It also has an awful name.
92 $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 This method does not care if you call it on an input ndarray that has
99 bad values. It always returns a Perl scalar with the original bad value
100 for the associated type.
101 check_badflag
103 Clear the badflag of an ndarray if it does not contain any bad values
104 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 print "State of bad flag == ", $pdl->check_badflag;
110 This method accepts ndarrays with or without bad values. It returns an
112 ndarray with the final badflag.
113 isbad
115 Signature: (a(); int [o]b())
116 Returns a binary mask indicating which values of the input are bad
118 values
119 Returns a 1 if the value is bad, 0 otherwise. Similar to isfinite.
121 $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 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 isgood
134 Signature: (a(); int [o]b())
135 Is a value good?
137 Returns a 1 if the value is good, 0 otherwise. Also see isfinite.
139 $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 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 nbadover
152 Signature: (a(n); indx [o] b())
153 Find the number of bad elements along the 1st dimension.
155 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 $x = nbadover($y);
164 $spectrum = nbadover $image->transpose
166 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 ngoodover
172 Signature: (a(n); indx [o] b())
173 Find the number of good elements along the 1st dimension.
175 This function reduces the dimensionality of an ndarray by one by
177 finding the number of good elements along the 1st dimension.
178 By using xchg etc. it is possible to use any dimension.
180 $x = ngoodover($y);
182 $spectrum = ngoodover $image->transpose
184 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 nbad
190 Returns the number of bad values in an ndarray
191 $x = nbad($data);
193 Accepts good and bad input ndarrays; output is a Perl scalar and
195 therefore is always good.
196 ngood
198 Returns the number of good values in an ndarray
199 $x = ngood($data);
201 Accepts good and bad input ndarrays; output is a Perl scalar and
203 therefore is always good.
204 setbadat
206 Set the value to bad at a given position.
207 setbadat $ndarray, @position
209 @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 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 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 setbadif
230 Signature: (a(); int mask(); [o]b())
231 Set elements bad based on the supplied mask, otherwise copy across the
233 data.
234 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 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 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 Also see "setvaltobad" and "setnantobad".
259 setvaltobad
261 Signature: (a(); [o]b(); double value)
262 Set bad all those elements which equal the supplied value.
264 $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 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 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 setnantobad
280 Signature: (a(); [o]b())
281 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 $y = $x->setnantobad;
286 $x->inplace->setnantobad;
287 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 setinftobad
295 Signature: (a(); [o]b())
296 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 $y = $x->setinftobad;
302 $x->inplace->setinftobad;
303 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 setnonfinitetobad
310 Signature: (a(); [o]b())
311 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 $y = $x->setnonfinitetobad;
317 $x->inplace->setnonfinitetobad;
318 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 setbadtonan
325 Signature: (a(); [o] b();)
326 Sets Bad values to NaN
328 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 $y = $x->setbadtonan;
334 $x->inplace->setbadtonan;
335 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 setbadtoval
342 Signature: (a(); [o]b(); double newval)
343 Replace any bad values by a (non-bad) value.
345 Can be done inplace. Also see "badmask".
347 $x->inplace->setbadtoval(23);
349 print "a badflag: ", $x->badflag, "\n";
350 a badflag: 0
351 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 badmask
356 Signature: (a(); b(); [o]c())
357 Clears all "infs" and "nans" in $a to the corresponding value in $b.
359 badmask can be run with $x inplace:
361 badmask($x->inplace,0);
363 $x->inplace->badmask(0);
364 If bad values are present, these are also cleared.
366 copybad
368 Signature: (a(); mask(); [o]b())
369 Copies values from one ndarray to another, setting them bad if they are
371 bad in the supplied mask.
372 Can be done inplace.
374 $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 It is equivalent to:
384 $c = $x + $mask * 0
386 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 locf
392 Signature: (a(n); [o]b(n))
393 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 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
402 Doug Burke (djburke@cpan.org), 2000, 2001, 2003, 2006.
403 The per-ndarray bad value support is by Heiko Klein (2006).
405 CPAN documentation fixes by David Mertens (2010, 2013).
407 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.
413perl v5.36.0 2022-07-22 Bad(3)