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