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 bad-value flag of an ndarray if it does not contain any bad
104 values
105 Given an ndarray whose bad flag is set, check whether it actually
107 contains any bad values and, if not, clear the flag. It returns the
108 final state of the bad-value flag.
109 print "State of bad flag == ", $pdl->check_badflag;
111 This method accepts ndarrays with or without bad values. It returns an
113 ndarray with the final bad-value.
114 isbad
116 Signature: (a(); int [o]b())
117 Returns a binary mask indicating which values of the input are bad
119 values
120 Returns a 1 if the value is bad, 0 otherwise. Similar to isfinite.
122 $x = pdl(1,2,3);
124 $x->badflag(1);
125 set($x,1,$x->badvalue);
126 $y = isbad($x);
127 print $y, "\n";
128 [0 1 0]
129 This method works with input ndarrays that are bad. The output ndarray
131 will never contain bad values, but its bad value flag will be the same
132 as the input ndarray's flag.
133 isgood
135 Signature: (a(); int [o]b())
136 Is a value good?
138 Returns a 1 if the value is good, 0 otherwise. Also see isfinite.
140 $x = pdl(1,2,3);
142 $x->badflag(1);
143 set($x,1,$x->badvalue);
144 $y = isgood($x);
145 print $y, "\n";
146 [1 0 1]
147 This method works with input ndarrays that are bad. The output ndarray
149 will never contain bad values, but its bad value flag will be the same
150 as the input ndarray's flag.
151 nbadover
153 Signature: (a(n); indx [o] b())
154 Find the number of bad elements along the 1st dimension.
156 This function reduces the dimensionality of an ndarray by one by
158 finding the number of bad elements along the 1st dimension. In this
159 sense it shares much in common with the functions defined in
160 PDL::Ufunc. In particular, by using xchg and similar dimension
161 rearranging methods, it is possible to perform this calculation over
162 any dimension.
163 $x = nbadover($y);
165 $spectrum = nbadover $image->transpose
167 nbadover processes input values that are bad. The output ndarray will
169 not have any bad values, but the bad flag will be set if the input
170 ndarray had its bad flag set.
171 ngoodover
173 Signature: (a(n); indx [o] b())
174 Find the number of good elements along the 1st dimension.
176 This function reduces the dimensionality of an ndarray by one by
178 finding the number of good elements along the 1st dimension.
179 By using xchg etc. it is possible to use any dimension.
181 $x = ngoodover($y);
183 $spectrum = ngoodover $image->transpose
185 ngoodover processes input values that are bad. The output ndarray will
187 not have any bad values, but the bad flag will be set if the input
188 ndarray had its bad flag set.
189 nbad
191 Returns the number of bad values in an ndarray
192 $x = nbad($data);
194 Accepts good and bad input ndarrays; output is a Perl scalar and
196 therefore is always good.
197 ngood
199 Returns the number of good values in an ndarray
200 $x = ngood($data);
202 Accepts good and bad input ndarrays; output is a Perl scalar and
204 therefore is always good.
205 setbadat
207 Set the value to bad at a given position.
208 setbadat $ndarray, @position
210 @position is a coordinate list, of size equal to the number of
212 dimensions in the ndarray. This is a wrapper around set and is
213 probably mainly useful in test scripts!
214 pdl> $x = sequence 3,4
216 pdl> $x->setbadat 2,1
217 pdl> p $x
218 [
219 [ 0 1 2]
220 [ 3 4 BAD]
221 [ 6 7 8]
222 [ 9 10 11]
223 ]
224 This method can be called on ndarrays that have bad values. The
226 remainder of the arguments should be Perl scalars indicating the
227 position to set as bad. The output ndarray will have bad values and
228 will have its badflag turned on.
229 setbadif
231 Signature: (a(); int mask(); [o]b())
232 Set elements bad based on the supplied mask, otherwise copy across the
234 data.
235 pdl> $x = sequence(5,5)
237 pdl> $x = $x->setbadif( $x % 2 )
238 pdl> p "a badflag: ", $x->badflag, "\n"
239 a badflag: 1
240 pdl> p "a is\n$x"
241 [
242 [ 0 BAD 2 BAD 4]
243 [BAD 6 BAD 8 BAD]
244 [ 10 BAD 12 BAD 14]
245 [BAD 16 BAD 18 BAD]
246 [ 20 BAD 22 BAD 24]
247 ]
248 Unfortunately, this routine can not be run inplace, since the current
250 implementation can not handle the same ndarray used as "a" and "mask"
251 (eg "$x->inplace->setbadif($x%2)" fails). Even more unfortunate: we
252 can't catch this error and tell you.
253 The output always has its bad flag set, even if it does not contain any
255 bad values (use "check_badflag" to check whether there are any bad
256 values in the output). The input ndarray can have bad values: any bad
257 values in the input ndarrays are copied across to the output ndarray.
258 Also see "setvaltobad" and "setnantobad".
260 setvaltobad
262 Signature: (a(); [o]b(); double value)
263 Set bad all those elements which equal the supplied value.
265 $x = sequence(10) % 3;
267 $x->inplace->setvaltobad( 0 );
268 print "$x\n";
269 [BAD 1 2 BAD 1 2 BAD 1 2 BAD]
270 This is a simpler version of "setbadif", but this function can be done
272 inplace. See "setnantobad" if you want to convert NaN to the bad
273 value.
274 The output always has its bad flag set, even if it does not contain any
276 bad values (use "check_badflag" to check whether there are any bad
277 values in the output). Any bad values in the input ndarrays are copied
278 across to the output ndarray.
279 setnantobad
281 Signature: (a(); [o]b())
282 Sets NaN values (for complex, where either is NaN) in the input ndarray
284 bad (only relevant for floating-point ndarrays). Can be done inplace.
285 $y = $x->setnantobad;
287 $x->inplace->setnantobad;
288 This method can process ndarrays with bad values: those bad values are
290 propagated into the output ndarray. Any value that is not a number
291 (before version 2.040 the test was for "not finite") is also set to bad
292 in the output ndarray. If all values from the input ndarray are good,
293 the output ndarray will not have its bad flag set.
294 setinftobad
296 Signature: (a(); [o]b())
297 Sets non-finite values (for complex, where either is non-finite) in the
299 input ndarray bad (only relevant for floating-point ndarrays). Can be
300 done inplace.
301 $y = $x->setinftobad;
303 $x->inplace->setinftobad;
304 This method can process ndarrays with bad values: those bad values are
306 propagated into the output ndarray. Any value that is not finite is
307 also set to bad in the output ndarray. If all values from the input
308 ndarray are finite, the output ndarray will not have its bad flag set.
309 setnonfinitetobad
311 Signature: (a(); [o]b())
312 Sets non-finite values (for complex, where either is non-finite) in the
314 input ndarray bad (only relevant for floating-point ndarrays). Can be
315 done inplace.
316 $y = $x->setnonfinitetobad;
318 $x->inplace->setnonfinitetobad;
319 This method can process ndarrays with bad values: those bad values are
321 propagated into the output ndarray. Any value that is not finite is
322 also set to bad in the output ndarray. If all values from the input
323 ndarray are finite, the output ndarray will not have its bad flag set.
324 setbadtonan
326 Signature: (a(); [o] b();)
327 Sets Bad values to NaN
329 This is only relevant for floating-point ndarrays. The input ndarray
331 can be of any type, but if done inplace, the input must be floating
332 point.
333 $y = $x->setbadtonan;
335 $x->inplace->setbadtonan;
336 This method processes input ndarrays with bad values. The output
338 ndarrays will not contain bad values (insofar as NaN is not Bad as far
339 as PDL is concerned) and the output ndarray does not have its bad flag
340 set. As an inplace operation, it clears the bad flag.
341 setbadtoval
343 Signature: (a(); [o]b(); double newval)
344 Replace any bad values by a (non-bad) value.
346 Can be done inplace. Also see badmask.
348 $x->inplace->setbadtoval(23);
350 print "a badflag: ", $x->badflag, "\n";
351 a badflag: 0
352 The output always has its bad flag cleared. If the input ndarray does
354 not have its bad flag set, then values are copied with no replacement.
355 copybad
357 Signature: (a(); mask(); [o]b())
358 Copies values from one ndarray to another, setting them bad if they are
360 bad in the supplied mask.
361 Can be done inplace.
363 $x = byte( [0,1,3] );
365 $mask = byte( [0,0,0] );
366 $mask->badflag(1);
367 set($mask,1,$mask->badvalue);
368 $x->inplace->copybad( $mask );
369 p $x;
370 [0 BAD 3]
371 It is equivalent to:
373 $c = $x + $mask * 0
375 This handles input ndarrays that are bad. If either $x or $mask have
377 bad values, those values will be marked as bad in the output ndarray
378 and the output ndarray will have its bad value flag set to true.
379 locf
381 Signature: (a(n); [o]b(n))
382 Last Observation Carried Forward - replace every BAD value with the
384 most recent non-BAD value prior to it. Any leading BADs will be set to
385 0.
386 locf processes bad values. It will set the bad-value flag of all
388 output ndarrays if the flag is set for any of the input ndarrays.
389
391 Doug Burke (djburke@cpan.org), 2000, 2001, 2003, 2006.
392 The per-ndarray bad value support is by Heiko Klein (2006).
394 CPAN documentation fixes by David Mertens (2010, 2013).
396 All rights reserved. There is no warranty. You are allowed to
398 redistribute this software / documentation under certain conditions.
399 For details, see the file COPYING in the PDL distribution. If this file
400 is separated from the PDL distribution, the copyright notice should be
401 included in the file.
402perl v5.34.0 2022-02-28 Bad(3)