hist — Histograms

matplotlib histograms are not super-great for real time monitoring. Sure enough, matplotlib will allow you to draw a histogram, but not, e.g., to update the content without rebinning the entire sample each time.

This module provides a base abstract class (AbstractHistogram) implemening a general, n-dimensional histogram, as well as concrete classes that can be used for online monitoring.

• Histogram1d: generic one-dimensional histogram;

• Histogram2d: generic two-dimensional histogram;

• Matrix2d: specialized two-dimensional histogram to display

  matrix-like data (e.g., hitmaps in logical space).

Warning

This module is still experimental and interfaces might change.

Module documentation

Histogram facilities.

class astropix_analysis.hist.RunningStats(n: int = 0, mean: float = 0.0, M2: float = 0.0)

Online mean and standard deviation using Welford’s algorithm.

classmethod from_sample(x: ndarray) → RunningStats

Create a RunningStats object from a data sample.

This is much more efficient than processing the numbers in the sample one by one because it is tranforming the input sample into a numpy array and doing the calculation of the sample average and variance in C.

Parameters:

x (array_like) – The input sample. This is generally a 1-dimensional numpy array. Lists, tuples and iterables in general will be converted to a numpy array if possible. Multidimensional arrays will be flattened.

merge(other: RunningStats) → RunningStats

Merge another RunningStat object into the current one.

Note this happens in place, and no new object is created. A reference to the original object is returned, so that multiple calls can be conveniently chained.

update(x: ndarray) → None

Update the running statistics with more data.

property n: int

Return the sample size.

property mean: float

Return the current mean of the sample.

property variance: float

Return the (unbiased) sample variance.

property stdev: float

Return the standard deviation of the sample.

exception astropix_analysis.hist.InvalidShapeError(expected, actual)

RuntimeError subclass to signal an invalid shape while operating with arrays.

class astropix_analysis.hist.AbstractHistogram(bin_edges: tuple, axis_labels: list)

Base class for an n-dimensional weighted histogram.

This interface to histograms is profoundly different for the minimal numpy/matplotlib approach, where histogramming methods return bare vectors of bin edges and counts.

Parameters:

• bin_edges (n-dimensional tuple of arrays) – the bin edges on the different axes.

• axis_labels (n-dimensional tuple of strings) – the text labels for the different axes.

PLOT_OPTIONS = {}

_zeros(dtype: type = <class 'float'>) → ndarray

Return an array of zeros of the proper shape for the underlying histograms quantities.

_check_array_shape(data: array) → None

Check the shape of a given array used to update the histogram.

reset() → None

Reset the histogram.

bin_centers(axis: int = 0) → array

Return the bin centers for a specific axis.

bin_widths(axis: int = 0) → array

Return the bin widths for a specific axis.

errors() → array

Return the errors on the bin content.

fill(*values, weights=None) → AbstractHistogram

Fill the histogram from unbinned data.

Note this method is returning the histogram instance, so that the function call can be chained.

set_content(content: array, errors: array = None)

Set the bin contents programmatically from binned data.

Note this method is returning the histogram instance, so that the function call can be chained.

set_errors(errors: array) → None

Set the proper value for the _sumw2 underlying array, given the errors on the bin content.

static bisect(bin_edges: array, values: array, side: str = 'left') → array

Return the indices corresponding to a given array of values for a given bin_edges.

find_bin(*coords) → tuple

Find the bin corresponding to a given set of “physical” coordinates on the histogram axes.

This returns a tuple of integer indices that can be used to address the histogram content.

find_bin_value(*coords) → float

Find the histogram content corresponding to a given set of “physical” coordinates on the histogram axes.

normalization(axis: int = None)

return the sum of weights in the histogram.

empty_copy()

Create an empty copy of a histogram.

copy()

Create a full copy of a histogram.

abstractmethod _draw(axes, **kwargs) → None

No-op method, to be overloaded by derived classes.

draw(axes=None, **kwargs) → None

Plot the histogram.

_abc_impl = <_abc._abc_data object>

class astropix_analysis.hist.Histogram1d(xbinning: array, xlabel: str = '', ylabel: str = 'Entries/bin')

A one-dimensional histogram.

PLOT_OPTIONS = {'alpha': 0.4, 'histtype': 'stepfilled', 'lw': 1.25}

_draw(axes, **kwargs) → None

Overloaded method.

_abc_impl = <_abc._abc_data object>

class astropix_analysis.hist.Histogram2d(xbinning, ybinning, xlabel='', ylabel='', zlabel='Entries/bin')

A two-dimensional histogram.

PLOT_OPTIONS = {'cmap': <matplotlib.colors.LinearSegmentedColormap object>}

_update_color_bar(axes, image) → None

Update the color bar after a histogram re-draw.

This is a little bit tricky, as by default the colorbar gets her own axes, and a call to plt.gca().cla() will not delete the color bar. This is a small utility function to draw the color bar the first time around, and then re-bind to the latest version of the data each time the histogram is re-drawn.

_draw(axes, logz=False, **kwargs)

Overloaded method.

slice(bin_index: int, axis: int = 0)

Return a slice of the two-dimensional histogram along the given axis.

slices(axis: int = 0)

Return all the slices along a given axis.

hslice(bin_index: int)

Return the horizontal slice for a given bin.

hslices()

Return a list of all the horizontal slices.

hbisect(y: float)

Return the horizontal slice corresponding to a given y value.

vslice(bin_index)

Return the vertical slice for a given bin.

vslices()

Return a list of all the vertical slices.

vbisect(x)

Return the vertical slice corresponding to a given y value.

_abc_impl = <_abc._abc_data object>

class astropix_analysis.hist.Matrix2d(num_cols: int, num_rows: int, xlabel='Column', ylabel='Row', zlabel='Entries/bin')

Specialized 2-dimensional histogram to display matrix-like data (e.g., hitmap in logical space).

_draw(axes, logz=False, **kwargs)

Overloaded method.

Note we have to transpose the underlying content due to the very nature of item addressing in numpy arrays.

Warning

This points to the fact that some of the Histogram2d interfaces might be broken, and we might better off with a content() method that one can overload.

_abc_impl = <_abc._abc_data object>