1Bad(3)                User Contributed Perl Documentation               Bad(3)
2
3
4

NAME

6       PDL::Bad - PDL does process bad values
7

DESCRIPTION

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
12       This module is loaded when you do "use PDL", "Use PDL::Lite" or
13       "PDL::LiteF".
14
15       Implementation details are given in PDL::BadValues.
16

SYNOPSIS

18        use PDL::Bad;
19        print "\nBad value support in PDL is turned " .
20            $PDL::Bad::Status ? "on" : "off" . ".\n";
21
22        Bad value support in PDL is turned on.
23
24        and some other things
25

VARIABLES

27       There are currently three variables that this module defines which may
28       be of use.
29
30       $PDL::Bad::Status
31           Set to 1
32
33       $PDL::Bad::UseNaN
34           Set to 1 if PDL was compiled with "BADVAL_USENAN" set, 0 otherwise.
35
36       $PDL::Bad::PerPdl
37           Set to 1 if PDL was compiled with the experimental "BADVAL_PER_PDL"
38           option set, 0 otherwise.
39

FUNCTIONS

41   badflag
42       getter/setter for the bad data flag
43
44         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
50       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
54       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
59       This function works with piddles that have bad values. It always
60       returns a Perl scalar, so it never returns bad values.
61
62   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
67          $badval = badvalue( float );
68          $x = ones(ushort,10);
69          print "The bad data value for ushort is: ",
70             $x->badvalue(), "\n";
71
72       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
80       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
83           $x = sequence (10);
84           $x->badvalue (3); $x->badflag (1);
85           $y = sequence (10);
86           $y->badvalue (4); $y->badflag (1);
87
88       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
94       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
98   orig_badvalue
99       returns the original value used to represent bad values for a given
100       type.
101
102       This routine operates the same as badvalue, except you can not change
103       the values.
104
105       It also has an awful name.
106
107          $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
112       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
116   check_badflag
117       Clear the bad-value flag of a piddle if it does not contain any bad
118       values
119
120       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
124        print "State of bad flag == ", $pdl->check_badflag;
125
126       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
130   isbad
131         Signature: (a(); int [o]b())
132
133       Returns a binary mask indicating which values of the input are bad
134       values
135
136       Returns a 1 if the value is bad, 0 otherwise.  Similar to isfinite.
137
138        $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
145       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
149   isgood
150         Signature: (a(); int [o]b())
151
152       Is a value good?
153
154       Returns a 1 if the value is good, 0 otherwise.  Also see isfinite.
155
156        $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
163       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
167   nbadover
168         Signature: (a(n); indx [o] b())
169
170       Find the number of bad elements along the 1st dimension.
171
172       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
178        $x = nbadover($y);
179
180        $spectrum = nbadover $image->xchg(0,1)
181
182       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
186   ngoodover
187         Signature: (a(n); indx [o] b())
188
189       Find the number of good elements along the 1st dimension.
190
191       This function reduces the dimensionality of a piddle by one by finding
192       the number of good elements along the 1st dimension.
193
194       By using xchg etc. it is possible to use any dimension.
195
196        $x = ngoodover($y);
197
198        $spectrum = ngoodover $image->xchg(0,1)
199
200       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
204   nbad
205       Returns the number of bad values in a piddle
206
207        $x = nbad($data);
208
209       Accepts good and bad input piddles; output is a Perl scalar and
210       therefore is always good.
211
212   ngood
213       Returns the number of good values in a piddle
214
215        $x = ngood($data);
216
217       Accepts good and bad input piddles; output is a Perl scalar and
218       therefore is always good.
219
220   setbadat
221       Set the value to bad at a given position.
222
223        setbadat $piddle, @position
224
225       @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
229        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
239       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
244   setbadif
245         Signature: (a(); int mask(); [o]b())
246
247       Set elements bad based on the supplied mask, otherwise copy across the
248       data.
249
250        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
263       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
268       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
273       Also see setvaltobad and setnantobad.
274
275   setvaltobad
276         Signature: (a(); [o]b(); double value)
277
278       Set bad all those elements which equal the supplied value.
279
280        $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
285       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
289       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
294   setnantobad
295         Signature: (a(); [o]b())
296
297       Sets NaN/Inf values in the input piddle bad (only relevant for
298       floating-point piddles).  Can be done inplace.
299
300        $y = $x->setnantobad;
301        $x->inplace->setnantobad;
302
303       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
310   setbadtonan
311         Signature: (a(); [o] b();)
312
313       Sets Bad values to NaN
314
315       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
318        $y = $x->setbadtonan;
319        $x->inplace->setbadtonan;
320
321       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
326   setbadtoval
327         Signature: (a(); [o]b(); double newval)
328
329       Replace any bad values by a (non-bad) value.
330
331       Can be done inplace. Also see badmask.
332
333        $x->inplace->setbadtoval(23);
334        print "a badflag: ", $x->badflag, "\n";
335        a badflag: 0
336
337       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
340   copybad
341         Signature: (a(); mask(); [o]b())
342
343       Copies values from one piddle to another, setting them bad if they are
344       bad in the supplied mask.
345
346       Can be done inplace.
347
348        $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
356       It is equivalent to:
357
358        $c = $x + $mask * 0
359
360       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

CHANGES

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

CONFIGURATION

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
374       $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
378       $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
385       $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

AUTHOR

393       Doug Burke (djburke@cpan.org), 2000, 2001, 2003, 2006.
394
395       The per-piddle bad value support is by Heiko Klein (2006).
396
397       CPAN documentation fixes by David Mertens (2010, 2013).
398
399       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.
404
405
406
407perl v5.30.2                      2020-04-02                            Bad(3)
Impressum