NAME
Math::SimpleHisto::XS - Simple histogramming, but kinda fast
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 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.