Axes

class histpy.Axes(axes, labels=None, axis_scale=None, copy_axes=True)

Bases: object

Holds a list of axes.

The operator Axes[key] return a subset of these. Key can be either the index or the label. If the key is a single index, a single Axis object will be returned

Parameters:

• edges (array or list of arrays or Axis) – Definition of bin edges.

• labels (array of str equal to # of axes) – Optionally label the axes for easier indexing. Will override any existing labels on passed-in Axis objects

• axis_scale (str or array) – Bin center mode e.g. “linear” or “log”. See Axis.axis_scale. If not an array, all axes will have this mode. Will override any existing mode on passed-in Axis objects

• copy (bool) – If True (default), Axis objects that are passed in as part of the ‘axes’ parameter will be copid unless axes is an Axes object that contains them. If False, they will be used without copying. But we always copy Axis objects if __init__ may change their labels or scales, regardless of how copy is set.

copy()

Make a ‘deep’ copy of an Axes object. We assume that Axis objects held by an Axes object are not mutable outside the class and are copy-on-write within it, so we are permitted to make a shallow copy of its axis list.

property ndim

Number of axes

property shape

Tuple with length of each axis

label_to_index(key)

Map a key or list-like of keys to indices in the axis list. key may be an integer or label; labels are mapped to their corresponding integer indices.

Parameters:

key – integer, label string, list-like of same, or slice (the latter is mapped to a tuple of integers)

Returns:

integer if key is scalar; otherwise, tuple of mapping results for each element of key

set(key, new, copy=True)

Replace one Axis of a Axes object. The new Axis must have the same number of bins as the axis it replaces, and it may not have the same label as an existing Axis other than the one we are replacing.

Parameters:

• key – axis to replace (must be a SINGLE scalar index or label)

• new – an Axis object or something that can be converted to it

• copy – if True, always copy the new axis Axis; otherwise, copy only if needed.

find_bin(*values)

Return the indices of the bins that would contain the specified values.

For one-dimensional arrays, values may be a scalar (one value) or an array-like of values. For multi-dimensional arrays, a single value’s components may be passed as an array-like of scalar values or as separate scalar argument; multiple values may be passed as an array-like of arra-likes or as separate array-like arguments. Hence, for 2D Axes, the following are all acceptable:

Single value: h.find_bin(x, y) h.find_bin([x, y])

Multiple values: h.find_bin([x0, x1],[y0, y1],[z0, z1]), h.find_bin([[x0, x1],[y0, y1],[z0, z1]])

Parameters:

values (scalar or array-like) – value(s) to find If single value, may be ndim coordinates as separate arguments or a single array-like if multiple values, may be ndim array-likes of coordinates as separate arguments or a single array-like containing same

Returns:

bin indices

For 1-D, returns scalar int if input was scalar,

or ndarray of int if it was array-like

For multi-D, returns tuple of ndim ints if input

was scalars or tuple of ndim ndarrays of ints if it was array-likes

Note: value array-likes for each dimension are not required to have same shape or size.

interp_weights(*values)

Get the bins and weights to linearly interpolate between bins. The bin contents are assigned to the center of the bin.

Note

The output format changed with respect to version <2.x. Previously, the bins and weights outputs had a shape (2^ndim, ndim, N) and (2^ndim, N), respectively, while now both have shape (ndim, N). This is which is more efficient. It is left to the user to compute all neccesary bins combinations and weight products. This can be done by e.g.

bins_expanded = np.asarray(list(itertools.product(*bins)))
weights_expanded = np.prod(np.array(list(itertools.product(*weights))), axis = 1)

Parameters:

values (float or array) – Coordinates within the axes to interpolate.

Returns:

Bins and weights to use. Each is a tuple of size (ndim, N), where N is the shape of the input values. Each element of the bins and weights tuples contains an array specifying the bins (integers) and weights (floats) needed for the interpolation along that particular dimension.

Shaped (2^ndim, N). Bins is an array of tupples for multi-dimensional histograms.

expand_dims(a, axis)

Given an array a of dimension n, and a list of n axes from this Axes object, expand a to have a total of self.ndims dimensions, and move the original dimensions of a to be at the the offsets corresponding to axes. This rearrangement permits a to be broadcast against a Histogram that uses this Axes object.

Note that for expansion to be well-defined, a must have at most self.ndim dimensions, and axes must specify a target offset for every dimension of a.

Parameters:

• array-like (a --) – array to be expanded

• label_to_index() (axis -- a.ndim axes in any form accepted by) – axes of self onto which the dimensions of a will be mapped after expansion.

Returns:

expanded, reorganized version of a

broadcast(a, axis)

Expand the dimensions of array a and broadcast it so that it has the same shape as self. Preserve any padding in a that may be used for under/overflow when combining it with a Histogram with the same axes as self.

Parameters:

• a – array-like array to broadcast

• axis – a.ndim axes in any form accepted by label_to_index() axes of self onto which the dimensions of a will be mapped after expansion.

Returns:

expanded, reorganized version of a

expand_dict(axis_value, default=None)

Convert pairs of axis:value to a tuple of length ndim.

Parameters:

• axis_value (dict) – Dictionary with axis-value pairs (can be labels)

• default – Default filling value for unspecified axes

Returns:

tuple

write(axes_group)

Write the component axes of this Axes objet into an HDF5 group.

Parameters:

axes_group (HDF5 group to write to)

static open(axes_group)

Read a set of Axis objects from an HDF5 group and return as an Axes object. If an axis is a subclass (e.g., a HealpixAxis), the class name is stored as a group attribute, and we read an object of the appropriate subtype.

Parameters:

axes_group (HDF5 group object containing Axes data)

Return type:

Axes object containing all axes in the group