1Bad(3) User Contributed Perl Documentation Bad(3)
2
6 PDL::Bad - PDL does process bad values
7
9 PDL has been compiled with WITH_BADVAL set to 1. Therefore, you can
10 enter the wonderful world of bad value support in PDL.
11 This module is loaded when you do "use PDL", "Use PDL::Lite" or
13 "PDL::LiteF".
14 Implementation details are given in PDL::BadValues.
16
18 use PDL::Bad;
19 print "\nBad value support in PDL is turned " .
20 $PDL::Bad::Status ? "on" : "off" . ".\n";
21 Bad value support in PDL is turned on.
23 and some other things
25
27 There are currently three variables that this module defines which may
28 be of use.
29 $PDL::Bad::Status
31 Set to 1
32 $PDL::Bad::UseNaN
34 Set to 1 if PDL was compiled with "BADVAL_USENAN" set, 0 otherwise.
35 $PDL::Bad::PerPdl
37 Set to 1 if PDL was compiled with the experimental "BADVAL_PER_PDL"
38 option set, 0 otherwise.
39
41 badflag
42 getter/setter for the bad data flag
43 if ( $x->badflag() ) {
45 print "Data may contain bad values.\n";
46 }
47 $x->badflag(1); # set bad data flag
48 $x->badflag(0); # unset bad data flag
49 When called as a setter, this modifies the piddle on which it is
51 called. This always returns a Perl scalar with the final value of the
52 bad flag.
53 A return value of 1 does not guarantee the presence of bad data in a
55 piddle; all it does is say that we need to check for the presence of
56 such beasties. To actually find out if there are any bad values present
57 in a piddle, use the check_badflag method.
58 This function works with piddles that have bad values. It always
60 returns a Perl scalar, so it never returns bad values.
61 badvalue
63 returns the value used to indicate a missing (or bad) element for the
64 given piddle type. You can give it a piddle, a PDL::Type object, or one
65 of $PDL_B, $PDL_S, etc.
66 $badval = badvalue( float );
68 $x = ones(ushort,10);
69 print "The bad data value for ushort is: ",
70 $x->badvalue(), "\n";
71 This can act as a setter (e.g. "$x->badvalue(23)") if the data type is
73 an integer or "$PDL::Bad::UseNaN == 0". Note that this never touches
74 the data in the piddle. That is, if $x already has bad values, they
75 will not be changed to use the given number and if any elements of $x
76 have that value, they will unceremoniously be marked as bad data. See
77 "setvaltobad", "setbadtoval", and "setbadif" for ways to actually
78 modify the data in piddles
79 If the $PDL::Bad::PerPdl flag is set then it is possible to change the
81 bad value on a per-piddle basis, so
82 $x = sequence (10);
84 $x->badvalue (3); $x->badflag (1);
85 $y = sequence (10);
86 $y->badvalue (4); $y->badflag (1);
87 will set $x to be "[0 1 2 BAD 4 5 6 7 8 9]" and $y to be "[0 1 2 3 BAD
89 5 6 7 8 9]". If the flag is not set then both $x and $y will be set to
90 "[0 1 2 3 BAD 5 6 7 8 9]". Please note that the code to support per-
91 piddle bad values is experimental in the current release, and it
92 requires that you modify the settings under which PDL is compiled.
93 This method does not care if you call it on an input piddle that has
95 bad values. It always returns a Perl scalar with the current or new bad
96 value.
97 orig_badvalue
99 returns the original value used to represent bad values for a given
100 type.
101 This routine operates the same as badvalue, except you can not change
103 the values.
104 It also has an awful name.
106 $orig_badval = orig_badvalue( float );
108 $x = ones(ushort,10);
109 print "The original bad data value for ushort is: ",
110 $x->orig_badvalue(), "\n";
111 This method does not care if you call it on an input piddle that has
113 bad values. It always returns a Perl scalar with the original bad value
114 for the associated type.
115 check_badflag
117 Clear the bad-value flag of a piddle if it does not contain any bad
118 values
119 Given a piddle whose bad flag is set, check whether it actually
121 contains any bad values and, if not, clear the flag. It returns the
122 final state of the bad-value flag.
123 print "State of bad flag == ", $pdl->check_badflag;
125 This method accepts piddles with or without bad values. It returns a
127 Perl scalar with the final bad-value flag, so it never returns bad
128 values itself.
129 isbad
131 Signature: (a(); int [o]b())
132 Returns a binary mask indicating which values of the input are bad
134 values
135 Returns a 1 if the value is bad, 0 otherwise. Similar to isfinite.
137 $x = pdl(1,2,3);
139 $x->badflag(1);
140 set($x,1,$x->badvalue);
141 $y = isbad($x);
142 print $y, "\n";
143 [0 1 0]
144 This method works with input piddles that are bad. The output piddle
146 will never contain bad values, but its bad value flag will be the same
147 as the input piddle's flag.
148 isgood
150 Signature: (a(); int [o]b())
151 Is a value good?
153 Returns a 1 if the value is good, 0 otherwise. Also see isfinite.
155 $x = pdl(1,2,3);
157 $x->badflag(1);
158 set($x,1,$x->badvalue);
159 $y = isgood($x);
160 print $y, "\n";
161 [1 0 1]
162 This method works with input piddles that are bad. The output piddle
164 will never contain bad values, but its bad value flag will be the same
165 as the input piddle's flag.
166 nbadover
168 Signature: (a(n); indx [o] b())
169 Find the number of bad elements along the 1st dimension.
171 This function reduces the dimensionality of a piddle by one by finding
173 the number of bad elements along the 1st dimension. In this sense it
174 shares much in common with the functions defined in PDL::Ufunc. In
175 particular, by using xchg and similar dimension rearranging methods, it
176 is possible to perform this calculation over any dimension.
177 $x = nbadover($y);
179 $spectrum = nbadover $image->xchg(0,1)
181 nbadover processes input values that are bad. The output piddle will
183 not have any bad values, but the bad flag will be set if the input
184 piddle had its bad flag set.
185 ngoodover
187 Signature: (a(n); indx [o] b())
188 Find the number of good elements along the 1st dimension.
190 This function reduces the dimensionality of a piddle by one by finding
192 the number of good elements along the 1st dimension.
193 By using xchg etc. it is possible to use any dimension.
195 $x = ngoodover($y);
197 $spectrum = ngoodover $image->xchg(0,1)
199 ngoodover processes input values that are bad. The output piddle will
201 not have any bad values, but the bad flag will be set if the input
202 piddle had its bad flag set.
203 nbad
205 Returns the number of bad values in a piddle
206 $x = nbad($data);
208 Accepts good and bad input piddles; output is a Perl scalar and
210 therefore is always good.
211 ngood
213 Returns the number of good values in a piddle
214 $x = ngood($data);
216 Accepts good and bad input piddles; output is a Perl scalar and
218 therefore is always good.
219 setbadat
221 Set the value to bad at a given position.
222 setbadat $piddle, @position
224 @position is a coordinate list, of size equal to the number of
226 dimensions in the piddle. This is a wrapper around set and is probably
227 mainly useful in test scripts!
228 pdl> $x = sequence 3,4
230 pdl> $x->setbadat 2,1
231 pdl> p $x
232 [
233 [ 0 1 2]
234 [ 3 4 BAD]
235 [ 6 7 8]
236 [ 9 10 11]
237 ]
238 This method can be called on piddles that have bad values. The
240 remainder of the arguments should be Perl scalars indicating the
241 position to set as bad. The output piddle will have bad values and will
242 have its badflag turned on.
243 setbadif
245 Signature: (a(); int mask(); [o]b())
246 Set elements bad based on the supplied mask, otherwise copy across the
248 data.
249 pdl> $x = sequence(5,5)
251 pdl> $x = $x->setbadif( $x % 2 )
252 pdl> p "a badflag: ", $x->badflag, "\n"
253 a badflag: 1
254 pdl> p "a is\n$x"
255 [
256 [ 0 BAD 2 BAD 4]
257 [BAD 6 BAD 8 BAD]
258 [ 10 BAD 12 BAD 14]
259 [BAD 16 BAD 18 BAD]
260 [ 20 BAD 22 BAD 24]
261 ]
262 Unfortunately, this routine can not be run inplace, since the current
264 implementation can not handle the same piddle used as "a" and "mask"
265 (eg "$x->inplace->setbadif($x%2)" fails). Even more unfortunate: we
266 can't catch this error and tell you.
267 The output always has its bad flag set, even if it does not contain any
269 bad values (use check_badflag to check whether there are any bad values
270 in the output). The input piddle can have bad values: any bad values
271 in the input piddles are copied across to the output piddle.
272 Also see setvaltobad and setnantobad.
274 setvaltobad
276 Signature: (a(); [o]b(); double value)
277 Set bad all those elements which equal the supplied value.
279 $x = sequence(10) % 3;
281 $x->inplace->setvaltobad( 0 );
282 print "$x\n";
283 [BAD 1 2 BAD 1 2 BAD 1 2 BAD]
284 This is a simpler version of setbadif, but this function can be done
286 inplace. See setnantobad if you want to convert NaN/Inf to the bad
287 value.
288 The output always has its bad flag set, even if it does not contain any
290 bad values (use check_badflag to check whether there are any bad values
291 in the output). Any bad values in the input piddles are copied across
292 to the output piddle.
293 setnantobad
295 Signature: (a(); [o]b())
296 Sets NaN/Inf values in the input piddle bad (only relevant for
298 floating-point piddles). Can be done inplace.
299 $y = $x->setnantobad;
301 $x->inplace->setnantobad;
302 This method can process piddles with bad values: those bad values are
304 propagated into the output piddle. Any value that is not finite is also
305 set to bad in the output piddle. If all values from the input piddle
306 are good and finite, the output piddle will not have its bad flag set.
307 One more caveat: if done inplace, and if the input piddle's bad flag is
308 set, it will no
309 setbadtonan
311 Signature: (a(); [o] b();)
312 Sets Bad values to NaN
314 This is only relevant for floating-point piddles. The input piddle can
316 be of any type, but if done inplace, the input must be floating point.
317 $y = $x->setbadtonan;
319 $x->inplace->setbadtonan;
320 This method processes input piddles with bad values. The output piddles
322 will not contain bad values (insofar as NaN is not Bad as far as PDL is
323 concerned) and the output piddle does not have its bad flag set. As an
324 inplace operation, it clears the bad flag.
325 setbadtoval
327 Signature: (a(); [o]b(); double newval)
328 Replace any bad values by a (non-bad) value.
330 Can be done inplace. Also see badmask.
332 $x->inplace->setbadtoval(23);
334 print "a badflag: ", $x->badflag, "\n";
335 a badflag: 0
336 The output always has its bad flag cleared. If the input piddle does
338 not have its bad flag set, then values are copied with no replacement.
339 copybad
341 Signature: (a(); mask(); [o]b())
342 Copies values from one piddle to another, setting them bad if they are
344 bad in the supplied mask.
345 Can be done inplace.
347 $x = byte( [0,1,3] );
349 $mask = byte( [0,0,0] );
350 $mask->badflag(1);
351 set($mask,1,$mask->badvalue);
352 $x->inplace->copybad( $mask );
353 p $x;
354 [0 BAD 3]
355 It is equivalent to:
357 $c = $x + $mask * 0
359 This handles input piddles that are bad. If either $x or $mask have bad
361 values, those values will be marked as bad in the output piddle and the
362 output piddle will have its bad value flag set to true.
363
365 The experimental "BADVAL_PER_PDL" configuration option, which - when
366 set - allows per-piddle bad values, was added after the 2.4.2 release
367 of PDL. The $PDL::Bad::PerPdl variable can be inspected to see if this
368 feature is available.
369
371 The way the PDL handles the various bad value settings depends on your
372 compile-time configuration settings, as held in "perldl.conf".
373 $PDL::Config{WITH_BADVAL}
375 Set this configuration option to a true value if you want bad value
376 support. The default setting is for this to be true.
377 $PDL::Config{BADVAL_USENAN}
379 Set this configuration option to a true value if you want floating-
380 pont numbers to use NaN to represent the bad value. If set to
381 false, you can use any number to represent a bad value, which is
382 generally more flexible. In the default configuration, this is set
383 to a false value.
384 $PDL::Config{BADVAL_PER_PDL}
386 Set this configuration option to a true value if you want each of
387 your piddles to keep track of their own bad values. This means that
388 for one piddle you can set the bad value to zero, while in another
389 piddle you can set the bad value to NaN (or any other useful
390 number). This is usually set to false.
391
393 Doug Burke (djburke@cpan.org), 2000, 2001, 2003, 2006.
394 The per-piddle bad value support is by Heiko Klein (2006).
396 CPAN documentation fixes by David Mertens (2010, 2013).
398 All rights reserved. There is no warranty. You are allowed to
400 redistribute this software / documentation under certain conditions.
401 For details, see the file COPYING in the PDL distribution. If this file
402 is separated from the PDL distribution, the copyright notice should be
403 included in the file.
404perl v5.32.0 2020-09-17 Bad(3)