MooX::PDL::Role::Proxy

MooX::PDL::Role::Proxy is a Moo::Role which turns its consumer into a
proxy object for some of its attributes, which are assumed to be PDL
objects (or other proxy objects). A subset of PDL methods applied to the
proxy object are applied to the selected attributes. (See PDL::QuckStart
for more information on PDL and its objects (ndarrays)).

As an example, consider an object representing a set of detected events
(think physics, not computing), which contains metadata describing the
events as well as ndarrays representing event position, energy, and
arrival time. The structure might look like this:

  {
      metadata => \%metadata,
      time   => $time,         # ndarray
      x      => $x,            # ndarray
      y      => $y,            # ndarray
      energy => $energy        # ndarray
  }

To filter the events on energy would traditionally be performed
explicitly on each element in the structure, e.g.

  my $mask = which( $obj->{energy} > 20 );

  my $copy = {};
  $copy->{time}   = $obj->{time}->where( $mask );
  $copy->{x}      = $obj->{x}->where( $mask );
  $copy->{y}      = $obj->{y}->where( $mask );
  $copy->{energy} = $obj->{energy}->where( $mask );

Or, more succinctly,

  $new->{$_} = $obj->{$_}->where( $mask ) for qw( time x y energy );

With MooX::PDL::Role::Proxy this turns into

  my $copy = $obj->where( $mask );

Or, if the results should be stored in the same object,

  $obj->inplace->where( $mask );

  Usage and Class requirements

Each attribute to be operated on by the common "PDL"-like operators
should be given a "ndarray" option, e.g.

  has p1 => (
      is      => 'rw',
      default => sub { sequence( 10 ) },
      ndarray  => 1,
  );

(Treat the option value as an identifier for the group of ndarrays which
should be operated on, rather than as a boolean).

  Results of Operations

The results of operations may either be stored "In Place" or returned in
"Cloned Objects". By default, operations return cloned objects.

   In Place

Use one of the following methods, "inplace", "inplace_store",
"inplace_set". to indicate that the next in-place aware operation should
be performed in-place. After the operation is completed, the in-place
flag will be reset.

To support inplace operations, attributes tagged with the "ndarray"
option must have write accessors. They may be public or private.

   Cloned Objects

The class must provide a a clone method. If cloning an object requires
extra arguments, use "_set_clone_args" and "_clear_clone_args" to set or
reset the arguments.

If the class provides the _clone_with_ndarrays method, then it will be
called as

   $object->_clone_with_ndarrays( \%ndarrays, ?$arg);

where $arg will only be passed if "_set_clone_args" was called.

For backwards compatibility, the clone_with_piddles method is supported,
but it is not possible to pass in extra arguments. It will be called as

   $object->clone_with_piddles ( %ndarrays );

  Nested Proxy Objects

A class with the applied role should respond equivalently to a true
ndarray when the supported methods are called on it (it's a bug
otherwise). Thus, it is possible for a proxy object to contain another,
and as long as the contained object has the "ndarray" attribute set, the
supported method will be applied to the contained object appropriately.

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) 2018 by Smithsonian Astrophysical
Observatory.

This is free software, licensed under:

  The GNU General Public License, Version 3, June 2007