pybdt.histlite module

Calculate and plot histograms easily.

Numerous solutions are possible and already exist for generating and plotting histograms with matplotlib. This module aims to provide the minimal interface needed to add this useful functionality to a matplotlib environment.

class pybdt.histlite.Binner(bins=50, range=None)

Bases: object

Tool to generate Hist instances.

property bins

The bins to be passed to numpy.histogram().

hist(array, weights=None)

Create a Hist.

property kwargs

The numpy.histogram() keyword arguments.

property range

The range to be passed to numpy.histogram().

class pybdt.histlite.Binner2D(bins=50, range=None)

Bases: object

Tool to generate Hist2D instances.

property bins

The bins to be passed to numpy.histogram2d().

hist(x, y, weights=None)

Create a Hist2D.

property kwargs

The numpy.histogram2d() keyword arguments.

property range

The range to be passed to numpy.histogram2d().

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

Bases: Line

A histogram.

property cumulative_left

The cumulative histogram, adding to the left.

property cumulative_right

The cumulative histogram, adding to the right.

efficiency(base_hist)

Get an efficiency plot 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.

property integral

The integral of the histogram.

property integral_normed

A copy of this Hist normalized so the integral is 1.

rebin(bins, tol=0.0001)

Produce coarser binning.

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)

Draw n random samples from the histogram.

property sum

The sum of the bin values.

property sum_normed

A copy of this Hist normalized so the bin counts sum to 1.

class pybdt.histlite.Hist2D(xbins, ybins, values, errors=None)

Bases: Surface2D

A 2D histogram.

property colcumulative_left
property colcumulative_right
property colintegrals

The sums of each row (adding along x).

property colintegrals_normed

A copy of this Hist2D normalized so each column sums to 1.

property colsums

The sums of each column (adding along y).

property colsums_normed

A copy of this Hist2D normalized so each column sums to 1.

property cumulative_left
property cumulative_right
efficiency(base_hist)

Get an efficiency plot 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.

property integral

The integral of the histogram.

This function assumes equal bin spacing.

property integral_normed

A copy of this Hist2D normalized so the bin counts sum to 1.

property rowcumulative_left
property rowcumulative_right
property rowintegrals

The sums of each row (adding along x).

property rowintegrals_normed

A copy of this Hist2D normalized so each row sums to 1.

property rowsums

The sums of each row (adding along x).

property rowsums_normed

A copy of this Hist2D normalized so each column sums to 1.

property sum

The sum of the bin values.

property sum_normed

A copy of this Hist2D normalized so the bin counts sum to 1.

property xhist

Flatten rows to get a 1D Hist.

property xhists

Give rows as an array of 1D Hists.

property yhist

Flatten columns to get a 1D Hist.

property yhists

Give columns as an array of 1D Hists.

class pybdt.histlite.Line(bins, values, errors=None)

Bases: object

Base class for binned lines such as histograms.

at(x)

The value of the line at x (number or array).

property bin_centers

The bin centers.

property bins

The bin boundaries.

bins_match(b)

Check whether two Lines have matching bins.

Parameters:

  • a (Line) – The first object.

  • b (Line) – The second object.

Returns:

Whether the bins match (bool).

property errors

The bin value errors.

property values

The bin values, or counts.

class pybdt.histlite.Plotter(axes, twin_axes=None, log=False, twin_log=None, expx=False, errormin=None)

Bases: object

Tool for plotting Line objects.

add(line_to_add, twin=False, style=None, **kwargs)

Add a Line.

Parameters:

  • line_to_add (Line) – The line.

  • twin (bool) – Whether to use the secondary axes (default: use main axes)

  • style (Style) – The style for this line.

If additional keyword arguments are given, then this line is plotted with a Style containing these extra keyword arguments.

property axes

The matplotlib Axes.

property expx

If true, convert \(x\) -> \(10^x\)

finish(legend=None)

Deprecated since plotting was moved to Plotter._do_plot().

legend(**kwargs)

Draw the legend.

All keyword arguments are passed to axes.legend().

property line_axes

The list of axes specifications for this Plotter (elements are ‘main’ or ‘twin’).

property line_styles

The list of keyword argument dicts for this Plotter.

property lines

The list of Lines for this Plotter.

property log

Whether to use a log y scale on the main axes.

property twin_axes

The matplotlib twinx Axes.

property twin_log

Whether to use a log y scale on the twin axes.

class pybdt.histlite.Style(line=True, markers=False, errorbars=False, errorcaps=False, **kwargs)

Bases: object

Simple style object for Lines.

copy(**kwargs)

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

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

property errorbars

Whether to draw error bars.

property errorcaps

Whether to draw error bar caps.

property kwargs

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

property line

Whether to draw a line.

property markers

Whether to draw point markers.

update(**kwargs)

Update the keyword args with the given values.

class pybdt.histlite.Surface2D(xbins, ybins, values, errors=None)

Bases: object

Base class for binned surfaces such as 2D histograms.

bins_match(b)

Check whether two Surface2Ds have matching bins.

Parameters:
Returns:

Whether the bins match (bool).

property errors

The bin value errors.

property values

The bin values, or counts.

property xbins

The x bin boundaries.

property ybins

The y bin boundaries.

pybdt.histlite.function_to_surface(x, y, func, hist=False)

Return a Surface2D evaluating func on the x, y grid.

Parameters:

  • x (array-like) – Evenly spaced x values.

  • y – array-like

  • y – Evenly spaced y values.

  • func (function) – Function to evaluate at each x,y point.

  • hist (bool) – If true, return a Hist2D instead of a Surface2D.

Returns:

A Surface2D or Hist2D where the bin values are the function values at each point.

pybdt.histlite.plot_surface(axes, surface, log=False, expx=False, expy=False, cbar=False, **kwargs)

Plot a Surface2D.

Parameters:

  • axes (matplotlib Axes) – The main axes on which to plot.

  • surface (Surface2D) – The histogram to plot.

  • log (bool) – Whether to use a log color scale

  • expx (bool) – If true, convert \(x\) -> \(10^x\)

  • expy (bool) – If true, convert \(y\) -> \(10^y\)

  • cbar (bool) – If true, draw colorbar.

  • zmin (float) – Minimum value to plot with color; bins below the minimum value will be white.

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

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

pybdt.histlite.plot_surface_lines(axes, surface, varname, horizontal='x', log=False, expx=False, fmt='.3f', cmap='jet')