Math::Histogram::Axis - Object representing single histogram dimension


  use Math::Histogram;
  # 10 bins between 0 and 1
  my $fixed_bin = Math::Histogram::Axis->new(10, 0., 1.);
  # 5 bins of variable size
  my $var_bin = Math::Histogram::Axis->new([1, 2, 4, 8, 16]);


An object of this class represents the binning information along one dimension of an N-dimensional histogram. A 1-D histogram will require one axis, a 2-D histogram two axises, etc. Axises can contain a number of equal-sized bins (also referred to as fixed-bin axises in other parts of the documentation) or a number of explicitly specified variable-width bins. Some of the algorithms, most notably the one for determining the bin number for a given coordinate, will be O(1) for fixed-width binning, but O(log(n)) for variable-width binning.



The constructor takes one or three arguments. With three arguments, the axis will have fixed-width bins. The first argument is the number of bins on the axis, the second is the lower boundary of the first bin, the third is the upper boundary of the last bin.

One argument indicates a variable-width binning. The argument must be a reference to an array of floating point numbers that increase strictly monotonically. They are interpreted in order as the lower boundary of the first bin, the boundary between first and second bin, ... and finally the upper boundary of the last bin. Given N elements of the array reference, the axis will have N-1 bins.

Bin numbers start at 1 since the bin with number 0 is the underflow bin which technically has the range (-Infty., min), so excluding the lower limit of the first bin.


Returns a deep clone of the axis object.


Returns the number of bins on the axis.


Returns the lower boundary of the first bin of the axis.


Returns the upper boundary of the last bin of the axis.


Returns the total width of all bins combined. Yes, that's simply $axis->max - $axis->min.


Given a bin number, returns the width of that bin. Defaults to '1', so for axis objects with fixed-width binning, calling this method without argument is valid.


Given a bin number, returns the lower boundary of that bin.


Given a bin number, returns the upper boundary of that bin.


Given a bin number, returns the center of that bin.


Given a coordinate, finds the bin number of the bin it lies in. Returns 0 for underflow and $nbins + 1 for overflow.


Returns a JSON string that represents this axis object.


Class method. Given a JSON string as generated by serialize(), recreates the axis object that it represents. Also accepts a scalar reference to a JSON string.




Steffen Mueller, <>


Copyright (C) 2012, 2015 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.