NAME

PDL::NDBin::Iterator - Iterator object for PDL::NDBin

VERSION

version 0.028

DESCRIPTION

This class provides an iterator object for PDL::NDBin. The iterator object is used to systematically step through all bins and variables using a simple interface. Actions will receive a PDL::NDBin::Iterator object as the first and only argument. This object can then be used to retrieve the current bin and variable, and other information.

METHODS

new()

        my $iter = PDL::NDBin::Iterator->new( bins => \@bins, array => \@array, idx => $idx );

Construct a PDL::NDBin::Iterator object. Requires three arguments:

bins

A reference to an array containing the number of bins per dimension. E.g., [ 4, 7 ] to indicate 4 bins in the first (contiguous) dimension, and 7 bins in the second dimension. There must be at least one bin in every dimension.

array

A reference to an array of ndarrays to operate on. The data values inside the ndarrays don't really matter, as far as the iterator object is concerned. The data inside the ndarrays will be made available to the actions in the order they appear, one by one. There must be at least one element in this array.

idx

A ndarray containing the flattened bin numbers corresponding to the data values in the ndarrays in \@array. The length of this ndarray must match the length of the ndarrays in \@array.

advance()

        while( $iter->advance ) { ... }

Advance the iterator to the next bin and/or active variable. If no bins or active variables remain, return undef to signal that the iteration is done. Otherwise, return 1.

bin()

Return the current bin number.

var()

Return the current variable index, i.e., the index into $self->{array} that points to the current variable.

done()

Return a boolean value indicating whether there remain bins or variables to visit.

bins()

Return a reference to the @bins array passed to the constructor.

nbins()

Return the total number of bins.

nvars()

Return the number of variables.

data()

Return the ndarray corresponding to the current variable.

idx()

Return the ndarray $idx passed to the constructor.

var_active()

This method is either a getter or a setter, depending on whether an argument is supplied.

If no arguments are supplied: return whether the current variable is still active, i.e., whether any bins remain to be computed. If all bins have been computed for this variable, the variable is inactive.

If a boolean is supplied: mark the current variable active or inactive. An inactive variable will be skipped by next(). An action may mark a variable inactive if it knows that all bins have been computed already, and that visiting the same variable again may either be redundant or wrong. For example, the action PDL::NDBin::Action::Count can deal with the indirection in $idx, and counts the elements of all bins the first time it is called. Visiting the same variable again would double-count the elements. Therefore, the variable must be marked inactive after the first time it has been visited.

        # if all bins have been set for this variable, mark inactive
        $iter->var_active( 0 );

want()

Return the indices of the elements that fall in the current bin. Not very useful in regular actions, except for the common case where only the number of elements is of importance (see PDL::NDBin::Action::Count):

        my $nelem = $iter->want->nelem;

Another use is when empty bins needs to be skipped:

        sub compute_maximum {
                my $iter = shift;
                # max() won't work with empty ndarrays
                return unless $iter->want->nelem;
                my $values = $iter->selection;
                return $values->max;
        }

Please note that the indexing is time-consuming. However, once computed, the indices are cached for the remainder of the current bin and variable.

selection()

Return the data values that actually fall in the current bin for the current variable. This is usually the only method that you need to call in an action.

        sub compute_median {
                my $iter = shift;
                my $values = $iter->selection;
                return $values->median;
        }

Please note that the extraction is time-consuming (and requires the indexing). However, once computed, the values are cached for the remainder of the current bin and variable.

unflatten()

Return the unflattened bin number, i.e., the bin number along each axis (cached). For example, if there 4 bins along the first dimension, and 7 along the second, and the current bin number is 9, calling

        my @pos = $iter->unflatten;

will set @pos to ( 1, 2 ).

AUTHOR

Edward Baudrez <ebaudrez@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2024 by Edward Baudrez.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm PDL::NDBin

perl -MCPAN -e shell
install PDL::NDBin