artemis.io.protobuf

Google’s protocol buffer I/O support.

Submodules

• artemis.io.protobuf.artemis_pb2
• artemis.io.protobuf.configuration_pb2
• artemis.io.protobuf.cronus_pb2
• artemis.io.protobuf.histogram_pb2
• artemis.io.protobuf.menu_pb2
• artemis.io.protobuf.simutable_pb2
• artemis.io.protobuf.table_pb2
• artemis.io.protobuf.tdigest_pb2

Package Contents

artemis.io.protobuf.__version__ = 0.4.6

artemis.io.protobuf.find_subclass(base: type, name: str) → type

Find a named subclass of a base class.

Uses only the class name without namespace.

class artemis.io.protobuf.HistogramBase(binnings, frequencies=None, errors2=None, **kwargs)

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

Schema for binning(s)

Type

Iterable[BinningBase]

_frequencies

Bin contents

Type

array_like

_errors2

Square errors associated with the bin contents

Type

array_like

_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.

(TODO

Type

Fix this?)

See also

histogram1d, histogram_nd, special

dtype

property meta_data(self)

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.

Returns

Return type

dict

property name(self)

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

property title(self)

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

If not specified, defaults to name.

property axis_names(self)

Names of axes (stored in meta-data).

_get_axis(self, name_or_index: AxisIdentifier)

Get a zero-based index of an axis and check its existence.

property shape(self)

Shape of histogram’s data.

Returns

Return type

One-element tuple with the number of bins along each axis.

property ndim(self)

Dimensionality of histogram’s data.

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

_get_dtype(self)

Data type of the bin contents.

Returns

Return type

np.dtype

classmethod _eval_dtype(cls, value)

Convert dtype into canonical form, check its applicability and return info.

Parameters

value (np.dtype or something convertible to it.) –

Returns

• value (np.dtype)

• type_info – Information about the dtype

set_dtype(self, value, check: bool = True)

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 (bool) – If True (default), all values are checked against the limits

_coerce_dtype(self, other_dtype)

Possibly change the bin content type to allow correct operations with other operand.

Parameters

other_dtype (np.dtype or type) –

property bin_count(self)

Total number of bins.

property frequencies(self)

Frequencies (values, contents) of the histogram bins.

property densities(self)

Frequencies normalized by bin sizes.

Useful when bins are not of the same size.

normalize(self, inplace: bool = False, percent: bool = False)

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

HistogramBase

Return type

either modified copy or self

See also

densities(), HistogramND.partial_normalize()

property errors2(self)

Squares of the bin errors.

property errors(self)

Bin errors.

property total(self)

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

property missed(self)

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

Returns

Return type

float

is_adaptive(self)

Whether the binning can be changed with operations.

set_adaptive(self, value: bool = True)

Change the histogram binning to (non)adaptive.

This requires binning in all dimensions to allow this.

property adaptive(self)

_change_binning(self, new_binning, bin_map: Iterable[Tuple[int, int]], axis: int = 0)

Set new binnning and update the bin contents according to a map.

Fills frequencies and errors with 0. It’s the caller’s responsibility to provide correct binning and map.

Parameters

• new_binning (physt.binnings.BinningBase) –

• bin_map (Iterable[tuple]) – tuples contain bin indices (old, new)

• axis (int) – What axis does the binning describe(0..ndim-1)

merge_bins(self, amount: Optional[int] = None, *, min_frequency: Optional[float] = None, axis: Optional[AxisIdentifier] = None, inplace: bool = False)

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 (int or None) – On which axis to do this (None => all)

• inplace (Whether to modify this histogram or return a new one) –

_reshape_data(self, new_size, bin_map, axis=0)

Reshape data to match new binning schema.

Fills frequencies and errors with 0.

Parameters

• new_size (int) –

• bin_map (Iterable[(old, new)] or int or None) – If None, we can keep the data unchanged. If int, it is offset by which to shift the data (can be 0) If iterable, pairs specify which old bin should go into which new bin

• axis (int) – On which axis to apply

_apply_bin_map(self, old_frequencies, new_frequencies, old_errors2, new_errors2, bin_map, axis=0)

Fill new data arrays using a map.

Parameters

• old_frequencies (np.ndarray) – Source of frequencies data

• new_frequencies (np.ndarray) – Target of frequencies data

• old_errors2 (np.ndarray) – Source of errors data

• new_errors2 (np.ndarray) – Target of errors data

• bin_map (Iterable[(old, new)] or int or None) – As in _reshape_data

• axis (int) – On which axis to apply

See also

HistogramBase._reshape_data()

has_same_bins(self, other: HistogramBase)

Whether two histograms share the same binning.

copy(self, include_frequencies: bool = True)

Copy the histogram.

Parameters

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

abstract fill(self, value, weight=1, **kwargs)

Add a value.

Abstract method - to be implemented in daughter classes.

Parameters

• value – Value to be added. Can be scalar or array depending on the histogram type.

• weight (Optional) – Weight of the value

Note

May change the dtype if weight is set

fill_n(self, values, weights=None, **kwargs)

Add more values at once.

This (default) implementation uses a simple loop to add values using fill method. Actually, it is not used in neither Histogram1D, nor HistogramND.

Parameters

• values (Iterable) – Values to add

• weights (Optional[Iterable]) – Optional values to assign to each value

Note

This method should be overloaded with a more efficient one.

May change the dtype if weight is set.

property plot(self)

to_dict(self)

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.

_update_dict(self, a_dict: dict)

Update the dictionary for export.

Override if you want to customize the process.

Parameters

a_dict (Dictionary exported by the default implementation of to_dict) –

classmethod _kwargs_from_dict(cls, a_dict: dict)

Modify __init__ arguments from an external dictionary.

Template method for from dict. Override if necessary (like it’s done in Histogram1D).

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

Create an instance from a dictionary.

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

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

Convert to JSON representation.

Parameters

path (Where to write the JSON.) –

Returns

Return type

The JSON representation.

__repr__(self)

__add__(self, other)

__radd__(self, other)

__iadd__(self, other)

__sub__(self, other)

__isub__(self, other)

__mul__(self, other)

__imul__(self, other)

__rmul__(self, other)

__truediv__(self, other)

__itruediv__(self, other)

__lshift__(self, value)

Convenience alias for fill.

Because of the limit to argument count, weight is not supported.

classmethod _merge_meta_data(cls, first: HistogramBase, second: HistogramBase)

Merge meta data of two histograms leaving only the equal values.

(Used in addition and subtraction)

__array__(self)

Convert to numpy array.

Returns

Return type

The array of frequencies

See also

frequencies()

artemis.io.protobuf.Histogram

artemis.io.protobuf.Meta

artemis.io.protobuf.HistogramCollection

artemis.io.protobuf.SIMPLE_CONVERSION_FIELDS = ['histogram_type', 'dtype']

artemis.io.protobuf.SIMPLE_META_KEYS = ['name', 'title']

artemis.io.protobuf.CURRENT_VERSION

artemis.io.protobuf.COMPATIBLE_VERSION = 0.3.42

exception artemis.io.protobuf.VersionError

Bases: Exception

artemis.io.protobuf.create_from_dict(data: dict, format_name: str, check_version: bool = True) → Union[HistogramBase, HistogramCollection]

Once dict from source data is created, turn this into histogram. :param data: Parsed JSON-like tree. :type data: dict

Returns

histogram – A histogram (of any dimensionality)

Return type

HistogramBase

artemis.io.protobuf.require_compatible_version(compatible_version, word='File')

Check that compatible version of input data is not too new.

artemis.io.protobuf.write(histogram)

Convert a histogram to a protobuf message.

Note: Currently, all binnings are converted to

static form. When you load the histogram again, you will lose any related behaviour.

Note: A histogram collection is also planned.

Parameters

histogram (HistogramBase | list | dict) – Any histogram

Returns

message – A protocol buffer message

Return type

google.protobuf.message.Message

artemis.io.protobuf.read(message)

Convert a parsed protobuf message into a histogram.

artemis.io.protobuf.write_many(histogram_collection)

artemis.io.protobuf.read_many(message)

artemis.io.protobuf._binning_to_dict(binning_message)

artemis.io.protobuf._dict_from_v0342(message)