physt package¶

Submodules¶

physt.bin_utils module¶

Methods for investigation and manipulation of bin arrays.

physt.bin_utils.find_human_width(raw_width: float, kind: Optional[str] = None) → float¶

physt.bin_utils.find_human_width_24(raw_width: float) → int¶

physt.bin_utils.find_human_width_60(raw_width: float) → int¶

physt.bin_utils.find_human_width_decimal(raw_width: float) → float¶

physt.bin_utils.is_bin_subset(sub: Union[numpy.ndarray, Iterable[T_co], int, float], sup: Union[numpy.ndarray, Iterable[T_co], int, float]) → bool¶

Check whether all bins in one binning are present also in another:

Parameters:	sub (array_like) – Candidate for the bin subset sup (array_like) – Candidate for the bin superset

physt.bin_utils.is_bin_superset(sup: Union[numpy.ndarray, Iterable[T_co], int, float], sub: Union[numpy.ndarray, Iterable[T_co], int, float]) → bool¶: Inverse of is_bin_subset

physt.bin_utils.is_consecutive(bins: Union[numpy.ndarray, Iterable[T_co], int, float], rtol: float = 1e-05, atol: float = 1e-08) → bool¶

Check whether the bins are consecutive (edges match).

Does not check if the bins are in rising order.

physt.bin_utils.is_rising(bins: Union[numpy.ndarray, Iterable[T_co], int, float]) → bool¶

Check whether the bins are in raising order.

Does not check if the bins are consecutive.

Parameters:	bins (array_like) –

physt.bin_utils.make_bin_array(bins: Union[numpy.ndarray, Iterable[T_co], int, float]) → numpy.ndarray¶

Turn bin data into array understood by HistogramXX classes.

Parameters:	bins (array_like) – Array of edges or array of edge tuples

Examples

>>> make_bin_array([0, 1, 2])
array([[0, 1],
       [1, 2]])
>>> make_bin_array([[0, 1], [2, 3]])
array([[0, 1],
       [2, 3]])

physt.bin_utils.to_numpy_bins(bins: Union[numpy.ndarray, Iterable[T_co], int, float]) → numpy.ndarray¶

Convert physt bin format to numpy edges.

Parameters:	bins (array_like) – 1-D (n) or 2-D (n, 2) array of edges
Returns:	edges
Return type:	all edges

physt.bin_utils.to_numpy_bins_with_mask(bins: Union[numpy.ndarray, Iterable[T_co], int, float]) → Tuple[numpy.ndarray, numpy.ndarray]¶

Numpy binning edges including gaps.

Parameters:	bins (1-D (n) or 2-D (n, 2) array of edges) –
Returns:	edges (All edges) mask (List of indices that correspond to bins that have to be included)

Examples

>>> to_numpy_bins_with_mask([0, 1, 2])
(array([0.,   1.,   2.]), array([0, 1]))

>>> to_numpy_bins_with_mask([[0, 1], [2, 3]])
(array([0, 1, 2, 3]), array([0, 2])

physt.binnings module¶

Different binning algorithms/schemas for the histograms.

class physt.binnings.BinningBase(bins: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, numpy_bins: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, includes_right_edge: bool = False, adaptive: bool = False)¶

Bases: object

Abstract base class for binning schemas.

define at least one of the following properties: bins, numpy_bins (cached conversion exists)
if you modify bins, put _bins and _numpy_bins into proper state (None may be sufficient)
checking of proper bins should be done in __init__
if you want to support adaptive histogram, override _force_bin_existence
implement _update_dict to contain the binning representation
the constructor (and facade methods) must accept any kwargs (and ignores those that are not used).

adaptive_allowed¶

Whether is possible to update the bins dynamically

Type:	bool

inconsecutive_allowed¶

Whether it is possible to have bins with gaps

Type:	bool

TODO¶

Type:	Check the last point (does it make sense?)

adapt(other: physt.binnings.BinningBase)¶

Adapt this binning so that it contains all bins of another binning.

Parameters:	other (BinningBase) –

adaptive_allowed = False

apply_bin_map(bin_map) → physt.binnings.BinningBase¶

Parameters:	bin_map (Iterator(tuple)) – The bins must be in ascending order

as_fixed_width(copy: bool = True) → physt.binnings.FixedWidthBinning¶

Convert binning to recipe with fixed width (if possible.)

Parameters:	copy (If True, ensure that we receive another object.) –

as_static(copy: bool = True) → physt.binnings.StaticBinning¶

Convert binning to a static form.

Parameters:	copy (bool) – Ensure that we receive another object
Returns:	A new static binning with a copy of bins.
Return type:	StaticBinning

bin_count¶: The total number of bins.

bins¶

Bins in the wider format (as edge pairs)

Returns:	bins – shape=(bin_count, 2)
Return type:	np.ndarray

copy() → BinningType¶: An identical, independent copy.

first_edge¶: The left edge of the first bin.

force_bin_existence(values)¶

Change schema so that there is a bin for value.

It is necessary to implement the _force_bin_existence template method.

Parameters:	values (np.ndarray) – All values we want bins for.
Returns:	bin_map – None => There was no change in bins int => The bins are only shifted (allows mass assignment) Otherwise => the iterable contains tuples (old bin index, new bin index) new bin index can occur multiple times, which corresponds to bin merging
Return type:	Iterable[tuple] or None or int

static from_dict(a_dict)¶

includes_right_edge¶

inconsecutive_allowed = False

is_adaptive() → bool¶: Whether the binning can be adapted to include values not currently spanned.

is_consecutive(rtol: float = 1e-05, atol: float = 1e-08) → bool¶

Whether all bins are in a growing order.

Parameters:	atol (rtol,) –

is_regular(*, rtol: float = 1e-05, atol: float = 1e-08) → bool¶

Whether all bins have the same width.

Parameters:	atol (rtol,) –

last_edge¶: The right edge of the last bin.

numpy_bins¶

Bins in the numpy format

This might not be available for inconsecutive binnings.

Returns:	edges – shape=(bin_count+1,)
Return type:	np.ndarray

numpy_bins_with_mask¶

Bins in the numpy format, including the gaps in inconsecutive binnings.

Returns:	edges, mask
Return type:	np.ndarray

See also

bin_utils.to_numpy_bins_with_mask

set_adaptive(value: bool = True) → None¶

Set/unset the adaptive property of the binning.

This is available only for some of the binning types.

to_dict() → Dict[str, Any]¶

Dictionary representation of the binning schema.

This serves as template method, please implement _update_dict

physt.binnings.BinningLike = typing.Union[physt.binnings.BinningBase, numpy.ndarray, typing.Iterable, int, float]¶: Anything that can be converted to a binning.

class physt.binnings.ExponentialBinning(log_min: float, log_width: float, bin_count: int, includes_right_edge: bool = True, adaptive: bool = False, **kwargs)¶

Bases: physt.binnings.BinningBase

Binning schema with exponentially distributed bins.

adaptive_allowed = False¶

copy() → physt.binnings.ExponentialBinning¶: An identical, independent copy.

is_regular(**kwargs) → bool¶

Whether all bins have the same width.

Parameters:	atol (rtol,) –

numpy_bins¶

Bins in the numpy format

This might not be available for inconsecutive binnings.

Returns:	edges – shape=(bin_count+1,)
Return type:	np.ndarray

class physt.binnings.FixedWidthBinning(*, bin_width, bin_count=0, bin_times_min=None, min=None, includes_right_edge=False, adaptive=False, bin_shift=None, align=True, **kwargs)¶

Bases: physt.binnings.BinningBase

Binning schema with predefined bin width.

adaptive_allowed = True¶

as_fixed_width(copy: bool = True) → physt.binnings.FixedWidthBinning¶

Convert binning to recipe with fixed width (if possible.)

Parameters:	copy (If True, ensure that we receive another object.) –

bin_count¶: The total number of bins.

bin_width¶

copy()¶: An identical, independent copy.

first_edge¶: The left edge of the first bin.

is_regular(**kwargs) → bool¶

Whether all bins have the same width.

Parameters:	atol (rtol,) –

last_edge¶: The right edge of the last bin.

numpy_bins¶

Bins in the numpy format

This might not be available for inconsecutive binnings.

Returns:	edges – shape=(bin_count+1,)
Return type:	np.ndarray

class physt.binnings.NumpyBinning(numpy_bins: Union[numpy.ndarray, Iterable[T_co], int, float], includes_right_edge=True, **kwargs)¶

Bases: physt.binnings.BinningBase

Binning schema working as numpy.histogram.

copy() → physt.binnings.NumpyBinning¶: An identical, independent copy.

numpy_bins¶

Bins in the numpy format

This might not be available for inconsecutive binnings.

Returns:	edges – shape=(bin_count+1,)
Return type:	np.ndarray

class physt.binnings.StaticBinning(bins, includes_right_edge=True, **kwargs)¶

Bases: physt.binnings.BinningBase

Binning defined by an array of bin edge pairs.

as_static(copy: bool = True) → physt.binnings.StaticBinning¶

Convert binning to a static form.

Returns:	A new static binning with a copy of bins.
Return type:	StaticBinning
Parameters:	copy (if True, returns itself (already satisfying conditions)) –

copy()¶: An identical, independent copy.

inconsecutive_allowed = True¶

physt.binnings.as_binning(obj: Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float], copy: bool = False) → physt.binnings.BinningBase¶

Ensure that an object is a binning

Parameters:	obj (BinningBase or array_like) – Can be a binning, numpy-like bins or full physt bins copy (If true, ensure that the returned object is independent) –

physt.binnings.binning_methods = {'exponential': <function exponential_binning>, 'fixed_width': <function fixed_width_binning>, 'human': <function human_binning>, 'integer': <function integer_binning>, 'numpy': <function numpy_binning>, 'quantile': <function quantile_binning>, 'static': <function static_binning>}¶: Dictionary of available binnnings.

physt.binnings.calculate_bins(array, _=None, **kwargs) → physt.binnings.BinningBase¶

Find optimal binning from arguments.

Parameters:	array (arraylike) – Data from which the bins should be decided (sometimes used, sometimes not) _ (int or str or Callable or arraylike or Iterable or BinningBase) – To-be-guessed parameter that specifies what kind of binning should be done check_nan (bool) – Check for the presence of nan’s in array? Default: True range (tuple) – Limit values to a range. Some of the binning methods also (subsequently) use this parameter for the bin shape.
Returns:	A two-dimensional array with pairs of bin edges (not necessarily consecutive).
Return type:	BinningBase

physt.binnings.calculate_bins_nd(array: Optional[numpy.ndarray], bins=None, dim: Optional[int] = None, check_nan=True, **kwargs) → List[physt.binnings.BinningBase]¶

Find optimal binning from arguments (n-dimensional variant)

Usage similar to calculate_bins.

physt.binnings.exponential_binning(data=None, bin_count: Optional[int] = None, *, range: Optional[Tuple[float, float]] = None, **kwargs) → physt.binnings.ExponentialBinning¶

Construct exponential binning schema.

Parameters:	bin_count (Number of bins) – range ((min, max)) –

See also

numpy.logspace()

physt.binnings.fixed_width_binning(data=None, bin_width: Union[float, int] = 1, *, range: Optional[Tuple[float, float]] = None, includes_right_edge: bool = False, **kwargs) → physt.binnings.FixedWidthBinning¶

Construct fixed-width binning schema.

Parameters:	bin_width (float) – range (Optional[tuple]) – (min, max) align (Optional[float]) – Must be multiple of bin_width

physt.binnings.human_binning(data: Optional[numpy.ndarray] = None, bin_count: Optional[int] = None, *, kind: Optional[str] = None, range: Optional[Tuple[float, float]] = None, min_bin_width: Optional[float] = None, max_bin_width: Optional[float] = None, **kwargs) → physt.binnings.FixedWidthBinning¶

Construct fixed-width ninning schema with bins automatically optimized to human-friendly widths.

Typical widths are: 1.0, 25,0, 0.02, 500, 2.5e-7, …

Parameters:	bin_count (Number of bins) – kind (Optional value "time" works in h,m,s scale instead of seconds) – range (Tuple of (min, max)) – min_bin_width (If present, the bin cannot be narrower than this.) – max_bin_width (If present, the bin cannot be wider than this.) –

physt.binnings.ideal_bin_count(data: numpy.ndarray, method: str = 'default') → int¶

A theoretically ideal bin count.

Parameters:	data (Data to work on. Most methods don't use this.) – method (str) – Name of the method to apply, available values: default (~sturges) sqrt sturges doane rice See https://en.wikipedia.org/wiki/Histogram for the description

physt.binnings.integer_binning(data=None, **kwargs) → physt.binnings.FixedWidthBinning¶

Construct fixed-width binning schema with bins centered around integers.

Parameters:	range (Optional[Tuple[int]]) – min (included) and max integer (excluded) bin bin_width (Optional[int]) – group “bin_width” integers into one bin (not recommended)

physt.binnings.numpy_binning(data: Optional[numpy.ndarray], bin_count: int = 10, range: Optional[Tuple[float, float]] = None, **kwargs) → physt.binnings.NumpyBinning¶

Construct binning schema compatible with numpy.histogram together with int argument

Parameters:	data (array_like, optional) – This is optional if both bins and range are set bin_count (int) – range (Optional[tuple]) – (min, max) includes_right_edge (Optional[bool]) – default: True

See also

numpy.histogram(), static_binning()

physt.binnings.quantile_binning(data: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, bin_count: Optional[int] = None, q: Optional[Sequence[int]] = None, qrange: Optional[Tuple[float, float]] = None, **kwargs) → physt.binnings.StaticBinning¶

Binning schema based on quantile ranges.

This binning finds equally spaced quantiles. This should lead to all bins having roughly the same frequencies.

Note: weights are not (yet) take into account for calculating quantiles.

Parameters:	bin_count (Number of bins) – q (Sequence of quantiles to be used as edges (a la numpy)) – qrange (Two floats as minimum and maximum quantile (default: 0.0, 1.0)) –
Returns:
Return type:	StaticBinning

physt.binnings.register_binning(f=None, *, name: Optional[str] = None)¶: Decorator to register among available binning methods.

physt.binnings.static_binning(data=None, bins=None, **kwargs) → physt.binnings.StaticBinning¶: Construct static binning with whatever bins.

physt.config module¶

physt.facade module¶

physt.facade.h1(data: Union[numpy.ndarray, Iterable[T_co], int, float, None], bins=None, *, adaptive: bool = False, dropna: bool = True, dtype: Union[type, numpy.dtype, str, None] = None, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, keep_missed: bool = True, name: Optional[str] = None, title: Optional[str] = None, axis_name: Optional[str] = None, **kwargs) → physt.histogram1d.Histogram1D¶

Facade function to create 1D histograms.

This proceeds in three steps: 1) Based on magical parameter bins, construct bins for the histogram 2) Calculate frequencies for the bins 3) Construct the histogram object itself

Guiding principle: parameters understood by numpy.histogram should be understood also by physt.histogram as well and should result in a Histogram1D object with (h.numpy_bins, h.frequencies) same as the numpy.histogram output. Additional functionality is a bonus.

Parameters:

data (array_like, optional) – Container of all the values (tuple, list, np.ndarray, pd.Series)
bins (int or sequence of scalars or callable or str, optional) – If iterable => the bins themselves If int => number of bins for default binning If callable => use binning method (+ args, kwargs) If string => use named binning method (+ args, kwargs)
weights (array_like, optional) – (as numpy.histogram)
keep_missed (Store statistics about how many values were lower than limits) – and how many higher than limits (default: True)
dropna (Whether to clear data from nan's before histogramming) –
name (Name of the histogram) –
title (What will be displayed in the title of the plot) –
axis_name (Name of the variable on x axis) –
adaptive (Whether we want the bins to be modifiable) – (useful for continuous filling of a priori unknown data)
dtype (Customize underlying data type: default int64 (without weight) or float (with weights)) –
numpy.histogram parameters are excluded, see the methods of the Histogram1D class itself. (Other) –

See also

numpy.histogram()

physt.facade.h2(data1: Union[numpy.ndarray, Iterable[T_co], int, float, None], data2: Union[numpy.ndarray, Iterable[T_co], int, float, None], bins=10, **kwargs) → physt.histogram_nd.Histogram2D¶

Facade function to create 2D histograms.

For implementation and parameters, see histogramdd.

See also

numpy.histogram2d(), histogramdd()

physt.facade.h3(data: Union[numpy.ndarray, Iterable[T_co], int, float, None], bins=None, **kwargs) → physt.histogram_nd.HistogramND¶

Facade function to create 3D histograms.

Parameters:	data (array_like or list[array_like] or tuple[array_like]) – Can be a single array (with three columns) or three different arrays (for each component)

physt.facade.histogram(data: Union[numpy.ndarray, Iterable[T_co], int, float, None], bins=None, *, adaptive: bool = False, dropna: bool = True, dtype: Union[type, numpy.dtype, str, None] = None, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, keep_missed: bool = True, name: Optional[str] = None, title: Optional[str] = None, axis_name: Optional[str] = None, **kwargs) → physt.histogram1d.Histogram1D¶

Facade function to create 1D histograms.

This proceeds in three steps: 1) Based on magical parameter bins, construct bins for the histogram 2) Calculate frequencies for the bins 3) Construct the histogram object itself

Guiding principle: parameters understood by numpy.histogram should be understood also by physt.histogram as well and should result in a Histogram1D object with (h.numpy_bins, h.frequencies) same as the numpy.histogram output. Additional functionality is a bonus.

Parameters:

data (array_like, optional) – Container of all the values (tuple, list, np.ndarray, pd.Series)
bins (int or sequence of scalars or callable or str, optional) – If iterable => the bins themselves If int => number of bins for default binning If callable => use binning method (+ args, kwargs) If string => use named binning method (+ args, kwargs)
weights (array_like, optional) – (as numpy.histogram)
keep_missed (Store statistics about how many values were lower than limits) – and how many higher than limits (default: True)
dropna (Whether to clear data from nan's before histogramming) –
name (Name of the histogram) –
title (What will be displayed in the title of the plot) –
axis_name (Name of the variable on x axis) –
adaptive (Whether we want the bins to be modifiable) – (useful for continuous filling of a priori unknown data)
dtype (Customize underlying data type: default int64 (without weight) or float (with weights)) –
numpy.histogram parameters are excluded, see the methods of the Histogram1D class itself. (Other) –

See also

numpy.histogram()

physt.facade.histogram2d(data1: Union[numpy.ndarray, Iterable[T_co], int, float, None], data2: Union[numpy.ndarray, Iterable[T_co], int, float, None], bins=10, **kwargs) → physt.histogram_nd.Histogram2D¶

Facade function to create 2D histograms.

For implementation and parameters, see histogramdd.

See also

numpy.histogram2d(), histogramdd()

physt.facade.histogramdd(data: Union[numpy.ndarray, Iterable[T_co], int, float, None], bins=10, *, adaptive=False, dropna: bool = True, name: Optional[str] = None, title: Optional[str] = None, axis_names: Optional[Iterable[str]] = None, dim: Optional[int] = None, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, **kwargs) → physt.histogram_nd.HistogramND¶

Facade function to create n-dimensional histograms.

3D variant of this function is also aliased as “h3”.

Parameters:

data (array_like) – Container of all the values
bins (Any) –
weights (array_like, optional) – (as numpy.histogram)
dropna (Whether to clear data from nan's before histogramming) –
name (Name of the histogram) –
axis_names (Names of the variable on x axis) –
adaptive (Whether the bins should be updated when new non-fitting value are filled) –
dtype (Optional[type]) – Underlying type for the histogram. If weights are specified, default is float. Otherwise int64
title (What will be displayed in the title of the plot) –
dim (Dimension - necessary if you are creating an empty adaptive histogram) –
Note (For most arguments, if a list is passed, its values are used as values for) –
axes. (individual) –

See also

numpy.histogramdd()

physt.facade.collection(data, bins=10, **kwargs) → physt.histogram_collection.HistogramCollection¶: Create histogram collection with shared binnning.

physt.facade.polar(xdata: Union[numpy.ndarray, Iterable[T_co], int, float], ydata: Union[numpy.ndarray, Iterable[T_co], int, float], *, radial_bins='numpy', radial_range: Optional[Tuple[float, float]] = None, phi_bins=16, phi_range: Tuple[float, float] = (0, 6.283185307179586), dropna: bool = False, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, transformed: bool = False, **kwargs) → physt.special_histograms.PolarHistogram¶: Facade construction function for the PolarHistogram.

physt.facade.azimuthal(xdata: Union[numpy.ndarray, Iterable[T_co], int, float], ydata: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, bins=16, range: Tuple[float, float] = (0, 6.283185307179586), dropna: bool = False, weights=None, transformed: bool = False, **kwargs) → physt.special_histograms.AzimuthalHistogram¶: Facade function to create an AzimuthalHistogram.

physt.facade.radial(xdata: Union[numpy.ndarray, Iterable[T_co], int, float], ydata: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, zdata: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, bins='numpy', range: Optional[Tuple[float, float]] = None, dropna: bool = False, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, transformed: bool = False, **kwargs) → physt.special_histograms.RadialHistogram¶: Facade function to create a radial histogram.

physt.facade.cylindrical(data: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, rho_bins='numpy', phi_bins=16, z_bins='numpy', transformed: bool = False, dropna: bool = True, rho_range: Optional[Tuple[float, float]] = None, phi_range: Tuple[float, float] = (0, 6.283185307179586), weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, z_range: Optional[Tuple[float, float]] = None, **kwargs) → physt.special_histograms.CylindricalHistogram¶: Facade function to create a cylindrical histogram.

physt.facade.cylindrical_surface(data=None, *, phi_bins=16, z_bins='numpy', transformed: bool = False, radius: Optional[float] = None, dropna: bool = False, weights=None, phi_range: Tuple[float, float] = (0, 6.283185307179586), z_range: Optional[Tuple[float, float]] = None, **kwargs) → physt.special_histograms.CylindricalSurfaceHistogram¶: Facade function to create a cylindrical surface histogram.

physt.facade.spherical(data: Union[numpy.ndarray, Iterable[T_co], int, float], *, radial_bins='numpy', theta_bins=16, phi_bins=16, dropna: bool = True, transformed: bool = False, theta_range: Tuple[float, float] = (0, 3.141592653589793), phi_range: Tuple[float, float] = (0, 6.283185307179586), radial_range: Optional[Tuple[float, float]] = None, weights=None, **kwargs) → physt.special_histograms.SphericalHistogram¶: Facade function to create a speherical histogram.

physt.facade.spherical_surface(data: Union[numpy.ndarray, Iterable[T_co], int, float], *, theta_bins=16, phi_bins=16, transformed: bool = False, radius: Optional[float] = None, dropna: bool = False, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, theta_range: Tuple[float, float] = (0, 3.141592653589793), phi_range: Tuple[float, float] = (0, 6.283185307179586), **kwargs) → physt.special_histograms.SphericalSurfaceHistogram¶: Facade construction function for the SphericalSurfaceHistogram.

physt.histogram1d module¶

One-dimensional histograms.

class physt.histogram1d.Histogram1D(binning: Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float], frequencies: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, errors2: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, keep_missed: bool = True, stats: Optional[Dict[str, float]] = None, overflow: Optional[float] = 0.0, underflow: Optional[float] = 0.0, inner_missed: Optional[float] = 0.0, axis_name: Optional[str] = None, **kwargs)¶

Bases: physt.histogram1d.ObjectWithBinning, physt.histogram_base.HistogramBase

One-dimensional histogram data.

The bins can be of different widths.

The bins need not be consecutive. However, some functionality may not be available for non-consecutive bins (like keeping information about underflow and overflow).

_stats¶

Type:	dict

These are the basic attributes that can be used in the constructor (see there) Other attributes are dynamic.

EMPTY_STATS = {'sum': 0.0, 'sum2': 0.0}¶

axis_name¶

binning¶

The binning.

Note: Please, do not try to update the object itself.

cumulative_frequencies¶

Cumulative frequencies.

Note: underflow values are not considered

fill(value: float, weight: float = 1, **kwargs) → Optional[int]¶

Update histogram with a new value.

Parameters:

value (Value to be added.) –
weight (Weight assigned to the value.) –

Returns:

index of bin which was incremented (-1=underflow, N=overflow, None=not found)
Note (If a gap in unconsecutive bins is matched, underflow & overflow are not valid anymore.)
Note (Name was selected because of the eponymous method in ROOT)

fill_n(values: Union[numpy.ndarray, Iterable[T_co], int, float], weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, dropna: bool = True) → None¶

Update histogram with more values at once.

It is an in-place operation.

Parameters:	values (Values to add) – weights (Optional weights to assign to each value) – drop_na (If true (default), all nan's are skipped.) –

Note

This method should be overloaded with a more efficient one.

May change the dtype if weight is set.

find_bin(value: Union[numpy.ndarray, Iterable[T_co], int, float], axis: Union[int, str, None] = None) → Optional[int]¶

Index of bin corresponding to a value.

Returns:	(-1=underflow, N=overflow, None=not found - inconsecutive)
Return type:	index of bin to which value belongs

classmethod from_calculate_frequencies(data: Union[numpy.ndarray, Iterable[T_co], int, float], binning: physt.binnings.BinningBase, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, validate_bins: bool = True, already_sorted: bool = False, dtype: Union[type, numpy.dtype, str, None] = None, **kwargs) → Histogram1DType¶: Construct the histogram from values and bins.

classmethod from_xarray(arr: xarray.Dataset) → Histogram1D¶

Convert form xarray.Dataset

Parameters:	arr (The data in xarray representation) –

inner_missed¶

mean() → Optional[float]¶

Statistical mean of all values entered into histogram.

This number is precise, because we keep the necessary data separate from bin contents.

numpy_like¶: Same result as would the numpy.histogram function return.

overflow¶

select(axis, index, *, force_copy: bool = False) → Union[physt.histogram1d.Histogram1D, Tuple[numpy.ndarray, float]]¶: Alias for [] to be compatible with HistogramND.

std() → Optional[float]¶

Standard deviation of all values entered into histogram.

This number is precise, because we keep the necessary data separate from bin contents.

Returns:
Return type:	float

to_dataframe() → pandas.DataFrame¶

Convert to pandas DataFrame.

This is not a lossless conversion - (under/over)flow info is lost.

to_xarray() → xarray.Dataset¶: Convert to xarray.Dataset

underflow¶

variance() → Optional[float]¶

Statistical variance of all values entered into histogram.

This number is precise, because we keep the necessary data separate from bin contents.

Returns:
Return type:	float

class physt.histogram1d.ObjectWithBinning¶

Bases: abc.ABC

Mixin with shared methods for 1D objects that have a binning.

Note: Used to share behaviour between Histogram1D and HistogramCollection.

bin_centers¶: Centers of all bins.

bin_left_edges¶: Left edges of all bins.

bin_right_edges¶: Right edges of all bins.

bin_sizes¶

bin_widths¶: Widths of all bins.

binning¶: The binning itself.

bins¶

Array of all bin edges.

Returns:
Return type:	Wide-format [[leftedge1, rightedge1], .. [leftedgeN, rightedgeN]]

edges¶

get_bin_left_edges(i)¶

get_bin_right_edges(i)¶

max_edge¶: Right edge of the last bin.

min_edge¶: Left edge of the first bin.

ndim¶

numpy_bins¶: Bins in the format of numpy.

total_width¶

Total width of all bins.

In inconsecutive histograms, the missing intervals are not counted in.

physt.histogram1d.calculate_frequencies(data: Union[numpy.ndarray, Iterable[T_co], int, float], binning: physt.binnings.BinningBase, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, validate_bins: bool = True, already_sorted: bool = False, dtype: Union[type, numpy.dtype, str, None] = None) → Tuple[numpy.ndarray, numpy.ndarray, float, float, dict]¶

Get frequencies and bin errors from the data.

Parameters:

data (Data items to work on.) –
binning (A set of bins.) –
weights (Weights of the items.) –
validate_bins (If True (default), bins are validated to be in ascending order.) –
already_sorted (If True, the data being entered are already sorted, no need to sort them once more.) –
dtype (Underlying type for the histogram.) – (If weights are specified, default is float. Otherwise long.)

Returns:

frequencies (Bin contents)
errors2 (Error squares of the bins)
underflow (Weight of items smaller than the first bin)
overflow (Weight of items larger than the last bin)
stats (dict) – { sum: …, sum2: …}

Note

Checks that the bins are in a correct order (not necessarily consecutive). Does not check for numerical overflows in bins.

physt.histogram_base module¶

HistogramBase - base for all histogram classes.

class physt.histogram_base.HistogramBase(binnings: Iterable[Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float]], frequencies: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, errors2: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, axis_names: Optional[Iterable[str]] = None, dtype: Union[type, numpy.dtype, str, None] = None, keep_missed: bool = True, **kwargs)¶

Bases: abc.ABC

Histogram base class.

Behaviour shared by all histogram classes.

The most important daughter classes are: - Histogram1D - HistogramND

There are also special histogram types that are modifications of these classes.

The methods you should override: - fill - fill_n (optional) - copy - _update_dict (optional)

Underlying data type is int64 / float or an explicitly specified other type (dtype).

_binnings¶

Type:	Schema for binning(s)

frequencies¶

Bin contents

Type:	np.ndarray

errors2¶

Square errors associated with the bin contents

Type:	np.ndarray

_meta_data¶

All meta-data (names, user-custom values, …). Anything can be put in. When exported, all information is kept.

Type:	dict

_dtype¶

Type of the frequencies and also errors (int64, float64 or user-overridden)

Type:	np.dtype

_missed¶

Various storage for missed values in different histogram types (1 value for multi-dimensional, 3 values for one-dimensional)

Type:	array_like

Invariants¶

----------

- Frequencies in the histogram should always be non-negative.

Many operations rely on that, but it is not always enforced.

(if you set config.free_arithmetics (see below), negative frequencies are also

allowed.

Arithmetics¶

-----------

Histograms offer standard arithmetic operators that by default allow only

meaningful application (i.e. addition / subtraction of two histograms

with matching or mutually adaptable bin sets, multiplication and division by a constant).

If you relax the criteria by setting `config.free_aritmetics` or inside

the config.enable_free_arithmetics() context manager, you are in addition

allowed to use any array-like with matching shape.

See also

histogram1d, histogram_nd, special

adaptive¶

axis_names¶: Names of axes (stored in meta-data).

bin_count¶: Total number of bins.

bin_sizes¶

binnings¶

The binnings.

Note: Please, do not try to update the objects themselves.

bins¶

copy(*, include_frequencies: bool = True) → HistogramType¶

Copy the histogram.

Parameters:	include_frequencies (If false, all frequencies are set to zero.) –

default_axis_names¶: Axis names to be used when an instance does not define them.

default_init_values = {}¶

densities¶

Frequencies normalized by bin sizes.

Useful when bins are not of the same size.

dtype¶: Data type of the bin contents.

errors¶: Bin errors.

errors2: Squares of the bin errors.

fill(value: float, weight: float = 1, **kwargs) → Union[None, int, Tuple[int, ...]]¶

Update histogram with a new value.

It is an in-place operation.

Parameters:	value (Value to be added. Can be scalar or array depending on the histogram type.) – weight (Weight of the value) –

Note

May change the dtype if weight is set

fill_n(values: Union[numpy.ndarray, Iterable[T_co], int, float], weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, dropna: bool = True)¶

Update histogram with more values at once.

It is an in-place operation.

Parameters:	values (Values to add) – weights (Optional weights to assign to each value) – drop_na (If true (default), all nan's are skipped.) –

Note

This method should be overloaded with a more efficient one.

May change the dtype if weight is set.

find_bin(value: Union[numpy.ndarray, Iterable[T_co], int, float], axis: Union[int, str, None] = None) → Union[None, int, Tuple[int, ...]]¶

Index(-ices) of bin corresponding to a value.

Parameters:	value (Value with dimensionality equal to histogram) – axis (If set, find axis along an axis. Otherwise, find bins along all axes.) – None = outside the bins
Returns:
Return type:	If axis is specified (or the histogram is 1D), a number. Otherwise, a tuple. If not available, None.

frequencies: Frequencies (values, contents) of the histogram bins.

classmethod from_dict(a_dict: Mapping[str, Any]) → physt.histogram_base.HistogramBase¶

Create an instance from a dictionary.

If customization is necessary, override the _from_dict_kwargs template method, not this one.

has_same_bins(other: physt.histogram_base.HistogramBase) → bool¶: Whether two histograms share the same binning.

is_adaptive() → bool¶: Whether the binning can be changed with operations.

merge_bins(amount: Optional[int] = None, *, min_frequency: Optional[float] = None, axis: Union[int, str, None] = None, inplace: bool = False) → HistogramType¶

Reduce the number of bins and add their content:

Parameters:	amount (How many adjacent bins to join together.) – min_frequency (Try to have at least this value in each bin) – (this is not enforce e.g. for minima between high bins) axis (On which axis to do this (None => all)) – inplace (Whether to modify this histogram or return a new one) –

meta_data¶

A dictionary of non-numerical information about the histogram.

It contains several pre-defined ones, but you can add any other. These are preserved when saving and also in operations.

missed¶: Total number (weight) of entries that missed the bins.

name¶: Name of the histogram (stored in meta-data).

ndim¶

Dimensionality of histogram’s data.

i.e. the number of axes along which we bin the values.

normalize(inplace: bool = False, percent: bool = False) → physt.histogram_base.HistogramBase¶

Normalize the histogram, so that the total weight is equal to 1.

Parameters:	inplace (If True, updates itself. If False (default), returns copy) – percent (If True, normalizes to percent instead of 1. Default: False) –
Returns:
Return type:	either modified copy or self

See also

densities(), HistogramND.partial_normalize()

plot¶

Proxy to plotting.

This attribute is a special proxy to plotting. In the most simple cases, it can be used as a method. For more sophisticated use, see the documentation for physt.plotting package.

select(axis: Union[int, str], index: Union[int, slice], *, force_copy: bool = False) → Any¶

Select in an axis.

Parameters:	axis (Axis, in which we select.) – index (Index of bin (as in numpy)) – force_copy (If True, identity slice force a copy to be made.) –

set_adaptive(value: bool = True)¶

Change the histogram binning to (non)adaptive.

This requires binning in all dimensions to allow this.

set_dtype(value: Union[type, numpy.dtype, str], *, check: bool = True) → None¶

Change data type of the bin contents.

Allowed conversions: - from integral to float types - between the same category of type (float/integer) - from float types to integer if weights are trivial

Parameters:	value (np.dtype or something convertible to it.) – check (If True (default), all values are checked against the limits) –

shape¶

Shape of histogram’s data.

Returns:
Return type:	Tuple with the number of bins along each axis.

title¶

Title of the histogram to be displayed when plotted (stored in meta-data).

If not specified, defaults to name.

to_dict() → Dict[str, Any]¶

Dictionary with all data in the histogram.

This is used for export into various formats (e.g. JSON) If a descendant class needs to update the dictionary in some way (put some more information), override the _update_dict method.

to_json(path: Optional[str] = None, **kwargs) → str¶

Convert to JSON representation.

Parameters:	path (Where to write the JSON.) –
Returns:
Return type:	The JSON representation.

total¶: Total number (sum of weights) of entries excluding underflow and overflow.

physt.histogram_collection module¶

class physt.histogram_collection.HistogramCollection(*histograms, binning: Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float, None] = None, title: Optional[str] = None, name: Optional[str] = None)¶

Bases: collections.abc.Container, typing.Generic, physt.histogram1d.ObjectWithBinning

Experimental collection of histograms.

It contains (potentially name-addressable) 1-D histograms with a shared binning.

add(histogram: physt.histogram1d.Histogram1D) → None¶: Add a histogram to the collection.

axis_name¶

axis_names¶

binning¶: The binning itself.

copy() → physt.histogram_collection.HistogramCollection¶

create(name: str, values, *, weights=None, dropna: bool = True, **kwargs) → physt.histogram1d.Histogram1D¶

classmethod from_dict(a_dict: Dict[str, Any]) → physt.histogram_collection.HistogramCollection¶

classmethod multi_h1(a_dict: Dict[str, Union[numpy.ndarray, Iterable[T_co], int, float]], bins=None, **kwargs) → physt.histogram_collection.HistogramCollection¶: Create a collection from multiple datasets.

normalize_all(inplace: bool = False) → physt.histogram_collection.HistogramCollection¶: Normalize all histograms so that total content of each of them is equal to 1.0.

normalize_bins(inplace: bool = False) → physt.histogram_collection.HistogramCollection¶

Normalize each bin in the collection so that the sum is 1.0 for each bin.

Note: If a bin is zero in all collections, the result will be inf.

plot¶

Proxy to plotting.

This attribute is a special proxy to plotting. In the most simple cases, it can be used as a method. For more sophisticated use, see the documentation for physt.plotting package.

sum() → physt.histogram1d.Histogram1D¶: Return the sum of all contained histograms.

to_dict() → Dict[str, Any]¶

to_json(path: Optional[str] = None, **kwargs) → str¶

Convert to JSON representation.

Parameters:	path (Where to write the JSON.) –
Returns:
Return type:	The JSON representation.

physt.histogram_nd module¶

Multi-dimensional histograms.

class physt.histogram_nd.Histogram2D(binnings, frequencies=None, **kwargs)¶

Bases: physt.histogram_nd.HistogramND

Specialized 2D variant of the general HistogramND class.

In contrast to general HistogramND, it is plottable.

T¶

Histogram with swapped axes.

Returns:
Return type:	Histogram2D - a copy with swapped axes

numpy_like¶: Same result as would the numpy.histogram function return.

partial_normalize(axis: Union[int, str] = 0, inplace: bool = False)¶

Normalize in rows or columns.

Parameters:	axis (int or str) – Along which axis to sum (numpy-sense) inplace (bool) – Update the object itself
Returns:	hist
Return type:	Histogram2D

class physt.histogram_nd.HistogramND(binnings: Iterable[Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float]], frequencies: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, dimension: Optional[int] = None, missed=0, **kwargs)¶

Bases: physt.histogram_base.HistogramBase

Multi-dimensional histogram data.

accumulate(axis: Union[int, str]) → physt.histogram_base.HistogramBase¶

Calculate cumulative frequencies along a certain axis.

Returns:	new_hist
Return type:	Histogram of the same type & size

bin_sizes¶

bins¶: List of bin matrices.

edges¶

fill(value, weight=1, **kwargs)¶

Update histogram with a new value.

It is an in-place operation.

Parameters:	value (Value to be added. Can be scalar or array depending on the histogram type.) – weight (Weight of the value) –

Note

May change the dtype if weight is set

fill_n(values: Union[numpy.ndarray, Iterable[T_co], int, float], weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, dropna: bool = True, columns: bool = False)¶

Add more values at once.

Parameters:

values (array_like) – Values to add. Can be array of shape (count, ndim) or array of shape (ndim, count) [use columns=True] or something convertible to it
weights (array_like) – Weights for values (optional)
dropna (bool) – Whether to remove NaN values. If False and such value is met, exception is thrown.
columns (bool) – Signal that the data are transposed (in columns, instead of rows). This allows to pass list of arrays in values.

find_bin(value, axis: Union[int, str, None] = None) → Union[None, int, Tuple[int, ...]]¶

Index(-ices) of bin corresponding to a value.

Parameters:	value (Value with dimensionality equal to histogram) – axis (If set, find axis along an axis. Otherwise, find bins along all axes.) – None = outside the bins
Returns:
Return type:	If axis is specified (or the histogram is 1D), a number. Otherwise, a tuple. If not available, None.

classmethod from_calculate_frequencies(data, binnings, weights=None, *, dtype=None, **kwargs)¶

get_bin_centers(axis: Union[int, str, None] = None) → numpy.ndarray¶

get_bin_edges(axis: Union[int, str, None] = None) → Tuple[numpy.ndarray, ...]¶

get_bin_left_edges(axis: Union[int, str, None] = None) → numpy.ndarray¶

get_bin_right_edges(axis: Union[int, str, None] = None) → numpy.ndarray¶

get_bin_widths(axis: Union[int, str, None] = None) → numpy.ndarray¶

numpy_bins¶: Numpy-like bins (if available).

numpy_like¶: Same result as would the numpy.histogram function return.

projection(*axes, **kwargs) → physt.histogram_base.HistogramBase¶

Reduce dimensionality by summing along axis/axes.

Parameters:	axes (Iterable[int or str]) – List of axes for the new histogram. Could be either numbers or names. Must contain at least one axis. name (Optional[str] # TODO: Check) – Name for the projected histogram (default: same) type (Optional[type] # TODO: Check) – If set, predefined class for the projection
Returns:
Return type:	HistogramND or Histogram2D or Histogram1D (or others in special cases)

select(axis: Union[int, str], index: Union[int, slice], *, force_copy: bool = False) → physt.histogram_base.HistogramBase¶

Select in an axis.

Parameters:	axis (Axis, in which we select.) – index (Index of bin (as in numpy)) – force_copy (If True, identity slice force a copy to be made.) –

total_size¶: The total size of the bin space.

Note

Perhaps not optimized, but should work also with transformed axes

physt.histogram_nd.calculate_frequencies(data: Union[numpy.ndarray, Iterable[T_co], int, float, None], binnings: Iterable[physt.binnings.BinningBase], weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, dtype: Union[type, numpy.dtype, str, None] = None) → Tuple[Optional[numpy.ndarray], Optional[numpy.ndarray], float]¶

“Get frequencies and bin errors from the data (n-dimensional variant).

Parameters:

data (2D array with ndim columns and row for each entry.) –
binnings (Binnings to apply in all axes.) –
weights (1D array of weights to assign to values.) – (If present, must have same length as the number of rows.)
dtype (Underlying type for the histogram.) – (If weights are specified, default is float. Otherwise int64.)

Returns:

frequencies (Frequencies (if data supplied))
errors2 (Errors squared if different from frequencies)
missing (scalar[dtype])

physt.special module¶

physt.special_histograms module¶

Transformed histograms.

These histograms use a transformation from input values to bins in a different coordinate system.

There are three basic classes:

PolarHistogram
CylindricalHistogram
SphericalHistogram

Apart from these, there are their projections into lower dimensions.

And of course, it is possible to re-use the general transforming functionality by adding TransformedHistogramMixin among the custom histogram class superclasses.

class physt.special_histograms.AzimuthalHistogram(binning: Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float], frequencies: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, errors2: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, keep_missed: bool = True, stats: Optional[Dict[str, float]] = None, overflow: Optional[float] = 0.0, underflow: Optional[float] = 0.0, inner_missed: Optional[float] = 0.0, axis_name: Optional[str] = None, **kwargs)¶

Bases: physt.special_histograms.TransformedHistogramMixin, physt.histogram1d.Histogram1D

Projection of polar histogram to 1D with respect to phi.

This is a special case of a 1D histogram with transformed coordinates.

bin_sizes¶

default_axis_names = ['phi']¶

default_init_values = {'radius': 1}¶

radius¶

Radius of the surface.

Useful for calculating densities.

source_ndim = 2¶

class physt.special_histograms.CylindricalHistogram(binnings: Iterable[Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float]], frequencies: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, dimension: Optional[int] = None, missed=0, **kwargs)¶

Bases: physt.special_histograms.TransformedHistogramMixin, physt.histogram_nd.HistogramND

3D histogram in cylindrical coordinates.

This is a special case of a 3D histogram with transformed coordinates: - r as radius projection to xy plane in the (0, +inf) range - phi as azimuthal angle (in the xy projection) in the (0, 2*pi) range - z as the last direction without modification, in (-inf, +inf) range

bin_sizes¶

default_axis_names = ['rho', 'phi', 'z']¶

projection(*axes, **kwargs)¶

Projection to lower-dimensional histogram.

The inheriting class should implement the _projection_class_map class attribute to suggest class for the projection. If the arguments don’t match any of the map keys, HistogramND is used.

source_ndim = 3¶

class physt.special_histograms.CylindricalSurfaceHistogram(binnings: Iterable[Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float]], frequencies: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, dimension: Optional[int] = None, missed=0, **kwargs)¶

Bases: physt.special_histograms.TransformedHistogramMixin, physt.histogram_nd.HistogramND

2D histogram in coordinates on cylinder surface.

This is a special case of a 2D histogram with transformed coordinates: - phi as azimuthal angle (in the xy projection) in the (0, 2*pi) range - z as the last direction without modification, in (-inf, +inf) range

radius¶

The radius of the surface. Useful for plotting

Type:	float

bin_sizes¶

default_axis_names = ['rho', 'phi', 'z']¶

default_init_values = {'radius': 1}¶

radius

Radius of the cylindrical surface.

Useful for calculating densities.

source_ndim = 3¶

class physt.special_histograms.PolarHistogram(binnings: Iterable[Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float]], frequencies: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, dimension: Optional[int] = None, missed=0, **kwargs)¶

Bases: physt.special_histograms.TransformedHistogramMixin, physt.histogram_nd.HistogramND

2D histogram in polar coordinates.

This is a special case of a 2D histogram with transformed coordinates: - r as radius in the (0, +inf) range - phi as azimuthal angle in the (0, 2*pi) range

bin_sizes¶

default_axis_names = ['r', 'phi']¶

source_ndim = 2¶

class physt.special_histograms.RadialHistogram(binning: Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float], frequencies: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, errors2: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, keep_missed: bool = True, stats: Optional[Dict[str, float]] = None, overflow: Optional[float] = 0.0, underflow: Optional[float] = 0.0, inner_missed: Optional[float] = 0.0, axis_name: Optional[str] = None, **kwargs)¶

Bases: physt.special_histograms.TransformedHistogramMixin, physt.histogram1d.Histogram1D

Projection of polar histogram to 1D with respect to radius.

This is a special case of a 1D histogram with transformed coordinates.

bin_sizes¶

default_axis_names = ['r']¶

source_ndim = (2, 3)¶

class physt.special_histograms.SphericalHistogram(binnings: Iterable[Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float]], frequencies: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, dimension: Optional[int] = None, missed=0, **kwargs)¶

Bases: physt.special_histograms.TransformedHistogramMixin, physt.histogram_nd.HistogramND

3D histogram in spherical coordinates.

This is a special case of a 3D histogram with transformed coordinates: - r as radius in the (0, +inf) range - theta as angle between z axis and the vector, in the (0, 2*pi) range - phi as azimuthal angle (in the xy projection) in the (0, 2*pi) range

bin_sizes¶

default_axis_names = ['r', 'theta', 'phi']¶

source_ndim = 3¶

class physt.special_histograms.SphericalSurfaceHistogram(binnings: Iterable[Union[physt.binnings.BinningBase, numpy.ndarray, Iterable[T_co], int, float]], frequencies: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, dimension: Optional[int] = None, missed=0, **kwargs)¶

Bases: physt.special_histograms.TransformedHistogramMixin, physt.histogram_nd.HistogramND

2D histogram in spherical coordinates.

This is a special case of a 2D histogram with transformed coordinates: - theta as angle between z axis and the vector, in the (0, 2*pi) range - phi as azimuthal angle (in the xy projection) in the (0, 2*pi) range

bin_sizes¶

default_axis_names = ['theta', 'phi']¶

default_init_values = {'radius': 1}¶

radius¶

Radius of the surface.

Useful for calculating densities.

source_ndim = 3¶

class physt.special_histograms.TransformedHistogramMixin¶

Bases: abc.ABC

Histogram with non-cartesian (or otherwise transformed) axes.

This is a mixin, providing transform-aware find_bin, fill and fill_n.

When implementing, you are required to provide tbe following: - _transform_correct_dimension method to convert rectangular (it must be a classmethod) - bin_sizes property

In certain cases, you may want to have default axis names + projections. Look at PolarHistogram / SphericalHistogram / CylindricalHistogram as an example.

bin_sizes¶

fill(value: Union[numpy.ndarray, Iterable[T_co], int, float], weight: Union[numpy.ndarray, Iterable[T_co], int, float, None] = 1, *, transformed: bool = False, **kwargs)¶

fill_n(values: Union[numpy.ndarray, Iterable[T_co], int, float], weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, dropna: bool = True, transformed: bool = False, **kwargs)¶

find_bin(value, axis: Union[int, str, None] = None, transformed: bool = False)¶

Parameters:	value (array_like) – Value with dimensionality equal to histogram. transformed (bool) – If true, the value is already transformed and has same axes as the bins.

projection(*axes, **kwargs)¶

Projection to lower-dimensional histogram.

The inheriting class should implement the _projection_class_map class attribute to suggest class for the projection. If the arguments don’t match any of the map keys, HistogramND is used.

classmethod transform(value) → Union[numpy.ndarray, float]¶

Convert cartesian (general) coordinates into internal ones.

Parameters:	value (array_like) – This method should accept both scalars and numpy arrays. If multiple values are to be transformed, it should of (nvalues, ndim) shape. Note (Implement _) –

physt.special_histograms.azimuthal(xdata: Union[numpy.ndarray, Iterable[T_co], int, float], ydata: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, bins=16, range: Tuple[float, float] = (0, 6.283185307179586), dropna: bool = False, weights=None, transformed: bool = False, **kwargs) → physt.special_histograms.AzimuthalHistogram¶: Facade function to create an AzimuthalHistogram.

physt.special_histograms.azimuthal_histogram(xdata: Union[numpy.ndarray, Iterable[T_co], int, float], ydata: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, bins=16, range: Tuple[float, float] = (0, 6.283185307179586), dropna: bool = False, weights=None, transformed: bool = False, **kwargs) → physt.special_histograms.AzimuthalHistogram¶: Facade function to create an AzimuthalHistogram.

physt.special_histograms.cylindrical(data: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, rho_bins='numpy', phi_bins=16, z_bins='numpy', transformed: bool = False, dropna: bool = True, rho_range: Optional[Tuple[float, float]] = None, phi_range: Tuple[float, float] = (0, 6.283185307179586), weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, z_range: Optional[Tuple[float, float]] = None, **kwargs) → physt.special_histograms.CylindricalHistogram¶: Facade function to create a cylindrical histogram.

physt.special_histograms.cylindrical_histogram(data: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, rho_bins='numpy', phi_bins=16, z_bins='numpy', transformed: bool = False, dropna: bool = True, rho_range: Optional[Tuple[float, float]] = None, phi_range: Tuple[float, float] = (0, 6.283185307179586), weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, z_range: Optional[Tuple[float, float]] = None, **kwargs) → physt.special_histograms.CylindricalHistogram¶: Facade function to create a cylindrical histogram.

physt.special_histograms.cylindrical_surface(data=None, *, phi_bins=16, z_bins='numpy', transformed: bool = False, radius: Optional[float] = None, dropna: bool = False, weights=None, phi_range: Tuple[float, float] = (0, 6.283185307179586), z_range: Optional[Tuple[float, float]] = None, **kwargs) → physt.special_histograms.CylindricalSurfaceHistogram¶: Facade function to create a cylindrical surface histogram.

physt.special_histograms.cylindrical_surface_histogram(data=None, *, phi_bins=16, z_bins='numpy', transformed: bool = False, radius: Optional[float] = None, dropna: bool = False, weights=None, phi_range: Tuple[float, float] = (0, 6.283185307179586), z_range: Optional[Tuple[float, float]] = None, **kwargs) → physt.special_histograms.CylindricalSurfaceHistogram¶: Facade function to create a cylindrical surface histogram.

physt.special_histograms.polar(xdata: Union[numpy.ndarray, Iterable[T_co], int, float], ydata: Union[numpy.ndarray, Iterable[T_co], int, float], *, radial_bins='numpy', radial_range: Optional[Tuple[float, float]] = None, phi_bins=16, phi_range: Tuple[float, float] = (0, 6.283185307179586), dropna: bool = False, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, transformed: bool = False, **kwargs) → physt.special_histograms.PolarHistogram¶: Facade construction function for the PolarHistogram.

physt.special_histograms.polar_histogram(xdata: Union[numpy.ndarray, Iterable[T_co], int, float], ydata: Union[numpy.ndarray, Iterable[T_co], int, float], *, radial_bins='numpy', radial_range: Optional[Tuple[float, float]] = None, phi_bins=16, phi_range: Tuple[float, float] = (0, 6.283185307179586), dropna: bool = False, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, transformed: bool = False, **kwargs) → physt.special_histograms.PolarHistogram¶: Facade construction function for the PolarHistogram.

physt.special_histograms.radial(xdata: Union[numpy.ndarray, Iterable[T_co], int, float], ydata: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, zdata: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, bins='numpy', range: Optional[Tuple[float, float]] = None, dropna: bool = False, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, transformed: bool = False, **kwargs) → physt.special_histograms.RadialHistogram¶: Facade function to create a radial histogram.

physt.special_histograms.radial_histogram(xdata: Union[numpy.ndarray, Iterable[T_co], int, float], ydata: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, zdata: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, *, bins='numpy', range: Optional[Tuple[float, float]] = None, dropna: bool = False, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, transformed: bool = False, **kwargs) → physt.special_histograms.RadialHistogram¶: Facade function to create a radial histogram.

physt.special_histograms.spherical(data: Union[numpy.ndarray, Iterable[T_co], int, float], *, radial_bins='numpy', theta_bins=16, phi_bins=16, dropna: bool = True, transformed: bool = False, theta_range: Tuple[float, float] = (0, 3.141592653589793), phi_range: Tuple[float, float] = (0, 6.283185307179586), radial_range: Optional[Tuple[float, float]] = None, weights=None, **kwargs) → physt.special_histograms.SphericalHistogram¶: Facade function to create a speherical histogram.

physt.special_histograms.spherical_histogram(xdata: Union[numpy.ndarray, Iterable[T_co], int, float], ydata: Union[numpy.ndarray, Iterable[T_co], int, float], *, radial_bins='numpy', radial_range: Optional[Tuple[float, float]] = None, phi_bins=16, phi_range: Tuple[float, float] = (0, 6.283185307179586), dropna: bool = False, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, transformed: bool = False, **kwargs) → physt.special_histograms.PolarHistogram¶: Facade construction function for the PolarHistogram.

physt.special_histograms.spherical_surface(data: Union[numpy.ndarray, Iterable[T_co], int, float], *, theta_bins=16, phi_bins=16, transformed: bool = False, radius: Optional[float] = None, dropna: bool = False, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, theta_range: Tuple[float, float] = (0, 3.141592653589793), phi_range: Tuple[float, float] = (0, 6.283185307179586), **kwargs) → physt.special_histograms.SphericalSurfaceHistogram¶: Facade construction function for the SphericalSurfaceHistogram.

physt.special_histograms.spherical_surface_histogram(xdata: Union[numpy.ndarray, Iterable[T_co], int, float], ydata: Union[numpy.ndarray, Iterable[T_co], int, float], *, radial_bins='numpy', radial_range: Optional[Tuple[float, float]] = None, phi_bins=16, phi_range: Tuple[float, float] = (0, 6.283185307179586), dropna: bool = False, weights: Union[numpy.ndarray, Iterable[T_co], int, float, None] = None, transformed: bool = False, **kwargs) → physt.special_histograms.PolarHistogram¶: Facade construction function for the PolarHistogram.

physt.time module¶

physt.typing_aliases module¶

Definitions for type hints.

physt.util module¶

Various utility functions to support physt implementation.

These functions are mostly general Python functions, not specific for numerical computing, histogramming, etc.

physt.util.all_subclasses(cls: type) → Tuple[type, ...]¶

All subclasses of a class.

From: http://stackoverflow.com/a/17246726/2692780

physt.util.deprecation_alias(f, deprecated_name: str)¶

Provide a deprecated copy of a function.

Parameters:	f (The correct function) – deprecated_name (The name the function will be given) –

Examples

>>> def new(x): return 1
>>> old = deprecated_name(new, "old")

physt.util.find_subclass(base: type, name: str) → type¶

Find a named subclass of a base class.

Uses only the class name without namespace.

physt.util.pop_many(a_dict: Dict[str, Any], *args, **kwargs) → Dict[str, Any]¶

Pop multiple items from a dictionary.

Parameters:	a_dict (Dictionary from which the items will popped) – args (Keys which will be popped (and not included if not present)) – kwargs (Keys + default value pairs (if key not found, this default is included)) –
Returns:
Return type:	A dictionary of collected items.

physt.version module¶

Package information.

Module contents¶

physt¶

P(i/y)thon h(i/y)stograms. Inspired (and based on) numpy.histogram, but designed for humans(TM) on steroids(TM).

(C) Jan Pipek, 2016-2021, MIT licence See https://github.com/janpipek/physt

physt package¶

Subpackages¶

Submodules¶

physt.bin_utils module¶

physt.binnings module¶

physt.config module¶

physt.facade module¶

physt.histogram1d module¶

physt.histogram_base module¶

physt.histogram_collection module¶

physt.histogram_nd module¶

physt.special module¶

physt.special_histograms module¶

physt.time module¶

physt.typing_aliases module¶

physt.util module¶

physt.version module¶

Module contents¶

physt¶