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
pickle
able.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. (Readwrite attribute)

max
¶ The (strict) upper bound on the range of values covered by the histogram. (Readwrite attribute)

num_bins
¶ The number of bins the range [min,max] is divided into, defining the bins. (Readwrite attribute)

values_center
¶ Readonly attribute returning a vector (NumPy array) of values corresponding to each bin center value.

values_lower
¶ Readonly attribute returning a vector (NumPy array) of values corresponding to each bin lower value.

values_upper
¶ Readonly 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 zerobased.

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
pickle
able.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 readonly. 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 weight1 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 aHistogram
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 humanreadable 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 xaxis 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
pickle
able.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 offchart 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 aHistogramWithErrorBars
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 humanreadable 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.
