artemis.externals.physt.binnings

Different binning algorithms/schemas for the histograms.

Module Contents

class artemis.externals.physt.binnings.BinningBase(bins=None, numpy_bins=None, includes_right_edge=False, adaptive=False)

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?)

adaptive_allowed = False
inconsecutive_allowed = False
__getitem__(self, index)
static from_dict(a_dict)
to_dict(self)

Dictionary representation of the binning schema.

This serves as template method, please implement _update_dict

abstract _update_dict(self, a_dict)
property includes_right_edge(self)
is_regular(self, rtol: float = 1e-05, atol: float = 1e-08)

Whether all bins have the same width.

Parameters

atol (rtol,) –

is_consecutive(self, rtol: float = 1e-05, atol: float = 1e-08)

Whether all bins are in a growing order.

Parameters

atol (rtol,) –

is_adaptive(self)

Whether the binning can be adapted to include values not currently spanned.

force_bin_existence(self, 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

abstract _force_bin_existence(self, values)
adapt(self, other: BinningBase)

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

Parameters

other (BinningBase) –

set_adaptive(self, value: bool = True)

Set/unset the adaptive property of the binning.

This is available only for some of the binning types.

_adapt(self, other)
property bins(self)

Bins in the wider format (as edge pairs)

Returns

bins – shape=(bin_count, 2)

Return type

np.ndarray

property bin_count(self)

The total number of bins.

property numpy_bins(self)

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(self)

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

property first_edge(self)

The left edge of the first bin.

property last_edge(self)

The right edge of the last bin.

as_static(self, copy: bool = True)

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

as_fixed_width(self, copy=True)

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

Parameters

copy (bool) – Ensure that we receive another object

Returns

Return type

FixedWidthBinning

abstract copy(self)

An identical, independent copy.

apply_bin_map(self, bin_map)
Parameters

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

__repr__(self)
class artemis.externals.physt.binnings.StaticBinning(bins, includes_right_edge=True, **kwargs)

Bases: artemis.externals.physt.binnings.BinningBase

inconsecutive_allowed = True
as_static(self, copy: bool = True)

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(self)
__getitem__(self, item)
_update_dict(self, a_dict)
_adapt(self, other)
__repr__(self)
class artemis.externals.physt.binnings.NumpyBinning(numpy_bins, includes_right_edge=True, **kwargs)

Bases: artemis.externals.physt.binnings.BinningBase

Binning schema working as numpy.histogram.

property numpy_bins(self)
copy(self)
_update_dict(self, a_dict: dict)
class artemis.externals.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: artemis.externals.physt.binnings.BinningBase

Binning schema with predefined bin width.

adaptive_allowed = True
__repr__(self)
is_regular(self, *args, **kwargs)
_force_bin_existence_single(self, value, includes_right_edge=None)
_force_bin_existence(self, values, includes_right_edge=None)
property first_edge(self)
property last_edge(self)
property numpy_bins(self)
property bin_count(self)
copy(self)
property bin_width(self)
_force_new_min_max(self, new_min, new_max)
_set_min_and_count(self, times_min, bin_count)
_adapt(self, other: BinningBase)
Returns

  • bin_map1 (Iterable[tuple] or None)

  • bin_map2 (Iterable[tuple] or None)

as_fixed_width(self, copy=True)
_update_dict(self, a_dict)
class artemis.externals.physt.binnings.ExponentialBinning(log_min, log_width, bin_count, includes_right_edge=True, adaptive=False, **kwargs)

Bases: artemis.externals.physt.binnings.BinningBase

Binning schema with exponentially distributed bins.

adaptive_allowed = False
is_regular(self, *args, **kwargs)
property numpy_bins(self)
copy(self)
_update_dict(self, a_dict)
artemis.externals.physt.binnings.numpy_binning(data, bins=10, range=None, *args, **kwargs) → NumpyBinning

Construct binning schema compatible with numpy.histogram

Parameters

  • data (array_like, optional) – This is optional if both bins and range are set

  • bins (int or array_like) –

  • range (Optional[tuple]) – (min, max)

  • includes_right_edge (Optional[bool]) – default: True

See also

numpy.histogram()

artemis.externals.physt.binnings.human_binning(data=None, bin_count: Optional[int] = None, *, range=None, **kwargs) → FixedWidthBinning

Construct fixed-width binning 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) –

  • range (Optional[tuple]) – (min, max)

artemis.externals.physt.binnings.quantile_binning(data=None, bins=10, *, qrange=(0.0, 1.0), **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

  • bins (sequence or Optional[int]) – Number of bins

  • qrange (Optional[tuple]) – Two floats as minimum and maximum quantile (default: 0.0, 1.0)

Returns

Return type

StaticBinning

artemis.externals.physt.binnings.static_binning(data=None, bins=None, **kwargs) → StaticBinning

Construct static binning with whatever bins.

artemis.externals.physt.binnings.integer_binning(data=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)

artemis.externals.physt.binnings.fixed_width_binning(data=None, bin_width: Union[float, int] = 1, *, range=None, includes_right_edge=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

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

Construct exponential binning schema.

Parameters

  • bin_count (Optional[int]) – Number of bins

  • range (Optional[tuple]) – (min, max)

See also

numpy.logspace()

artemis.externals.physt.binnings.calculate_bins(array, _=None, *args, **kwargs) → 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

artemis.externals.physt.binnings.calculate_bins_nd(array, bins=None, *args, **kwargs)

Find optimal binning from arguments (n-dimensional variant)

Usage similar to calculate_bins.

Returns

Return type

List[BinningBase]

artemis.externals.physt.binnings.binning_methods
artemis.externals.physt.binnings.bayesian_blocks_binning(data, range=None, **kwargs) → NumpyBinning

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

artemis.externals.physt.binnings.ideal_bin_count(data, method: str = 'default') → int

A theoretically ideal bin count.

Parameters

  • data (array_likes) – 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

artemis.externals.physt.binnings.bincount_methods = ['default', 'sturges', 'rice', 'sqrt', 'doane']
artemis.externals.physt.binnings.as_binning(obj, 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) –