API reference

Calculate and plot histograms, easily.

class histlite.Hist(bins, values, errors=None, data=None, weights=None)

A histogram.

T

A transposed version of the Hist.

bins

A list of bin edge arrays, one for each dimension.

centers

A list of bin center arrays for each dimension.

contain(axis, frac=0.6826894921370859)

Project the histogram onto a subset of its dimensions by taking the containment interval along axis.

Parameters:

• axis (int) – the axis along which to measure containment and thus the dimensions no longer present in the resulting Hist.
• frac (float) – the containment interval, measured from self.range[axis][0] and moving to the “right”

Returns:

Hist

contain_project(axis, frac=0.6826894921370859, n_sigma=None)

Project the histogram taking median along one dimension, with errorbars reflecting the eliminated axis.

Parameters:

• axis (int) – the axis along which to measure containment and thus the dimensions no longer present in the resulting Hist.
• frac (float) – the containment fraction, which will be centered on the median value along the given axis
• n_sigma (float) – the containment fraction, specified as a number of sigmas

Returns:

Hist

If given, n_sigma overrides frac.

cumsum(axes=[-1], normalize=False)

Calculate the cumulative sum along specified axes(in order).

curve_fit(func, **kw)

Fit a function to the histogram.

Parameters:func (function) – model function as in scipy.optimize.curve_fit(). Returns:popt, pcov as in scipy.optimize.curve_fit()

This function unravels the values and bin centers into n_dim 1D arrays which are then passed, along with any keyword arguments, to scipy.optimize.curve_fit().

data

The data used to construct the histogram(if given upon construction).

efficiency(base_hist)

Get an efficiency Hist for this Hist divided by base_hist.

Parameters:base_hist (Hist) – The base histogram, of which this one should be a subset.

This method differs from __div__ in the way that errors are propagated.

errors

An nD array of bin errors(sqrt(sum(squares of weights))) in each bin.

gaussian_filter(*a, **kw)

Smooth both values and errors with scipy.ndimage.gaussian_filter().

gaussian_filter1d(*a, **kw)

Smooth both values and errors with scipy.ndimage.gaussian_filter1d().

get_error(*xs)

Get the error value at the specified coordinates.

get_errors(*xs)

Get the error values at the specified lists of coordinates.

get_value(*xs)

Get the counts value at the specified coordinates.

get_values(*xs)

Get the counts values at the specified lists of coordinates.

index(x, axis=0)

The bin index for value x in dimension axis.

indices(*xs)

Get the indices for the specified coordinates.

integrate(axes=None)

Project the histogram onto a subset of its dimensions by integrating over axes.

Parameters:axes (sequence of int) – the axes along which to integrate and thus the dimensions no longer present in the resulting Hist. Returns:Hist

log

A list of bools describing whether each dimenion is binned linearly or logarithmically.

matches(other)

True if self and other have the same binning.

mean(axis=-1)

Project the histogram onto a subset of its dimensions by taking the mean along axis.

Parameters:axis (int) – the axis along which to find the median and thus the dimensions no longer present in the resulting Hist. Returns:Hist

median(axis=-1)

Project the histogram onto a subset of its dimensions by taking the median along axis.

Parameters:axis (int) – the axis along which to find the median and thus the dimensions no longer present in the resulting Hist. Returns:Hist

n_bins

A list of the number of bins in each dimension.

n_dim

The number of dimensions in the histogram.

normalize(axes=None, integrate=True, density=False)

Return a histogram normalized so the sums(or integrals) over the given axes are unity.

Parameters:

• axes (sequence of int, optional) – the axes that will sum(or integrate) to unity for the normalized histogram
• integrate (bool) – if True, normalize so the integral is unity; otherwise, normalize so the sum is unity
• density (bool) – if True, normalize so the integral is unity, but as though the binning were linspaced, even if it is actually not. This option supersedes the integrate argument.

Returns:

Hist

The norm is found by summing over all axes other than the ones specified, or by summing over all axes if axis is not given. Note that setting density=True should obtain equivalent behavior to numpy.histogram(..., density=True).

plotrange(N=100)

Get linspace or logspace along each binning axis.

project(axes=[-1], integrate=False)

Project the histogram onto a subset of its dimensions by summing over axes other than those listed in axes.

Parameters:axes (sequence of int) – the axes along which NOT to sum or integrate, and thus the dimensions no longer present in the resulting Hist. Returns:Hist

range

A list of(min_value,max_value) tuples for each dimension.

ravel_indices(*xs)

Get the indices into values.ravel() for the specified coordinates.

Index of -1 indicates out-of-bounds

rebin(axis, bins, tol=0.0001)

Produce coarser binning along the given axis.

Parameters:

• axis (int) – the axis along which to rebin
• bins (sequence) – the new bin edges
• tol (float) – the absolute error between the given bins and ones found in the original histogram

Returns:

Hist

Each bin in bins should be contained in the existing bins, and the endpoints should match. Tolerance for bin agreement is given as an absolute error by tol.

sample(n_samples=1, *values, **kw)

Draw n samples from the data.

Parameters:n_samples (int) – the number of samples

Any given values select bins in the first len(values) dimensions, such that sampling is done only from the remaining dimensions.

Returns:tuple of arrays of length n_dim

spline_fit(log=False, floor=None, *a, **kw)

Get a scipy spline fit to the histogram.

Parameters:

• log (bool) – whether to fit in log-value or linear-value
• floor (float) – 10**floor is the arbitrary small number to stand in for zeros when log is true. If not set, log10 of 0.1 times the smallest nonzero value will be used.

Returns:

SplineFit

This method produces a spline fit to the histogram values for 1D or 2D histograms. The domain of the fitted spline will be the same as that of the histogram.

sum(axes=None, integrate=False)

Project the histogram onto a subset of its dimensions by summing over axes.

Parameters:

• axes (sequence of int) – the axes along which to sum and thus the dimensions no longer present in the resulting Hist.
• integrate (bool) – if True, evaluate sum of(value * width) rather than just value.

Returns:

Hist

values

An nD array of bin values(sum of weights in each bin).

volumes

An nD array of bin volumes(product of bin widths in each dimension).

weights

The weights used to construct the histogram(if given upon construction).

widths

A list of bin width arrays for each dimension.

class histlite.LineStyle(line=True, marker='None', errorbars=False, errorcaps=False, errorbands=False, xerrorbars=False, crosses=False, poisson=False, **kwargs)

Style object for 1D Hist s.

copy(**kwargs)

Get a copy of this LineStyle, updating the given keyword args.

All arguments accepted by the LineStyle constructor may be given, including line, markers, errorbars, errorcaps, and arbitrary matplotlib arguments.

errorbands

Whether to draw error bands.

errorbars

Whether to draw error bars.

errorcaps

Whether to draw error bar caps.

kwargs

Keyword args for matplotlib.axes.Axes.errorbar().

line

Whether to draw a line.

marker

The marker to use.

markers

Whether to draw point markers.

poisson

Whether to draw Poisson error bars.

update(**kwargs)

Update the keyword args with the given values.

xerrorbars

Whether to draw error bars.

class histlite.SplineFit(hist, spline, bin_logs, log, floor)

Wrapper for spline fits to histograms.

histlite.fill_between(ax, h1, h2, interpolate=False, drawstyle='steps', **kw)

Fill the region between histograms h1 and h2.

Parameters:

• ax (matplotlib Axes) – the axes on which to plot
• h1 (number or Hist) – a number or the first histogram
• h2 (number or Hist) – a number or the second histogram
• where – see pyplot.fill_between().
• interpolate – see pyplot.fill_between().
• drawstyle (str) – if ‘line’, plot smooth curves; otherwise, plot with histogram steps

Other keyword arguments are passed to pyplot.fill_between().

histlite.hist(data, weights=None, bins=10, range=None, log=False, round_int_bins=False, keep_data=False)

Factory function for Hist.

Parameters:

• data (array-like or tuple of array-like) – the source data for the histogram: a tuple of array-like each of length(number of samples), or just a single array of that length
• weights (array-like) – the weights of the source datapoints
• bins (sequence or int, optional) – a numpy.histogramdd() bins specification
• range (sequence, optional) – a numpy.histogramdd() range specification
• log (sequence or bool) – if bins gives bin counts rather than edges, log=True causes logarithmic bin edges to be chosen(can be given per-dimension)
• keep_data (bool) – whether to keep the data and weights for the histogram

Returns:

the Hist

histlite.hist_bootstrap(N, data, weights=None, *args, **kwargs)

Like hist(), but for N iterations of sampling from data with replacement.

Parameters:

• stacked (bool) – if True, output is an ndim+1 dimensional Hist where the first dimension has n_bins=``N`` and values are sorted along this first dimension. otherwise output is ndim dimensional
• errors (str) – ‘original’ to obtain errorbars from standard (non-bootstrapped) Hist; ‘bootstrap’ to obtain errors from containment interval along the Hist that would have been returned if stacked=True. default is ‘bootstrap’
• frac (float in [0,1]) – fraction of samples to use in each iteration. default is 1.0
• slide_Ns (float or sequence of float) – if given, use hist_slide() instead of hist(), with the given number(s) of slided binnings

histlite.hist_direct(data, weights=None, bins=None, range=None, keep_data=False)

Fast factory function for Hist.

Parameters:

• data (array-like) – the data to be histogrammed. For multidimensional histograms, data will be transposed for input into np.histogramdd().
• weights (array-like) – the weights
• bins (sequence or int, optional) – a np.histogramdd() bins specification
• bins – a np.histogramdd() range specification
• keep_data (bool) – whether to keep the data and weights for the histogram

Returns:

the Hist

This method creates a Hist by calling np.histogramdd() as directly as possible. Note that this requires a slightly more constrained format for data compared with hist().

histlite.hist_from_eval(f, vectorize=True, err_f=None, ndim=None, **kwargs)

Create a Hist by evaluating a function.

Parameters:

• f (callable) – the function to evaluate
• ndim (int) – number of arguments to function
• vectorize (bool) – whether numpy.vectorize is needed to evaluate f over many sets of values
• err_f (callable) – if given, function to evaluate to obtain “errors”

All other keyword arguments define the binning the same as for hist().

This function supersedes hist_from_function().

histlite.hist_from_function(bins, func, *args, **kwargs)

[Deprecated] Create a Hist by evaluating func at the centers of specified bins.

Parameters:

• bins (list of np.array) – the bin edges
• func (function) – the function to evaluate. it should return floats and respect numpy broadcasting rules. if splat is true, it should take len(bins) (that is, n_dim) arguments; otherwise, it should accept a single argument containing all values of all independent variables
• err_func (function) – if given, the function that returns the uncertainty at each part of the parameter space
• splat (bool) – determines the signature of func as described above (default: True)

Returns:

the Hist

Any additional positional or keyword arguments are passed to func.

Note: This function is now deprecated; use hist_from_eval() instead.

histlite.hist_like(other, data, weights=None, keep_data=False)

Create a Hist using the same binning as other.

Parameters:

• other (Hist) – the other Hist
• data (array-like) – the data to be histogrammed. For multidimensional histograms, data will be transposed for input into np.histogramdd().
• weights (array-like) – the weights

Returns:

the Hist

histlite.hist_like_indices(other, ravel_indices, weights=None)

Create a Hist using pre-computed per-sample indices from other.

Parameters:

• other (Hist) – the pre-existing histogram which defines the binning
• ravel_indices (array-like) – result of a Hist.ravel_indices() call for the samples.
• weights (array-like) – the weights of the source datapoints

histlite.hist_slide(Ns, data, weights=None, *args, **kwargs)

Construct a “histogram” from N partially-overlapping Hist’s.

Parameters:

• Ns (int or sequence of int) – number of sliding iterations, optionally per-axis
• data (array-like or tuple of array-like) – the source data for the histogram: a tuple of array-like each of length(number of samples), or just a single array of that length
• weights (array-like) – the weights of the source datapoints
• indices (sequence of array-like) – ravel_indices for each individual histogram, obtained from a previous hist_slide call
• get_indices (bool) – if True, obtain ravel_indices values for use in later hist_slide calls

histlite.plot1d(ax, h=None, style=None, **kwargs)

Plot 1D Hist h on matplotlib Axes ax.

Parameters:

• ax (matplotlib Axes) – if given, the axes on which to plot
• h (Hist) – the 1D histogram
• style (LineStyle) – the line style

Other keyword arguments are propagated to pyplot.errorbar() and pyplot.plot() as appropriate.

histlite.plot2d(ax, h=None, log=False, cbar=False, levels=None, **kwargs)

Plot 1D Hist h on ax on a color scale.

Parameters:

• ax (matplotlib Axes) – The main axes on which to plot.
• h (Hist) – The 2D histogram to plot.
• log (bool) – Whether to use a log color scale
• cbar (bool) – If true, draw colorbar.
• levels (int or array of float) – if given, plot with contourf rather than pcolormesh. if a number is given, automatically select that many levels between vmin and vmax.
• zmin (float) – Minimum value to plot with color; bins below the minimum value will be white.

Returns:

If cbar, a dict containing a matplotlib.collection.QuadMesh and a matplotlib.colorbar.Colorbar as values; otherwise, just the QuadMesh.

Other keyword arguments are passed to ax.pcolormesh().

histlite.reindex(a, order)

Rearrange the axes of a multidimensional array.

Parameters:

• a (ndarray) – the input array
• order (sequence of int) – the axis that should wind up in each ordinal position

Returns:

reindexed array

Note: this is useful for implementing Hist.sum(), etc., but you probably should prefer np.swapaxes, possibly using multiple applications, instead.

histlite.stack1d(ax, hs, colors=None, labels=None, kws=None, interpolate=False, drawstyle='steps', ymin=0, **morekw)

Stack histograms hs using fill_between().

Parameters:

• ax (matplotlib Axes) – the axes on which to plot
• hs (sequence of Hist) – the histograms
• colors (sequence) – the fill colors
• labels (sequence of str) – the labels
• kws (sequence of str to value mappings) – keyword arguments for individual fills
• interpolate – see pyplot.fill_between()
• drawstyle (str) – if ‘line’, plot smooth curves; otherwise, plot with histogram steps
• ymin (number) – minimum value(useful for semilogy plots)

Other keyword arguments are passed to each fill_between() call.

histlite.unreindex(a, order)

Reverse the effects of reindex().

Parameters:

• a (ndarray) – the already reindexed array
• order (sequence of int) – order previously applied to reindex()

Returns:

unreindexed array

Note: this is useful for implementing Hist.sum(), etc., but you probably should prefer np.swapaxes, possibly using multiple applications, instead.