API Reference for Profile Module

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.profile.ProfileND(dim: int, minBin: Sequence, maxBin: Sequence, nBins: Sequence, minValue: float = None, maxValue: float = None, title='')[source]

Profile histograms are used to compute the mean value of Y and its error for each bin in X.

For each bin we have:

- The mean of Y is the sum of all values in that bin divided by the number of entries per bin.
- The error on X is the width of the bin divided by 2.
- The error on Y is the standard deviation divided by the sqrt(number_of_entries_per_bin).
Parameters:
  • dim (int) – the number of dimensions of the profile
  • minBin (array like) – an array containing the minimum value of lower edge of bins for each dimension.
  • maxBin (array like) – an array containing the maximum value of upper edge of bins for each dimension.
  • nBins (array like) – an array containing the number of bins for each dimension.
  • title (string) – the title of the profile.
  • minValue (float) – the minimum value accepted to fill a bin. the lowest value accepted on Y (vertical axis). This filter is not used when minValue is None
  • maxValue (float) – the maximum value accepted to fill a bin. the highest value accepted on Y (vertical axis). This filter is not used when maxValue is None
fill(*args, **kwargs) → int[source]

Fill the profile (using coordinate positions).

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).
  • kwargs – this dict can accept 2 key: weight (float) - the weight to fill in. Defaults to 1.0 value (float) - to specify the value to fill the cell. (Mandatory)
Returns:

int. The index of the affected bin or -1 if no bin was found or the input values are not valid
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 : this dict can accept 2 key:
weight (float) - the weight to fill in. Defaults to 1.0 value (float) - to specify the value to fill the cell. (Mandatory)
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_pos(), fill_cell()

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

Fill the profile using global cell index.

Parameters:
  • i_cell (int) – the global bin index (cell index).
  • kwargs (Dict) – currently this dict can accept 3 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 value (float) - to specify the value to fill the cell. (Mandatory)

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 profile using a position.

Parameters:
  • args (a list of parameters) – the 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 – this dict can accept 2 key: weight (float) - the weight to fill in. Defaults to 1.0 value (float) - to specify the value to fill the cell. (Mandatory)
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()

get_cell_content(i: int) → float[source]

Returns the content of the cell ‘i’

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’

The error on per cell is the standard deviation (in that cell) divided by the sqrt(number_of_entries_per_cell).

Parameters:i (int) – a valid cell index (aka global linear bin)
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 on the Y axis associated to each bin. By default it does not include empty bins.

The error on Y per bin is the standard deviation (in that bin) divided by the sqrt(number_of_entries_per_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.
class qksplot.profile.Profile1D(nBins: int, minBin: float, maxBin: float, minValue=None, maxValue=None, title='')[source]

A 1-Dimensional Profile

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.profile.Profile2D(nBinsX: int, minBinX: float, maxBinX: float, nBinsY: int, minBinY: float, maxBinY: float, minValue=None, maxValue=None, title='')[source]

A 2-Dimensional Profile

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
class qksplot.profile.Profile3D(nBinsX: int, minBinX: float, maxBinX: float, nBinsY: int, minBinY: float, maxBinY: float, nBinsZ: int, minBinZ: float, maxBinZ: float, minValue=None, maxValue=None, title='')[source]

A 3-Dimensional Profile

Parameters:nBinsX – the number of bins on the X-axis