Containers

Simulations

Hit

class bctools.containers.Hit(detector, position, time, energy)

Bases: object

Single interaction with a SiPM

Attributes:

• time (float) – Time of the hits

• detector (str) – Detector ID

• energy (float) – Deposited energy

SimEvent

class bctools.containers.SimEvent(particle, direction, energy, time, hits=[])

Bases: object

Simulation event, with MC truth and possibly some triggered hits

Parameters:

• particle (int) – Incoming particle type ID (see Cosima manual)

• direction (list of float) – [x,y,z] direction of incoming particle

• energy (float) – kinetic energy of incoming partigle

• time (float) – Time of the event. Hit times are relative to this

• hits (list of Hit) – Triggered hits.

Attributes:

• particle (int) – Incoming particle type ID (see Cosima manual)

• direction (list of float) – [x,y,z] direction of incoming particle

• energy (float) – kinetic energy of incoming partigle

• time (float) – Time of the event. Hit times are relative to this

• hits (list of Hit) – Triggered hits.

add_hit(hit)

Add a hit to the event

Parameters:

hit (Hit) – triggered hit (detector, time and energy)

is_fully_defined()

Returns True if no attribute is None

Returns:

bool

Detector

Detector

class bctools.containers.Detector(config)

Bases: object

Contains the detector configuration

Parameters:

config (Configurator) – Configurator with detector characteristics

Attributes:

• energy_channel_edges (array) – Definition of energy channels

• detectors (list) – Detector IDs

property detectors

Detector list

property max_energy

Upper bound of last energy channepl

property min_energy

Lower bound of first energy channel

Histogram

Histogram

class bctools.containers.Histogram(edges, contents=None, sumw2=None, labels=None, scale=None)

Bases: object

This is a wrapper of a numpy array with axes and a fill method.

Like an array, the histogram can have an arbitrary number of dimensions.

Standard numpy array indexing is supported to get the contents –i.e. h[:], h[4], h[[1,3,4]], h[:,5:50:2]], etc.–. However, the meaning of the -1 index is different. Instead of counting from the end, -1 corresponds to the underflow bin. Similarly, an index equal to the number of bins corresponds to the overflow bin.

You can however give relative position with respect to h.NBINS –e.g. h[0:h.NBINS] result in all regular bins, h[-1:h.NBINS+1] includes also the underflow/overflow bins and h[h.NBINS] gives you the contents of the overflow bin.

You can also use an Ellipsis object (…) at the end to specify that the contents from the rest of the dimension are to have the under and overflow bins included. e.g. for a 3D histogram h[1,-1:h.NBINS+1,-1:h.NBINS+1] = h[1,...]. h[:] returns all contents without under/overflow bins and h[…] returns everything, including those special bins.

Additionally, you can specify with a dictionary the indices for specific axes, with all the rest being the default. e.g. h[:,:,1:,:,6] <==> h[{2:slice(1,None), 4:6}]. If you also use the axes id if you labeled them, e.g. h[{'x':slice(0,h.NBINS+1)}]

If sumw2 is not None, then the histogram will keep track of the sum of the weights squared –i.e. you better use this if you are using weighted data and are concern about error bars–

You can use the *= operator to weight by a number or an array of weights with the shape of h.nbins+2 (to include under/overflow bins).

The operators +, -, += and -= are available. Both operands need to be histograms. An exception will be raised if the axes are not the same. Note that h += h0 is more efficient than h = h + h0 since latter involves the instantiation of a new histogram.

Parameters:

• edges (Axes or array) – Definition of bin edges, Anything that can be processes by Axes. Lower edge value is included in the bin, upper edge value is excluded.

• contents (array) – Initialization of histogram contents. Might or might not include under/overflow bins. Initialize to 0 by default.

• sumw2 (None, bool or array) – If True, it will keep track of the sum of the weights squared. You can also initialize them with an array

• labels (array of str) – Optionally label the axes for easier indexing

• scale (str or array) – Bin center mode e.g. “linear” or “log”. See Axis.scale(). Not to be confused with the Histogram`'s `method ``scale(), which scales the bin contents, rather than defining what the scale mode of an axis is.

Attributes:

sumw2 (Histogram) – An auxiliary histogram whose contents are the sum of the square of the weight that were used to fill this histogram

property axes

Underlaying axes object

property axis

Equivalent to self.axes[0], but fails if ndim > 1

clear()

Set all counts to 0

classmethod concatenate(edges, histograms, label=None)

Generate a Histogram from a list os histograms. The axes of all input histograms must be equal, and the new histogram will have one more dimension than the input. The new axis has index 0.

Parameters:

• edges (Axes or array) – Definition of bin edges of the new dimension

• histograms (list of Histogram) – List of histogram to fill contents. Might or might not include under/overflow bins.

• labels (str) – Label the new dimension

Returns:

Histogram

fill(*values, weight=1)

And an entry to the histogram. Can be weighted.

Follow same convention as find_bin()

Parameters:

• values (float or array) – Value of entry

• weight (float) – Value weight in histogram.

Note

Note that weight needs to be specified explicitely by key, otherwise it will be considered a value an a IndexError will be thrown.

find_bin(*values, axis=None)

Return one or more indices corresponding to the bin this value or set of values correspond to.

You can pass either an array, or specified the values as different arguments. i.e. h.find_bin(x,y,z) = h.find_bin([x,y,z])

Parameters:

• values (float or array) – Vaule or list of values

• axis (int or str or list) – If set, values correspond to the subset of axes listed here

Returns:

Bin index

Return type:

int or tuple

interp(*values)

Get a linearly interpolated content for a given set of values along each axes. The bin contents are assigned to the center of the bin.

Parameters:

values (float or array) – Coordinates within the axes to interpolate. Must have the same size as ndims. Input values as (1,2,3) or ([1,2,3])

Returns:

float

project(*axis)

Return a histogram consisting on a projection of the current one

Parameters:

axis (int or str or list) – axis or axes onto which the histogram will be projected –i.e. will sum up over the other dimensiones–. The axes of the new histogram will have the same order –i.e. you can transpose axes–

Returns:

Projected histogram

Return type:

Histogram

scale(weight, indices=Ellipsis, axis=None)

Scale the histogram contents.

By default, h.scale(weight) <==> h *= weight

The parameter indices can be used to specify the slice that will be multiplied by the weights. Follow the same index convention as in [].

If axis is specified, then weights and indices correspond to a single axis.

Parameters:

• weights (array-like) – Weights

• indices (int or tuple) – Bin indices

• axis (int or str) – Axis index

property shape

Tuple with number of bins along each dimensions

slice(axis, start=None, stop=None, underflow=True, overflow=True)

Return a histogram which is a slice of the current one, along a given dimension.

Follows same indexing convention as [] operator

Parameters:

• axis (int or str) – Dimension that will be sliced

• start (None or int) – Start bin (inclusive)

• stop (None or int) – Stop bin (exclusive). Must be greater than start

• underflow (bool) – If True, the contents before the start bin will be summed up and kept in the underflow bins, otherwise they’ll be discarded

• overflow (overflow) – same as underflow

Returns:

Sliced histogram

Return type:

Histogram

Axis

class bctools.containers.histogram.Axis(edges, label=None, scale=None)

Bases: object

Bin edges. Optionally labeled

Parameters:

• edges (array-like) – Bin edges

• label (str) – Label for axis. If edges is an Axis object, this will override its label

• scale (str) – Bin center mode e.g. “linear” or “log”. See scale(). If edges is an Axis object, this will override its mode

Attributes:

• edges (array-like) – Bin edges

• label (str) – Label for axis

property bounds

Start of [lower_bound, upper_bound] values for each bin.

property centers

Center of each bin.

find_bin(value)

Return the bin value corresponds to.

Returns:

Bin number. -1 for underflow, nbins for overflow

Return type:

int

interp_weights(value)

Get the two closest bins to value, together with the weights to linearly interpolate between them. The bin contents are assigned to the center of the bin.

Values in the edges beyond the center of the first/last bin will result in no interpolation.

Returns:

Bins [float, float]: Weights

Return type:

[int, int]

property lower_bounds

Lower bound of each bin

property max

Overall upper bound of histogram

property min

Overall lower bound

property nbins

Number of elements along each axis. Either an int (1D histogram) or an array

scale(mode=None)

Control what is considered the center of the bin. This affects centers() and interpolations.

Parameters:

mode (str or None) –

• linear (default): The center is the midpoint between the bin edges

• symmetric: same as linear, except for the first center, which will correspond to the lower edge. This is, for example, useful when the histogram is filled with the absolute value of a variable.

• log: The center is the logarithmic (or geometrical) midpoint between the bin edges.

Returns:

The new mode (or current if mode is None).

Return type:

str

property upper_bounds

Upper bound of each bin

property widths

Width each bin.

Axes

class bctools.containers.histogram.Axes(edges, labels=None, scale=None)

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) – Optionally label the axes for easier indexing. Will override the labels of edges, if they are Axis objects

• scale (str or array) – Bin center mode e.g. “linear” or “log”. See Axis.scale. If not an array, all axes will have this mode.

interp_weights(*values)

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

Parameters:

values (float or array) – Coordinates within the axes to interpolate. Must have the same size as ndims. Input values as (1,2,3) or ([1,2,3]).

Returns:

Bins and weights to use. Size=2^ndim. Each bin is specified by a tuple containing ndim integers

Return type:

array of tuples of int, array of floats

key_to_index(key)

Turn a key or list of keys, either indices or labels, into indices

Parameters:

key (int or str) – Index or label

Returns:

Index

Return type:

int

property labels

Label of axes.

Returns:

Either a string or a tuple of string. None if they are not defined

property ndim

Number of axes