Types

The library consists of a single histogram and several axis types which are stored in a boost::variant called axis_type. The axis types are created and passed to the constructor of the histogram to define its binning scheme. All following types are embedded in the boost::histogram namespace, which is omitted for brevity.

Histogram type

#include <boost/histogram/histogram.hpp>

C++ interface

class histogram : public basic_histogram

The class implements an n-dimensional histogram, managing counts in bins.

It inherits from basic_histogram, which manages the stored axis instances and the conversion of an n-dimensional tuple or index into an internal linear offset that is used to address the bin count. How the bin count is stored is an encapsulated implementation detail.

histogram(const axis_type &a0, ...)

Constructors for a variable number of axis types, each defining the binning scheme for its dimension. Up to BOOST_HISTOGRAM_AXIS_LIMIT axis types can be passed to the constructor, yielding the same number of dimensions.

void fill_c(unsigned n, const double *v)

Fills the histogram with a c-array v of length n. A checks at run-time asserts that n agrees with the dimensions of the histogram.

Allocation of internal memory is delayed until the first call to this function.

void fill(double x0, ...)

Same as fill_c(), but passing the values of the tuple directly.

void wfill_c(unsigned n, const double *v, double w)

Fills the histogram with a c-array v of length n, using weight w. A checks at run-time asserts that n agrees with the dimensions of the histogram.

Allocation of internal memory is delayed until the first call to this function. If the histogram was filled with fill_c() before, the internal memory is converted to the wide format used for storing weighted counts.

If the data is not weighted (all weights are 1.0), using fill() is much more space-efficient. In the most extreme case, storing of weighted counts consumes 16x more memory.

void wfill(unsigned n, const double *v, double w)

Same as wfill_c(), but passing the values of the tuple directly.

double value_c(unsigned n, const int *idx) const

Returns the count of the bin addressed by the supplied index. Just like in Python, negative indices like -1 are allowed and count from the end. So if an axis has k bins, -1 points to k-1.

double value(int i0, ...) const

Same as value_c(), but passing the values of the index directly.

double variance_c(unsigned n, const int *idx) const

Returns the variance estimate for the count of the bin addressed by the supplied index. Negative indices are allowed just like in case of value_c().

Note that it does not return the standard deviation \(\sigma\), commonly called “error”, but the variance \(\sigma^2\).

In case of unweighted counts, the variance estimate returned is \(n\), if the count is \(n\). This is a common estimate for the variance based on the theory of the Poisson distribution.

In case of weighted counts, the variance estimate returned is \(\sum_i w_i^2\), if the individual weights are \(w_i\). This estimate can be derived from the estimate above using uncertainty propagation. The extra storage needed for keeping track of the this sum is the reason why a histogram with weighted counts consumes more memory.

double variance(int i0, ...) const

Same as variance_c(), but passing the values of the index directly.

unsigned depth() const

Returns the current size of a count in the internal memory buffer in number of bytes.

double sum() const

Returns the sum of bin counts, including overflow and underflow bins. This could be implemented as a free function.

bool operator==(const histogram &other) const

Returns true if the two histograms have the dimension, same axis types, and same data content. Two otherwise identical histograms are not considered equal, if they do not have the same depth, even if counts and variances are the same. This case only occurs if one histogram is filled using fill() and the other with wfill(), using weights of 1.

histogram &operator+=(const histogram &other) const

Adds the counts of the histogram on the right hand side to this histogram, if the two histograms have the same signature. Otherwise, a std::logic_error is thrown. Returns itself.

The following member functions are inherited from basic_histogram:

unsigned dim() const

Returns the number of dimensions of the histogram, how many axis it has.

unsigned bins(unsigned i) const

Returns the number of bins for axis i.

unsigned shape(unsigned i) const

Returns the actual number of fields used by the axis. If the axis has no underflow and overflow bins, this is equal to bins(). Otherwise, the number is larger by 2.

template<typename T>
T &axis(unsigned i)

Returns the axis object at index i, casted to type T. A runtime exception is thrown if the type cast is invalid.

template<typename T>
const T &axis(unsigned i) const

The const-version of the previous member function.

Python interface

The operators ==, +=, and + are defined for histograms. They are also pickable.

class histogram.histogram

N-dimensional histogram for real-valued data.

__init__(*axes)

Pass one or more axis objects as arguments to define the dimensions of the histogram.

dim

dimensions of the histogram

shape((basic_histogram)self, (int)i) → int :
Parameters:i (int) – index of the axis
Returns:number of count fields for axis i (bins + 2 if underflow and overflow bins are enabled, otherwise equal to bins
axis((basic_histogram)self, (int)i) → object :
Parameters:i (int) – index of the axis
Returns:axis object for axis i
fill(*values, w=None)

Pass a sequence of values with a length n is equal to the dimensions of the histogram, and optionally a weight w for this fill (int or float).

If Numpy support is enabled, values my also be a 2d-array of shape (m, n), where m is the number of tuples to pass at once, and optionally another a second 1d-array w of shape (m,).

value(*indices)
Parameters:indices (int) – indices of the bin
Returns:count for the bin
variance(*indices)
Parameters:indices (int) – indices of the bin
Returns:variance estimate for the bin

Axis Types

#include <boost/histogram/axis.hpp>

C++ interface

Axis types have a similar and often common interface, but have no common base type. To increase performance, axis types are internally stored by basic_histogram in a boost::variant.

typedef boost::variant<regular_axis, polar_axis, variable_axis, category_axis, integer_axis> axis_type

A variant which stores one of several axis objects. It needs to be cast to the type it currently holds to be useful or passed to a visitor.

All axis types support the == operator.

class regular_axis

An axis for real-valued data and bins of equal width. Binning is a O(1) operation.

regular_axis(unsigned n, double min, double max, const std::string &label = std::string(), bool uoflow = true)
Parameters:
  • n – number of bins
  • min – low edge of first bin
  • max – high edge of last bin
  • label – description of the axis
  • uoflow – add underflow and overflow bins to the histogram for this axis or not
class polar_axis

An axis for real-valued angles. There are no overflow/underflow bins for this axis, since the axis is circular and wraps around after \(2 \pi\). Binning is a O(1) operation.

polar_axis(unsigned n, double start, const std::string &label = std::string())
Parameters:
  • n – number of bins
  • start – starting phase of the angle
  • label – description of the axis
class variable_axis

An axis for real-valued data and bins of varying width. Binning is a O(log(N)) operation. If speed matters and the problem domain allows it, prefer a regular_axis.

variable_axis(const std::vector<double> &x, const std::string &label = std::string(), bool uoflow = true)
Parameters:
  • x – bin edges, the number of bins is one less the size of this vector
  • label – description of the axis
  • uoflow – add underflow and overflow bins to the histogram for this axis or not
class category_axis

An axis for enumerated categories. The axis stores the category labels, and expects that they are addressed using an integer from 0 to n-1. There are no underflow/overflow bins for this axis. Binning is a O(1) operation.

category_axis(const std::vector<std::string> &categories)
Parameters:categories – an ordered sequence of categories that this axis discriminates
category_axis(const std::string &categories)
Parameters:categories – a string of categories separated by the character ;
const std::string &operator[](int index) const

Returns the category for the bin index.

class integer_axis

An axis for a contiguous range of integers. There are no underflow/overflow bins for this axis. Binning is a O(1) operation.

integer_axis(int min, int max, const std::string &label = std:string(), bool uoflow = true)
int operator[](int index) const

Returns the integer that is mapped to the bin index.

Common interface among axis types:

unsigned bins() const

Returns the number of bins.

bool uoflow() const

Returns whether overflow and underflow bins will be added in the histogram.

const std::string &label() const

Returns the axis label, which is a name or description (not implemented for category_axis).

void label(const std::string &label)

Change the label of an axis (not implemented for category_axis).

int index(const double x) const

Returns the bin index for the passed argument.

double operator[](int index) const

Returns the low edge of the bin (not implemented for category_axis and integer_axis).

Python interface

All axis types support the operators == and []. They support the len() and repr() calls, and the iterator protocol.

class histogram.regular_axis

An axis for real-valued data and bins of equal width. Binning is a O(1) operation.

index((regular_axis)self, (float)x) → int :
Parameters:x (float) – value
Returns:bin index for the passed value
label

Name or description for the axis.

class histogram.polar_axis

An axis for real-valued angles. There are no overflow/underflow bins for this axis, since the axis is circular and wraps around after 2pi. Binning is a O(1) operation.

index((polar_axis)self, (float)x) → int :
Parameters:x (float) – value
Returns:bin index for the passed value
label

Name or description for the axis.

class histogram.variable_axis

An axis for real-valued data and bins of varying width. Binning is a O(log(N)) operation. If speed matters and the problem domain allows it, prefer a regular_axis.

index((variable_axis)self, (float)x) → int :
Parameters:x (float) – value
Returns:bin index for the passed value
label

Name or description for the axis.

class histogram.category_axis

An axis for enumerated categories. The axis stores the category labels, and expects that they are addressed using an integer from 0 to n-1. There are no underflow/overflow bins for this axis. Binning is a O(1) operation.

class histogram.integer_axis

An axis for a contiguous range of integers. There are no underflow/overflow bins for this axis. Binning is a O(1) operation.

index((integer_axis)self, (float)x) → int :
Parameters:x (float) – value
Returns:bin index for the passed value
label

Name or description for the axis.