Histogram Classes (tomographer)

This collection of classes take care of recording, storing and manipulating a histogram. Typically such a class would be returned by a core task such as tomographer.tomorun.tomorun().

class tomographer.UniformBinsHistogramParams

Bases: object

Specify histogram bins parameters: the minimum value, the maximum value, and the number of bins. The interval [min,max[ is split into num_bins equally spaced bins.

This class is pickleable.

See also

This python class interfaces its corresponding C++ class Tomographer::UniformBinsHistogramParams, with the template parameter Scalar=double.

UniformBinsHistogramParams(min=0.0, max=1.0, num_bins=50)

Construct a histogram parameters configuration.

min

The lower bound on the range of values covered by the histogram. (Read-write attribute)

max

The (strict) upper bound on the range of values covered by the histogram. (Read-write attribute)

num_bins

The number of bins the range [min,max] is divided into, defining the bins. (Read-write attribute)

values_center

Read-only attribute returning a vector (numpy array) of values corresponding to each bin center value.

values_lower

Read-only attribute returning a vector (numpy array) of values corresponding to each bin lower value.

values_upper

Read-only attribute returning a vector (numpy array) of values corresponding to each bin upper value.

binCenterValue(index)

Returns the value which a given bin index represents (center bin value).

binIndex(value)

Get the index of the bin in which the given value would be saved in. Indexes are of course zero-based.

binLowerValue(index)

Returns the value which a given bin index represents (lower bin value limit).

Raise a TomographerCxxError if the index is invalid.

binResolution()

Returns the width of a bin. This is simply \((\mathit{max} - \mathit{min})/\mathit{num_bins}\).

binUpperValue(index)

Returns the value which a given bin index represents (upper bin value limit).

isWithinBounds(value)

Check whether the given value is within the bounds of the histogram, that is, in the range [min, max[.

class tomographer.UniformBinsHistogram

Bases: object

A histogram object. An interval [min,max] is divided into num_bins bins, each of same width. Each time a new value is to be recorded, the corresponding bin’s counter is incremented.

This class is pickleable.

See also

This python class interfaces the C++ class Tomographer::UniformBinsHistogramParams, with the template parameters Scalar=double and CountType=int. See the C++ class documentation for more information.

UniformBinsHistogram([params=UniformBinsHistogramParams()])

Construct a new histogram object with the given histogram parameters.

UniformBinsHistogram(min, max, num_bins)

Alternative call syntax; the effect is the same as the other constructor.

params

The UniformBinsHistogramParams object which stores the current histogram parameters. This attribute is read-only. The parameters are specified to the constructor, and cannot be changed.

values_center

A shorthand for params.values_center. See UniformBinsHistogramParams.

values_lower

A shorthand for params.values_lower. See UniformBinsHistogramParams.

values_upper

A shorthand for params.values_upper. See UniformBinsHistogramParams.

bins

The histogram bin counts, interfaced as a NumPy array object storing integers. This attribute is readable and writable, although you may not change the size or type of the array.

off_chart

The number of recorded data points which were beyond the histogram range [params.min, params.max[.

HasErrorBars

This is a class attribute, i.e. is accessed as UniformBinsHistogram.HasErrorBars, and is set to the constant value False.

add(bins[, off_chart=0])

Add a number of counts to each bin, specifed by a vector of values bins which is expected to be a NumPy array. If off_chart is specified, the current off_chart count is increased by this number, otherwise it is left to its current value.

count(index)

Returns the number of counts in the bin indexed by index. Indexes start at zero. Raises TomographerCxxError if index is out of range.

load(bins[, off_chart=0])

Load bin values from the vector of values bins, which is expected to be a NumPy array. If off_chart is specified, the current off_chart count is also set to the given value; otherwise it is reset to zero.

normalization()

Calculate the normalization factor for the histogram. This corresponds to the total number of weight-1 data points, where the weight of a data point may be specified as a second argument to record().

normalized()

Returns a normalized version of this histogram. The bin counts as well as the off_chart counts are divided by normalization(). The returned object is a UniformBinsRealHistogram instance.

numBins()

A shorthand for params.num_bins. See UniformBinsHistogramParams.

prettyPrint([max_width=0])

Produce a human-readable representation of the histogram, with horizontal visual bars, which is suitable to be displayed in a terminal (for instance). The formatted histogram is returned as a string. If max_width is specified and nonzero, the output is designed to fit into a terminal display of the given number of characters wide, otherwise a default width is used.

record(value[, weight=1])

Record a new data sample. This increases the corresponding bin count by one, or by weight if the latter argument is provided.

reset()

Clears the current histogram counts (including off_chart counts) to zero. The histogram parameters in params are kept intact.

class tomographer.UniformBinsRealHistogram

Bases: object

A histogram (with uniform bin size), with a real count type. This class is basically a copy of UniformBinsHistogram, except that each bin’s count is a real value. (This allows, for example, the histogram to be normalized.) Every method documented in UniformBinsHistogram is available to this class as well.

This class is pickleable.

The corresponding C++ class is also Tomographer::UniformBinsHistogram, although the CountType template parameter is set to double instead of int.

class tomographer.UniformBinsHistogramWithErrorBars

Bases: tomographer.UniformBinsRealHistogram

A histogram (with uniform bin size), with a real count type and with error bars associated to each bin.

This class internally inherits UniformBinsRealHistogram, and all those methods are exposed in this class, except for add(). In addition, the reset() method also clears the error bar values, and the normalized() method returns a histogram with the appropriate error bars on the normalized histogram.

This class is pickleable.

In addition to the members inherited from UniformBinsRealHistogram, the following members are available:

delta

The error bar values on each of the histogram bin counts, interfaced as a NumPy array object storing real values. This attribute is readable and writable, although you may not change the size or type of the array.

errorBar(index)

Get the error bar value associated to the bin of the given index. Raises TomographerCxxError if index is out of range.

load(y, yerr[, off_chart=0])

Load data into the histogram. The array y specifies the bin counts, and yerr specifies the error bars on those bin counts. The off-chart counter is set to off_chart.

normalized()

Returns a normalized version of this histogram, including the error bars. The bin counts, the error bars and the off_chart counts are divided by normalization(). The returned object is again a UniformBinsHistogramWithErrorBars instance.

class tomographer.AveragedSimpleHistogram

Bases: tomographer.UniformBinsHistogramWithErrorBars

A UniformBinsHistogramWithErrorBars which results from the averaging of several UniformBinsHistogram histograms.

Add histograms to average together using the addHistogram() method, and then call finalize(). Then, the data stored in the current object will correspond to the averaged histogram. (See here the theory about how this is implemented.)

This histogram object inherits UniformBinsHistogramWithErrorBars, so all the methods exposed in that class are available to access the averaged histogram data.

This class is pickleable.

Warning

You must not forget to call finalize() before accessing the averaged histogram data. The data stored in the current histogram object is UNDEFINED before having calling finalize().

num_histograms

The number of histograms currently stored (read-only). This property may be accessed at any time, also before having called finalize().

addHistogram(histogram)

Add a new histogram to the average with the others.

finalize()

Call this function after all the histograms have been added with calls to addHistogram(). Only after calling this function may you access the averaged histogram in the current histogram object.

reset([param])

Clear all stored histograms and start a new averaging sequence. The histogram parameters are changed to param if you specify param, otherwise they are left unchanged. After calling this function, the averaged histogram class is in the same state as a freshly constructed averaged histogram object: you may call addHistogram() to add histograms to the average, after which you must call finalize() to finalize the averaging procedure.

class tomographer.AveragedSimpleRealHistogram

Bases: tomographer.UniformBinsHistogramWithErrorBars

A UniformBinsHistogramWithErrorBars which results from the averaging of several UniformBinsRealHistogram histograms.

This class is identical in functionality to AveragedSimpleHistogram, except that the histograms which are to be averaged are UniformBinsRealHistogram objects.

This class is pickleable.

Warning

You must not forget to call finalize() before accessing the averaged histogram data. The data stored in the current histogram object is UNDEFINED before having calling finalize().

num_histograms

The number of histograms currently stored (read-only). This property may be accessed at any time, also before having called finalize().

addHistogram(histogram)

Add a new histogram to the average with the others.

finalize()

Call this function after all the histograms have been added with calls to addHistogram(). Only after calling this function may you access the averaged histogram in the current histogram object.

reset([param])

Clear all stored histograms and start a new averaging sequence. The histogram parameters are changed to param if you specify param, otherwise they are left unchanged. After calling this function, the averaged histogram class is in the same state as a freshly constructed averaged histogram object: you may call addHistogram() to add histograms to the average, after which you must call finalize() to finalize the averaging procedure.

class tomographer.AveragedErrorBarHistogram

Bases: tomographer.UniformBinsHistogramWithErrorBars

A UniformBinsHistogramWithErrorBars which results from the averaging of several UniformBinsHistogramWithErrorBars histograms.

This class is essentially identical in functionality to AveragedSimpleHistogram and AveragedSimpleRealHistogram, except that the histograms which are to be averaged are UniformBinsHistogramWithErrorBars objects, i.e. each histogram added already has information about error bars. Those error bars are then combined appropriately, as described in the theory about how this class is implemented.

This class is pickleable.

Warning

You must not forget to call finalize() before accessing the averaged histogram data. The data stored in the current histogram object is UNDEFINED before having calling finalize().

num_histograms

The number of histograms currently stored (read-only). This property may be accessed at any time, also before having called finalize().

addHistogram(histogram)

Add a new histogram to the average with the others.

finalize()

Call this function after all the histograms have been added with calls to addHistogram(). Only after calling this function may you access the averaged histogram in the current histogram object.

reset([param])

Clear all stored histograms and start a new averaging sequence. The histogram parameters are changed to param if you specify param, otherwise they are left unchanged. After calling this function, the averaged histogram class is in the same state as a freshly constructed averaged histogram object: you may call addHistogram() to add histograms to the average, after which you must call finalize() to finalize the averaging procedure.