API reference¶
Calculate and plot histograms, easily.
-
class
histlite.
Hist
(bins, values, errors=None, data=None, weights=None)[source]¶ 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)[source]¶ 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:
-
contain_project
(axis, frac=0.6826894921370859, n_sigma=None)[source]¶ 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: If given,
n_sigma
overridesfrac
.
-
cumsum
(axes=[-1], normalize=False)[source]¶ Calculate the cumulative sum along specified axes (in order).
-
curve_fit
(func, **kw)[source]¶ 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)[source]¶ 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)[source]¶ Smooth both values and errors with
scipy.ndimage.gaussian_filter()
.
-
gaussian_filter1d
(*a, **kw)[source]¶ Smooth both values and errors with
scipy.ndimage.gaussian_filter1d()
.
-
integrate
(axes=None)[source]¶ 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.
-
median
(axis)[source]¶ 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)[source]¶ 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: 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 settingdensity=True
should obtain equivalent behavior tonumpy.histogram(..., density=True)
.
-
project
(axes=[-1], integrate=False)[source]¶ 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)[source]¶ Get the indices into values.ravel() for the specified coordinates.
Index of -1 indicates out-of-bounds
-
rebin
(axis, bins, tol=0.0001)[source]¶ 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: 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)[source]¶ 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)[source]¶ 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: 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)[source]¶ 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:
-
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)[source]¶ Style object for 1D
Hist
s.-
copy
(**kwargs)[source]¶ 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.
-
xerrorbars
¶ Whether to draw error bars.
-
-
class
histlite.
SplineFit
(hist, spline, bin_logs, log, floor)[source]¶ Wrapper for spline fits to histograms.
-
histlite.
fill_between
(ax, h1, h2, interpolate=False, drawstyle='steps', **kw)[source]¶ 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)[source]¶ 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)[source]¶ Like
hist()
, but for N iterations of sampling fromdata
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)[source]¶ Fast factory function for
Hist
.Parameters: - data (array-like) – the data to be histogrammed. For multidimensional
histograms,
data
will be transposed for input intonp.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 callingnp.histogramdd()
as directly as possible. Note that this requires a slightly more constrained format fordata
compared withhist()
.- data (array-like) – the data to be histogrammed. For multidimensional
histograms,
-
histlite.
hist_from_eval
(f, vectorize=True, err_f=None, ndim=None, **kwargs)[source]¶ 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 evaluatef
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)[source]¶ [Deprecated] Create a
Hist
by evaluatingfunc
at the centers of specifiedbins
.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 takelen(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)[source]¶ Create a
Hist
using the same binning asother
.Parameters: - other (
Hist
) – the other Hist - data (array-like) – the data to be histogrammed. For multidimensional
histograms,
data
will be transposed for input intonp.histogramdd()
. - weights (array-like) – the weights
Returns: the
Hist
- other (
-
histlite.
hist_like_indices
(other, ravel_indices, weights=None)[source]¶ Create a
Hist
using pre-computed per-sample indices fromother
.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
- other (
-
histlite.
hist_slide
(Ns, data, weights=None, *args, **kwargs)[source]¶ 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)[source]¶ Plot 1D
Hist
h
on matplotlib Axesax
.Parameters: 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)[source]¶ Plot 1D
Hist
h
onax
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)[source]¶ 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 prefernp.swapaxes
, possibly using multiple applications, instead.
-
histlite.
stack1d
(ax, hs, colors=None, labels=None, kws=None, interpolate=False, drawstyle='steps', ymin=0, **morekw)[source]¶ Stack histograms
hs
usingfill_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)[source]¶ 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 prefernp.swapaxes
, possibly using multiple applications, instead.