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 If the $PDL::Bad::PerPdl flag is set then it is possible to change the
71 bad value on a per-ndarray basis, so
72 $x = sequence (10);
74 $x->badvalue (3); $x->badflag (1);
75 $y = sequence (10);
76 $y->badvalue (4); $y->badflag (1);
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
79 5 6 7 8 9]". If the flag is not set then both $x and $y will be set to
80 "[0 1 2 3 BAD 5 6 7 8 9]". Please note that the code to support per-
81 ndarray bad values is experimental in the current release, and it
82 requires that you modify the settings under which PDL is compiled.
83 This method does not care if you call it on an input ndarray that has
85 bad values. It always returns a Perl scalar with the current or new bad
86 value.
87 orig_badvalue
89 returns the original value used to represent bad values for a given
90 type.
91 This routine operates the same as "badvalue", except you can not change
93 the values.
94 It also has an awful name.
96 $orig_badval = orig_badvalue( float );
98 $x = ones(ushort,10);
99 print "The original bad data value for ushort is: ",
100 $x->orig_badvalue(), "\n";
101 This method does not care if you call it on an input ndarray that has
103 bad values. It always returns a Perl scalar with the original bad value
104 for the associated type.
105 check_badflag
107 Clear the bad-value flag of an ndarray if it does not contain any bad
108 values
109 Given an ndarray whose bad flag is set, check whether it actually
111 contains any bad values and, if not, clear the flag. It returns the
112 final state of the bad-value flag.
113 print "State of bad flag == ", $pdl->check_badflag;
115 This method accepts ndarrays with or without bad values. It returns an
117 ndarray with the final bad-value.
118 isbad
120 Signature: (a(); int [o]b())
121 Returns a binary mask indicating which values of the input are bad
123 values
124 Returns a 1 if the value is bad, 0 otherwise. Similar to isfinite.
126 $x = pdl(1,2,3);
128 $x->badflag(1);
129 set($x,1,$x->badvalue);
130 $y = isbad($x);
131 print $y, "\n";
132 [0 1 0]
133 This method works with input ndarrays that are bad. The output ndarray
135 will never contain bad values, but its bad value flag will be the same
136 as the input ndarray's flag.
137 isgood
139 Signature: (a(); int [o]b())
140 Is a value good?
142 Returns a 1 if the value is good, 0 otherwise. Also see isfinite.
144 $x = pdl(1,2,3);
146 $x->badflag(1);
147 set($x,1,$x->badvalue);
148 $y = isgood($x);
149 print $y, "\n";
150 [1 0 1]
151 This method works with input ndarrays that are bad. The output ndarray
153 will never contain bad values, but its bad value flag will be the same
154 as the input ndarray's flag.
155 nbadover
157 Signature: (a(n); indx [o] b())
158 Find the number of bad elements along the 1st dimension.
160 This function reduces the dimensionality of an ndarray by one by
162 finding the number of bad elements along the 1st dimension. In this
163 sense it shares much in common with the functions defined in
164 PDL::Ufunc. In particular, by using xchg and similar dimension
165 rearranging methods, it is possible to perform this calculation over
166 any dimension.
167 $x = nbadover($y);
169 $spectrum = nbadover $image->transpose
171 nbadover processes input values that are bad. The output ndarray will
173 not have any bad values, but the bad flag will be set if the input
174 ndarray had its bad flag set.
175 ngoodover
177 Signature: (a(n); indx [o] b())
178 Find the number of good elements along the 1st dimension.
180 This function reduces the dimensionality of an ndarray by one by
182 finding the number of good elements along the 1st dimension.
183 By using xchg etc. it is possible to use any dimension.
185 $x = ngoodover($y);
187 $spectrum = ngoodover $image->transpose
189 ngoodover processes input values that are bad. The output ndarray will
191 not have any bad values, but the bad flag will be set if the input
192 ndarray had its bad flag set.
193 nbad
195 Returns the number of bad values in an ndarray
196 $x = nbad($data);
198 Accepts good and bad input ndarrays; output is a Perl scalar and
200 therefore is always good.
201 ngood
203 Returns the number of good values in an ndarray
204 $x = ngood($data);
206 Accepts good and bad input ndarrays; output is a Perl scalar and
208 therefore is always good.
209 setbadat
211 Set the value to bad at a given position.
212 setbadat $ndarray, @position
214 @position is a coordinate list, of size equal to the number of
216 dimensions in the ndarray. This is a wrapper around set and is
217 probably mainly useful in test scripts!
218 pdl> $x = sequence 3,4
220 pdl> $x->setbadat 2,1
221 pdl> p $x
222 [
223 [ 0 1 2]
224 [ 3 4 BAD]
225 [ 6 7 8]
226 [ 9 10 11]
227 ]
228 This method can be called on ndarrays that have bad values. The
230 remainder of the arguments should be Perl scalars indicating the
231 position to set as bad. The output ndarray will have bad values and
232 will have its badflag turned on.
233 setbadif
235 Signature: (a(); int mask(); [o]b())
236 Set elements bad based on the supplied mask, otherwise copy across the
238 data.
239 pdl> $x = sequence(5,5)
241 pdl> $x = $x->setbadif( $x % 2 )
242 pdl> p "a badflag: ", $x->badflag, "\n"
243 a badflag: 1
244 pdl> p "a is\n$x"
245 [
246 [ 0 BAD 2 BAD 4]
247 [BAD 6 BAD 8 BAD]
248 [ 10 BAD 12 BAD 14]
249 [BAD 16 BAD 18 BAD]
250 [ 20 BAD 22 BAD 24]
251 ]
252 Unfortunately, this routine can not be run inplace, since the current
254 implementation can not handle the same ndarray used as "a" and "mask"
255 (eg "$x->inplace->setbadif($x%2)" fails). Even more unfortunate: we
256 can't catch this error and tell you.
257 The output always has its bad flag set, even if it does not contain any
259 bad values (use "check_badflag" to check whether there are any bad
260 values in the output). The input ndarray can have bad values: any bad
261 values in the input ndarrays are copied across to the output ndarray.
262 Also see "setvaltobad" and "setnantobad".
264 setvaltobad
266 Signature: (a(); [o]b(); double value)
267 Set bad all those elements which equal the supplied value.
269 $x = sequence(10) % 3;
271 $x->inplace->setvaltobad( 0 );
272 print "$x\n";
273 [BAD 1 2 BAD 1 2 BAD 1 2 BAD]
274 This is a simpler version of "setbadif", but this function can be done
276 inplace. See "setnantobad" if you want to convert NaN/Inf to the bad
277 value.
278 The output always has its bad flag set, even if it does not contain any
280 bad values (use "check_badflag" to check whether there are any bad
281 values in the output). Any bad values in the input ndarrays are copied
282 across to the output ndarray.
283 setnantobad
285 Signature: (a(); [o]b())
286 Sets NaN/Inf values in the input ndarray bad (only relevant for
288 floating-point ndarrays). Can be done inplace.
289 $y = $x->setnantobad;
291 $x->inplace->setnantobad;
292 This method can process ndarrays with bad values: those bad values are
294 propagated into the output ndarray. Any value that is not finite is
295 also set to bad in the output ndarray. If all values from the input
296 ndarray are good and finite, the output ndarray will not have its bad
297 flag set. One more caveat: if done inplace, and if the input ndarray's
298 bad flag is set, it will no
299 setbadtonan
301 Signature: (a(); [o] b();)
302 Sets Bad values to NaN
304 This is only relevant for floating-point ndarrays. The input ndarray
306 can be of any type, but if done inplace, the input must be floating
307 point.
308 $y = $x->setbadtonan;
310 $x->inplace->setbadtonan;
311 This method processes input ndarrays with bad values. The output
313 ndarrays will not contain bad values (insofar as NaN is not Bad as far
314 as PDL is concerned) and the output ndarray does not have its bad flag
315 set. As an inplace operation, it clears the bad flag.
316 setbadtoval
318 Signature: (a(); [o]b(); double newval)
319 Replace any bad values by a (non-bad) value.
321 Can be done inplace. Also see badmask.
323 $x->inplace->setbadtoval(23);
325 print "a badflag: ", $x->badflag, "\n";
326 a badflag: 0
327 The output always has its bad flag cleared. If the input ndarray does
329 not have its bad flag set, then values are copied with no replacement.
330 copybad
332 Signature: (a(); mask(); [o]b())
333 Copies values from one ndarray to another, setting them bad if they are
335 bad in the supplied mask.
336 Can be done inplace.
338 $x = byte( [0,1,3] );
340 $mask = byte( [0,0,0] );
341 $mask->badflag(1);
342 set($mask,1,$mask->badvalue);
343 $x->inplace->copybad( $mask );
344 p $x;
345 [0 BAD 3]
346 It is equivalent to:
348 $c = $x + $mask * 0
350 This handles input ndarrays that are bad. If either $x or $mask have
352 bad values, those values will be marked as bad in the output ndarray
353 and the output ndarray will have its bad value flag set to true.
354
356 Doug Burke (djburke@cpan.org), 2000, 2001, 2003, 2006.
357 The per-ndarray bad value support is by Heiko Klein (2006).
359 CPAN documentation fixes by David Mertens (2010, 2013).
361 All rights reserved. There is no warranty. You are allowed to
363 redistribute this software / documentation under certain conditions.
364 For details, see the file COPYING in the PDL distribution. If this file
365 is separated from the PDL distribution, the copyright notice should be
366 included in the file.
367perl v5.34.0 2021-08-16 Bad(3)