File Coverage

blib/lib/CXC/PDL/Bin1D.pm

Criterion	Covered	Total	%
statement	146	159	91.8
branch	22	44	50.0
condition	37	53	69.8
subroutine	27	27	100.0
pod	2	2	100.0
total	234	285	82.1

#
# GENERATED WITH PDL::PP from lib/CXC/PDL/Bin1D.pd! Don't modify!
#
package CXC::PDL::Bin1D;

our @EXPORT_OK = qw( );
our %EXPORT_TAGS = (Func=>\@EXPORT_OK);

use PDL::Core();
use PDL::Exporter;
use DynaLoader;


   our $VERSION = '0.28';
   our @ISA = ( 'PDL::Exporter','DynaLoader' );
   push @PDL::Core::PP, __PACKAGE__;
   bootstrap CXC::PDL::Bin1D $VERSION;








#line 203 "lib/CXC/PDL/Bin1D.pd"

use v5.10;
use strict;
use warnings;
no namespace::clean;
use CXC::PDL::Bin1D::Utils;
use namespace::clean;

#line 222 "lib/CXC/PDL/Bin1D.pd"
use constant {
BIN_RC_OK => 1,
BIN_RC_GEWMAX => 2,
BIN_RC_GENMAX => 4,
BIN_RC_FOLDED => 8,
BIN_RC_GTMINSN => 16,
BIN_ARG_HAVE_ERROR => 1,
BIN_ARG_HAVE_WEIGHT => 2,
BIN_ARG_SET_BAD => 4,
BIN_ARG_FOLD => 8,
BIN_ARG_HAVE_WIDTH => 16,
BIN_ARG_ERROR_SDEV => 32,
BIN_ARG_ERROR_POISSON => 64,
BIN_ARG_ERROR_RSS => 128,
BIN_ARG_HAVE_SIGNAL => 256,
BIN_ARG_SAVE_OOB_START_END => 512,
BIN_ARG_SAVE_OOB_START_NBINS => 1024,
BIN_ARG_SHIFT_IMIN => 1536,
BIN_ARG_SAVE_OOB_END => 2048,
BIN_ARG_SAVE_OOB_NBINS => 4096,
BIN_ARG_SAVE_OOB => 7680,
BIN_ARG_WANT_EXTREMA => 8192,
BIN_ARG_WANT_SUM_WEIGHT => 16384,
BIN_ARG_WANT_SUM_WEIGHT2 => 32768,
};

#line 227 "lib/CXC/PDL/Bin1D.pd"

=for Pod::Coverage
BIN_RC_OK
BIN_RC_GEWMAX
BIN_RC_GENMAX
BIN_RC_FOLDED
BIN_RC_GTMINSN
BIN_ARG_HAVE_ERROR
BIN_ARG_HAVE_WEIGHT
BIN_ARG_SET_BAD
BIN_ARG_FOLD
BIN_ARG_HAVE_WIDTH
BIN_ARG_ERROR_SDEV
BIN_ARG_ERROR_POISSON
BIN_ARG_ERROR_RSS
BIN_ARG_HAVE_SIGNAL
BIN_ARG_SAVE_OOB_START_END
BIN_ARG_SAVE_OOB_START_NBINS
BIN_ARG_SHIFT_IMIN
BIN_ARG_SAVE_OOB_END
BIN_ARG_SAVE_OOB_NBINS
BIN_ARG_SAVE_OOB
BIN_ARG_WANT_EXTREMA
BIN_ARG_WANT_SUM_WEIGHT
BIN_ARG_WANT_SUM_WEIGHT2

=cut

#line 230 "lib/CXC/PDL/Bin1D.pd"
my %MapErrorAlgo = (

    sdev    => BIN_ARG_ERROR_SDEV,
    rss     => BIN_ARG_ERROR_RSS,
    poisson => BIN_ARG_ERROR_POISSON,
);

#line 239 "lib/CXC/PDL/Bin1D.pd"

=for Pod::Coverage
set_boundscheck
set_debugging

=for stopwords
merchantability

=cut

=head1 NAME

CXC::PDL::Bin1D - one dimensional binning functions

=head1 SYNOPSIS

  use PDL;
  use CXC::PDL::Bin1D;

=head1 DESCRIPTION

One dimensional binning functions,

=over

=item *

binning up to a given S/N

=item *

optimized one-pass robust statistics

=back

All functions are made available in the B namespace.

=head1 SUBROUTINES

=cut

#line 441 "lib/CXC/PDL/Bin1D.pd"
$EXPORT_TAGS{constants} = [ qw(
BIN_RC_FOLDED
BIN_RC_GTMINSN
BIN_RC_OK
BIN_RC_GENMAX
BIN_RC_GEWMAX
BIN_ARG_SAVE_OOB_END
BIN_ARG_SHIFT_IMIN
BIN_ARG_SAVE_OOB
BIN_ARG_WANT_EXTREMA
BIN_ARG_SAVE_OOB_START_NBINS
BIN_ARG_ERROR_RSS
BIN_ARG_HAVE_SIGNAL
BIN_ARG_ERROR_SDEV
BIN_ARG_FOLD
BIN_ARG_WANT_SUM_WEIGHT2
BIN_ARG_HAVE_WIDTH
BIN_ARG_HAVE_WEIGHT
BIN_ARG_HAVE_ERROR
BIN_ARG_SAVE_OOB_START_END
BIN_ARG_SET_BAD
BIN_ARG_ERROR_POISSON
BIN_ARG_WANT_SUM_WEIGHT
BIN_ARG_SAVE_OOB_NBINS
)];

#line 443 "lib/CXC/PDL/Bin1D.pd"
$EXPORT_TAGS{Func} = [ qw(
bin_adaptive_snr
bin_on_index
)];

#line 444 "lib/CXC/PDL/Bin1D.pd"
@EXPORT_OK = map { @{$_} } values %EXPORT_TAGS;
#line 177 "Bin1D.pm"

no namespace::clean;

use Types::Common::Numeric qw[ PositiveNum PositiveInt PositiveOrZeroInt ];
use Types::Standard        qw[ Optional InstanceOf slurpy Dict Bool Enum ];
use Type::Params           qw[ compile ];

use Carp      ();
use PDL::Lite ();

use namespace::clean;

use constant PP_PASS_TMPS => do { require version; PDL->VERSION < version->parse( '2.073' ) };

my $bin_adaptive_snr_check;

BEGIN {

    $bin_adaptive_snr_check = compile(
        slurpy Dict [
            signal     => InstanceOf ['PDL'],
            error      => Optional [ InstanceOf ['PDL'] ],
            width      => Optional [ InstanceOf ['PDL'] ],
            min_snr    => PositiveNum,
            min_nelem  => Optional [PositiveInt],
            max_nelem  => Optional [PositiveInt],
            min_width  => Optional [PositiveNum],
            max_width  => Optional [PositiveNum],
            fold       => Optional [Bool],
            error_algo => Optional [ Enum [ keys %MapErrorAlgo ] ],
            set_bad    => Optional [Bool],
        ] );
}

## no critic (Subroutines::ProhibitExcessComplexity)
sub bin_adaptive_snr {

    my ( $opts ) = $bin_adaptive_snr_check->( @_ );

    # specify defaults
    my %opt = (
        error_algo => 'sdev',
        min_nelem  => 1,
        %$opts,
    );

    Carp::croak( "width must be specified if either of min_width or max_width is specified\n" )
      if ( defined $opt{min_width} || defined $opt{max_width} )
      && !defined $opt{width};

    Carp::croak( "must specify error attribute if 'rss' errors selected\n" )
      if !defined $opt{error} && $opt{error_algo} eq 'rss';

    $opt{min_width} ||= 0;
    $opt{max_width} ||= 0;
    $opt{max_nelem} ||= 0;

    # if the user hasn't specified whether to fold the last bin,
    # turn it on if there aren't *maximum* constraints
    $opt{fold} = !defined $opt{max_width} || !defined $opt{max_nelem}
      unless defined $opt{fold};

    $opt{flags}
      = ( ( defined $opt{error} && BIN_ARG_HAVE_ERROR ) || 0 )
      | ( ( defined $opt{width} && BIN_ARG_HAVE_WIDTH ) || 0 )
      | ( ( $opt{fold}          && BIN_ARG_FOLD ) || 0 ) | ( ( $opt{set_bad} && BIN_ARG_SET_BAD ) || 0 )
      | $MapErrorAlgo{ $opt{error_algo} };

    my @pin  = qw[ signal error width ];
    my @pout = qw[ index nbins nelem b_signal b_error b_mean b_snr
      b_width ifirst ilast rc ];
    my @oargs = qw[ flags min_snr min_nelem max_nelem min_width max_width ];

    # several of the input piddles are optional.  the PP routine
    # doesn't know that and will complain about the wrong number of
    # dimensions if we pass a null piddle. A 1D zero element piddle
    # will have its dimensions auto-expanded without much
    # wasted memory.
    $opt{$_} = PDL->new( 0 ) for grep { !defined $opt{$_} } @pin;
    $opt{$_} = PDL->null     for grep { !defined $opt{$_} } @pout;

    my @pars;
    if ( PP_PASS_TMPS ) {
        my @ptmp = qw[ berror2 bsignal2 b_m2 b_weight b_weight_sig b_weight_sig2 ];
        $opt{$_} = PDL->null for grep { !defined $opt{$_} } @ptmp;
        @pars = ( @pin, @pout, @ptmp, @oargs );
    }
    else {
        @pars = ( @pin, @pout, @oargs );
    }

    _bin_adaptive_snr_int( @opt{@pars} );

    my %results = map {    ## no critic (BuiltinFunctions::ProhibitComplexMappings)
        ( my $nkey = $_ ) =~ s/^b_//;
        ( $nkey, $opt{$_} )
    } @pout;

    return wantarray ? %results : \%results;
}

=pod

=head2 bin_adaptive_snr

=for usage

  %hash = bin_adaptive_snr( %options  );

=for stopwords
Adaptively

=for ref

Adaptively bin a data set to achieve a minimum signal to noise ratio
in each bin.

This routine ignores data with bad values or with errors that have
bad values.

B groups data into bins such that each bin meets
one or more conditions:

=over

=item *

a minimum signal to noise ratio (S/N).

=item *

A minimum number of data elements (optional).

=item *

A maximum number of data elements (optional).

=item *

A maximum data I (see below) (optional).

=item *

A minimum data I (see below) (optional).

=back

The data are typically dependent values (e.g. flux as a function of
energy or counts as a function of radius).  The data should be sorted
by the independent variable (e.g. energy or radius).

Calculation of the S/N requires an estimate of the error associated
with each datum.  The error may be provided or may be estimated from
the population using either the number of data elements in a bin
(e.g. Poisson errors) or the standard deviation of the signal in a bin.
If errors are provided, they may be used to weight the population standard
deviation or may be added in quadrature.

Binning begins at the start of the signal vector.  Data are accumulated
into a bin until one or more of the possible criteria is met. If the
final bin does not meet the required criteria, it may optionally be
successively folded into preceding bins until the final bin passes the
criteria or there are no bins left.

Each datum may be assigned an extra parameter, its I,
which is summed for each bin, and can be used as an additional constraint
on bin membership.

=head3 Parameters

B is passed a hash or a reference to a hash containing
its parameters.  The available parameters are:

=over

=item C

A piddle containing the signal data.  This is required.

=item C

A piddle with the error for signal datum. Optional.

=item C

A piddle with the I of each element of the signal. Optional.

=item C

A string indicating how the error is to be handled or calculated.  It
may be have one of the following values:

=over

=item * C

Poisson errors will be calculated based upon the number of elements in a bin,

  error**2 = N

Any input errors are ignored.

=item * C

The error is the population standard deviation of the signal in a bin.

  error**2 = Sum [ ( signal - mean ) **2 ] / ( N - 1 )

If errors are provided, they are used to calculated the weighted population
standard deviation.

  error**2 = ( Sum [ (signal/error)**2 ] / Sum [ 1/error**2 ] - mean**2 )
             * N / ( N - 1 )

=item * C

Errors must be provided; the errors of elements in a bin are added in
quadrature.

=back

=item C

The minimum signal to noise ratio to be achieved in each bin.  Required.

=item C

=item C

The minimum and/or maximum number of elements to be achieved in each bin. Optional

=item C

=item C

The minimum and/or maximum width of the elements to be achieved in each bin. Optional.

=item C I

If true, the last bin may be folded into the preceding bin in order to
ensure that the last bin meets one or more of the criteria. It defaults to false.

=back

=head3 Results

B returns a hashref with the following entries:

=over

=item C

A piddle containing the bin indices for the elements in the input
data piddle.  Data which were skipped because of bad values will have
their index set to the bad value.

=item C

A piddle containing the number of bins which spanned the range of the
input data.

=item C

A piddle containing the sum of the data values in each bin.  Only
indices C<0> through C are valid.

=item C

A piddle containing the number of data elements in each bin. Only
indices C<0> through C are valid.

=item C

A piddle containing the errors in each bin, calculated using the
algorithm specified via C. Only indices C<0> through
C are valid.

=item C

A piddle containing the weighted mean of the signal in each bin. Only
indices C<0> through C are valid.

=item C

A piddle containing the index into the input data piddle of the first
data value in a bin. Only indices C<0> through C are valid.

=item C

A piddle containing the index into the input data piddle of the last
data value in a bin. Only indices C<0> through C are valid.

=item C

A piddle containing a results code for each output bin.  Only indices
C<0> through C are valid.  The code is the bitwise "or" of
the following constants (available in the C
namespace)

=over

=item BIN_RC_OK

The bin met the minimum S/N, data element count and weight requirements

=item BIN_RC_GEWMAX

The bin weight was greater or equal to that requested.

=item BIN_RC_GENMAX

The number of data elements was greater or equal to that requested.

=item BIN_RC_FOLDED

The bin is the result of folding bins at the end of the bin vector to
achieve a minimum S/N.

=item BIN_RC_GTMINSN

The bin accumulated more data elements than was necessary to meet the
S/N requirements.  This results from constraints on the minimum number
of data elements or bin weight.

=back

=back

=cut








use v5.10;
no namespace::clean;

use Types::Common::Numeric qw[ PositiveOrZeroInt ];
use Types::Standard        qw[ Optional Bool StrMatch Undef Int ];
use Types::PDL -types;
use Type::Params qw[ compile_named ];

use Carp      ();
use PDL::Lite ();

use Hash::Wrap ( { -class => __PACKAGE__ . '::bin_on_index' } );

use constant PP_PASS_TMPS => do { require version; PDL->VERSION < version->parse( '2.073' ) };

# this is ugly
sub CoercedPiddle {

    my $to_type = shift;

    my $convert = sprintf(
        <<'EOS',
do { local $@;
     require PDL::Core;
     my $new = eval { PDL::Core::convert( $_, PDL::%s )  };
     length($@) ? $_ : $new
     }
EOS
        $to_type,
    );
    return Piddle( [ type => $to_type ] )->plus_coercions( map { $_ => $convert } Piddle, @_ );
}

use namespace::clean;

{

    my $check;
    my $range_RE;

    BEGIN {
        $range_RE = qr/(flat|slice)(?:,(minmax|min|max))?/;

        $check = compile_named(
            index  => CoercedPiddle( 'indx' ),
            data   => Piddle,
            nbins  => Optional [ CoercedPiddle( indx => PositiveOrZeroInt ) ],
            weight => Optional [ Piddle | Undef ],
            # Enum is preferred for the following, but see https://rt.cpan.org/Ticket/Display.html?id=129729
            oob => Optional [ StrMatch( [qr/^start-end|start-nbins|end|nbins$/] ) | Bool ] => { default => 0 },
            want_sum_weight  => Optional [Bool],
            want_sum_weight2 => Optional [Bool],
            imin             => Optional [ CoercedPiddle( indx => Int ) ],
            imax             => Optional [ CoercedPiddle( indx => Int ) ],
            range            => Optional [ StrMatch( [$range_RE] ) ] );
    }

    my %Map_OOB = (
        'start-end'   => BIN_ARG_SAVE_OOB_START_END,
        'start-nbins' => BIN_ARG_SAVE_OOB_START_NBINS,
        'end'         => BIN_ARG_SAVE_OOB_END,
        'nbins'       => BIN_ARG_SAVE_OOB_NBINS,
    );

    sub bin_on_index {

        my $opt = $check->( @_ );

        _bin_on_index_parse_range_opts( $opt );

        $opt->{flags}
          = ( ( defined $opt->{weight}   && BIN_ARG_HAVE_WEIGHT )      || 0 )
          | ( ( $opt->{want_sum_weight}  && BIN_ARG_WANT_SUM_WEIGHT )  || 0 )
          | ( ( $opt->{want_sum_weight2} && BIN_ARG_WANT_SUM_WEIGHT2 ) || 0 )
          | ( ( $opt->{want_extrema}     && BIN_ARG_WANT_EXTREMA )     || 0 );

        $opt->{flags}
          |= $Map_OOB{ lc( $opt->{oob} ) }    # prefer fc, but requires 5.16
          // ( $opt->{oob} && BIN_ARG_SAVE_OOB_START_END )
          || 0;

        my @pin   = qw[ data index weight imin nbins ];
        my @pout  = qw[ b_count b_data b_weight b_weight2 b_mean b_dmin b_dmax b_dev2 ];
        my @oargs = qw[ flags nbins_max ];

        # several of the input piddles are optional.  the PP routine
        # doesn't know that and will complain about the wrong number of
        # dimensions if we pass a null piddle. A 1D one-element piddle
        # will have its dimensions auto-expanded without much
        # wasted memory.

        $opt->{$_} = $opt->{data}->zeroes( 1 ) for grep { !defined $opt->{$_} } @pin;

        # output and temp piddles will be auto-inflated, so we can use
        # null piddles. In a perfect world PDL::PP would have a mechanism
        # to avoid inflating the optional ones.
        # TODO: use nullcreate here to get correct piddle type?

        $opt->{$_} = PDL->null for grep { !defined $opt->{$_} } @pout;

        my @pars;
        if ( PP_PASS_TMPS ) {
            my @ptmp = qw[ b_data_error b_weight_error b_weight2_error ];
            $opt->{$_} = PDL->null for grep { !defined $opt->{$_} } @ptmp;
            @pars = ( @pin, @pout, @ptmp, @oargs );
        }
        else {
            @pars = ( @pin, @pout, @oargs );
        }

        _bin_on_index_int( @{$opt}{@pars} );
        my %results = map {    ## no critic (BuiltinFunctions::ProhibitComplexMappings)
            ( my $nkey = $_ ) =~ s/^b_//;
            ( $nkey, $opt->{$_} )
        } @pout;

        if ( $opt->{flags} & BIN_ARG_HAVE_WEIGHT ) {
            delete $results{weight}
              unless $opt->{flags} & BIN_ARG_WANT_SUM_WEIGHT;
            delete $results{weight2}
              unless $opt->{flags} & BIN_ARG_WANT_SUM_WEIGHT2;
        }
        else {
            delete @results{qw( weight weight2)};
        }

        $results{imin}  = $opt->{imin};
        $results{nbins} = $opt->{nbins};

        return wrap_hash( \%results );
    }

    sub _bin_on_index_parse_range_opts {

        my $opt = shift;

        if ( $opt->{range} ) {

            my ( $dims, $range ) = $opt->{range} =~ $range_RE;
            $range //= 'minmax';

            eval {

                # treat the index as a one big pool of numbers, or
                # as threaded piddles.
                my ( $imin, $imax )
                  = $dims eq 'slice'
                  ? map { $_->dummy( 0 ) } $opt->{index}->minmaximum
                  : map { PDL::indx( [$_] ) } $opt->{index}->minmax;

                if ( $range eq 'minmax' ) {

                    die( "do not specify $_ when specifying 'minmax'\range with " )
                      for grep { defined $opt->{$_} } qw[ imin imax nbins ];

                    $opt->{imin} = $imin;
                    $opt->{imax} = $imax;
                }

                elsif ( $range eq 'min' ) {

                    die( "do not specify imin when specifying 'min'\n" )
                      if defined $opt->{imin};

                    die( "specify exactly one of 'imax' or 'nbins'\n" )
                      if defined $opt->{imax} && defined $opt->{nbins};

                    $opt->{imin} = $imin;
                }

                elsif ( $range eq 'max' ) {
                    die( "do not specify imax\n" )
                      if defined $opt->{imax};

                    die( "specify exactly one of 'imin' or 'nbins'\n" )
                      if defined $opt->{imin} && defined $opt->{nbins};

                    $opt->{imax} = $imax;
                }
                1;
            } // do {
                my $error = $@;
                chomp $error;
                Carp::croak( $opt->{range}, ": error: $error\n" );
            };

        }
        else {

            my $nrange_opts = grep { defined $opt->{$_} } qw[ imin imax nbins ];

            if ( $nrange_opts == 0 ) {

                @{$opt}{ 'imin', 'imax' }
                  = map { PDL::indx( $_ ) } $opt->{index}->minmax;
            }

            elsif ( $nrange_opts == 1 ) {

                if ( defined $opt->{nbins} ) {
                    $opt->{imin} = PDL::indx( 0 );
                }
                elsif ( defined $opt->{imax} ) {
                    $opt->{imin} = PDL::indx( 0 );
                }
                elsif ( defined $opt->{imin} ) {
                    $opt->{imax} = PDL::indx( $opt->{index}->max );
                }
            }
            elsif ( $nrange_opts == 3 ) {
                Carp::croak( "error: too many options. specify only two of imin, imax, nbins\n" );
            }
        }

        # don't care about imax.

        $opt->{imin}  //= $opt->{imax} - $opt->{nbins} + 1;
        $opt->{nbins} //= $opt->{imax} - $opt->{imin} + 1;
        $opt->{nbins_max} = $opt->{nbins}->max;
    }

}

=pod

=for stopwords
ACM
Bevington
Commun
Golub
Higham
Kahan
LeVeque
McGraw
superset

=head2 bin_on_index

=for usage

  $hashref = bin_on_index( %pars  );

=for ref

Calculate basic statistics on optionally weighted, binned data using a
provided index.  The input data are assumed to be one-dimensional; extra
dimensions are threaded over.

This routine ignores data with bad values or with weights that have bad values.

=head3 Description

When generating statistics for multiple-component data binned on a
common component, it's more efficient to calculate a bin index for the
common component and then use it to generate statistics for each component.

For example, if a time dependent stream of events is binned into time
intervals, statistics of the events' properties (such as position or
energy) must be evaluated on data binned on the intervals.

Some statistics (such as the summed squared deviation from the mean)
may be calculated in two passes over the data, but may suffer from
numerical inaccuracies depending upon the magnitude of the
intermediate values.

C uses numerically stable algorithms to calculate
various statistics on binned data in a single pass.  It uses an index
piddle to assign data to bins and calculates basic statistics on the
data in those bins.  Data may have associated weights, and the index
piddle need not be sorted.  It by default ignores out-of-bounds data, but
can be directed to operate on them.

The statistics which are returned for each bin are:

=over

=item *

The number of elements, I

=item *

The (weighted) sum of the data,
I<< Sum(x_i) >>,
I<< Sum(w_i * x_i) >>.

=item *

The (weighted) mean of the data,
I<< Sum(x_i) / N >>,
I<< Sum(w_i * x_i) / Sum(w_i) >>

=item *

The sum of the weights, I<< Sum(w_i) >>

=item *

The sum of the square of the weights, I<< Sum(w_i^2) >>

=item *

The sum of the (weighted) squared deviation of the data from mean,
 I<< Sum( (x_i-u)^2 ) >>,
 I<< Sum( w_i(x_i-u)^2 ) >>.  These are I normalized!.

=item *

The minimum and maximum data values

=back

The sum of the squared deviations are I normalized, to allow the
user to handle it according to their needs.

For unweighted data, the typical normalization factor is I,
while for weighted data, the normalization factor varies depending
upon whether the weights represent errors or quality weights.  In the
former case, where I<< w_i = 1 / sigma^2 >>, the normalization factor
is typically I<< N / (N - 1) / Sum(w_i) >>, while for the latter the
normalization is typically I<< Sum(w_i) / ( Sum(w_i)^2 - Sum(w_i^2) ) >>.
See L and L.

The algorithms used are chosen for their numerical stability.  Sums
are computed using Kahan summation and the mean and squared deviations are
calculated with stable updating algorithms.  See L, L, L.

=head4 Threading

The parameters L, L, L, L, L, and
L are threaded over.  This keeps things quite flexible, as one
can specialize things for complex datasets or keep them simple by
specifying the minimum information for a given parameter to have it
remain constant over the threaded dimensions. (Note that C
must have the same shape or be a superset of the other parameters).

Unless otherwise specified, the term I refers to those of the
core (non-threaded) one-dimensional slices of the input and output
piddles.

For some parameters there is value in applying an algorithm to
either the entire dataset (including threaded dimensions) or just
the core one-dimensional data.  For example, the L
option can indicate that the in-bounds bins are defined by the range
in each one-dimensional slice of L or in L as a whole.

=head4 Minimum Bin Index, Number of Bins, Out-Of-Bounds Data

By default, the minimum bin index and the number of bins are
determined from the values in the L piddle, treating it as if
it were one-dimensional.  Statistics for data with the minimum index
are stored in the results piddles at index I<0>.

The caller may use the options L, L, and
L, and L to change how the index range is mapped onto
the results piddles, and whether the range should be specific to each
one-dimensional slice of L. If none of these are specified,
the default is equivalent to setting L to C.
To most efficiently store the statistics, set L to C.

Data with indices outside of the range C<[$imin, $imin + $nbins - 1]>
are treated as I data, and by default are ignored.  If the
user wishes to accumulate statistics on these data, the L option
may be used to indicate where in the results piddles the statistics
should be stored.

=head3 Parameters

B is passed a hash or a reference to a hash containing
its parameters.  The possible parameters are:

=over

=item C I

The data.
I

=item C I

The bin index. It should be of type C, but will be converted to that if not.
It must be thread compatible with L.
I

=item C I

Data weight.
It must be thread compatible with L.
I

=item C  I | I

The number of bins.
It must be thread compatible with L.

If C is set and neither of C or C are set, C is set to C<0>.

Use L for more control over automatic determination of the range.

=item C I | I

The index value associated with the first in-bounds index in the
result piddle.
It must be thread compatible with L.

If C is set and neither of C or C are set, C is set to C<< $index->max >>.

Use L for more control over automatic determination of the range.

=item C I | I

The index value associated with the last in-bounds index in the
result piddle. It must be thread compatible with L.

If C is set and neither of C or C are set, C is set to C<< 0 >>.

Use L for more control over automatic determination of the range.

=item C I<"spec,spec,...">

Determine the in-bounds range of indices from L.  The value is
a string containing a list of comma separated specifications.

The first element must be one of the following values:

=over

=item C

Treat L as one-dimensional, and determine a single range which
covers it.

=item C

Determine a separate range for each one-dimensional slice of L.

=back

It may optionally be followed by one of the following

=over

=item C

Determine the full range (i.e. both minimum and maximum) from
L.  This is the default.  Do not specify L,
L, or L.

=item C

Determine the minimum of the range from L.  Specify only one of L
or L.

=item C

Determine the maximum of the range from L.  Specify only one of L
or L.

=back

=item C

An index is out-of-bounds if it is not within the range

  [ $imin, $imin + $nbins )

By default, it will be ignored.

This option specifies where in the results piddles the out-of-bound
data statistics should be stored.  It may be one of:

=over

=item C

The extent of the results piddle is increased by two, and out-of-bound
statistics are written as follows:

  $index - $imin < 0          ==> $result->at(0)
  $index - $imin >= $nbins    ==> $result->at(-1)

=item C

The extent of the results piddle is increased by two, and out-of-bound
statistics are written as follows:

  $index - $imin < 0          ==> $result->at(0)
  $index - $imin >= $nbins    ==> $result->at($nbins)

This differs from C if C<$nbins> is different for each
one-dimensional slice.

=item C

The extent of the results piddle is increased by two, and out-of-bound
statistics are written as follows:

  $index - $imin < 0          ==> $result->at(-2)
  $index - $imin >=  $nbins   ==> $result->at(-1)

=item C

The extent of the results piddle is increased by two, and out-of-bound
statistics are written as follows:

  $index - $imin < 0          ==> $result->at($nbins-1)
  $index - $imin >=  $nbins   ==> $result->at($nbins)

This differs from C if C<$nbins> is different for each
one-dimensional slice.

=item I

If false (the default) out-of-bounds data are ignored.  If true, it is
equivalent to specifying L

=back

=item C I I<[false]>

if true, the sum of the bins' weights are calculated.

=item C I I<[false]>

if true, the sum of square of the bins' weights are calculated.

=back

=head3 Results

B returns a reference which may be used either a hash
or object reference.

The keys (or methods) and their values are as follows:

=over

=item C

A piddle containing the (possibly weighted) sum of the data in each bin.

=item C

A piddle containing the number of data elements in each bin.

=item C

A piddle containing the sum of the weights in each bin (only if
L was provided and L specified).

=item C

A piddle containing the sum of the square of the weights in each bin
(only if L was provided and L specified).

=item C

A piddle containing the (possibly weighted) mean of the data in each bin.

=item C

=item C

Piddles containing the minimum and maximum values of the data in each bin.

=item C

=item C

The index value associated with the first in-bounds index
in the statistics piddles, and the number of in-bounds bins.

=back

=head3 References

=over

=item [Chan83]

Chan, Tony F., Golub, Gene H., and LeVeque, Randall J., Algorithms for
Computing the Sample Variance: Analysis and Recommendations, The
American Statistician, August 1983, Vol. 37, No.3, p 242.

=item [West79]

D. H. D. West. 1979. Updating mean and variance estimates: an improved
method. Commun. ACM 22, 9 (September 1979), 532-535.

=item [Higham]

Higham, N. (1996). Accuracy and stability of numerical
algorithms. Philadelphia: Society for Industrial and Applied
Mathematics.

=item [Robinson]

Robinson, E.L., Data Analysis for Scientists and Engineers, 2016,
Princeton University Press. ISBN 978-0-691-16992-7.

=item [Bevington]

Bevington, P.R., Robinson, D.K., Data Reduction and Error Analysis for
the Physical Sciences, Second Edition, 1992, McGraw-Hill, ISBN
0-07-91243-9.

=back

=cut










#line 408 "lib/CXC/PDL/Bin1D.pd"

=head1 BUGS AND LIMITATIONS

No bugs have been reported.

=head1 AUTHOR

Diab Jerius, [e-mail]

=head1 COPYRIGHT AND LICENSE

Copyright 2008 Smithsonian Astrophysical Observatory

CXC::PDL::Bin1D is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful,
but without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see L.

=cut
#line 1162 "Bin1D.pm"

# Exit with OK status

1;