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().

Skip to:

Changed in version 5.0: The histogram classes now use NumPy internal arrays for storing their data, so that the count data type is not statically fixed. The HistogramReal class has been deprecated.

Changed in version 5.0: The AveragedSimpleHistogram, AveragedSimpleRealHistogram and AveragedErrorBarHistogram classes have been deprecated. The logic is that they aren’t really needed especially on the Python side, and if we wish to make this functionality available it would make more sense to do so via the AggregatedHistogram classes.

Deprecated Aliases

The following aliases are provided for compatibility with older versions of Tomographer (before Tomographer 5): UniformBinsHistogramParams, UniformBinsHistogram, UniformBinsRealHistogram, and UniformBinsHistogramWithErrorBars.

class tomographer.HistogramParams

Bases: pybind11_builtins.pybind11_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::HistogramParams, with the template parameter Scalar=double.

HistogramParams(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.Histogram

Bases: pybind11_builtins.pybind11_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 mirrors the C++ class Tomographer::HistogramParams. See the C++ class documentation for more information. However, the Python implementation uses NumPy arrays internally, so it can transparently store different bin count types.

Changed in version 4.1: Replaced the class static attribute HasErrorBars by the property has_error_bars.

Changed in version 5.0: This class no longer has a fixed storage type, now using a NumPy array internally. The HistogramReal has been deprecated.

Histogram([params=HistogramParams()])

Construct a new histogram object with the given histogram parameters.

Histogram(min, max, num_bins)

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

params

The HistogramParams 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 HistogramParams.

values_lower

A shorthand for params.values_lower. See HistogramParams.

values_upper

A shorthand for params.values_upper. See HistogramParams.

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[.

has_error_bars

The constant False. Note that, by contrast to the correpsonding C++ class, this is an instance property and not a class property. (This is because in Python, you don’t usually have natural direct access to the type, only to the instance.)

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 Histogram instance.

normalizedCounts()

Get a version of this histogram, normalized by total counts. See the doc for the corresponding C++ function.

numBins()

A shorthand for params.num_bins. See HistogramParams.

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.

totalCounts()

Return the total number of histogram counts (no normalization)

This returns the sum of all bins contents, plus the off_chart counts. This does not account for the normalization and completely ignores the x-axis scaling.

class tomographer.HistogramWithErrorBars

Bases: tomographer.Histogram

A histogram (with uniform bin size), with error bars associated to each bin.

This class internally inherits Histogram, 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.

Changed in version 4.1: Replaced the class static attribute HasErrorBars by the property has_error_bars.

Changed in version 5.0: This class no longer has a fixed storage type, now using NumPy arrays internally.

In addition to the members inherited from Histogram, 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.

has_error_bars

The constant True. Note that, by contrast to the correpsonding C++ class, this is an instance property and not a class property. (This is because in Python, you don’t usually have natural direct access to the type, only to the instance.)

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 HistogramWithErrorBars instance.

normalizedCounts()

Get a version of this histogram, normalized by total counts. See the doc for the corresponding C++ function.

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.

reset()

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