.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bad 3pm"
.TH Bad 3pm "2020-11-19" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDL::Bad \- PDL does process bad values
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1PDL\s0 has been compiled with \s-1WITH_BADVAL\s0 set to 1. Therefore,
you can enter the wonderful world of bad value support in
\&\s-1PDL.\s0
.PP
This module is loaded when you do \f(CW\*(C`use PDL\*(C'\fR,
\&\f(CW\*(C`Use PDL::Lite\*(C'\fR or \f(CW\*(C`PDL::LiteF\*(C'\fR.
.PP
Implementation details are given in
PDL::BadValues.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& use PDL::Bad;
\& print "\enBad value support in PDL is turned " .
\&     $PDL::Bad::Status ? "on" : "off" . ".\en";
\&
\& Bad value support in PDL is turned on.
\&
\& and some other things
.Ve
.SH "VARIABLES"
.IX Header "VARIABLES"
There are currently three variables that this module defines
which may be of use.
.ie n .IP "$PDL::Bad::Status" 4
.el .IP "\f(CW$PDL::Bad::Status\fR" 4
.IX Item "$PDL::Bad::Status"
Set to 1
.ie n .IP "$PDL::Bad::UseNaN" 4
.el .IP "\f(CW$PDL::Bad::UseNaN\fR" 4
.IX Item "$PDL::Bad::UseNaN"
Set to 1 if \s-1PDL\s0 was compiled with \f(CW\*(C`BADVAL_USENAN\*(C'\fR set,
0 otherwise.
.ie n .IP "$PDL::Bad::PerPdl" 4
.el .IP "\f(CW$PDL::Bad::PerPdl\fR" 4
.IX Item "$PDL::Bad::PerPdl"
Set to 1 if \s-1PDL\s0 was compiled with the \fIexperimental\fR
\&\f(CW\*(C`BADVAL_PER_PDL\*(C'\fR option set, 0 otherwise.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.SS "badflag"
.IX Subsection "badflag"
getter/setter for the bad data flag
.PP
.Vb 5
\&  if ( $x\->badflag() ) {
\&    print "Data may contain bad values.\en";
\&  }
\&  $x\->badflag(1);      # set bad data flag
\&  $x\->badflag(0);      # unset bad data flag
.Ve
.PP
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.
.PP
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
\&\fIcheck\fR 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.
.PP
This function works with piddles that have bad values. It
always returns a Perl scalar, so it never returns bad values.
.SS "badvalue"
.IX Subsection "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 \f(CW$PDL_B\fR, \f(CW$PDL_S\fR, etc.
.PP
.Vb 4
\&   $badval = badvalue( float );
\&   $x = ones(ushort,10);
\&   print "The bad data value for ushort is: ",
\&      $x\->badvalue(), "\en";
.Ve
.PP
This can act as a setter (e.g. \f(CW\*(C`$x\->badvalue(23)\*(C'\fR)
if the data type is an integer or \f(CW\*(C`$PDL::Bad::UseNaN == 0\*(C'\fR.
Note that this \fBnever touches the data in the piddle\fR.
That is, if \f(CW$x\fR already has bad values, they will not
be changed to use the given number and if any elements of
\&\f(CW$x\fR have that value, they will unceremoniously be marked
as bad data. See \*(L"setvaltobad\*(R", \*(L"setbadtoval\*(R", and
\&\*(L"setbadif\*(R" for ways to actually modify the data in piddles
.PP
If the \f(CW$PDL::Bad::PerPdl\fR flag is set then it is possible to
change the bad value on a per-piddle basis, so
.PP
.Vb 4
\&    $x = sequence (10);
\&    $x\->badvalue (3); $x\->badflag (1);
\&    $y = sequence (10);
\&    $y\->badvalue (4); $y\->badflag (1);
.Ve
.PP
will set \f(CW$x\fR to be \f(CW\*(C`[0 1 2 BAD 4 5 6 7 8 9]\*(C'\fR and \f(CW$y\fR to be
\&\f(CW\*(C`[0 1 2 3 BAD 5 6 7 8 9]\*(C'\fR. If the flag is not set then both
\&\f(CW$x\fR and \f(CW$y\fR will be set to \f(CW\*(C`[0 1 2 3 BAD 5 6 7 8 9]\*(C'\fR. Please
note that the code to support per-piddle bad values is
\&\fIexperimental\fR in the current release, and it requires that
you modify the settings under which \s-1PDL\s0 is compiled.
.PP
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.
.SS "orig_badvalue"
.IX Subsection "orig_badvalue"
returns the original value used to represent bad values for
a given type.
.PP
This routine operates the same as badvalue,
except you can not change the values.
.PP
It also has an \fIawful\fR name.
.PP
.Vb 4
\&   $orig_badval = orig_badvalue( float );
\&   $x = ones(ushort,10);
\&   print "The original bad data value for ushort is: ", 
\&      $x\->orig_badvalue(), "\en";
.Ve
.PP
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.
.SS "check_badflag"
.IX Subsection "check_badflag"
Clear the bad-value flag of a piddle if it does not
contain any bad values
.PP
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.
.PP
.Vb 1
\& print "State of bad flag == ", $pdl\->check_badflag;
.Ve
.PP
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.
.SS "isbad"
.IX Subsection "isbad"
.Vb 1
\&  Signature: (a(); int [o]b())
.Ve
.PP
Returns a binary mask indicating which values of
the input are bad values
.PP
Returns a 1 if the value is bad, 0 otherwise.
Similar to isfinite.
.PP
.Vb 6
\& $x = pdl(1,2,3);
\& $x\->badflag(1);
\& set($x,1,$x\->badvalue);
\& $y = isbad($x);
\& print $y, "\en";
\& [0 1 0]
.Ve
.PP
This method works with input piddles that are bad. The output piddle
will never contain bad values, but its bad value flag will be the
same as the input piddle's flag.
.SS "isgood"
.IX Subsection "isgood"
.Vb 1
\&  Signature: (a(); int [o]b())
.Ve
.PP
Is a value good?
.PP
Returns a 1 if the value is good, 0 otherwise.
Also see isfinite.
.PP
.Vb 6
\& $x = pdl(1,2,3);
\& $x\->badflag(1);
\& set($x,1,$x\->badvalue);
\& $y = isgood($x);
\& print $y, "\en";
\& [1 0 1]
.Ve
.PP
This method works with input piddles that are bad. The output piddle
will never contain bad values, but its bad value flag will be the
same as the input piddle's flag.
.SS "nbadover"
.IX Subsection "nbadover"
.Vb 1
\&  Signature: (a(n); indx [o] b())
.Ve
.PP
Find the number of bad elements along the 1st dimension.
.PP
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 \fIany\fR dimension.
.PP
.Vb 1
\& $x = nbadover($y);
.Ve
.PP
.Vb 1
\& $spectrum = nbadover $image\->xchg(0,1)
.Ve
.PP
nbadover processes input values that are bad. The output piddle will not have
any bad values, but the bad flag will be set if the input piddle had its bad
flag set.
.SS "ngoodover"
.IX Subsection "ngoodover"
.Vb 1
\&  Signature: (a(n); indx [o] b())
.Ve
.PP
Find the number of good elements along the 1st dimension.
.PP
This function reduces the dimensionality of a piddle
by one by finding the number of good elements
along the 1st dimension.
.PP
By using xchg etc. it is possible to use
\&\fIany\fR dimension.
.PP
.Vb 1
\& $x = ngoodover($y);
.Ve
.PP
.Vb 1
\& $spectrum = ngoodover $image\->xchg(0,1)
.Ve
.PP
ngoodover processes input values that are bad. The output piddle will not have
any bad values, but the bad flag will be set if the input piddle had its bad
flag set.
.SS "nbad"
.IX Subsection "nbad"
Returns the number of bad values in a piddle
.PP
.Vb 1
\& $x = nbad($data);
.Ve
.PP
Accepts good and bad input piddles; output is a Perl scalar
and therefore is always good.
.SS "ngood"
.IX Subsection "ngood"
Returns the number of good values in a piddle
.PP
.Vb 1
\& $x = ngood($data);
.Ve
.PP
Accepts good and bad input piddles; output is a Perl scalar
and therefore is always good.
.SS "setbadat"
.IX Subsection "setbadat"
Set the value to bad at a given position.
.PP
.Vb 1
\& setbadat $piddle, @position
.Ve
.PP
\&\f(CW@position\fR 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!
.PP
.Vb 9
\& 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]
\& ]
.Ve
.PP
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 output piddle will have bad values
and will have its badflag turned on.
.SS "setbadif"
.IX Subsection "setbadif"
.Vb 1
\&  Signature: (a(); int mask(); [o]b())
.Ve
.PP
Set elements bad based on the supplied mask, otherwise
copy across the data.
.PP
.Vb 12
\& pdl> $x = sequence(5,5)
\& pdl> $x = $x\->setbadif( $x % 2 )
\& pdl> p "a badflag: ", $x\->badflag, "\en"
\& a badflag: 1
\& pdl> p "a is\en$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]
\& ]
.Ve
.PP
Unfortunately, this routine can \fInot\fR be run inplace, since the
current implementation can not handle the same piddle used as
\&\f(CW\*(C`a\*(C'\fR and \f(CW\*(C`mask\*(C'\fR (eg \f(CW\*(C`$x\->inplace\->setbadif($x%2)\*(C'\fR fails).
Even more unfortunate: we can't catch this error and tell you.
.PP
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.
.PP
Also see setvaltobad and setnantobad.
.SS "setvaltobad"
.IX Subsection "setvaltobad"
.Vb 1
\&  Signature: (a(); [o]b(); double value)
.Ve
.PP
Set bad all those elements which equal the supplied value.
.PP
.Vb 4
\& $x = sequence(10) % 3;
\& $x\->inplace\->setvaltobad( 0 );
\& print "$x\en";
\& [BAD 1 2 BAD 1 2 BAD 1 2 BAD]
.Ve
.PP
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.
.PP
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.
.SS "setnantobad"
.IX Subsection "setnantobad"
.Vb 1
\&  Signature: (a(); [o]b())
.Ve
.PP
Sets NaN/Inf values in the input piddle bad
(only relevant for floating-point piddles).
Can be done inplace.
.PP
.Vb 2
\& $y = $x\->setnantobad;
\& $x\->inplace\->setnantobad;
.Ve
.PP
This method can process piddles with bad values: those bad values
are propagated 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 \fBnot\fR have its
bad flag set. One more caveat: if done inplace, and if the input piddle's
bad flag is set, it will no
.SS "setbadtonan"
.IX Subsection "setbadtonan"
.Vb 1
\&  Signature: (a(); [o] b();)
.Ve
.PP
Sets Bad values to NaN
.PP
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.
.PP
.Vb 2
\& $y = $x\->setbadtonan;
\& $x\->inplace\->setbadtonan;
.Ve
.PP
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 \s-1PDL\s0 is concerned)
and the output piddle does not have its bad flag set. As an inplace
operation, it clears the bad flag.
.SS "setbadtoval"
.IX Subsection "setbadtoval"
.Vb 1
\&  Signature: (a(); [o]b(); double newval)
.Ve
.PP
Replace any bad values by a (non-bad) value.
.PP
Can be done inplace. Also see
badmask.
.PP
.Vb 3
\& $x\->inplace\->setbadtoval(23);
\& print "a badflag: ", $x\->badflag, "\en";
\& a badflag: 0
.Ve
.PP
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.
.SS "copybad"
.IX Subsection "copybad"
.Vb 1
\&  Signature: (a(); mask(); [o]b())
.Ve
.PP
Copies values from one piddle to another, setting them
bad if they are bad in the supplied mask.
.PP
Can be done inplace.
.PP
.Vb 7
\& $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]
.Ve
.PP
It is equivalent to:
.PP
.Vb 1
\& $c = $x + $mask * 0
.Ve
.PP
This handles input piddles that are bad. If either \f(CW$x\fR
or \f(CW$mask\fR 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.
.SH "CHANGES"
.IX Header "CHANGES"
The \fIexperimental\fR \f(CW\*(C`BADVAL_PER_PDL\*(C'\fR configuration option,
which \- when set \- allows per-piddle bad values, was added
after the 2.4.2 release of \s-1PDL.\s0
The \f(CW$PDL::Bad::PerPdl\fR variable can be
inspected to see if this feature is available.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
The way the \s-1PDL\s0 handles the various bad value settings depends on your
compile-time configuration settings, as held in \f(CW\*(C`perldl.conf\*(C'\fR.
.ie n .IP "$PDL::Config{WITH_BADVAL}" 4
.el .IP "\f(CW$PDL::Config{WITH_BADVAL}\fR" 4
.IX Item "$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.
.ie n .IP "$PDL::Config{BADVAL_USENAN}" 4
.el .IP "\f(CW$PDL::Config{BADVAL_USENAN}\fR" 4
.IX Item "$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.
.ie n .IP "$PDL::Config{BADVAL_PER_PDL}" 4
.el .IP "\f(CW$PDL::Config{BADVAL_PER_PDL}\fR" 4
.IX Item "$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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Doug Burke (djburke@cpan.org), 2000, 2001, 2003, 2006.
.PP
The per-piddle bad value support is by Heiko Klein (2006).
.PP
\&\s-1CPAN\s0 documentation fixes by David Mertens (2010, 2013).
.PP
All rights reserved. There is no warranty. You are allowed to
redistribute this software / documentation under certain conditions. For
details, see the file \s-1COPYING\s0 in the \s-1PDL\s0 distribution. If this file is
separated from the \s-1PDL\s0 distribution, the copyright notice should be
included in the file.