NAME¶
PDL::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¶
getter/setter for the 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
When called as a setter, this modifies the piddle on which it is called. This
always returns a Perl scalar with the final value of the bad 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.
This function works with piddles that have bad values. It always returns a Perl
scalar, so it never returns 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";
This can act as a setter (e.g. "$a->badvalue(23)") if the data type
is an integer or "$PDL::Bad::UseNaN == 0". Note that this
never
touches the data in the piddle. That is, if $a already has bad values,
they will not be changed to use the given number and if any elements of $a
have that value, they will unceremoniously be marked as bad data. See
"setvaltobad", "setbadtoval", and "setbadif" for
ways to actually modify the data in piddles
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, and it
requires that you modify the settings under which PDL is compiled.
This method does not care if you call it on an input piddle that has bad values.
It always returns a Perl scalar with the current or new bad value.
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";
This method does not care if you call it on an input piddle that has bad values.
It always returns a Perl scalar with the original bad value for the associated
type.
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;
This method accepts piddles with or without bad values. It returns a Perl scalar
with the final bad-value flag, so it never returns bad values itself.
isbad¶
Signature: (a(); int [o]b())
Returns a binary mask indicating which values of the input are bad values
Returns a 1 if the value is bad, 0 otherwise. Similar to isfinite.
$a = pdl(1,2,3);
$a->badflag(1);
set($a,1,$a->badvalue);
$b = isbad($a);
print $b, "\n";
[0 1 0]
This method works with input piddles that are bad. The ouptut piddle will never
contain bad values, but its bad value flag will be the same as the input
piddle's flag.
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]
This method works with input piddles that are bad. The ouptut piddle will never
contain bad values, but its bad value flag will be the same as the input
piddle's flag.
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. In this sense it shares much
in common with the functions defined in PDL::Ufunc. In particular, by using
xchg and similar dimension rearranging methods, it is possible to perform this
calculation over
any dimension.
$a = nbadover($b);
$spectrum = nbadover $image->xchg(0,1)
nbadover processes input values that are bad. The ouput piddle will not have any
bad values, but the bad flag will be set if the input piddle had its bad flag
set.
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 processes input values that are bad. The ouput piddle will not have
any bad values, but the bad flag will be set if the input piddle had its bad
flag set.
nbad¶
Returns the number of bad values in a piddle
$x = nbad($data);
Accepts good and bad input piddles; output is a Perl scalar and therefore is
always good.
ngood¶
Returns the number of good values in a piddle
$x = ngood($data);
Accepts good and bad input piddles; output is a Perl scalar and therefore is
always good.
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]
]
This method can be called on piddles that have bad values. The remainder of the
arguments should be Perl scalars indicating the position to set as bad. The
ouptut piddle will have bad values and will have its badflag turned on.
setbadif¶
Signature: (a(); int mask(); [o]b())
Set elements bad based on the supplied mask, otherwise copy across the data.
pdl> $a = sequence(5,5)
pdl> $a = $a->setbadif( $a % 2 )
pdl> p "a badflag: ", $a->badflag, "\n"
a badflag: 1
pdl> p "a is\n$a"
[
[ 0 BAD 2 BAD 4]
[BAD 6 BAD 8 BAD]
[ 10 BAD 12 BAD 14]
[BAD 16 BAD 18 BAD]
[ 20 BAD 22 BAD 24]
]
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).
Even more unfortunate: we can't catch this error and tell you.
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). The input piddle can have bad values: any bad values in the input
piddles are copied across to the output piddle.
Also see setvaltobad and setnantobad.
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;
This method can process piddles with bad values: those bad values are propogated
into the output piddle. Any value that is not finite is also set to bad in the
output piddle. If all values from the input piddle are good and finite, the
output piddle will
not have its bad flag set. One more caveat: if done
inplace, and if the input piddle's bad flag is set, it will no
setbadtonan¶
Signature: (a(); [o] b();)
Sets Bad values to NaN
This is only relevant for floating-point piddles. The input piddle can be of any
type, but if done inplace, the input must be floating point.
$b = $a->setbadtonan;
$a->inplace->setbadtonan;
This method processes input piddles with bad values. The output piddles will not
contain bad values (insofar as NaN is not Bad as far as PDL is concerned) and
the output piddle does not have its bad flag set. As an inplace operation, it
clears the bad flag.
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
This handles input piddles that are bad. If either $a or $mask have bad values,
those values will be marked as bad in the output piddle and the output piddle
will have its bad value flag set to true.
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 $PDL::Bad::PerPdl 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, 2013).
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.