Axis descriptors¶

Each dimension of a Hist is specified by an Axis object. There are three main categories (abstract classes): GroupAxis, FixedAxis, and ProfileAxis.

class histbook.axis.Axis¶: Abstract class for a histogram axis.

class histbook.axis.GroupAxis¶: Abstract class for histogram axes that fill bin contents as a dict (dynamic memory allocation).

class histbook.axis.FixedAxis¶: Abstract class for histogram axes that fill bin contents as a Numpy array (static memory allocation).

class histbook.axis.ProfileAxis¶: Abstract class for profile axes (dependent variables).

Concrete Axis types¶

The following are intended for use in Hist constructors.

class histbook.axis.groupby(expr, keeporder=False)¶

Describes an axis of categorical values, such as strings.

Memory use scales with distinct values encountered in the data.

Parameters:	expr (algebraic expression (string)) – quantity to use as an independent variable in the probability distribution represented by this histogram; distinct values are used to determine bin membership keeporder (boolean) – if `True` (not default), keep track of the order in which new categories are seen

compatible(other)¶: Returns True if the two axes have the same types and binning, regardless of the expression used to compute them.

copy()¶: Returns a copy of the groupby.

expr¶: Algebraic expression <histbook.expr.Expr>

items(content)¶: Returns (key, value) pairs of the content.

keys(content)¶: Returns key labels in the order of the bin content, to index the content.

relabel(label)¶: Returns a groupby with a new expr.

class histbook.axis.groupbin(expr, binwidth, origin=0, nanflow=True, closedlow=True)¶

Describes an axis of sparse, numeric values.

Memory use scales with distinct bins encountered in the data.

Parameters:

expr (algebraic expression (string)) – quantity to use as an independent variable in the probability distribution represented by this histogram
binwidth (positive number) – width of the intervals used to determine bin membership
origin (number (default 0)) – the low edge of all bin intervals modulo binwidth; use this to offset the phase of the bins
nanflow (bool) – if True (default), include a single bin for NaN (not a number)
closedlow (bool) – if True (default), the low edge of all bins is included in the bin, high edge is excluded; if False, the high edge is included and low edge is excluded (exception: if an edge is infinite, it is always included)

compatible(other)¶: Returns True if the two axes have the same types and binning, regardless of the expression used to compute them.

copy()¶: Returns a copy of the groupbin.

items(content)¶: Returns (key, value) pairs of the content.

keys(content)¶: Returns key labels in the order of the bin content, to index the content.

relabel(label)¶: Returns a groupbin with a new expr.

class histbook.axis.bin(expr, numbins, low, high, underflow=True, overflow=True, nanflow=True, closedlow=True)¶

Describes an axis of regularly spaced, dense, numeric values.

Memory use is fixed: number of bins is numbins + (1 if underflow else 0) + (1 if overflow else 0) + (1 if nanflow else 0).

Parameters:

expr (algebraic expression (string)) – quantity to use as an independent variable in the probability distribution represented by this histogram
numbins (positive integer) – number of bins between low and high
low (number) – the low edge of the first finite bin
high (number) – the high edge of the last finite bin
underflow (bool) – if True (default), include an underflow bin representing the interval from negative infinity to low
overflow (bool) – if True (default), include an overflow bin representing the interval from high to positive infinity
nanflow (bool) – if True (default), include a single nanflow bin representing NaN (not a number) values
closedlow (bool) – if True (default), the low edge of all bins is included in the bin, high edge is excluded; if False, the high edge is included and low edge is excluded (exception: if an edge is infinite, it is always included)

compatible(other)¶: Returns True if the two axes have the same types and binning, regardless of the expression used to compute them.

copy()¶: Returns a copy of the bin.

items(content)¶: Returns (key, value) pairs of the content.

keys(content=None)¶: Returns key labels in the order of the bin content, to index the content.

relabel(label)¶: Returns a :py:class:bin` <histbook.axis.bin>` with a new expr.

class histbook.axis.intbin(expr, min, max, underflow=True, overflow=True)¶

Describes an axis of integer values.

Memory use is fixed: number of bins is max - min + 1 + (1 if underflow else 0) + (1 if overflow else 0).

Parameters:

expr (algebraic expression (string)) – quantity to use as an independent variable in the probability distribution represented by this histogram
min (integer) – the minimum bin value (inclusive)
high (number) – the maximum bin value (inclusive)
underflow (bool) – if True (default), include an underflow bin representing the interval from negative infinity to min
overflow (bool) – if True (default), include an overflow bin representing the interval from max to positive infinity

compatible(other)¶: Returns True if the two axes have the same types and binning, regardless of the expression used to compute them.

copy()¶: Returns a copy of the intbin.

items(content)¶: Returns (key, value) pairs of the content.

keys(content=None)¶: Returns key labels in the order of the bin content, to index the content.

relabel(label)¶: Returns an intbin with a new expr.

class histbook.axis.split(expr, edges, underflow=True, overflow=True, nanflow=True, closedlow=True)¶

Describes an axis of irregularly spaced, dense, numeric values.

Memory use is fixed: number of bins is len(edges) - 1 + (1 if underflow else 0) + (1 if overflow else 0) + (1 if nanflow else 0).

Parameters:

expr (algebraic expression (string)) – quantity to use as an independent variable in the probability distribution represented by this histogram
edges (non-empty iterable of numbers or a single number) – thresholds defining a partitioning of space
underflow (bool) – if True (default), include an underflow bin representing the interval from negative infinity to low
overflow (bool) – if True (default), include an overflow bin representing the interval from high to positive infinity
nanflow (bool) – if True (default), include a single nanflow bin representing NaN (not a number) values
closedlow (bool) – if True (default), the low edge of all bins is included in the bin, high edge is excluded; if False, the high edge is included and low edge is excluded (exception: if an edge is infinite, it is always included)

compatible(other)¶: Returns True if the two axes have the same types and binning, regardless of the expression used to compute them.

copy()¶: Returns a copy of the split.

items(content)¶: Returns (key, value) pairs of the content.

keys(content=None)¶: Returns key labels in the order of the bin content, to index the content.

relabel(label)¶: Returns a split with a new expr.

class histbook.axis.cut(expr)¶

Describes an axis of two bins: those that fail and those that pass a boolean expression.

Memory use is fixed: number of bins is 2.

Parameters:	expr (algebraic expression (string)) – boolean quantity to use as an independent variable in the probability distribution represented by this histogram; `False` and `True` values are the two distinct bins

compatible(other)¶: Returns True if the two axes have the same types and binning, regardless of the expression used to compute them.

copy()¶: Returns a copy of the cut.

items(content)¶: Returns (key, value) pairs of the content.

keys(content=None)¶: Returns key labels in the order of the bin content, to index the content.

relabel(label)¶: Returns a cut with a new expr.

class histbook.axis.profile(expr)¶

Describes an axis in which to compute mean and error in the mean.

Memory use is fixed: number of bins is 2 (to accumulate mean and error in the mean).

Parameters:	expr (algebraic expression (string)) – quantity to use as a dependent variable, binned by other axes in the `Hist`

copy()¶: Returns a copy of the profile.

relabel(label)¶: Returns a profile with a new expr.