physt package

Subpackages

Submodules

physt.bin_utils module

physt.binnings module

Different binning algorithms/schemas for the histograms.

class physt.binnings.BinningBase(bins: ArrayLike | None = None, numpy_bins: ArrayLike | None = None, includes_right_edge: bool = False, adaptive: bool = False)

Bases: object

Abstract base class for binning schemas.

Inheriting

  • 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).

adapt(other: BinningBase)

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

Parameters:

other (BinningBase)

adaptive_allowed: ClassVar[bool] = False

Whether it is possible to update the bins dynamically.

apply_bin_map(bin_map) → BinningBase
Parameters:

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

as_fixed_width(copy: bool = True) → 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) → 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

property bin_count: int

The total number of bins.

property bins: ndarray

Bins in the wider format (as edge pairs)

Returns:

bins – shape=(bin_count, 2)

Return type:

np.ndarray

copy() → Self

An identical, independent copy.

property first_edge: float

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: Dict[str, Any]) → BinningBase
property includes_right_edge: bool
inconsecutive_allowed: ClassVar[bool] = False

Whether it is possible to have bins with gaps.

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:

  • rtol (numpy tolerance parameters)

  • atol (numpy tolerance parameters)

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

Whether all bins have the same width.

Parameters:

  • rtol (numpy tolerance parameters)

  • atol (numpy tolerance parameters)

property last_edge: float

The right edge of the last bin.

property numpy_bins: ndarray

Bins in the numpy format

This might not be available for inconsecutive binnings.

Returns:

edges – shape=(bin_count+1,)

Return type:

np.ndarray

property numpy_bins_with_mask: Tuple[np.ndarray, np.ndarray]

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

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

Bases: BinningBase

Binning schema with exponentially distributed bins.

adaptive_allowed: ClassVar[bool] = False

Whether it is possible to update the bins dynamically.

copy() → ExponentialBinning

An identical, independent copy.

is_regular(**kwargs) → bool

Whether all bins have the same width.

Parameters:

  • rtol (numpy tolerance parameters)

  • atol (numpy tolerance parameters)

property 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: BinningBase

Binning schema with predefined bin width.

adaptive_allowed: ClassVar[bool] = True

Whether it is possible to update the bins dynamically.

as_fixed_width(copy: bool = True) → FixedWidthBinning

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

Parameters:

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

property bin_count

The total number of bins.

property bin_width
copy()

An identical, independent copy.

property first_edge: float

The left edge of the first bin.

is_regular(**kwargs) → bool

Whether all bins have the same width.

Parameters:

  • rtol (numpy tolerance parameters)

  • atol (numpy tolerance parameters)

property last_edge: float

The right edge of the last bin.

property 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: ArrayLike, includes_right_edge=True, **kwargs)

Bases: BinningBase

Binning schema working as numpy.histogram.

copy() → NumpyBinning

An identical, independent copy.

property 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: BinningBase

Binning defined by an array of bin edge pairs.

as_static(copy: bool = True) → 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() → StaticBinning

An identical, independent copy.

inconsecutive_allowed: ClassVar[bool] = True

Whether it is possible to have bins with gaps.

physt.binnings.as_binning(obj: BinningLike, copy: bool = False) → 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.bayesian_blocks_binning(data, range=None, **kwargs) → StaticBinning

Binning schema based on Bayesian blocks (from astropy).

Computationally expensive for large data sets.

Parameters:

range (Optional[tuple])

See also

astropy.stats.histogram.bayesian_blocks, astropy.stats.histogram.histogram

physt.binnings.binning_methods = {'blocks': <function bayesian_blocks_binning>, 'exponential': <function exponential_binning>, 'fixed_width': <function fixed_width_binning>, 'freedman': <function freedman_binning>, 'human': <function pretty_binning>, 'integer': <function integer_binning>, 'knuth': <function knuth_binning>, 'numpy': <function numpy_binning>, 'pretty': <function pretty_binning>, 'quantile': <function quantile_binning>, 'scott': <function scott_binning>, 'static': <function static_binning>}

Dictionary of available binnnings.

physt.binnings.exponential_binning(data: np.ndarray | None = None, bin_count: int | None = None, *, range: RangeTuple | None = None, **kwargs) → ExponentialBinning

Construct exponential binning schema.

Parameters:

  • bin_count (Number of bins)

  • range ((min, max))

See also

numpy.logspace

physt.binnings.fixed_width_binning(data: np.ndarray | None = None, bin_width: float | int = 1, *, range: RangeTuple | None = None, includes_right_edge: bool = False, **kwargs) → 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.freedman_binning(data, range=None, **kwargs) → StaticBinning

Binning schema based on Freedman-Diaconis rule (from astropy).

Parameters:

  • data (arraylike)

  • range (Optional[tuple])

See also

astropy.stats.histogram.freedman_bin_width, astropy.stats.histogram.histogram

physt.binnings.human_binning(data: np.ndarray | None, bin_count: int | None = None, *, kind: Literal['time'] | None = None, range: RangeTuple | None = None, min_bin_width: float | None = None, max_bin_width: float | None = None, **kwargs) → 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 (Starting number of bins (the result will be close))

  • 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: 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: np.ndarray | None = None, **kwargs) → 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.knuth_binning(data, range=None, **kwargs) → StaticBinning

Binning schema based on Knuth’s rule (from astropy).

Computationally expensive for large data sets.

Parameters:

  • data (arraylike)

  • range (Optional[tuple])

See also

astropy.stats.histogram.knuth_bin_width, astropy.stats.histogram.histogram

physt.binnings.numpy_binning(data: np.ndarray | None = None, bin_count: int = 10, range: RangeTuple | None = None, **kwargs) → 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.pretty_binning(data: np.ndarray | None, bin_count: int | None = None, *, kind: Literal['time'] | None = None, range: RangeTuple | None = None, min_bin_width: float | None = None, max_bin_width: float | None = None, **kwargs) → 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 (Starting number of bins (the result will be close))

  • 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.quantile_binning(data: np.ndarray | None, *, bin_count: int | None = None, q: Sequence[float] | None = None, qrange: RangeTuple | None = None, **kwargs) → 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))

physt.binnings.register_binning(name: str | None = None) → Callable[[Callable], Callable]

Decorator to register among available binning methods.

physt.binnings.scott_binning(data, range=None, **kwargs) → StaticBinning

Binning schema based on Scott’s rule (from astropy).

Parameters:

  • data (arraylike)

  • range (Optional[tuple])

See also

astropy.stats.histogram.scott_bin_width, astropy.stats.histogram.histogram

physt.binnings.static_binning(data: np.ndarray | None = None, *, bins: ArrayLike, **kwargs) → StaticBinning

Construct static binning with whatever bins.

physt.config module

physt.facade module

physt.histogram1d module

One-dimensional histograms.

class physt.histogram1d.Histogram1D(binning: BinningLike, frequencies: ArrayLike | None = None, errors2: ArrayLike | None = None, *, keep_missed: bool = True, stats: Statistics | None = None, overflow: float | None = 0.0, underflow: float | None = 0.0, inner_missed: float | None = 0.0, axis_name: str | None = None, **kwargs)

Bases: ObjectWithBinning, 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).

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

property axis_name: str
property binning: BinningBase

The binning.

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

copy(*, include_frequencies: bool = True) → Histogram1D

Copy the histogram.

Parameters:

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

property cumulative_frequencies: ndarray

Cumulative frequencies.

Note: underflow values are not considered

fill(value: float, weight: float = 1, **kwargs) → int | None

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: ArrayLike, weights: ArrayLike | 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: float, axis: Axis | None = None) → int | None

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: np.ndarray | None, binning: BinningBase, weights: np.ndarray | None = None, *, validate_bins: bool = True, already_sorted: bool = False, keep_missed: bool = True, dtype: DTypeLike | None = None, **kwargs) → Histogram1DType

Construct the histogram from values and bins.

classmethod from_xarray(arr: Dataset) → Histogram1D

Convert form xarray.Dataset

Parameters:

arr (The data in xarray representation)

property inner_missed
property numpy_like: Tuple[np.ndarray, np.ndarray]

Same result as would the numpy.histogram function return.

property overflow
select(axis, index, *, force_copy: bool = False) → 'Histogram1D' | Tuple[np.ndarray, float]

Alias for [] to be compatible with HistogramND.

property statistics: Statistics
to_dataframe() → DataFrame

Convert histogram to pandas DataFrame.

to_series() → Series

Convert histogram to pandas Series.

to_xarray() → Dataset

Convert histogram to an xarray Datates representation.

See also: Histogram1D.from_xarray (inverse operation)

property underflow
class physt.histogram1d.ObjectWithBinning

Bases: ABC

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

Note: Used to share behaviour between Histogram1D and HistogramCollection.

property bin_centers: ndarray

Centers of all bins.

property bin_left_edges: ndarray

Left edges of all bins.

property bin_right_edges: ndarray

Right edges of all bins.

property bin_sizes: ndarray
property bin_widths: ndarray

Widths of all bins.

abstract property binning: BinningBase

The binning itself.

property bins: ndarray

Array of all bin edges.

Return type:

Wide-format [[leftedge1, rightedge1], … [leftedgeN, rightedgeN]]

property edges: ndarray
get_bin_left_edges(i)
get_bin_right_edges(i)
property max_edge: float

Right edge of the last bin.

property min_edge: float

Left edge of the first bin.

property ndim: int
property numpy_bins: ndarray

Bins in the format of numpy.

property total_width: float

Total width of all bins.

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

physt.histogram_base module

HistogramBase - base for all histogram classes.

class physt.histogram_base.HistogramBase(binnings: Iterable[BinningLike], frequencies: ArrayLike | None = None, errors2: ArrayLike | None = None, *, axis_names: Iterable[str] | None = None, dtype: DTypeLike | None = None, keep_missed: bool = True, **kwargs)

Bases: 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

SUPPORTED_DTYPES: ClassVar[Collection[Type[np.number]]] = (<class 'numpy.int16'>, <class 'numpy.int32'>, <class 'numpy.int64'>, <class 'numpy.float16'>, <class 'numpy.float32'>, <class 'numpy.float64'>, <class 'numpy.longdouble'>)
property adaptive: bool
property axis_names: Tuple[str, ...]

Names of axes (stored in meta-data).

property bin_count: int

Total number of bins.

abstract property bin_sizes: ndarray
property binnings: List[BinningBase]

The binnings.

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

abstract property bins: np.ndarray | List[np.ndarray]
copy(*, include_frequencies: bool = True) → HistogramType

Copy the histogram.

Parameters:

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

property default_axis_names: List[str]

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

default_init_values: Dict[str, Any] = {}
property densities: ndarray

Frequencies normalized by bin sizes.

Useful when bins are not of the same size.

property dtype: dtype

Data type of the bin contents.

property errors: ndarray

Bin errors.

property errors2: ndarray

Squares of the bin errors.

abstract fill(value: float, weight: float = 1, **kwargs) → 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

abstract fill_n(values: ArrayLike, weights: ArrayLike | 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.

property frequencies: ndarray

Frequencies (values, contents) of the histogram bins.

classmethod from_dict(a_dict: Mapping[str, Any]) → Self

Create an instance from a dictionary.

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

has_same_bins(other: HistogramBase) → bool

Whether two histograms share the same binning.

is_adaptive() → bool

Whether the binning can be changed with operations.

merge_bins(amount: int | None = None, *, min_frequency: float | None = None, axis: Axis | 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)

property meta_data: Dict[str, Any]

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.

property missed: float

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

property name: str | None

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

property ndim: int

Dimensionality of histogram’s data.

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

normalize(inplace: bool = False, percent: bool = False) → 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)

Return type:

either modified copy or self

See also

densities, HistogramND.partial_normalize

property plot: physt.plotting.PlottingProxy

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.

abstract select(axis: Axis, index: 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: DTypeLike, *, 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)

property shape: Tuple[int, ...]

Shape of histogram’s data.

Return type:

Tuple with the number of bins along each axis.

property title: str | None

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: str | None = None, **kwargs) → str

Convert to JSON representation.

Parameters:

path (Where to write the JSON.)

Return type:

The JSON representation.

property total: float

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

physt.histogram_collection module

class physt.histogram_collection.HistogramCollection(*histograms: Histogram1D, binning: BinningLike | None = None, title: str | None = None, name: str | None = None)

Bases: Container[Histogram1D], ObjectWithBinning

Experimental collection of histograms.

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

add(histogram: Histogram1D) → None

Add a histogram to the collection.

property axis_name: str
property axis_names: Tuple[str]
property binning: BinningBase

The binning itself.

copy() → HistogramCollection
create(name: str, values, *, weights=None, dropna: bool = True, **kwargs) → Histogram1D
classmethod from_dict(a_dict: Dict[str, Any]) → HistogramCollection
classmethod multi_h1(a_dict: Mapping[str, ArrayLike], bins=None, **kwargs) → HistogramCollection

Create a collection from multiple datasets.

normalize_all(inplace: bool = False) → HistogramCollection

Normalize all histograms so that total content of each of them is equal to 1.0.

normalize_bins(inplace: bool = False) → 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.

property plot: PlottingProxy

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() → Histogram1D

Return the sum of all contained histograms.

to_dict() → Dict[str, Any]
to_json(path: str | None = None, **kwargs) → str

Convert to JSON representation.

Parameters:

path (Where to write the JSON.)

Return type:

The JSON representation.

physt.histogram_nd module

Multi-dimensional histograms.

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

Bases: HistogramND

Specialized 2D variant of the general HistogramND class.

In contrast to general HistogramND, it is plottable.

property T: Histogram2D

Histogram with swapped axes.

Return type:

Histogram2D - a copy with swapped axes

property numpy_like: Tuple[ndarray, ...]

Same result as would the numpy.histogram function return.

partial_normalize(axis: Axis = 0, inplace: bool = False) → Histogram2D

Normalize in rows or columns.

Parameters:

  • axis (int or str) – Along which axis to sum (numpy-sense)

  • inplace (bool) – Update the object itself

class physt.histogram_nd.HistogramND(binnings: Iterable[BinningLike], frequencies: ArrayLike | None = None, *, dimension: int | None = None, axis_names: Iterable[str] | None = None, missed=0, **kwargs)

Bases: HistogramBase

Multi-dimensional histogram data.

accumulate(axis: Axis) → HistogramBase

Calculate cumulative frequencies along a certain axis.

Returns:

new_hist

Return type:

Histogram of the same type & size

property bin_sizes: ndarray
property bins: List[np.ndarray]

List of bin matrices.

property edges: List[np.ndarray]
fill(value: ArrayLike, weight: float = 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: ArrayLike, weights: ArrayLike | 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: ArrayLike, axis: Axis | None = None) → 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

Return type:

If axis is specified, a number. Otherwise, a tuple. If not available, None.

classmethod from_calculate_frequencies(data, binnings, weights=None, *, dtype=None, **kwargs)
get_bin_centers(axis: Axis) → ndarray
get_bin_centers(axis: None = None) → Sequence[np.ndarray]
get_bin_edges(axis: Axis) → ndarray
get_bin_edges(axis: None = None) → Sequence[np.ndarray]
get_bin_left_edges(axis: Axis) → ndarray
get_bin_left_edges(axis: None = None) → Sequence[np.ndarray]
get_bin_right_edges(axis: Axis) → ndarray
get_bin_right_edges(axis: None = None) → Sequence[np.ndarray]
get_bin_widths(axis: Axis) → ndarray
get_bin_widths(axis: None = None) → Sequence[np.ndarray]
property numpy_bins: List[np.ndarray]

Numpy-like bins (if available).

property numpy_like: Tuple

Same result as would the numpy.histogram function return.

projection(*axes: Axis, **kwargs) → 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

Return type:

HistogramND or Histogram2D or Histogram1D (or others in special cases)

select(axis: Axis, index: int | slice, *, force_copy: bool = False) → 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.)

property total_size: float

The total size of the bin space.

Note

Perhaps not optimized, but should work also with transformed axes

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: BinningLike, frequencies: ArrayLike | None = None, errors2: ArrayLike | None = None, *, keep_missed: bool = True, stats: Statistics | None = None, overflow: float | None = 0.0, underflow: float | None = 0.0, inner_missed: float | None = 0.0, axis_name: str | None = None, **kwargs)

Bases: TransformedHistogramMixin, Histogram1D

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

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

property bin_sizes
default_axis_names = ['phi']
default_init_values: Dict[str, Any] = {'radius': 1}
property radius

Radius of the surface.

Useful for calculating densities.

source_ndim: int | Tuple[int, ...] = 2
class physt.special_histograms.CylindricalHistogram(binnings: Iterable[BinningLike], frequencies: ArrayLike | None = None, *, dimension: int | None = None, axis_names: Iterable[str] | None = None, missed=0, **kwargs)

Bases: TransformedHistogramMixin, 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

property 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: int | Tuple[int, ...] = 3
class physt.special_histograms.CylindricalSurfaceHistogram(binnings: Iterable[BinningLike], frequencies: ArrayLike | None = None, *, dimension: int | None = None, axis_names: Iterable[str] | None = None, missed=0, **kwargs)

Bases: TransformedHistogramMixin, 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

property bin_sizes: ndarray
default_axis_names = ['rho', 'phi', 'z']
default_init_values: Dict[str, Any] = {'radius': 1}
property radius: float

Radius of the cylindrical surface.

Useful for calculating densities.

source_ndim: int | Tuple[int, ...] = 3
class physt.special_histograms.PolarHistogram(binnings: Iterable[BinningLike], frequencies: ArrayLike | None = None, *, dimension: int | None = None, axis_names: Iterable[str] | None = None, missed=0, **kwargs)

Bases: TransformedHistogramMixin, 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

property bin_sizes
default_axis_names = ['r', 'phi']
source_ndim: int | Tuple[int, ...] = 2
class physt.special_histograms.RadialHistogram(binning: BinningLike, frequencies: ArrayLike | None = None, errors2: ArrayLike | None = None, *, keep_missed: bool = True, stats: Statistics | None = None, overflow: float | None = 0.0, underflow: float | None = 0.0, inner_missed: float | None = 0.0, axis_name: str | None = None, **kwargs)

Bases: TransformedHistogramMixin, Histogram1D

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

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

property bin_sizes
default_axis_names = ['r']
source_ndim: int | Tuple[int, ...] = (2, 3)
class physt.special_histograms.SphericalHistogram(binnings: Iterable[BinningLike], frequencies: ArrayLike | None = None, *, dimension: int | None = None, axis_names: Iterable[str] | None = None, missed=0, **kwargs)

Bases: TransformedHistogramMixin, 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

property bin_sizes
default_axis_names = ['r', 'theta', 'phi']
source_ndim: int | Tuple[int, ...] = 3
class physt.special_histograms.SphericalSurfaceHistogram(binnings: Iterable[BinningLike], frequencies: ArrayLike | None = None, *, dimension: int | None = None, axis_names: Iterable[str] | None = None, missed=0, **kwargs)

Bases: TransformedHistogramMixin, 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

property bin_sizes
default_axis_names = ['theta', 'phi']
default_init_values: Dict[str, Any] = {'radius': 1}
property radius: float

Radius of the surface.

Useful for calculating densities.

source_ndim: int | Tuple[int, ...] = 3
class physt.special_histograms.TransformedHistogramMixin

Bases: 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.

abstract property bin_sizes
fill(value: ArrayLike, weight: ArrayLike | None = 1, *, transformed: bool = False, **kwargs)
fill_n(values: ArrayLike, weights: ArrayLike | None = None, *, dropna: bool = True, transformed: bool = False, **kwargs)
find_bin(value: ArrayLike, axis: Axis | 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.

source_ndim: int | Tuple[int, ...]
classmethod transform(value: ArrayLike) → np.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: ArrayLike, ydata: ArrayLike | None = None, *, bins=16, range: RangeTuple = (0, 6.283185307179586), dropna: bool = False, weights=None, transformed: bool = False, **kwargs) → AzimuthalHistogram

Facade function to create an AzimuthalHistogram.

physt.special_histograms.azimuthal_histogram(xdata: ArrayLike, ydata: ArrayLike | None = None, *, bins=16, range: RangeTuple = (0, 6.283185307179586), dropna: bool = False, weights=None, transformed: bool = False, **kwargs) → AzimuthalHistogram

Facade function to create an AzimuthalHistogram.

physt.special_histograms.cylindrical(data: ArrayLike | None = None, *, rho_bins='numpy', phi_bins=16, z_bins='numpy', transformed: bool = False, dropna: bool = True, rho_range: RangeTuple | None = None, phi_range: RangeTuple = (0, 6.283185307179586), weights: ArrayLike | None = None, z_range: RangeTuple | None = None, **kwargs) → CylindricalHistogram

Facade function to create a cylindrical histogram.

physt.special_histograms.cylindrical_histogram(data: ArrayLike | None = None, *, rho_bins='numpy', phi_bins=16, z_bins='numpy', transformed: bool = False, dropna: bool = True, rho_range: RangeTuple | None = None, phi_range: RangeTuple = (0, 6.283185307179586), weights: ArrayLike | None = None, z_range: RangeTuple | None = None, **kwargs) → 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: float | None = None, dropna: bool = False, weights=None, phi_range: RangeTuple = (0, 6.283185307179586), z_range: RangeTuple | None = None, **kwargs) → 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: float | None = None, dropna: bool = False, weights=None, phi_range: RangeTuple = (0, 6.283185307179586), z_range: RangeTuple | None = None, **kwargs) → CylindricalSurfaceHistogram

Facade function to create a cylindrical surface histogram.

physt.special_histograms.extract_transformed_data(data: ArrayLike, transformed: bool, klass: Type[TransformedHistogramMixin], *, dropna: bool = False) → Tuple[np.ndarray, np.ndarray]
physt.special_histograms.extract_transformed_data(data: None, transformed: bool, klass: Type[TransformedHistogramMixin], *, dropna: bool = False) → Tuple[None, None]

Extract and potentially transform data for binning.

physt.special_histograms.polar(xdata: ArrayLike, ydata: ArrayLike, *, radial_bins='numpy', radial_range: RangeTuple | None = None, phi_bins=16, phi_range: RangeTuple = (0, 6.283185307179586), dropna: bool = False, weights: ArrayLike | None = None, transformed: bool = False, **kwargs) → PolarHistogram

Facade construction function for the PolarHistogram.

physt.special_histograms.polar_histogram(xdata: ArrayLike, ydata: ArrayLike, *, radial_bins='numpy', radial_range: RangeTuple | None = None, phi_bins=16, phi_range: RangeTuple = (0, 6.283185307179586), dropna: bool = False, weights: ArrayLike | None = None, transformed: bool = False, **kwargs) → PolarHistogram

Facade construction function for the PolarHistogram.

physt.special_histograms.radial(xdata: ArrayLike, ydata: ArrayLike | None = None, zdata: ArrayLike | None = None, *, bins='numpy', range: RangeTuple | None = None, dropna: bool = False, weights: ArrayLike | None = None, transformed: bool = False, **kwargs) → RadialHistogram

Facade function to create a radial histogram.

physt.special_histograms.radial_histogram(xdata: ArrayLike, ydata: ArrayLike | None = None, zdata: ArrayLike | None = None, *, bins='numpy', range: RangeTuple | None = None, dropna: bool = False, weights: ArrayLike | None = None, transformed: bool = False, **kwargs) → RadialHistogram

Facade function to create a radial histogram.

physt.special_histograms.spherical(data: ArrayLike, *, radial_bins='numpy', theta_bins=16, phi_bins=16, dropna: bool = True, transformed: bool = False, theta_range: RangeTuple = (0, 3.141592653589793), phi_range: RangeTuple = (0, 6.283185307179586), radial_range: RangeTuple | None = None, weights=None, **kwargs) → SphericalHistogram

Facade function to create a spherical histogram.

physt.special_histograms.spherical_histogram(xdata: ArrayLike, ydata: ArrayLike, *, radial_bins='numpy', radial_range: RangeTuple | None = None, phi_bins=16, phi_range: RangeTuple = (0, 6.283185307179586), dropna: bool = False, weights: ArrayLike | None = None, transformed: bool = False, **kwargs) → PolarHistogram

Facade construction function for the PolarHistogram.

physt.special_histograms.spherical_surface(data: ArrayLike, *, theta_bins=16, phi_bins=16, transformed: bool = False, radius: float | None = None, dropna: bool = False, weights: ArrayLike | None = None, theta_range: RangeTuple = (0, 3.141592653589793), phi_range: RangeTuple = (0, 6.283185307179586), **kwargs) → SphericalSurfaceHistogram

Facade construction function for the SphericalSurfaceHistogram.

physt.special_histograms.spherical_surface_histogram(xdata: ArrayLike, ydata: ArrayLike, *, radial_bins='numpy', radial_range: RangeTuple | None = None, phi_bins=16, phi_range: RangeTuple = (0, 6.283185307179586), dropna: bool = False, weights: ArrayLike | None = None, transformed: bool = False, **kwargs) → PolarHistogram

Facade construction function for the PolarHistogram.

physt.testing module

Support testing.

More detailed comparisons of histograms mostly for unit testing.

physt.testing.assert_histograms_equal(left: HistogramBase, right: HistogramBase, *, check_dtype: bool = True, check_frequencies: bool = True, check_bins: bool = True, check_binnings: bool = True, check_metadata: bool = True, rtol: float = 1e-07, atol: float = 0) → None

Helper function to compare two histograms.

physt.testing.assert_optional_array_equal(actual: ndarray | None, desired: ndarray | None, **kwargs) → None

Assert the arrays are equal or both None (helper for out tests).

physt.time module

physt.types module

All public types of physt.

class physt.types.Histogram1D(binning: BinningLike, frequencies: ArrayLike | None = None, errors2: ArrayLike | None = None, *, keep_missed: bool = True, stats: Statistics | None = None, overflow: float | None = 0.0, underflow: float | None = 0.0, inner_missed: float | None = 0.0, axis_name: str | None = None, **kwargs)

Bases: ObjectWithBinning, 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).

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

property axis_name: str
property binning: BinningBase

The binning.

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

copy(*, include_frequencies: bool = True) → Histogram1D

Copy the histogram.

Parameters:

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

property cumulative_frequencies: ndarray

Cumulative frequencies.

Note: underflow values are not considered

fill(value: float, weight: float = 1, **kwargs) → int | None

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: ArrayLike, weights: ArrayLike | 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: float, axis: Axis | None = None) → int | None

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: np.ndarray | None, binning: BinningBase, weights: np.ndarray | None = None, *, validate_bins: bool = True, already_sorted: bool = False, keep_missed: bool = True, dtype: DTypeLike | None = None, **kwargs) → Histogram1DType

Construct the histogram from values and bins.

classmethod from_xarray(arr: Dataset) → Histogram1D

Convert form xarray.Dataset

Parameters:

arr (The data in xarray representation)

property inner_missed
property numpy_like: Tuple[np.ndarray, np.ndarray]

Same result as would the numpy.histogram function return.

property overflow
select(axis, index, *, force_copy: bool = False) → 'Histogram1D' | Tuple[np.ndarray, float]

Alias for [] to be compatible with HistogramND.

property statistics: Statistics
to_dataframe() → DataFrame

Convert histogram to pandas DataFrame.

to_series() → Series

Convert histogram to pandas Series.

to_xarray() → Dataset

Convert histogram to an xarray Datates representation.

See also: Histogram1D.from_xarray (inverse operation)

property underflow
class physt.types.Histogram2D(binnings, frequencies=None, **kwargs)

Bases: HistogramND

Specialized 2D variant of the general HistogramND class.

In contrast to general HistogramND, it is plottable.

property T: Histogram2D

Histogram with swapped axes.

Return type:

Histogram2D - a copy with swapped axes

property numpy_like: Tuple[ndarray, ...]

Same result as would the numpy.histogram function return.

partial_normalize(axis: Axis = 0, inplace: bool = False) → Histogram2D

Normalize in rows or columns.

Parameters:

  • axis (int or str) – Along which axis to sum (numpy-sense)

  • inplace (bool) – Update the object itself

class physt.types.HistogramBase(binnings: Iterable[BinningLike], frequencies: ArrayLike | None = None, errors2: ArrayLike | None = None, *, axis_names: Iterable[str] | None = None, dtype: DTypeLike | None = None, keep_missed: bool = True, **kwargs)

Bases: 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

SUPPORTED_DTYPES: ClassVar[Collection[Type[np.number]]] = (<class 'numpy.int16'>, <class 'numpy.int32'>, <class 'numpy.int64'>, <class 'numpy.float16'>, <class 'numpy.float32'>, <class 'numpy.float64'>, <class 'numpy.longdouble'>)
property adaptive: bool
property axis_names: Tuple[str, ...]

Names of axes (stored in meta-data).

property bin_count: int

Total number of bins.

abstract property bin_sizes: ndarray
property binnings: List[BinningBase]

The binnings.

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

abstract property bins: np.ndarray | List[np.ndarray]
copy(*, include_frequencies: bool = True) → HistogramType

Copy the histogram.

Parameters:

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

property default_axis_names: List[str]

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

default_init_values: Dict[str, Any] = {}
property densities: ndarray

Frequencies normalized by bin sizes.

Useful when bins are not of the same size.

property dtype: dtype

Data type of the bin contents.

property errors: ndarray

Bin errors.

property errors2: ndarray

Squares of the bin errors.

abstract fill(value: float, weight: float = 1, **kwargs) → 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

abstract fill_n(values: ArrayLike, weights: ArrayLike | 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.

property frequencies: ndarray

Frequencies (values, contents) of the histogram bins.

classmethod from_dict(a_dict: Mapping[str, Any]) → Self

Create an instance from a dictionary.

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

has_same_bins(other: HistogramBase) → bool

Whether two histograms share the same binning.

is_adaptive() → bool

Whether the binning can be changed with operations.

merge_bins(amount: int | None = None, *, min_frequency: float | None = None, axis: Axis | 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)

property meta_data: Dict[str, Any]

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.

property missed: float

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

property name: str | None

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

property ndim: int

Dimensionality of histogram’s data.

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

normalize(inplace: bool = False, percent: bool = False) → 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)

Return type:

either modified copy or self

See also

densities, HistogramND.partial_normalize

property plot: physt.plotting.PlottingProxy

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.

abstract select(axis: Axis, index: 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: DTypeLike, *, 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)

property shape: Tuple[int, ...]

Shape of histogram’s data.

Return type:

Tuple with the number of bins along each axis.

property title: str | None

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: str | None = None, **kwargs) → str

Convert to JSON representation.

Parameters:

path (Where to write the JSON.)

Return type:

The JSON representation.

property total: float

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

class physt.types.HistogramCollection(*histograms: Histogram1D, binning: BinningLike | None = None, title: str | None = None, name: str | None = None)

Bases: Container[Histogram1D], ObjectWithBinning

Experimental collection of histograms.

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

add(histogram: Histogram1D) → None

Add a histogram to the collection.

property axis_name: str
property axis_names: Tuple[str]
property binning: BinningBase

The binning itself.

copy() → HistogramCollection
create(name: str, values, *, weights=None, dropna: bool = True, **kwargs) → Histogram1D
classmethod from_dict(a_dict: Dict[str, Any]) → HistogramCollection
classmethod multi_h1(a_dict: Mapping[str, ArrayLike], bins=None, **kwargs) → HistogramCollection

Create a collection from multiple datasets.

normalize_all(inplace: bool = False) → HistogramCollection

Normalize all histograms so that total content of each of them is equal to 1.0.

normalize_bins(inplace: bool = False) → 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.

property plot: PlottingProxy

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() → Histogram1D

Return the sum of all contained histograms.

to_dict() → Dict[str, Any]
to_json(path: str | None = None, **kwargs) → str

Convert to JSON representation.

Parameters:

path (Where to write the JSON.)

Return type:

The JSON representation.

class physt.types.HistogramND(binnings: Iterable[BinningLike], frequencies: ArrayLike | None = None, *, dimension: int | None = None, axis_names: Iterable[str] | None = None, missed=0, **kwargs)

Bases: HistogramBase

Multi-dimensional histogram data.

accumulate(axis: Axis) → HistogramBase

Calculate cumulative frequencies along a certain axis.

Returns:

new_hist

Return type:

Histogram of the same type & size

property bin_sizes: ndarray
property bins: List[np.ndarray]

List of bin matrices.

property edges: List[np.ndarray]
fill(value: ArrayLike, weight: float = 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: ArrayLike, weights: ArrayLike | 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: ArrayLike, axis: Axis | None = None) → 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

Return type:

If axis is specified, a number. Otherwise, a tuple. If not available, None.

classmethod from_calculate_frequencies(data, binnings, weights=None, *, dtype=None, **kwargs)
get_bin_centers(axis: Axis) → ndarray
get_bin_centers(axis: None = None) → Sequence[np.ndarray]
get_bin_edges(axis: Axis) → ndarray
get_bin_edges(axis: None = None) → Sequence[np.ndarray]
get_bin_left_edges(axis: Axis) → ndarray
get_bin_left_edges(axis: None = None) → Sequence[np.ndarray]
get_bin_right_edges(axis: Axis) → ndarray
get_bin_right_edges(axis: None = None) → Sequence[np.ndarray]
get_bin_widths(axis: Axis) → ndarray
get_bin_widths(axis: None = None) → Sequence[np.ndarray]
property numpy_bins: List[np.ndarray]

Numpy-like bins (if available).

property numpy_like: Tuple

Same result as would the numpy.histogram function return.

projection(*axes: Axis, **kwargs) → 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

Return type:

HistogramND or Histogram2D or Histogram1D (or others in special cases)

select(axis: Axis, index: int | slice, *, force_copy: bool = False) → 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.)

property total_size: float

The total size of the bin space.

Note

Perhaps not optimized, but should work also with transformed axes

physt.typing_aliases module

Definitions for type hints.

physt.typing_aliases.Axis

Identifier for axis - either the numerical order or the name.

alias of int | str

physt.util module

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-2022, MIT licence See https://github.com/janpipek/physt

physt.azimuthal(xdata: ArrayLike, ydata: ArrayLike | None = None, *, bins=16, range: RangeTuple = (0, 6.283185307179586), dropna: bool = False, weights=None, transformed: bool = False, **kwargs) → AzimuthalHistogram

Facade function to create an AzimuthalHistogram.

physt.collection(data, bins=10, **kwargs) → HistogramCollection

Create histogram collection with shared binning.

physt.cylindrical(data: ArrayLike | None = None, *, rho_bins='numpy', phi_bins=16, z_bins='numpy', transformed: bool = False, dropna: bool = True, rho_range: RangeTuple | None = None, phi_range: RangeTuple = (0, 6.283185307179586), weights: ArrayLike | None = None, z_range: RangeTuple | None = None, **kwargs) → CylindricalHistogram

Facade function to create a cylindrical histogram.

physt.cylindrical_surface(data=None, *, phi_bins=16, z_bins='numpy', transformed: bool = False, radius: float | None = None, dropna: bool = False, weights=None, phi_range: RangeTuple = (0, 6.283185307179586), z_range: RangeTuple | None = None, **kwargs) → CylindricalSurfaceHistogram

Facade function to create a cylindrical surface histogram.

physt.h(data: ArrayLike | None, bins=10, *, adaptive: bool = False, dropna: bool = True, name: str | None = None, title: str | None = None, axis_names: Iterable[str] | None = None, dim: int | None = None, weights: ArrayLike | None = None, **kwargs) → HistogramND

Facade function to create n-dimensional histograms.

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

Parameters:

  • data (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.h1(data: ArrayLike | None, bins=None, *, adaptive: bool = False, dropna: bool = True, dtype: DTypeLike | None = None, weights: ArrayLike | None = None, keep_missed: bool = True, name: str | None = None, title: str | None = None, axis_name: str | None = None, **kwargs) → 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))

  • excluded (Other numpy.histogram parameters are)

  • itself. (see the methods of the Histogram1D class)

See also

numpy.histogram

physt.h2(data1: ArrayLike | None, data2: ArrayLike | None, bins=10, **kwargs) → Histogram2D

Facade function to create 2D histograms.

For implementation and parameters, see histogramdd.

See also

numpy.histogram2d, histogramdd

physt.h3(data: ArrayLike | None, bins=None, **kwargs) → 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.polar(xdata: ArrayLike, ydata: ArrayLike, *, radial_bins='numpy', radial_range: RangeTuple | None = None, phi_bins=16, phi_range: RangeTuple = (0, 6.283185307179586), dropna: bool = False, weights: ArrayLike | None = None, transformed: bool = False, **kwargs) → PolarHistogram

Facade construction function for the PolarHistogram.

physt.radial(xdata: ArrayLike, ydata: ArrayLike | None = None, zdata: ArrayLike | None = None, *, bins='numpy', range: RangeTuple | None = None, dropna: bool = False, weights: ArrayLike | None = None, transformed: bool = False, **kwargs) → RadialHistogram

Facade function to create a radial histogram.

physt.spherical(data: ArrayLike, *, radial_bins='numpy', theta_bins=16, phi_bins=16, dropna: bool = True, transformed: bool = False, theta_range: RangeTuple = (0, 3.141592653589793), phi_range: RangeTuple = (0, 6.283185307179586), radial_range: RangeTuple | None = None, weights=None, **kwargs) → SphericalHistogram

Facade function to create a spherical histogram.

physt.spherical_surface(data: ArrayLike, *, theta_bins=16, phi_bins=16, transformed: bool = False, radius: float | None = None, dropna: bool = False, weights: ArrayLike | None = None, theta_range: RangeTuple = (0, 3.141592653589793), phi_range: RangeTuple = (0, 6.283185307179586), **kwargs) → SphericalSurfaceHistogram

Facade construction function for the SphericalSurfaceHistogram.