Provided by: pdl_2.085-1ubuntu1_amd64 
NAME
PDL::Bad - PDL always processes bad values
DESCRIPTION
This module is loaded when you do "use PDL", "use PDL::Lite" or "use PDL::LiteF".
Implementation details are given in PDL::BadValues.
SYNOPSIS
use PDL::Bad;
print "\nBad value per PDL support in PDL is turned " .
$PDL::Bad::PerPdl ? "on" : "off" . ".\n";
VARIABLES
$PDL::Bad::UseNaN
Set to 0 as of PDL 2.040, as no longer available, though NaN can be used as a badvalue for a given
PDL object.
$PDL::Bad::PerPdl
Set to 1 as of PDL 2.040 as always available.
$PDL::Bad::Status
Set to 1 as of PDL 2.035 as always available.
FUNCTIONS
badflag
getter/setter for the bad data flag
if ( $x->badflag() ) {
print "Data may contain bad values.\n";
}
$x->badflag(1); # set bad data flag
$x->badflag(0); # unset bad data flag
When called as a setter, this modifies the ndarray 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 an ndarray; 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 an ndarray, use the "check_badflag" method.
This function works with ndarrays 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 ndarray type. You can give it
an ndarray, a PDL::Type object, or one of $PDL_B, $PDL_S, etc.
$badval = badvalue( float );
$x = ones(ushort,10);
print "The bad data value for ushort is: ",
$x->badvalue(), "\n";
This can act as a setter (e.g. "$x->badvalue(23)"), including with the value "NaN" for floating-point
types. Note that this never touches the data in the ndarray. That is, if $x already has bad values,
they will not be changed to use the given number and if any elements of $x have that value, they will
unceremoniously be marked as bad data. See "setvaltobad", "setbadtoval", and "setbadif" for ways to
actually modify the data in ndarrays
It is possible to change the bad value on a per-ndarray basis, so
$x = sequence (10);
$x->badvalue (3); $x->badflag (1);
$y = sequence (10);
$y->badvalue (4); $y->badflag (1);
will set $x to be "[0 1 2 BAD 4 5 6 7 8 9]" and $y to be "[0 1 2 3 BAD 5 6 7 8 9]".
This method does not care if you call it on an input ndarray that has bad values. It always returns an
ndarray 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 );
$x = ones(ushort,10);
print "The original bad data value for ushort is: ",
$x->orig_badvalue(), "\n";
This method does not care if you call it on an input ndarray that has bad values. It always returns an
ndarray with the original bad value for the associated type.
check_badflag
Clear the badflag of an ndarray if it does not contain any bad values
Given an ndarray 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 badflag.
print "State of bad flag == ", $pdl->check_badflag;
This method accepts ndarrays with or without bad values. It returns an ndarray with the final badflag.
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.
$x = pdl(1,2,3);
$x->badflag(1);
set($x,1,$x->badvalue);
$y = isbad($x);
print $y, "\n";
[0 1 0]
This method works with input ndarrays that are bad. The output ndarray will never contain bad values, but
its bad value flag will be the same as the input ndarray'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.
$x = pdl(1,2,3);
$x->badflag(1);
set($x,1,$x->badvalue);
$y = isgood($x);
print $y, "\n";
[1 0 1]
This method works with input ndarrays that are bad. The output ndarray will never contain bad values, but
its bad value flag will be the same as the input ndarray's flag.
nbadover
Signature: (a(n); indx [o] b())
Find the number of bad elements along the 1st dimension.
This function reduces the dimensionality of an ndarray 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.
$x = nbadover($y);
$spectrum = nbadover $image->transpose
nbadover processes input values that are bad. The output ndarray will not have any bad values, but the
bad flag will be set if the input ndarray had its bad flag set.
ngoodover
Signature: (a(n); indx [o] b())
Find the number of good elements along the 1st dimension.
This function reduces the dimensionality of an ndarray by one by finding the number of good elements
along the 1st dimension.
By using xchg etc. it is possible to use any dimension.
$x = ngoodover($y);
$spectrum = ngoodover $image->transpose
ngoodover processes input values that are bad. The output ndarray will not have any bad values, but the
bad flag will be set if the input ndarray had its bad flag set.
nbad
Returns the number of bad values in an ndarray
$x = nbad($data);
Accepts good and bad input ndarrays; output is an ndarray and is always good.
ngood
Returns the number of good values in an ndarray
$x = ngood($data);
Accepts good and bad input ndarrays; output is an ndarray and is always good.
setbadat
Set the value to bad at a given position.
setbadat $ndarray, @position
@position is a coordinate list, of size equal to the number of dimensions in the ndarray. 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 ndarrays that have bad values. The remainder of the arguments should be
Perl scalars indicating the position to set as bad. The output ndarray 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> $x = sequence(5,5)
pdl> $x = $x->setbadif( $x % 2 )
pdl> p "a badflag: ", $x->badflag, "\n"
a badflag: 1
pdl> p "a is\n$x"
[
[ 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 ndarray used as "a" and "mask" (eg "$x->inplace->setbadif($x%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 ndarray can have bad values: any bad
values in the input ndarrays are copied across to the output ndarray.
Also see "setvaltobad" and "setnantobad".
setvaltobad
Signature: (a(); [o]b(); double value)
Set bad all those elements which equal the supplied value.
$x = sequence(10) % 3;
$x->inplace->setvaltobad( 0 );
print "$x\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 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 ndarrays are
copied across to the output ndarray.
setnantobad
Signature: (a(); [o]b())
Sets NaN values (for complex, where either is NaN) in the input ndarray bad (only relevant for floating-
point ndarrays). Can be done inplace.
$y = $x->setnantobad;
$x->inplace->setnantobad;
This method can process ndarrays with bad values: those bad values are propagated into the output
ndarray. Any value that is not a number (before version 2.040 the test was for "not finite") is also set
to bad in the output ndarray. If all values from the input ndarray are good, the output ndarray will not
have its bad flag set.
setinftobad
Signature: (a(); [o]b())
Sets non-finite values (for complex, where either is non-finite) in the input ndarray bad (only relevant
for floating-point ndarrays). Can be done inplace.
$y = $x->setinftobad;
$x->inplace->setinftobad;
This method can process ndarrays with bad values: those bad values are propagated into the output
ndarray. Any value that is not finite is also set to bad in the output ndarray. If all values from the
input ndarray are finite, the output ndarray will not have its bad flag set.
setnonfinitetobad
Signature: (a(); [o]b())
Sets non-finite values (for complex, where either is non-finite) in the input ndarray bad (only relevant
for floating-point ndarrays). Can be done inplace.
$y = $x->setnonfinitetobad;
$x->inplace->setnonfinitetobad;
This method can process ndarrays with bad values: those bad values are propagated into the output
ndarray. Any value that is not finite is also set to bad in the output ndarray. If all values from the
input ndarray are finite, the output ndarray will not have its bad flag set.
setbadtonan
Signature: (a(); [o] b();)
Sets Bad values to NaN
This is only relevant for floating-point ndarrays. The input ndarray can be of any type, but if done
inplace, the input must be floating point.
$y = $x->setbadtonan;
$x->inplace->setbadtonan;
This method processes input ndarrays with bad values. The output ndarrays will not contain bad values
(insofar as NaN is not Bad as far as PDL is concerned) and the output ndarray 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".
$x->inplace->setbadtoval(23);
print "a badflag: ", $x->badflag, "\n";
a badflag: 0
The output always has its bad flag cleared. If the input ndarray does not have its bad flag set, then
values are copied with no replacement.
badmask
Signature: (a(); b(); [o]c())
Clears all "infs" and "nans" in $a to the corresponding value in $b.
badmask can be run with $x inplace:
badmask($x->inplace,0);
$x->inplace->badmask(0);
If bad values are present, these are also cleared.
copybad
Signature: (a(); mask(); [o]b())
Copies values from one ndarray to another, setting them bad if they are bad in the supplied mask.
Can be done inplace.
$x = byte( [0,1,3] );
$mask = byte( [0,0,0] );
$mask->badflag(1);
set($mask,1,$mask->badvalue);
$x->inplace->copybad( $mask );
p $x;
[0 BAD 3]
It is equivalent to:
$c = $x + $mask * 0
This handles input ndarrays that are bad. If either $x or $mask have bad values, those values will be
marked as bad in the output ndarray and the output ndarray will have its bad value flag set to true.
locf
Signature: (a(n); [o]b(n))
Last Observation Carried Forward - replace every BAD value with the most recent non-BAD value prior to
it. Any leading BADs will be set to 0.
locf processes bad values. It will set the bad-value flag of all output ndarrays if the flag is set for
any of the input ndarrays.
AUTHOR
Doug Burke (djburke@cpan.org), 2000, 2001, 2003, 2006.
The per-ndarray 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.
perl v5.38.2 2024-04-10 Bad(3pm)