pyhistogram package

Submodules

pyhistogram.axis module

The Axis class functions allows quick access to information about the histograms binnings etc.

class pyhistogram.axis.Axis(hist, *args)

Bases: object

The Axis is the container for all the functions specific to one particular dimension of the histogram.

E.g. the type of the edge values, number of bins etc.

Initialization of a new axis

Parameters:

• hist (Hist) – The histogram to which this axis belongs
• args (array_like) – Either: * Only element of type list it gives the bin edges * Three elements: nbins (int), lowest bound, highest bound

Example

Initialization with bin edges

>>> ax = Axis(hist, [1, 4, 9])
>>> ax = Axis(hist, ['My', 'name', 'is', 'Bond']])

Initialization with number of bins (10), lowest (0) and highest bound (1)

>>> ax = Axis(hist, 10, 0, 1)

get_bin_center(i)

Returns the center of the given bin, if appropriate converted to the axis’s type.

This function is not available if the axis is of type ‘regex’.

Parameters:i (int) – Axis bin number Return type:float or datetime

get_bin_centers()

Returns the centers of the bins along this axis.

This function is not available if the axis is of type ‘regex’.

Return type:array_like

get_bin_edges(convert=True)

Returns the edges of the bins along this axis.

This function is not available if the axis is of type ‘regex’.

Parameters:convert (bool) – If true, the returned value will be converted to the appropriate type of the axis (e.g. datetime) Returns:The length of this array is nbins + 1 Return type:array_like

get_bin_low_edge(i, convert=True)

Returns only the lower bin edges of the bins along this axis.

This function is not available if the axis is of type ‘regex’.

Parameters:convert (bool) – If true, the returned value will be converted to the appropriate type of the axis (e.g. datetime) Return type:array_like

get_bin_regex(i)

Return the regex for the respective bin on this axis.

This function is not available if the axis is of type datetime, numerical

Parameters:i (int) – Axis bin number Return type:array_like

get_bin_regexes()

Returns the regexes (not the patterns) of the bins along this axis.

This function is only available for axes of the type ‘regex’.

Return type:array_like

get_bin_up_edge(i, convert=True)

Returns only the upper bin edge of for a given axis-bin number.

This function is not available if the axis is of type ‘regex’.

Parameters:convert (bool) – If true, the returned value will be converted to the appropriate type of the axis (e.g. datetime) Return type:array_like

get_bin_width(i)

Returns the width of the given bin in the appropriate type.

This function is not available if the axis is of type ‘regex’.

Parameters:i (int) – Axis bin number Return type:float or datetime

nbins

Returns the number of bins along this axis.

Return type:int

pyhistogram.bin_container module

class pyhistogram.bin_container.Bin_container(nxbins, nybins=1, nzbins=1)

Bases: object

This class provides access to the histogram’s bins without creating the need for the user to know anything about the internal storage mechanisms. Bins are organized in one long array with a unique mapping from the axis bin numbers i, j, k to the global bin number b. It is important to remember that each of these indices starts at 1 not 0.

Having I bins along the x-axis, J bins along the y-axis and K bins along the z-axis, the mapping from the xyz bin numbers (i, j, k) to the global bin number b is given by::

b = (k-1)*(J-1)*I + (j-1)*I + i

Thus, in case of a 2D histogram (k=K=1; j>1) this reduces to::

b = (j-1)*I + i

and for a 1D histogram (k=K=1=j=J=1)::

b = i

The bin container class does not deal with the finding of bins in user defined units. It exclusively deals with bin numbers and leaves the user defined bin sizes and units to the axis class.

Initialization of the Bin_container.

Parameters:nybins, nzbins (nxbins,) – Number of bins along each axis. Must be greater than 1

fill_bin(gidx, weight=1)

Increment the value of the given bin by the given weight

Parameters:gidx (int) – Global bin number Return type:None

get_bin_content(gidx)

Returns the content of a given bin.

Parameters:gidx (int) – Global bin number Return type:float

get_bin_error(gidx)

Returns the error of a given bin.

Parameters:gidx (int) – Global bin number Return type:float

get_global_bin_from_ijk(i, j=1, k=1)

Returns the global bin number given the axis bin numbers.

The axis bin numbers are denoted as i, j, k for the x, y and z axis respectively. They are element of [1, N] where N is I, J, or K respectively.

Parameters:

• i (int) – Local bin number of the x axis
• j,k (int, optional) – Local bin numbers of the y and z axis. (Default 1)

Return type:

int

get_ijk_from_global_bin(gidx)

Returns the local bin numbers for each axis given the global bin number.

Parameters:gidx (int) – Global bin number Returns:The three axis bin numbers (i, j, k) Return type:tuple

nbins

Returns the total number of bins of in this histogram

Return type:int

set_bin_content(gidx, v)

Replaces the content of a bin with the given value.

Parameters:

• gidx (int) – Global bin number
• v (float) – New content of this bin

set_bin_error(gidx, e)

Replaces the error of a bin with the given value.

Parameters:

• gidx (int) – Global bin number
• e (float) – New error of this bin

pyhistogram.bin_proxy module

class pyhistogram.bin_proxy.Bin_proxy(hist, gidx)

Bases: object

The bin proxy is a convenient interface for getting additional information about each bin when iterating through several bins of the histogram.

The bin proxy is created for each bin yielded by h.bins(), e.g.::

>>> for bin in h.bins():
...     print bin.center

Initialization of a new Bin_proxy.

Parameters:

• hist (pyhistogram.Hist) – Parent histogram to which this bin belongs
• gidx (int) – Global bin index

axial_indices

Returns the axial indices (i, j, k) for this bin.

This function always returns three indices regardless of the histograms dimensionality.

Returns:Tuple of the three axial indices (i, j, k) Return type:tuple

axis_bininfo(ax, ax_idx)

effective_entries

Number of effective entries in this bin. The number of unweighted entries this bin would need to contain in order to have the same statistical power as this bin with possibly weighted entries, estimated by:

(sum of weights) ** 2 / (sum of squares of weights)

error

Return the error of this bin.

Return type:float

value

Return the value of this bin.

Return type:float

x

Provides an entry point for retrieving x-axis specific information from this bin.

Return type:pyhistogram.bin_proxy.bi

y

Provides an entry point for retrieving y-axis specific information from this bin.

Return type:pyhistogram.bin_proxy.bi

z

Provides an entry point for retrieving z-axis specific information from this bin.

Return type:pyhistogram.bin_proxy.bi

pyhistogram.flow_exceptions module

Defining exceptions to be raised if a look for a bin yielded an over/under flow

exception pyhistogram.flow_exceptions.OverflowException

Bases: exceptions.Exception

exception pyhistogram.flow_exceptions.UnderflowException

Bases: exceptions.Exception

pyhistogram.hist module

The Hist classes are the entry point for the user for creating and using the histogram

class pyhistogram.hist.Hist(*args)

Bases: object

Initialization of a one dimensional histogram

A histogram can either be specified in two ways:

1. By the number of bins, lower and upper bound. The equidistant bin edges will be calculated automatically.
2. By specifying the bin edges explicitly.

Parameters:

• width (Variable) –
• args (array_like) – The first element must be an int (number of bins), the second and third may be either int or float or datetime
• width –
• args – Array like object of length one. The first and only element is of type list or tuple with elements of type int or float or datetime

bins()

A iterator for all the bins in the histogram.

Returns:A class giving easy access to all the information of this bin. Return type:Bin_proxy

fill(x, y=None, z=None, weight=1)

Function for adding content to the histogram.

The bin containing the given x coordinate will be incremented with the value given as weight.

Parameters:

• y, z (x,) – The given type has to be compatible to the type used when initializing the histogram. y and z only have to be specified if the histogram is of corresponding dimensionality.
• weight (int or float) – value by which the content of the bin containing the given coordinates is increased.

Example

>>> h = Hist(10, 0, 1)
>>> h.fill(2.5, weight=0.5)

get_overflow()

Return overflow of the entire histogram.

No differentiation between individual axes nor under and overflow is implemented, yet.

Returns:The number of times the histogram was filled with coordinates not matching any bins Return type:int

plot(**kwargs)

Plot the current histogram.

This requires matplotlib to be installed. All the given keywords are passed to the bar() function of matplotlib.

Parameters:kwargs (dict) – are passed on to the bar() function of matplotlib. Returns:This is the return value of the bar() function Return type:matplotlib.patches.Rectangle

pyhistogram.hist.Hist1D(*args, **kwargs)

pyhistogram.utils module

class pyhistogram.utils.UTC

Bases: datetime.tzinfo

UTC

dst(dt)

tzname(dt)

utcoffset(dt)

pyhistogram.utils.convert_to_dtype(v, dtype)

Convert v to a python datetime if dtype is ‘datetime’

Module contents