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
pickle
able.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
pickle
able.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 aUniformBinsRealHistogram
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 inUniformBinsHistogram
is available to this class as well.This class is
pickle
able.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
pickle
able.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 aUniformBinsHistogramWithErrorBars
instance.
-
-
class
tomographer.
AveragedSimpleHistogram
¶ Bases:
tomographer.UniformBinsHistogramWithErrorBars
A
UniformBinsHistogramWithErrorBars
which results from the averaging of severalUniformBinsHistogram
histograms.Add histograms to average together using the
addHistogram()
method, and then callfinalize()
. 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
pickle
able.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 callfinalize()
to finalize the averaging procedure.
-
-
class
tomographer.
AveragedSimpleRealHistogram
¶ Bases:
tomographer.UniformBinsHistogramWithErrorBars
A
UniformBinsHistogramWithErrorBars
which results from the averaging of severalUniformBinsRealHistogram
histograms.This class is identical in functionality to
AveragedSimpleHistogram
, except that the histograms which are to be averaged areUniformBinsRealHistogram
objects.This class is
pickle
able.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 callfinalize()
to finalize the averaging procedure.
-
-
class
tomographer.
AveragedErrorBarHistogram
¶ Bases:
tomographer.UniformBinsHistogramWithErrorBars
A
UniformBinsHistogramWithErrorBars
which results from the averaging of severalUniformBinsHistogramWithErrorBars
histograms.This class is essentially identical in functionality to
AveragedSimpleHistogram
andAveragedSimpleRealHistogram
, except that the histograms which are to be averaged areUniformBinsHistogramWithErrorBars
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
pickle
able.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 callfinalize()
to finalize the averaging procedure.
-