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.
-
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.
-
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; ifFalse
, 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.
-
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.
-
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
andhigh
- 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 tolow
- overflow (bool) – if
True
(default), include an overflow bin representing the interval fromhigh
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; ifFalse
, 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.
-
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 tomin
- overflow (bool) – if
True
(default), include an overflow bin representing the interval frommax
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.
-
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.
-
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 tolow
- overflow (bool) – if
True
(default), include an overflow bin representing the interval fromhigh
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; ifFalse
, 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.
-
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.
-
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
andTrue
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.
-
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.
-
-
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