PDLx::Mask

Typically PDL uses bad values to mark elements in a piddle which contain
invalid data. When multiple piddles should have the same elements marked
as invalid, a separate *mask* piddle (whose values are true for valid
data and false otherwise) is often used.

PDLx::Mask in concert with PDLx::MaskedData simplifies the management of
multiple piddles sharing the same mask. PDLx::Mask is the shared mask,
and PDLx::MaskedData is a specialized piddle which will dynamically
respond to changes in the mask, so that they are always up-to-date.

Additionally, invalid elements in the data piddles may automatically be
added to the shared mask, so that there is a consistent view of valid
elements across all piddles.

  Details

PDLx::Mask is a subclass of PDL which manages a mask across on or more
piddles. It can be used directly as a piddle, but be careful not to
change its contents inadvertently. *It should only be manipulated via
the provided methods or overloaded operators.*

It maintains two views of the mask:

1   the original *base* mask; and

2   the *effective* mask, which is the base mask combined with
    additional invalid elements from the data piddles.

The subscribe method is used to register callbacks to be invoked when
the mask has been changed. Multiple subscriptions are allowed; each can
register two callbacks:

*   A subroutine invoked when the mask has changed. It is passed a
    piddle containing the mask. It should not alter it.

*   A subroutine which will return a data mask. If the data mask
    changes, the mask's update method *must* be called.

INSTALLATION

This is a Perl module distribution. It should be installed with whichever
tool you use to manage your installation of Perl, e.g. any of

  cpanm .
  cpan  .
  cpanp -i .

Consult http://www.cpan.org/modules/INSTALL.html for further instruction.
Should you wish to install this module manually, the procedure is

  perl Build.PL
  ./Build
  ./Build test
  ./Build install

COPYRIGHT AND LICENSE

This software is Copyright (c) 2016 by Smithsonian Astrophysical
Observatory.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007
