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 switch on/off/examine bad data flag
43 if ( $a->badflag() ) {
45 print "Data may contain bad values.\n";
46 }
47 $a->badflag(1); # set bad data flag
48 $a->badflag(0); # unset bad data flag
49 A return value of 1 does not guarantee the presence of bad data in a
51 piddle; all it does is say that we need to check for the presence of
52 such beasties. To actually find out if there are any bad values present
53 in a piddle, use the check_badflag method.
54 Does support bad values.
56 badvalue
58 returns the value used to indicate a missing (or bad) element for the
59 given piddle type. You can give it a piddle, a PDL::Type object, or one
60 of $PDL_B, $PDL_S, etc.
61 $badval = badvalue( float );
63 $a = ones(ushort,10);
64 print "The bad data value for ushort is: ",
65 $a->badvalue(), "\n";
66 If a new value is supplied via a piddle (e.g. "$a->badvalue(23)"), then
68 the data in the supplied piddle is converted to use the new bad value
69 as well if the data type is an integer or "$PDL::Bad::UseNaN == 0".
70 Currently there is no way of automatically converting the bad values of
72 already existing piddles. This could be supported - e.g. by having a
73 per-piddle bad value or by storing a time index in the piddle structure
74 - if required.
75 If the $PDL::Bad::PerPdl flag is set then it is possible to change the
77 bad value on a per-piddle basis, so
78 $a = sequence (10);
80 $a->badvalue (3); $a->badflag (1);
81 $b = sequence (10);
82 $b->badvalue (4); $b->badflag (1);
83 will set $a to be "[0 1 2 BAD 4 5 6 7 8 9]" and $b to be "[0 1 2 3 BAD
85 5 6 7 8 9]". If the flag is not set then both $a and $b will be set to
86 "[0 1 2 3 BAD 5 6 7 8 9]". Please note that the code to support per-
87 piddle bad values is experimental in the current release.
88 Does support bad values.
90 orig_badvalue
92 returns the original value used to represent bad values for a given
93 type.
94 This routine operates the same as badvalue, except you can not change
96 the values.
97 It also has an awful name.
99 $orig_badval = orig_badvalue( float );
101 $a = ones(ushort,10);
102 print "The original bad data value for ushort is: ",
103 $a->orig_badvalue(), "\n";
104 Does support bad values.
106 check_badflag
108 clear the bad-value flag of a piddle if it does not contain any bad
109 values
110 Given a piddle whose bad flag is set, check whether it actually
112 contains any bad values and, if not, clear the flag. It returns the
113 final state of the bad-value flag.
114 print "State of bad flag == ", $pdl->check_badflag;
116 Does support bad values.
118 isbad
120 Signature: (a(); int [o]b())
121 Is a value bad?
123 Returns a 1 if the value is bad, 0 otherwise. Also see isfinite.
125 $a = pdl(1,2,3);
127 $a->badflag(1);
128 set($a,1,$a->badvalue);
129 $b = isbad($a);
130 print $b, "\n";
131 [0 1 0]
132 isbad does handle bad values. The output piddles will NOT have their
134 bad-value flag set.
135 isgood
137 Signature: (a(); int [o]b())
138 Is a value good?
140 Returns a 1 if the value is good, 0 otherwise. Also see isfinite.
142 $a = pdl(1,2,3);
144 $a->badflag(1);
145 set($a,1,$a->badvalue);
146 $b = isgood($a);
147 print $b, "\n";
148 [1 0 1]
149 isgood does handle bad values. The output piddles will NOT have their
151 bad-value flag set.
152 nbadover
154 Signature: (a(n); int+ [o]b())
155 Find the number of bad elements along the 1st dimension.
157 This function reduces the dimensionality of a piddle by one by finding
159 the number of bad elements along the 1st dimension.
160 By using xchg etc. it is possible to use any dimension.
162 $a = nbadover($b);
164 $spectrum = nbadover $image->xchg(0,1)
166 nbadover does handle bad values. It will set the bad-value flag of all
168 output piddles if the flag is set for any of the input piddles.
169 ngoodover
171 Signature: (a(n); int+ [o]b())
172 Find the number of good elements along the 1st dimension.
174 This function reduces the dimensionality of a piddle by one by finding
176 the number of good elements along the 1st dimension.
177 By using xchg etc. it is possible to use any dimension.
179 $a = ngoodover($b);
181 $spectrum = ngoodover $image->xchg(0,1)
183 ngoodover does handle bad values. It will set the bad-value flag of
185 all output piddles if the flag is set for any of the input piddles.
186 nbad
188 Returns the number of bad values in a piddle
189 $x = nbad($data);
191 Does support bad values.
193 ngood
195 Returns the number of good values in a piddle
196 $x = ngood($data);
198 Does support bad values.
200 setbadat
202 Set the value to bad at a given position.
203 setbadat $piddle, @position
205 @position is a coordinate list, of size equal to the number of
207 dimensions in the piddle. This is a wrapper around set and is probably
208 mainly useful in test scripts!
209 perldl> $x = sequence 3,4
211 perldl> $x->setbadat 2,1
212 perldl> p $x
213 [
214 [ 0 1 2]
215 [ 3 4 BAD]
216 [ 6 7 8]
217 [ 9 10 11]
218 ]
219 Supports badvalues.
221 setbadif
223 Signature: (a(); int mask(); [o]b())
224 Set elements bad based on the supplied mask, otherwise copy across the
226 data.
227 $a = sequence(5,5);
229 $a = $a->setbadif( $a % 2 );
230 print "a badflag: ", $a->badflag, "\n";
231 a badflag: 1
232 Unfortunately, this routine can not be run inplace, since the current
234 implementation can not handle the same piddle used as "a" and "mask"
235 (eg "$a->inplace->setbadif($a%2)" fails).
236 Also see setvaltobad and setnantobad.
238 The output always has its bad flag set, even if it does not contain any
240 bad values (use check_badflag to check whether there are any bad values
241 in the output). Any bad values in the input piddles are copied across
242 to the output piddle.
243 setvaltobad
245 Signature: (a(); [o]b(); double value)
246 Set bad all those elements which equal the supplied value.
248 $a = sequence(10) % 3;
250 $a->inplace->setvaltobad( 0 );
251 print "$a\n";
252 [BAD 1 2 BAD 1 2 BAD 1 2 BAD]
253 This is a simpler version of setbadif, but this function can be done
255 inplace. See setnantobad if you want to convert NaN/Inf to the bad
256 value.
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 values
260 in the output). Any bad values in the input piddles are copied across
261 to the output piddle.
262 setnantobad
264 Signature: (a(); [o]b())
265 Sets NaN/Inf values in the input piddle bad (only relevant for
267 floating-point piddles). Can be done inplace.
268 $b = $a->setnantobad;
270 $a->inplace->setnantobad;
271 Supports bad values.
273 setbadtonan
275 Signature: (a(); [o]b())
276 Sets Bad values to NaN (only relevant for floating-point piddles). Can
278 be done inplace and it clears the bad flag.
279 $b = $a->setbadtonan;
281 $a->inplace->setbadtonan;
282 Supports bad values.
284 setbadtoval
286 Signature: (a(); [o]b(); double newval)
287 Replace any bad values by a (non-bad) value.
289 Can be done inplace. Also see badmask.
291 $a->inplace->setbadtoval(23);
293 print "a badflag: ", $a->badflag, "\n";
294 a badflag: 0
295 The output always has its bad flag cleared. If the input piddle does
297 not have its bad flag set, then values are copied with no replacement.
298 copybad
300 Signature: (a(); mask(); [o]b())
301 Copies values from one piddle to another, setting them bad if they are
303 bad in the supplied mask.
304 Can be done inplace.
306 $a = byte( [0,1,3] );
308 $mask = byte( [0,0,0] );
309 set($mask,1,$mask->badvalue);
310 $a->inplace->copybad( $mask );
311 p $a;
312 [0 BAD 3]
313 It is equivalent to:
315 $c = $a + $mask * 0
317 Handles bad values.
319
321 The experimental "BADVAL_PER_PDL" configuration option, which - when
322 set - allows per-piddle bad values, was added after the 2.4.2 release
323 of PDL. The "" variable can be inspected to see if this feature is
324 available.
325
327 Doug Burke (djburke@cpan.org), 2000, 2001, 2003, 2006.
328 The per-piddle bad value support is by Heiko Klein (2006).
330 All rights reserved. There is no warranty. You are allowed to
332 redistribute this software / documentation under certain conditions.
333 For details, see the file COPYING in the PDL distribution. If this file
334 is separated from the PDL distribution, the copyright notice should be
335 included in the file.
336perl v5.12.3 2011-03-31 Bad(3)