Christian Soeller > PDL-2.4.3 > PDL::Bad

Download:
PDL-2.4.3.tar.gz

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Source   Latest Release: PDL-2.007_04

AUTHOR ^

Doug Burke (djburke@cpan.org), 2000, 2001, 2003, 2006.

The per-piddle bad value support is by Heiko Klein (2006).

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.

';

#########################################################

# if no bad-value support, this is easy

unless ( $bvalflag ) {

    pp_addpm({At=>'Top'},<<'!NO!SUBS!');

NAME ^

PDL::Bad - PDL does not process bad values

DESCRIPTION ^

PDL has been compiled with WITH_BADVAL either 0 or undef, so it does not contain any bad-value support code. Actually, a number of methods are defined, but they are only placeholders to make writing other code, that has to handle WITH_BADVAL being true or false, easier.

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 off.

VARIABLES ^

There are currently three variables that this module defines which may be of use.

$PDL::Bad::Status

Set to 0

$PDL::Bad::UseNaN

Set to 0

$PDL::Bad::PerPdl

Set to 0

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.

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.

$author

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.

Is a value $name?

Returns a 1 if the value is $name, 0 otherwise. Also see isfinite.

 \$a = pdl(1,2,3);
 \$a->badflag(1);
 set(\$a,1,\$a->badvalue);
 \$b = is$name(\$a);
 print \$b, \"\\n\";
 $out

"; } # isdocs()

pp_def( 'isbad', HandleBad => 1, Pars => 'a(); int [o]b();', Code => '$b() = 0;', BadCode => '$b() = $ISBAD(a());', CopyBadStatusCode => '', Doc => isdocs("bad","[0 1 0]"), );

pp_def( 'isgood', HandleBad => 1, Pars => 'a(); int [o]b();', Code => '$b() = 1;', BadCode => '$b() = $ISGOOD(a());', CopyBadStatusCode => '', Doc => isdocs("good","[1 0 1]"), );

# modified from primitive.pd # sub projectdocs { my $name = shift; my $op = shift; return <<EOD;

Find the number of $name elements along the 1st dimension.

This function reduces the dimensionality of a piddle by one by finding the number of $name elements along the 1st dimension.

By using xchg etc. it is possible to use any dimension.

 \$a = $op(\$b);
 \$spectrum = $op \$image->xchg(0,1)

$op->[0]

Returns the number of $op->[2] values in a piddle

 \$x = $op->[0](\$data);

Does support bad values.

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!

 perldl> $x = sequence 3,4
 perldl> $x->setbadat 2,1
 perldl> p $x
 [
  [  0   1   2]
  [  3   4 BAD]
  [  6   7   8]
  [  9  10  11]
 ]

Supports badvalues.

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.

', BadDoc => '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. ', ); # pp_def: setbadif

# this is useful because $a->setbadif( $a == 23 ) # is common and that can't be done inplace # # this doesn't need a BadCode section pp_def( 'setvaltobad', HandleBad => 1, Pars => 'a(); [o]b();', OtherPars => 'double value;', Inplace => 1, CopyBadStatusCode => 'if ( a == b && $ISPDLSTATEGOOD(a) ) PDL->propogate_badflag( b, 1 ); /* propogate badflag if inplace */ $SETPDLSTATEBAD(b); /* always make sure the output is "bad" */ ', Code => 'if ( $a() == $COMP(value) ) { $SETBAD(b()); } else { $b() = $a(); }', Doc => ' =for ref

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.

', BadDoc => '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. ', ); # pp_def: setvaltobad

# setnantobad \ are straight copies if $PDL::Bad::UseNaN == 1 # setbadtonan / # if ( $usenan ) { pp_add_exported( '', 'setnantobad setbadtonan' ); pp_addpm(<<'!NO!SUBS!');

setnantobad

Sets NaN/Inf values in the input piddle bad (only relevant for floating-point piddles). Can be done inplace.

As $PDL::Bad::UseNan == 1, this is just a copy with a call to check_badflag() thrown in.

 $b = $a->setnantobad;
 $a->inplace->setnantobad;

Supports bad values.

setbadtonan

Sets Bad values to NaN (only relevant for floating-point piddles). Can be done inplace.

As $PDL::Bad::UseNan == 1, this is just a copy, with the bad flag being cleared.

 $b = $a->setbadtonan;
 $a->inplace->setbadtonan;

Supports bad values.

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;

', BadDoc => 'Supports bad values.', ); # pp_def: setnantobad

pp_def( 'setbadtonan', HandleBad => 1, Pars => 'a(); [o]b();', GenericTypes => [ 'F', 'D' ], Inplace => 1, CopyBadStatusCode => 'if ( a == b ) PDL->propogate_badflag( b, 0 ); /* propogate cleared badflag if inplace */ $SETPDLSTATEGOOD(b); /* always make sure the output is "good" */ ', Code => 'if ( $ISBAD(a()) ) { $b() = $TFD(_nan_float,_nan_double); } /* _nan_xxx set up at top of file */ else { $b() = $a(); } ', Doc => ' =for ref

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;

', BadDoc => 'Supports bad values.', ); # pp_def: setbadtonan

} # if: $usenan

# renamed replacebad by setbadtoval pp_def( 'setbadtoval', HandleBad => 1, Pars => 'a(); [o]b();', OtherPars => 'double newval;', Inplace => 1, Code => '$b() = $a();', BadCode => '$GENERIC(b) replace = ($GENERIC(b)) $COMP(newval); $GENERIC(b) a_val; threadloop %{ a_val = $a(); if ( $ISBADVAR(a_val,a) ) { $b() = replace; } else { $b() = a_val; } %}', CopyBadStatusCode => 'if ( a == b && $ISPDLSTATEBAD(a) ) PDL->propogate_badflag( b, 0 ); /* propogate badflag if inplace AND its changed */ $SETPDLSTATEGOOD(b); /* always make sure the output is "good" */ ', Doc => ' =for ref

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

', BadDoc => '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. ', ); # pp_def: setbadtoval

pp_def( 'copybad', HandleBad => 1, Pars => 'a(); mask(); [o]b();', Inplace => [ 'a' ], Code => '$b() = $a();', BadCode => 'if ( $ISBAD(mask()) ) { $SETBAD(b()); } else { $b() = $a(); }', CopyBadStatusCode => 'if ( $BADFLAGCACHE() ) { if ( a == b && $ISPDLSTATEGOOD(a) ) { PDL->propogate_badflag( b, 1 ); /* have inplace op AND badflag has changed */ } $SETPDLSTATEBAD(b); }', Doc => ' =for ref

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

', BadDoc => 'Handles bad values.',

    ); # pp_def: copybad

pp_done;

## End

syntax highlighting: