Histogram

class Histogram.Histogram(bin_boundaries)[source]

Defines a histogram object.

The histograms can be initialized either with a tuple (hist_min,hist_max,num_bins) or a list/numpy.ndarray containing the bin boundaries, which allows for different bin widths. Multiple histograms can be added and averaged.

Note

It may be important to keep in mind that each bin contains it left edge but not the right edge. If a value is added to a histogram the bin assignment therefore follows:

bins[i-1] <= value < bins[i]

Parameters:
bin_boundariestuple

A tuple with three values (hist_min, hist_max, num_bins). This creates an evenly sized histogram in the range [hist_min, hist_max] divided into num_bins bins.

bin_boundarieslist/numpy.ndarray

A list or numpy array that contains all bin edges. This allows for non- uniform bin sizes.

Examples

Creating histograms

To create multiple histograms with the same number and size of bins we can initialize the Histogram object with a tuple (otherwise initialize with a list containing all bin edges). To fill these histograms store them in a variable, the methods add_value(value), add_histogram() and histogram() can be used.

 1>>> from Histogram import Histogram
 2>>>
 3>>> # Initialize a histogram in the range [0,10] with 10 bins
 4>>> histObj = Histogram((0, 10, 10))
 5>>>
 6>>> # Add the values [1, 1.2, 3, 5, 6.5, 9, 9] to the histogram 
 7>>> histObj.add_value([1, 1.2, 3, 5, 6.5, 9, 9])
 8>>> print(histObj.histogram())
 9[0. 2. 0. 1. 0. 1. 1. 0. 0. 2.]
10>>>
11>>> # Add a second histogram and add the values [2, 7, 7.2, 9]
12>>> histObj.add_histogram()
13>>> histObj.add_value([2, 7, 7.2, 9])
14>>> print(histObj.histogram())
15[[0. 2. 0. 1. 0. 1. 1. 0. 0. 2.]
16 [0. 0. 1. 0. 0. 0. 0. 2. 0. 1.]]
17>>>
18>>> # Store the histograms in hist as numpy.ndarray
19>>> hist = histObj.histogram()
Attributes:
number_of_bins_: int

Number of histogram bins.

bin_edges_: numpy.ndarray

Array containing the edges of the bins.

number_of_histograms_: int

Number of created histograms.

histograms_: numpy.ndarray

Array containing the histograms (might be scaled).

histograms_raw_count_: numpy.ndarray

Array containing the raw counts of the histograms.

error_: numpy.ndarray

Array containing the histogram error.

scaling_: numpy.ndarray

Array containing scaling factors for each bin.

Methods

histogram:

Get the created histogram(s)

histogram_raw_counts:

Get the raw bin counts of the histogram(s).

number_of_histograms:

Get the number of current histograms.

bin_centers: numpy.ndarray

Get the bin centers.

bin_width: numpy.ndarray

Get the bin widths.

bin_bounds_left: numpy.ndarray

Extract the lower bounds of the individual bins.

bin_bounds_right: numpy.ndarray

Extract the upper bounds of the individual bins.

bin_boundaries: numpy.ndarray

Get the bin boundaries.

add_value:

Add one or multiple values to the latest histogram.

add_histogram:

Add a new histogram.

average:

Averages over all histograms.

average_weighted:

Performs a weighted average over all histograms.

standard_error:

Get the standard deviation for each bin.

statistical_error:

Statistical error of all histogram bins in all histograms.

scale_histogram:

Multiply latest histogram with a factor.

set_error:

Set the error for the histogram by hand.

print_histogram:

Print the histogram(s) to the terminal.

write_to_file:

Write one histogram to a csv file.

Histogram.histogram()[source]

Get the current histogram(s).

Returns:
histograms_: numpy.ndarray

Array containing the histogram(s).

Histogram.histogram_raw_counts()[source]

Get the raw bin counts of the histogram(s), even after the original histograms are scaled or averaged.

Returns:
histograms_raw_count_: numpy.ndarray

Array containing the raw counts of the histogram(s)

Histogram.number_of_histograms()[source]

Get the number of current histograms.

Returns:
number_of_histograms_: int

Number of histograms.

Histogram.bin_centers()[source]

Get the bin centers.

Returns:
numpy.ndarray

Array containing the bin centers.

Histogram.bin_width()[source]

Get the bin widths.

Returns:
numpy.ndarray

Array containing the bin widths.

Histogram.bin_bounds_left()[source]

Extract the lower bounds of the individual bins.

Returns:
numpy.ndarray

Array containing the lower bin boundaries.

Histogram.bin_bounds_right()[source]

Extract the upper bounds of the individual bins.

Returns:
numpy.ndarray

Array containing the upper bin boundaries.

Histogram.bin_boundaries()[source]

Get the bin boundaries.

Returns:
numpy.ndarray

Array containing the bin boundaries.

Histogram.add_value(value)[source]

Add value(s) to the latest histogram.

Different cases, if there is just one number added or a whole list/ array of numbers.

Parameters:
value: int, float, np.number, list, numpy.ndarray

Value(s) which are supposed to be added to the histogram instance.

Raises:
TypeError

if the input is not a number or numpy.ndarray or list

Histogram.add_histogram()[source]

Add a new histogram to the Histogram class instance.

If new values are added to the histogram afterwards, these are added to the last histogram.

Histogram.average()[source]

Average over all histograms.

When this function is called the previously generated histograms are averaged with the same weigths and they are overwritten by the averaged histogram. The standard error of the histograms is computed.

Returns:
Histogram

Returns a Histogram object.

Raises:
TypeError

if there is only one histogram

Histogram.average_weighted(weights)[source]

Weighted average over all histograms.

When this function is called the previously generated histograms are averaged with the given weigths and they are overwritten by the averaged histogram. The standard error of the histograms is computed.

Parameters:
weights: numpy.ndarray

Array containing a weight for each histogram.

Returns:
Histogram

Returns a Histogram object.

Raises:
TypeError

if there is only one histogram

Histogram.standard_error()[source]

Get the standard deviation over all histogram counts for each bin.

Returns:
numpy.ndarray

Array containing the standard deviation for each bin.

Histogram.statistical_error()[source]

Compute the statistical error of all histogram bins for all histograms.

Returns:
numpy.ndarray

2D Array containing the statistical error for each bin and histogram.

Histogram.scale_histogram(value)[source]

Scale the latest histogram by a factor.

Multiplies the latest histogram by a number or a list/numpy array with a scaling factor for each bin.

Parameters:
value: int, float, np.number, list, numpy.ndarray

Scaling factor for the histogram.

Histogram.set_error(own_error)[source]

Sets the histogram error by hand. This is helpful for weighted histograms where the weight has also an uncertainty.

This function has to be called after averaging, otherwise the error will be overwritten by the standard error.

Parameters:
value: list, numpy.ndarray

Values for the uncertainties of the individual bins.

Histogram.print_histogram()[source]

Print the histograms to the terminal.

Histogram.write_to_file(filename, label_bin_center, label_bin_low, label_bin_high, label_distribution, label_error, comment='')[source]

Write one histogram to a csv file.

Parameters:
filename: string

Name for the output file

label_bin_center: string

Label for the bin center column.

label_bin_low: string

Label for the lower boundary of the bins.

label_bin_high: string

Label for the upper boundary of the bins.

label_distribution: string

Label for the histogram / distribution.

label_error: string

Label for the statistical error.

comment: string

Additional comment at the beginning of the file. It is possible to give a multi line comment, where each line should start with a ‘#’.

Raises:
ValueError

if there is more than one histogram