NAME

Math::SimpleHisto::XS::Named - Named histograms for Math::SimpleHisto::XS

SYNOPSIS

  use Math::SimpleHisto::XS::Named;
  my $hist = Math::SimpleHisto::XS::Named->new(
    names => [qw(boys girls)],
  );
  $hist->fill('boys', 12);
  $hist->fill($_) for map $_->gender, @kids;

DESCRIPTION

EXPERIMENTAL

This module provides histograms with named bins. It is built on top of Math::SimpleHisto::XS and attempts to provide the same interface as far as it makes sense to support. The following documentation covers only the differences between the two modules, so a basic familiarity with Math::SimpleHisto::XS is required.

It is important to not attempt to use a histogram with named bins by looking at its internal coordinates or bin numbering.

API DIFFERENCES TO Math::SimpleHisto::XS

Constructors

The regular constructor, new requires one named parameter: names, an array reference of bin names.

The clone, new_alike methods work the same as with Math::SimpleHisto::XS, but the new_from_bin_range, and new_alike_from_bin_range methods are not implemented for named histograms.

Filling Histograms

The fill() method normally takes any of the following parameters:

• A single coordinate to fill into the histogram

• A single coordinate followed by a single weight

• An array reference containing coordinates to fill into the histogram

• Two array references of the same array length, the first of which contains coordinates, the second of which contains the respective weights

The fill() method has been overridden in such a way that wherever the interface normally calls for coordinates, you need to pass in bin names instead.

Effectively, that means fill works much like fill_by_bin for named histograms.

Additional Methods

This class provides a get_bin_names() method which returns a list of bin names in storage order.

Unimplemented Methods

Apart from the aforementioned new_from_bin_range and new_alike_from_bin_range methods, the following are not implemented, generally, because they do not apply to named bins:

find_bin, min, max, binsize, width, integral, rand bin_center, bin_lower_boundary, bin_upper_boundary, bin_centers, bin_lower_boundaries, bin_upper_boundaries

Methods With Bin Number Parameters

Methods that normally take a bin number as the first parameter, require a bin name instead. These are:

bin_content, set_bin_content, fill_by_bin.

Serialization

This class implements the dump() and new_from_dump() methods of the Math::SimpleHisto::XS interface by wrapping the histogram dump in JSON which contains the additional information.

If you always stick to using dump() and new_from_dump(), then this is an implementation details that should not matter to your code.

The Storable freeze/thaw hooks are delegated to the Math::SimpleHisto::XS implementation and should work as is.

The serialization wrapping does not currently handle dumping/loading dumps in the same backwards compatible way that Math::SimpleHisto::XS does. Since there are no version-incompatibilities in the Math::SimpleHisto::XS::Named code yet, this is not currently an issue and will be addressed when the first incompatibility pops up.

SEE ALSO

This module is built on top of Math::SimpleHisto::XS.

AUTHOR

Steffen Mueller, <smueller@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2011,2012 by Steffen Mueller

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.1 or, at your option, any later version of Perl 5 you may have available.

cpanm Math::SimpleHisto::XS

perl -MCPAN -e shell
install Math::SimpleHisto::XS