Bad(3) User Contributed Perl Documentation Bad(3)NAMEPDL::Bad - PDL does process bad values
DESCRIPTION
PDL has been compiled with WITH_BADVAL set to 1. Therefore, you can
enter the wonderful world of bad value support in PDL.
This module is loaded when you do "use PDL", "Use PDL::Lite" or
"PDL::LiteF".
Implementation details are given in PDL::BadValues.
SYNOPSIS
use PDL::Bad;
print "\nBad value support in PDL is turned " .
$PDL::Bad::Status ? "on" : "off" . ".\n";
Bad value support in PDL is turned on.
and some other things
VARIABLES
There are currently three variables that this module defines which may
be of use.
$PDL::Bad::Status
Set to 1
$PDL::Bad::UseNaN
Set to 1 if PDL was compiled with "BADVAL_USENAN" set, 0 otherwise.
$PDL::Bad::PerPdl
Set to 1 if PDL was compiled with the experimental "BADVAL_PER_PDL"
option set, 0 otherwise.
FUNCTIONS
badflag
switch on/off/examine bad data flag
if ( $a->badflag() ) {
print "Data may contain bad values.\n";
}
$a->badflag(1); # set bad data flag
$a->badflag(0); # unset bad data flag
A return value of 1 does not guarantee the presence of bad data in a
piddle; all it does is say that we need to check for the presence of
such beasties. To actually find out if there are any bad values present
in a piddle, use the check_badflag method.
Does support bad values.
badvalue
returns the value used to indicate a missing (or bad) element for the
given piddle type. You can give it a piddle, a PDL::Type object, or one
of $PDL_B, $PDL_S, etc.
$badval = badvalue( float );
$a = ones(ushort,10);
print "The bad data value for ushort is: ",
$a->badvalue(), "\n";
If a new value is supplied via a piddle (e.g. "$a->badvalue(23)"), then
the data in the supplied piddle is converted to use the new bad value
as well if the data type is an integer or "$PDL::Bad::UseNaN == 0".
Currently there is no way of automatically converting the bad values of
already existing piddles. This could be supported - e.g. by having a
per-piddle bad value or by storing a time index in the piddle structure
- if required.
If the $PDL::Bad::PerPdl flag is set then it is possible to change the
bad value on a per-piddle basis, so
$a = sequence (10);
$a->badvalue (3); $a->badflag (1);
$b = sequence (10);
$b->badvalue (4); $b->badflag (1);
will set $a to be "[0 1 2 BAD 4 5 6 7 8 9]" and $b to be "[0 1 2 3 BAD
5 6 7 8 9]". If the flag is not set then both $a and $b will be set to
"[0 1 2 3 BAD 5 6 7 8 9]". Please note that the code to support per-
piddle bad values is experimental in the current release.
Does support bad values.
orig_badvalue
returns the original value used to represent bad values for a given
type.
This routine operates the same as badvalue, except you can not change
the values.
It also has an awful name.
$orig_badval = orig_badvalue( float );
$a = ones(ushort,10);
print "The original bad data value for ushort is: ",
$a->orig_badvalue(), "\n";
Does support bad values.
check_badflag
clear the bad-value flag of a piddle if it does not contain any bad
values
Given a piddle whose bad flag is set, check whether it actually
contains any bad values and, if not, clear the flag. It returns the
final state of the bad-value flag.
print "State of bad flag == ", $pdl->check_badflag;
Does support bad values.
isbad
Signature: (a(); int [o]b())
Is a value bad?
Returns a 1 if the value is bad, 0 otherwise. Also see isfinite.
$a = pdl(1,2,3);
$a->badflag(1);
set($a,1,$a->badvalue);
$b = isbad($a);
print $b, "\n";
[0 1 0]
isbad does handle bad values. The output piddles will NOT have their
bad-value flag set.
isgood
Signature: (a(); int [o]b())
Is a value good?
Returns a 1 if the value is good, 0 otherwise. Also see isfinite.
$a = pdl(1,2,3);
$a->badflag(1);
set($a,1,$a->badvalue);
$b = isgood($a);
print $b, "\n";
[1 0 1]
isgood does handle bad values. The output piddles will NOT have their
bad-value flag set.
nbadover
Signature: (a(n); int+ [o]b())
Find the number of bad elements along the 1st dimension.
This function reduces the dimensionality of a piddle by one by finding
the number of bad elements along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = nbadover($b);
$spectrum = nbadover $image->xchg(0,1)
nbadover does handle bad values. It will set the bad-value flag of all
output piddles if the flag is set for any of the input piddles.
ngoodover
Signature: (a(n); int+ [o]b())
Find the number of good elements along the 1st dimension.
This function reduces the dimensionality of a piddle by one by finding
the number of good elements along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$a = ngoodover($b);
$spectrum = ngoodover $image->xchg(0,1)
ngoodover does handle bad values. It will set the bad-value flag of
all output piddles if the flag is set for any of the input piddles.
setbadat
Set the value to bad at a given position.
setbadat $piddle, @position
@position is a coordinate list, of size equal to the number of
dimensions in the piddle. This is a wrapper around set and is probably
mainly useful in test scripts!
pdl> $x = sequence 3,4
pdl> $x->setbadat 2,1
pdl> p $x
[
[ 0 1 2]
[ 3 4 BAD]
[ 6 7 8]
[ 9 10 11]
]
Supports badvalues.
setbadif
Signature: (a(); int mask(); [o]b())
Set elements bad based on the supplied mask, otherwise copy across the
data.
$a = sequence(5,5);
$a = $a->setbadif( $a % 2 );
print "a badflag: ", $a->badflag, "\n";
a badflag: 1
Unfortunately, this routine can not be run inplace, since the current
implementation can not handle the same piddle used as "a" and "mask"
(eg "$a->inplace->setbadif($a%2)" fails).
Also see setvaltobad and setnantobad.
The output always has its bad flag set, even if it does not contain any
bad values (use check_badflag to check whether there are any bad values
in the output). Any bad values in the input piddles are copied across
to the output piddle.
setvaltobad
Signature: (a(); [o]b(); double value)
Set bad all those elements which equal the supplied value.
$a = sequence(10) % 3;
$a->inplace->setvaltobad( 0 );
print "$a\n";
[BAD 1 2 BAD 1 2 BAD 1 2 BAD]
This is a simpler version of setbadif, but this function can be done
inplace. See setnantobad if you want to convert NaN/Inf to the bad
value.
The output always has its bad flag set, even if it does not contain any
bad values (use check_badflag to check whether there are any bad values
in the output). Any bad values in the input piddles are copied across
to the output piddle.
setnantobad
Signature: (a(); [o]b())
Sets NaN/Inf values in the input piddle bad (only relevant for
floating-point piddles). Can be done inplace.
$b = $a->setnantobad;
$a->inplace->setnantobad;
Supports bad values.
setbadtonan
Signature: (a(); [o]b())
Sets Bad values to NaN (only relevant for floating-point piddles). Can
be done inplace and it clears the bad flag.
$b = $a->setbadtonan;
$a->inplace->setbadtonan;
Supports bad values.
setbadtoval
Signature: (a(); [o]b(); double newval)
Replace any bad values by a (non-bad) value.
Can be done inplace. Also see badmask.
$a->inplace->setbadtoval(23);
print "a badflag: ", $a->badflag, "\n";
a badflag: 0
The output always has its bad flag cleared. If the input piddle does
not have its bad flag set, then values are copied with no replacement.
copybad
Signature: (a(); mask(); [o]b())
Copies values from one piddle to another, setting them bad if they are
bad in the supplied mask.
Can be done inplace.
$a = byte( [0,1,3] );
$mask = byte( [0,0,0] );
set($mask,1,$mask->badvalue);
$a->inplace->copybad( $mask );
p $a;
[0 BAD 3]
It is equivalent to:
$c = $a + $mask * 0
Handles bad values.
CHANGES
The experimental "BADVAL_PER_PDL" configuration option, which - when
set - allows per-piddle bad values, was added after the 2.4.2 release
of PDL. The "" variable can be inspected to see if this feature is
available.
CONFIGURATION
The way the PDL handles the various bad value settings depends on your
compile-time configuration settings, as held in "perldl.conf".
$PDL::Config{WITH_BADVAL}
Set this configuration option to a true value if you want bad value
support. The default setting is for this to be true.
$PDL::Config{BADVAL_USENAN}
Set this configuration option to a true value if you want floating-
pont numbers to use NaN to represent the bad value. If set to
false, you can use any number to represent a bad value, which is
generally more flexible. In the default configuration, this is set
to a false value.
$PDL::Config{BADVAL_PER_PDL}
Set this configuration option to a true value if you want each of
your piddles to keep track of their own bad values. This means that
for one piddle you can set the bad value to zero, while in another
piddle you can set the bad value to NaN (or any other useful
number). This is usually set to false.
AUTHOR
Doug Burke (djburke@cpan.org), 2000, 2001, 2003, 2006.
The per-piddle bad value support is by Heiko Klein (2006).
CPAN documentation fixes by David Mertens (2010).
All rights reserved. There is no warranty. You are allowed to
redistribute this software / documentation under certain conditions.
For details, see the file COPYING in the PDL distribution. If this file
is separated from the PDL distribution, the copyright notice should be
included in the file.
perl v5.14.1 2011-07-26 Bad(3)
