API Reference for Histogram Module

This module defines classes required for histogramming:

Hist1D - A 1D histogram

Hist2D - A 2D histogram

Hist3D - A 3D histogram

HistND - An N-Dimensional histogram

Note

The classes defined in this module do NOT provide drawing capabilities, so there is NO draw() nor paint() method. Use other libraries like matplotlib to plot the data. But for your convenience, this package provides a module for easy plotting using matplotlib. See, qksplot.mpl

class qksplot.hist.HistAxis(bins, title='')[source]

An axis for use in constructing histograms

Parameters:bins (Sequence) – an ordered (ascending order) array of floats containing the lower edges of the bins
density() → float[source]

the density of the bins = number of bins over the length (maxBin - minBin)

get_bin(x: float) → int[source]

Returns the bin index that contains ‘x’ value, such that for that bin minBin <= x < maxBin

Parameters:x (float) – a valid value on the axis
Returns:int. Or, -1 is returned if there is no such bin.
get_bin_center(i: int) → float[source]

Returns the value of the center in bin ‘i’

get_bins() → Sequence[source]

Returns all bins lower edges of the axis.

Returns:List[float]. A list with lower edges of each bin
get_bins_centers()[source]

Returns the a list containing the centers of all bins.

maxBin

returns the maximum right edge of the last bin

minBin

returns the minimum low edge of first bin

nbins

returns the total number of the bins

class qksplot.hist.HistND(dim: int, minBin: Sequence, maxBin: Sequence, nBins: Sequence, title='')[source]

An N-Dimensional Histogram.

Parameters:
  • dim (int) – the number of dimensions of the histogram
  • minBin (Sequence) – an array containing the minimum value of lower (leftmost) edge of bins for each dimension.
  • maxBin (Sequence) – an array containing the maximum value of upper (rightmost) edge of bins for each dimension.
  • nBins (Sequence) – an array containing the number of bins for each dimension.
  • title (string) – the title of the histogram.
bins_to_cell(*args) → int[source]

Converts bin indexes to global linear bin (cell) index.

Returns the index of the cell that is located by the bin indexes on the axes

Parameters:args (a list of parameters) – bin index on each dimension. The number of arguments must be the same as the number of dimensions. Or pass one argument as a sequence (same size as number of dimensions).
Returns:int. The cell index (global linear bin index)

See also

cell_to_bins(), pos_to_cell()

cell_to_bins(idx_cell: int) → List[int][source]

Converts cell index to indexes of bins.

returns a list of bin indexes on the axes that refer to this cell “idx_cell”

Parameters:idx_cell (int) – the cell indexes.
Returns:List[int]. A length of the same as the histogram dimension

See also

bins_to_cell(), pos_to_cell()

cells

total number of cells (global linear bins)

dimension

number of dimensions

entries

total number of entries

fill(*args, **kwargs) → int[source]

Fill the histogram.

Parameters:
  • args (a list of parameters) – a list of positions on each dimension. The number of arguments must be the same as the number of dimensions. Or pass one argument as a sequence (same size as number of dimensions).
  • weight (float) – the weight to fill in. Defaults to 1.0
  • kwargs (Dict) – currently this parameter is not used for histograms
Returns:

int. The index of the affected cell (global linear bin) or -1 if no cell was found or the input values are not valid

See also

fill_cell(), fill_bins()

fill_bins(*args, **kwargs) → int[source]

Fill the histogram using bin indexes.

Parameters:
  • args (a list of parameters) – the bin indexes for each dimension. The number of arguments must be the same as the number of dimensions. Or pass one argument as a sequence (same size as number of dimensions).
  • kwargs (Dict) – this dict can accept 1 key: weight (float) - the weight to fill in. Defaults to 1.0
Returns:

int. The index of the affected cell (global linear bin) or -1 if no cell was found or the input values

are not valid

Note

b contains indexes of the bins on each axis, not the positions on axis

See also

fill_pos(), fill_cell()

fill_cell(i_cell: int, **kwargs) → int[source]

Fill the histogram using global cell index.

Parameters:
  • i_cell (int) – the global bin index (cell index).
  • kwargs (Dict) – currently this dict can accept 2 keys: weight (float) - the weight to fill in. Defaults to 1.0 error_per_bin(bool) - whether to compute weights per bins. Default is True

Warning

This is expensive operation because it computes the bins indexes (it decomposes cell index) and positions per axis before filling weights per bin. Its Recommended to use other fill_* methods

Returns:int. The index of the affected cell (global linear bin) or -1 if no cell was found or the input values are not valid (underflow or overflow)

See also

fill_pos(), fill_bins()

fill_pos(*args, **kwargs) → int[source]

Fill the histogram using a position.

Parameters:
  • args (a list of parameters) – ta list of positions on each dimension. The number of arguments must be the same as the number of dimensions. Or pass one argument as a sequence (same size as number of dimensions).
  • kwargs (Dict) – this dict can accept 1 key: weight (float) - the weight to fill in. Defaults to 1.0
Returns:

int. The index of the affected cell (global linear bin) or -1 if no cell was found or the input values

are not valid

Note

x contains coordinates not indexes of the bins

See also

fill_cell(), fill_bins()

get_axes_list() → List[qksplot.hist.HistAxis][source]

a list of axes

get_axis(i: int) → qksplot.hist.HistAxis[source]

get the axis for dimension ‘i’

get_bins_centers(includeEmptyBins: bool = False) → List[List[float]][source]

Returns the positions of the centers of all bins per each dimension (axis). By default it does not include empty cells.

Parameters:includeEmptyBins (bool) – if empty bins are included in the list. If True then empty bins are included, otherwise they are NOT included
Returns:list of list.
get_bins_edges(includeEmptyBins: bool = False) → List[List[float]][source]

Returns all bins per each dimension (axis). By default it does not include empty cells.

The list contains for each dimension the list of minimum edges for each cell (global linear bin)

Parameters:includeEmptyBins (bool) – if empty bins are included in the list. If True then empty bins are included, otherwise they are NOT included
Returns:list of list.
get_cell_content(i: int) → float[source]

Returns the content of the cell ‘i’ or the value of Underflow (if i<0) or Overflow (if i>= # of cells)

Parameters:i (int) – a valid cell index (aka global linear bin)
Returns:float or 0.0 if the position is outside cells ranges
get_cell_content_error(i: int) → float[source]

Returns the error value associated with cell ‘i’

Parameters:i (int) – a valid cell index (aka global linear bin)
The error is computed as follows:
  • sqrt(Sum of squared weights): If weights were used during fill
  • sqrt(bin content): If weights were NOT used during fill
Returns:float.
get_cells_contents(includeEmptyBins=False) → List[float][source]

Returns the contents of all bins (cells) per each dimension. By default it does not include empty cells.

Parameters:includeEmptyBins (bool) – if empty bins are included in the list. If True then empty bins are included, otherwise they are NOT included
Returns:list of list.
get_cells_contents_errors(includeEmptyBins=False) → List[float][source]

Returns a list containing the errors associated to each cell. By default it does not include empty cells.

Parameters:includeEmptyBins (bool) – if empty cell are included in the list. If True then empty cell are included, otherwise they are NOT included
Returns:list.
get_pos_content(*args) → float[source]

Returns the content of the cell located at position x

Parameters:args (a list of parameters) – the bin indexes for each dimension. The number of arguments must be the same as the number of dimensions. Or pass one argument as a sequence (same size as number of dimensions).
Returns:float or 0.0 if the position is outside bin ranges
get_stats() → Dict[str, float][source]

Returns general statistics about the histogram.

A dictionary with the keys: “Entries”, “SumWeights”, “SumWeights2”, “SumWeightsX”, “SumWeightsX2”
Returns:Dict{str,Any}.
integral(minCellId: int = 0, maxCellId: int = None) → float[source]

Computes integral over cells range ‘[minCellId, maxCellId]’

The integral is the sum over all cells of the product of cell’s content and the volume described by its bins:
I = Sum_i CELL_CONTENT dx * dy * dz * … dXn
Parameters:
  • minCellId (int) – minimum cell id. Default it is 0 (zero).
  • maxCellId (int) – maximum cell id. default is None, meaning all cells
Returns:

float.

See also

integral_over_bins(), integral_over_pos()

integral_over_bins(minBinsIds: Sequence, maxBinsIds: Sequence) → float[source]

Computes integral over bins range

Parameters:
  • minBinsIds (Sequence) – an array of ints containing the minimum bins over each dimension
  • maxBinsIds (Sequence) – an array of ints containing the maximum bins over each dimension
Returns:

float.

See also

integral(), integral_over_pos()

integral_over_pos(minPos: Sequence, maxPos: Sequence) → float[source]

Computes integral between 2 positions.

Parameters:
  • minPos (Sequence) – an array of floats containing the minimum position on each dimension
  • maxPos (Sequence) – an array of floats containing the maximum position on each dimension
Returns:

float.

See also

integral(), integral_over_pos()

intersect(other)[source]

intersection of 2 histograms

Parameters:other – another histogram
Returns:another histogram that represent the reunion of these 2 histograms
pos_to_cell(*args) → int[source]

Converts coordinate positions to global linear bin (cell) index.

Returns the cell index (global linear bin) that contains the point at position ‘x’. Where ‘x’ are the coordinates of a point in dimension().

Parameters:args (a list of parameters) – positions on each dimension. The number of arguments must be the same as the number of dimensions. Or pass one argument as a sequence (same size as number of dimensions).
Returns:int. If there is no such bin a -1 is returned.

See also

bins_to_cell(), cell_to_bins()

projection(*keepDims)[source]

Project this Histogram to another Histogram keeping the axis defined in keepDims

Parameters:keepDims (variadic argument list) – a variadic arguments list of the id’s of the dimensions to keep when projecting. The number of dimensions of the projected histogram is the length of keepDims
Returns:HistND. The projected histogram.
scale(factor: float, scale_errors: bool = False)[source]

Scales the histograms.

The values of all cells are multiplied by ‘factor’

Parameters:
  • factor (float) – the value to scale the histogram
  • scale_errors (bool) – if true then it also scales the errors per dimension
Returns:

none.
sum_of_weights

Total Sum of weights

sum_of_weights2

Total Sum of weights squared

sum_of_weightsX

a list of total sum of weights*X for each dimension

sum_of_weightsX2

a list of total sum of weights*X*X for each dimension

title

the title of the histogram

class qksplot.hist.Hist1D(nBins: int, minBin: float, maxBin: float, title='')[source]

A 1-Dimensional Histogram

Parameters:
  • minBin (float) – the minimum value of lower edge of bins
  • maxBin (float) – the maximum value of upper edge of bins
  • nBins (integer) – the number of bins
  • title (string) – the title of the histogram
class qksplot.hist.Hist2D(nBinsX, minBinX, maxBinX, nBinsY, minBinY, maxBinY, title='')[source]

A 2-Dimensional Histogram

Parameters:
  • nBinsX (integer) – the number of bins on the X-axis
  • minBinX (float) – the minimum value of lower edge of bins on the X-axis
  • maxBinX (float) – the maximum value of upper edge of bins on the X-axis
  • nBinsY (integer) – the number of bins on the Y-axis
  • minBinY (float) – the minimum value of lower edge of bins on the Y-axis
  • maxBinY (float) – the maximum value of upper edge of bins on the Y-axis
  • title (string) – the title of the histogram
projection_x()[source]

Project this histogram on the X-axis

Returns:HistND. The projected histogram has dimension 1.
projection_y()[source]

Project this histogram on the Y-axis

Returns:HistND. The projected histogram has dimension 1.
class qksplot.hist.Hist3D(nBinsX, minBinX, maxBinX, nBinsY, minBinY, maxBinY, nBinsZ, minBinZ, maxBinZ, title='')[source]

A 3-Dimensional Histogram

Parameters:
  • nBinsX (integer) – the number of bins on the X-axis
  • minBinX (float) – the minimum value of lower edge of bins on the X-axis
  • maxBinX (float) – the maximum value of upper edge of bins on the X-axis
  • nBinsY (integer) – the number of bins on the Y-axis
  • minBinY (float) – the minimum value of lower edge of bins on the Y-axis
  • maxBinY (float) – the maximum value of upper edge of bins on the Y-axis
  • nBinsZ (integer) – the number of bins on the Z-axis
  • minBinZ (float) – the minimum value of lower edge of bins on the Z-axis
  • maxBinZ (float) – the maximum value of upper edge of bins on the Z-axis
  • title (string) – the title of the histogram
projection_x()[source]

Project this histogram on the X-axis

Returns:HistND. The projected histogram has dimension 1.
projection_xy()[source]

Project this histogram on the X-axis and Y-axis

Returns:HistND. The projected histogram has dimension 2.
projection_xz()[source]

Project this histogram on the X-axis and Z-axis

Returns:HistND. The projected histogram has dimension 2.
projection_y()[source]

Project this histogram on the Y-axis

Returns:HistND. The projected histogram has dimension 1.
projection_yz()[source]

Project this histogram on the Y-axis and Z-axis

Returns:HistND. The projected histogram has dimension 2.
projection_z()[source]

Project this histogram on the Z-axis

Returns:HistND. The projected histogram has dimension 1.