histbook¶

Versatile, high-performance histogram toolkit for Numpy.

histbook computes histograms from Numpy arrays. It differs from most other histogramming tools in that its histograms are primarily tables of numbers, rather than display graphics. Histograms can be filled and refilled iteratively through a large dataset, or in parallel and later combined with addition*. Histograms have arbitrarily many dimensions with convenient methods for selecting, rebinning, and projecting into lower-dimensional spaces.

Axis dimensions are managed by algebraic expressions, rather than string labels or index positions, so they are computable: an axis named x + y requires two Numpy arrays, x and y, which will be added before filling the histogram. Expressions in different axes or different histograms in the same “book” (a collection of named histograms) are computed in an optimized way, reusing subexpressions wherever possible for quicker filling without giving up clarity.

Histogram data may be exported to a variety of formats, such as Pandas, ROOT, and HEPData. It can also be plotted with Vega-Lite, which makes short work of projecting many dimensions of data as overlays and trellises.

(*In this respect, histbook is like histogramming packages developed for particle physics, from CERN HBOOK in the 1970’s (name similarity intended) to modern-day ROOT.)

Installation¶

Install histbook like any other Python package:

pip install histbook --user

or similar (use sudo, --user, virtualenv, or pip-in-conda if you wish).

Strict dependencies:¶

Python (2.7+, 3.4+)
Numpy (1.8.0+)

Recommended dependencies:¶

Pandas for more convenient programmatic access to bin contents
Jupyter Notebook for interlaced histogramming and plotting
JupyterLab for a complete IDE-like environment
ipyvega to view plots in a Jupyter Notebook (not needed for JupyterLab)
Altair to mix histograms with Altair graphics (usable in both Jupyter Notebook and JupyterLab)
VegaScope to view plots in a web browser without Jupyter
ROOT to analyze histograms in a complete statistical toolkit
uproot to access ROOT files without the full ROOT framework

Tutorial¶

See the project homepage for a tutorial.

Interactive tutorial¶

Run this tutorial on Binder.

Reference documentation¶

Histograms¶

histbook has only one histogram class, which can have arbitrarily many independent dimensions (binned axes) and dependent dimensions (profiles). Plotable one and two-dimensional histograms are derived by projection.

class histbook.hist.Hist(*axis, **opts)¶

Parameters:

*axis (Axis) – axis or axes that define the independent and dependent variables of the histogram

Keyword Arguments:

weight (None, algebraic expression (string) or number) – if None (default), data will be filled with weight 1; if an expression, weights are computed from the expression; if a number, weights are constant
filter (None, algebraic expression (string)) – if not None, data will be filtered through this logical expression (equivalent to multiplying weight by where(filter, 1, 0))
defs (None or dict of str → algebraic expression (string) or Expr) – if not None, definitions to use when computing expressions
fill (None, single Numpy array or dict of str → Numpy arrays) – if not None, data to immediately fill after constructing the histogram; single Numpy array is only permitted if there’s only one field
attachment (None or dict of str → any JSON) – histogram metadata, such as fit results or other context
systematic (None, tuple of numbers) – the systematic error vector this histogram represents; a special case of attachment (and stored in attachment)

COUNTTYPE¶: alias of numpy.float64

area(axis=None, profile=None, error=False, normalized=False, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None, shapescale=None)¶

Display bins in axis (if not the only axis) as areas on the horizontal axis.

Parameters:	axis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay; if `None` (default), use the only axis in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) error (bool) – if `True`, overlay error bars normalized (bool) – if `True`, normalize the histogram height, title, config, xscale, yscale, colorscale, shapescale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable1d`

attach(key, value)¶: Add an attachment to the histogram (changing it in-place and returning it).

attachment¶: Python dict of attachment metadata (linked, not a copy).

axis¶: The axes that define a histogram’s binning of space.

bar(axis=None, profile=None, error=False, normalized=False, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None, shapescale=None)¶

Display bins in axis (if not the only axis) as bars on the horizontal axis.

Parameters:	axis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay; if `None` (default), use the only axis in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) error (bool) – if `True`, overlay error bars normalized (bool) – if `True`, normalize the histogram height, title, config, xscale, yscale, colorscale, shapescale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable1d`

below(axis)¶

Display bins in axis next to each other vertically.

Parameters:	axis (`Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay
Returns:
Return type:	`PlottingChain`

beside(axis)¶

Display bins in axis next to each other horizontally.

Parameters:	axis (`Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay
Returns:
Return type:	`PlottingChain`

clear()¶: Effectively reset all bins to zero.

cleared()¶: Return a copy with all bins set to zero.

compatible(other)¶: Returns True if the histograms have the same non-profile axis types and binning, regardless of the expressions used to compute them.

copy()¶: Return an immediate copy of the histogram.

copyonfill()¶: Return a copy of the histogram whose content is copied if filled.

defs¶: Definitions used by axis expressions.

detach(key)¶: Remove an attachment from the histogram (changing it in-place and returning it).

drop(*profile)¶

Remove one or more profile axes.

Parameters:	*profile (`profile`, algebraic expression (string), or index position (integer)) – the axis or axes to drop
Returns:	a histogram without the selected `profiles`.
Return type:	`Hist`

fields¶: Names of fields that must be provided in the fill method.

fill(arrays=None, **more)¶

Fill the histogram: identify bins for independent variables, increase their counts by 1 or weight, and increment any profile (dependent variable) means and errors in the means.

All arrays must have the same length (one-dimensional shape). Numbers are treated as one-element arrays.

Parameters:	arrays (dict → Numpy array or number; Spark DataFrame; Pandas DataFrame) – field values to use in the calculation of independent and dependent variables (axes) *more (Numpy arrays* or numbers) – more field values

filter(expr)¶: Returns a copy of this histogram with expr as filter (for fluent construction).

fraction(*cut, **opts)¶

Return a table of the fraction of entries that pass a set of cuts in each bin.

Parameters:

*cut (profile) – the cut axis or axes to include in the table

Keyword Arguments:

count (bool) – if True (default), include the (possibly weighted) count of entries in each bin (denominator of the fraction)
error (string or None) – if not None, include “errors” on all parameters (uncertainty in the mean of the distribution the count or fraction represents); options are "clopper-pearson", "normal" (default), "wilson", "agresti-coull", "feldman-cousins", "jeffrey", "bayesian-uniform"
level (number or iterable of numbers) – confidence level or levels at which to evaluate error; default is erf(sqrt(0.5)) or 0.6827, otherwise known as “one sigma”
recarray (bool) – if True (default), return results as a Numpy record array, which is rank-2 with named columns; if False, return a plain Numpy array, which is rank-N for N axes and has no column labels.
columns (bool) – if True (not default), return a 2-tuple in which the second argument is a list of column labels.

get(key, *default)¶

Get an item of attachment metadata.

If key isn’t found and no default is specified, raise a KeyError. If key isn’t found and a default is provided, return the default instead.

Only one default is allowed.

classmethod group(by='source', **hists)¶

Combine histograms, maintaining their distinctiveness by adding a new categorical axis to each.

To combine histograms by adding bins, just use the + operator.

Parameters:	by (string) – name of the new axis (must not already exist) **hists (`Hist`) – histograms to combine (must have the same axes)

groupkeys(axis)¶

Return all categorical keys associated with a groupby axis or non-zero bins associated with a groupbin axis.

Parameters:	axis (`Axis`, algebraic expression (string), or index position (integer)) – the groupby or groupbin axis
Returns:	all keys for this axis, even if that is a union over other group axes
Return type:	set

has(key)¶: Returns True if key exists in the attachment metadata.

heatmap(xaxis=None, yaxis=None, profile=None, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None)¶

Display bins in xaxis and yaxis (if not the only two axes) as a heatmap.

Parameters:	xaxis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the horizontal axis to overlay; if `None` (default), use the first of the only two axes in this `Hist` yaxis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the vertical axis to overlay; if `None` (default), use the second of the only two axes in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) height, title, config, xscale, yscale, colorscale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable2d`

line(axis=None, profile=None, error=False, normalized=False, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None, shapescale=None)¶

Display bins in axis (if not the only axis) as lines on the horizontal axis.

Parameters:	axis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay; if `None` (default), use the only axis in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) error (bool) – if `True`, overlay error bars normalized (bool) – if `True`, normalize the histogram height, title, config, xscale, yscale, colorscale, shapescale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable1d`

marker(axis=None, profile=None, error=True, normalized=False, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None, shapescale=None)¶

Display bins in axis (if not the only axis) as markers on the horizontal axis.

Parameters:	axis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay; if `None` (default), use the only axis in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) error (bool) – if `True`, overlay error bars normalized (bool) – if `True`, normalize the histogram height, title, config, xscale, yscale, colorscale, shapescale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable1d`

overlay(axis)¶

Display bins in axis overlaid on each other in different colors.

Parameters:	axis (`Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay
Returns:
Return type:	`PlottingChain`

pandas(*axis, **opts)¶

Exports the data in the histogram to a Pandas DataFrame.

Keyword Arguments:
Parameters:	*axis (`Axis`, algebraic expression (lambda or string), or index position (integer)) – axis or axes to include in the table; if no axes or all `profile` axes, this function calls `Hist.table`; if all `cut` axes, this function calls `Hist.fraction`
	*opts (any*) – passed to `Hist.table` or `Hist.fraction`; see these methods for options

project(*axis)¶

Project onto a given set of axis.

Parameters:	*axis (`Axis`, algebraic expression (string), or index position (integer)) – the axis or axes to keep (all `profile` axes are kept)
Returns:	a histogram projected onto the selected axis or axes.
Return type:	`Hist`

rebin(axis, edges)¶

Reduce the number of bins by combining existing bins at a specified set of edges.

Parameters:	axis (`Axis`, algebraic expression (string), or index position (integer)) – the axis to rebin edges (iterable of numbers) – new bin edges; must be a subset of existing bin edges
Returns:	a rebinned histogram.
Return type:	`Hist`

rebinby(axis, factor)¶

Reduce the number of bins by an approximate factor by combining existing bins.

Parameters:	axis (`Axis`, algebraic expression (string), or index position (integer)) – the axis to rebin factor (positive integer) – number of bins to combine into a single bin (inexact if the number of bins in `axis` is not an exact multiple of `factor`)
Returns:	a rebinned histogram.
Return type:	`Hist`

root(*axis, **opts)¶

Exports the data in the histogram to a ROOT histogram.

The histogram may need to be selected (Hist.select) or projected (Hist.project) to make it useful in a ROOT histogram.

Keyword Arguments:
Parameters:	*axis (`Axis`, algebraic expression (lambda or string), or index position (integer)) – axis or axes to include in the output; if no axes, this function returns a histogram of counts; if one `profile`, this function returns a profile; …
	name (string) – name to give to the ROOT object (default is the empty string) title (string) – title to give to the ROOT object (default is the empty string) cache (dict-like object) – if supplied, the return value is inserted into `cache` keyed by its name; this for convenience (ROOT objects must be kept in scope to be drawn)

select(expr, tolerance=1e-12)¶

Eliminate bins by selecting data with a boolean expr.

Parameters:	expr (algebraic expression (string)) – boolean expression of data to keep; selection thresholds must align with bin edges with the right inequality (e.g. `<` vs `<=`) tolerance (small positive number) – absolute difference between selection threshold and bin edge to qualify as a match
Returns:	a histogram with data removed (fewer bins)
Return type:	`Hist`

shape¶: Shape of the Numpy array defining the content of the fixed-memory axes (FixedAxis) only.

stack(axis, order=None)¶

Display bins in axis stacked on one another in an area plot.

Parameters:	axis (`Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay order (iterable of strings) – stacking order of bins
Returns:
Return type:	`PlottingChain`

step(axis=None, profile=None, error=False, normalized=False, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None, shapescale=None)¶

Display bins in axis (if not the only axis) as steps on the horizontal axis.

Parameters:	axis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay; if `None` (default), use the only axis in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) error (bool) – if `True`, overlay error bars normalized (bool) – if `True`, normalize the histogram height, title, config, xscale, yscale, colorscale, shapescale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable1d`

systematic(vector)¶: Returns a copy of this histogram with vector as systematic (for fluent construction).

table(*profile, **opts)¶

Return histogram data as a table of counts and, optionally, dependent variables (profiles).

Parameters:

*profile (profile) – the dependent variables to include in the table

Keyword Arguments:

count (bool) – if True (default), include the (possibly weighted) count of entries in each bin
effcount (bool) – if True (not default), include the effective count, which is used to convert between weighted profile errors and weighted profile spreads (equal to count for unweighted data)
error (bool) – if True (default), include “errors” on all parameters (uncertainty in the mean of the distribution the count or profile average represents)
normalized (bool) – if True (not default), scale each count and err(count) such that the sum over counts times bin widths is 1; does not affect profiles
recarray (bool) – if True (default), return results as a Numpy record array, which is rank-2 with named columns; if False, return a plain Numpy array, which is rank-N for N axes and has no column labels.
columns (bool) – if True (not default), return a 2-tuple in which the second argument is a list of column labels.

togroup()¶

Add histograms to the groupby that is the first axis.

Histograms created with Hist.group have a first axis that is a groupby.

Keyword Arguments:
	**hists (dict of str → `Hist`) – histograms to add to the existing group

weight(expr)¶: Returns a copy of this histogram with expr as weights (for fluent construction).

Books of histograms¶

Histograms can be collected into “books,” both as a user convenience (fill all histograms in a book with a single call to fill) and for performance (avoid multiple passes over the data or repeated calculations).

Books of histograms behave like dicts, with access to individual histograms through square brackets (__getitem__ and __setitem__).

class histbook.book.Book(hists1={}, *hists2, **hists3)¶

A collection of histograms (Hist) or other Books that can be filled with a single fill call.

Behaves like a dict (item assignment, keys, values).

Positional arguments may be a dict of str → Hist or GenericBook.

Or they may be Hist or GenericBook as unnamed varargs.

In either case, keyword name → Hist or Book are also accepted.

allitems(onlyhist=False)¶

Return a recursive list of path, book-or-histogram pairs.

Parameters:	onlyhist (bool) – if `True` (not default), only return histograms (type `Hist`), not books

allkeys(onlyhist=False)¶

Return a recursive list of paths.

Parameters:	onlyhist (bool) – if `True` (not default), only return names of histograms (type `Hist`), not books

allvalues(onlyhist=False)¶

Return a recursive list of books and histograms.

Parameters:	onlyhist (bool) – if `True` (not default), only return histograms (type `Hist`), not books

assertcompatible()¶: Raises ValueError if not all books have the same set of histogram names and those histograms with matching names are compatible.

attach(key, value)¶: Add an attachment to the book (changing it in-place and returning it).

attachment¶: Python dict of attachment metadata (linked, not a copy).

clear()¶: Effectively reset all bins of all histograms to zero.

cleared()¶: Return a copy with all bins of all histograms set to zero.

compatible(other)¶: Returns True if the books have the same set of histogram names and those histograms with matching names are compatible.

copy()¶: Return an immediate copy of the book of histograms.

copyonfill()¶: Return a copy of the book of histograms whose content is copied if filled.

detach(key)¶: Remove an attachment from the book (changing it in-place and returning it).

fields¶: Names of fields that must be provided in the fill method.

fill(arrays=None, **more)¶

Fill the histograms: identify bins for independent variables, increase their counts by 1 or weight, and increment any profile (dependent variable) means and errors in the means.

All arrays must have the same length (one-dimensional shape). Numbers are treated as one-element arrays.

All histograms in the book are filled with the same inputs.

Parameters:	arrays (dict → Numpy array or number; Spark DataFrame; Pandas DataFrame) – field values to use in the calculation of independent and dependent variables (axes) *more (Numpy arrays* or numbers) – more field values

classmethod fromdicts(content, attachment)¶: Construct a book from its content and attachment dicts.

get(key, *default)¶

Get an item of attachment metadata.

If key isn’t found and no default is specified, raise a KeyError. If key isn’t found and a default is provided, return the default instead.

Only one default is allowed.

classmethod group(by='source', **books)¶

Combine histograms, maintaining their distinctiveness by adding a new categorical axis to each.

To combine histograms by adding bins, just use the + operator.

Parameters:	by (string) – name of the new axis (must not already exist) **books (`Book`) – books to combine (histograms with the same names must have the same axes)

has(key)¶: Returns True if key exists in the attachment metadata.

items(recursive=False, onlyhist=False)¶

Return a list of path, book-or-histogram pairs.

Parameters:	recursive (bool) – if `True` (default), descend into books of books onlyhist (bool) – if `True` (not default), only return histograms (type `Hist`), not books

iteritems(recursive=False, onlyhist=False)¶

Iterate through path, book-or-histogram pairs.

Parameters:	recursive (bool) – if `True` (default), descend into books of books onlyhist (bool) – if `True` (not default), only return histograms (type `Hist`), not books

iterkeys(recursive=False, onlyhist=False)¶

Iterate through paths.

Parameters:	recursive (bool) – if `True` (default), descend into books of books onlyhist (bool) – if `True` (not default), only return names of histograms (type `Hist`), not books

itervalues(recursive=False, onlyhist=False)¶

Iterate through books and histograms.

Parameters:	recursive (bool) – if `True` (default), descend into books of books onlyhist (bool) – if `True` (not default), only return histograms (type `Hist`), not books

keys(recursive=False, onlyhist=False)¶

Return a list of paths.

Parameters:	recursive (bool) – if `True` (default), descend into books of books onlyhist (bool) – if `True` (not default), only return names of histograms (type `Hist`), not books

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair¶: as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D¶

update([E, ]**F) → None. Update D from mapping/iterable E and F.¶: If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values(recursive=False, onlyhist=False)¶

Return a list of books and histograms.

Parameters:	recursive (bool) – if `True` (default), descend into books of books onlyhist (bool) – if `True` (not default), only return histograms (type `Hist`), not books

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.

Plotting¶

The plotting interface is fluent, meaning that the graphical content of the plot is configured by a chain of method calls. Steps along this chain (including the Hist itself) are PlottingChain objects and the last one is Plotable1d or Plotable2d.

class histbook.vega.PlottingChain(source, item)¶

Mix-in for Hist (as the first in a plotting chain) and Channels in a plotting chain.

area(axis=None, profile=None, error=False, normalized=False, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None, shapescale=None)¶

Display bins in axis (if not the only axis) as areas on the horizontal axis.

Parameters:	axis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay; if `None` (default), use the only axis in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) error (bool) – if `True`, overlay error bars normalized (bool) – if `True`, normalize the histogram height, title, config, xscale, yscale, colorscale, shapescale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable1d`

bar(axis=None, profile=None, error=False, normalized=False, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None, shapescale=None)¶

Display bins in axis (if not the only axis) as bars on the horizontal axis.

Parameters:	axis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay; if `None` (default), use the only axis in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) error (bool) – if `True`, overlay error bars normalized (bool) – if `True`, normalize the histogram height, title, config, xscale, yscale, colorscale, shapescale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable1d`

below(axis)¶

Display bins in axis next to each other vertically.

Parameters:	axis (`Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay
Returns:
Return type:	`PlottingChain`

beside(axis)¶

Display bins in axis next to each other horizontally.

Parameters:	axis (`Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay
Returns:
Return type:	`PlottingChain`

heatmap(xaxis=None, yaxis=None, profile=None, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None)¶

Display bins in xaxis and yaxis (if not the only two axes) as a heatmap.

Parameters:	xaxis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the horizontal axis to overlay; if `None` (default), use the first of the only two axes in this `Hist` yaxis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the vertical axis to overlay; if `None` (default), use the second of the only two axes in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) height, title, config, xscale, yscale, colorscale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable2d`

line(axis=None, profile=None, error=False, normalized=False, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None, shapescale=None)¶

Display bins in axis (if not the only axis) as lines on the horizontal axis.

Parameters:	axis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay; if `None` (default), use the only axis in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) error (bool) – if `True`, overlay error bars normalized (bool) – if `True`, normalize the histogram height, title, config, xscale, yscale, colorscale, shapescale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable1d`

marker(axis=None, profile=None, error=True, normalized=False, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None, shapescale=None)¶

Display bins in axis (if not the only axis) as markers on the horizontal axis.

Parameters:	axis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay; if `None` (default), use the only axis in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) error (bool) – if `True`, overlay error bars normalized (bool) – if `True`, normalize the histogram height, title, config, xscale, yscale, colorscale, shapescale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable1d`

overlay(axis)¶

Display bins in axis overlaid on each other in different colors.

Parameters:	axis (`Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay
Returns:
Return type:	`PlottingChain`

stack(axis, order=None)¶

Display bins in axis stacked on one another in an area plot.

Parameters:	axis (`Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay order (iterable of strings) – stacking order of bins
Returns:
Return type:	`PlottingChain`

step(axis=None, profile=None, error=False, normalized=False, width=None, height=None, title=None, config=None, xscale=None, yscale=None, colorscale=None, shapescale=None)¶

Display bins in axis (if not the only axis) as steps on the horizontal axis.

Parameters:	axis (`None`, `Axis`, algebraic expression (lambda or string), or index position (integer)) – the axis to overlay; if `None` (default), use the only axis in this `Hist` profile (`None`, `profile`, algebraic expression (lambda or string) or index position (integer)) – if `None` (default), display bin counts; otherwise, display profile means (and errors on the mean) error (bool) – if `True`, overlay error bars normalized (bool) – if `True`, normalize the histogram height, title, config, xscale, yscale, colorscale, shapescale (width,) – graphical directives to pass to Vega-Lite
Returns:
Return type:	`Plotable1d`

class histbook.vega.Plotable1d(source, item)¶

Mix-in for Channels and Combinations that can be plotted.

altair(validate=True)¶: Return an altair.Chart of this plot using the Altair library.

ipyvega()¶: Draw this plot inline in a Jupyter notebook (not lab) using the vega library.

to(fcn)¶: Call fcn on the Vega-Lite JSON for this plot.

vegalite()¶: Return the Vega-Lite JSON for this plot.

vegascope(canvas=None)¶: Draw this plot in a (possibly remote) browser using the VegaScope library.

class histbook.vega.Plotable2d(source, item)¶

Mix-in for Channels and Combinations that can be plotted.

altair(validate=True)¶: Return an altair.Chart of this plot using the Altair library.

ipyvega()¶: Draw this plot inline in a Jupyter notebook (not lab) using the vega library.

to(fcn)¶: Call fcn on the Vega-Lite JSON for this plot.

vegalite()¶: Return the Vega-Lite JSON for this plot.

vegascope(canvas=None)¶: Draw this plot in a (possibly remote) browser using the VegaScope library.

Inheritance diagram of histbook.vega.overlay, histbook.vega.beside, histbook.vega.below, histbook.vega.grid

class histbook.vega.Combination(plotables, types, opts)¶

Abstract class for Plotable1ds that have been combined as an overlay or side-by-side plots.

altair(validate=True)¶: Return an altair.Chart of this plot using the Altair library.

ipyvega()¶: Draw this plot inline in a Jupyter notebook (not lab) using the vega library.

to(fcn)¶: Call fcn on the Vega-Lite JSON for this plot.

vegascope(canvas=None)¶: Draw this plot in a (possibly remote) browser using the VegaScope library.

class histbook.vega.overlay(*plotables, **opts)¶

Plotable1d overlaying two or more independently produced Plotable1ds.

altair(validate=True)¶: Return an altair.Chart of this plot using the Altair library.

ipyvega()¶: Draw this plot inline in a Jupyter notebook (not lab) using the vega library.

to(fcn)¶: Call fcn on the Vega-Lite JSON for this plot.

vegascope(canvas=None)¶: Draw this plot in a (possibly remote) browser using the VegaScope library.

class histbook.vega.beside(*plotables, **opts)¶

Plotable1d displaying two or more independently produced Plotable1ds beside each other horizontally.

altair(validate=True)¶: Return an altair.Chart of this plot using the Altair library.

ipyvega()¶: Draw this plot inline in a Jupyter notebook (not lab) using the vega library.

to(fcn)¶: Call fcn on the Vega-Lite JSON for this plot.

vegascope(canvas=None)¶: Draw this plot in a (possibly remote) browser using the VegaScope library.

class histbook.vega.below(*plotables, **opts)¶

Plotable1d displaying two or more independently produced Plotable1ds below each other vertically.

altair(validate=True)¶: Return an altair.Chart of this plot using the Altair library.

ipyvega()¶: Draw this plot inline in a Jupyter notebook (not lab) using the vega library.

to(fcn)¶: Call fcn on the Vega-Lite JSON for this plot.

vegascope(canvas=None)¶: Draw this plot in a (possibly remote) browser using the VegaScope library.

class histbook.vega.grid(numcol, *plotables, **opts)¶

Plotable1d displaying two or more independently produced Plotable1ds in a rectangular grid of numcol columns.

altair(validate=True)¶: Return an altair.Chart of this plot using the Altair library.

ipyvega()¶: Draw this plot inline in a Jupyter notebook (not lab) using the vega library.

to(fcn)¶: Call fcn on the Vega-Lite JSON for this plot.

vegascope(canvas=None)¶: Draw this plot in a (possibly remote) browser using the VegaScope library.