Variables

Functions:

analyze_layers(batch)	Analyzes the layers of a point cloud representation of particle showers, computing the peak layer, the turn-on layer, and the ratio of distances from turn-off layer to the peak layer and from the peak layer to the turn-on layer.
calc_vars(batch[, sum_multihits, ...])	Calculates specified variables for each event in a batch.
cyratio(batch)	Similar to the sphereratio function, this function computes energy fractions within a cylinder around the center of energy for each event in a batch, and returns the ratios of these energy fractions.
first_principal_components(batch)	Calculates the first principal component (PC) from a point cloud (PC).
response(batch)	Computes the energy response for each event in a batch.
sphereratio(batch)	Computes energy fractions within a sphere around the center of energy for each event in a batch, and returns the ratios of these energy fractions.

caloutils.variables.analyze_layers(batch: <Mock name='mock.Batch' id='140552768441696'>) → dict[str, <Mock name='mock.Tensor' id='140552768372112'>]

Analyzes the layers of a point cloud representation of particle showers, computing the peak layer, the turn-on layer, and the ratio of distances from turn-off layer to the peak layer and from the peak layer to the turn-on layer.

The function performs the following main steps: 1. Computes a histogram of the z coordinates (layers) of each point in the point cloud. 2. Identifies the layer with the maximum number of points (peak layer) for each shower. 3. Identifies the first (turn-on) and last (turn-off) layer that contains at least half the maximum number of points in a layer for each shower. 4. Computes the ratio of the distance from the turn-off layer to the peak layer and the distance from the peak layer to the turn-on layer.

Parameters

batchBatch

A Batch object from the PyTorch Geometric library that contains the point cloud representation of the showers.

Returns

dict

A dictionary with keys ‘peak_layer’, ‘psr’, and ‘turnon_layer’, where:

• ‘peak_layer’ corresponds to the tensor of peak layers for each shower in the batch.

• ‘psr’ corresponds to the tensor of ratios for each shower in the batch.

• ‘turnon_layer’ corresponds to the tensor of turn-on layers for each shower in the batch.

Raises

AssertionError

If the sum of the elements in each row of the histogram does not equal the difference of consecutive elements in the batch pointers.

caloutils.variables.calc_vars(batch: <Mock name='mock.Batch' id='140552768441696'>, sum_multihits: bool = True, shift_multihits: bool = False, vars: list = ['voxel', 'sphereratio', 'cyratio', 'fpc', 'showershape', 'response'])

Calculates specified variables for each event in a batch.

The function supports calculation of “sphereratio”, “cyratio”, “fpc”, “showershape”, and “response”. Calculated variables are added to the input batch object.

Parameters

batchBatch

A Batch object from the PyTorch Geometric library that contains the point cloud representation of the events.

sum_multihitsbool, optional

If True, aggregates the energies of hits in the same cell for each event. Defaults to True.

shift_multihitsbool, optional

If True, tries to shift hits that occupy the same cell to neihgboring, empty cells. Defaults to False.

varslist of str, optional

List of variables to calculate for the events in the batch. Defaults to all supported variables: [“voxel”,”sphereratio”,”cyratio”,”fpc”,”showershape”,”response”].

Returns

Batch

The input Batch object with calculated variables added.

caloutils.variables.cyratio(batch: <Mock name='mock.Batch' id='140552768441696'>) → dict[str, <Mock name='mock.Tensor' id='140552768372112'>]

Similar to the sphereratio function, this function computes energy fractions within a cylinder around the center of energy for each event in a batch, and returns the ratios of these energy fractions.

The function only considers the x and y coordinates of the points to calculate the energy fractions and the center of energy, effectively projecting the points onto the xy-plane and creating a cylindrical region.

Parameters and return values are the same as those for the sphereratio function.

caloutils.variables.first_principal_components(batch: <Mock name='mock.Batch' id='140552768441696'>) → dict[str, <Mock name='mock.Tensor' id='140552768372112'>]

Calculates the first principal component (PC) from a point cloud (PC).

Parameters

batchBatch

A Batch object from the PyTorch Geometric library that contains the point cloud representation of the events. Batch.xyz contains the 3D coordinates of hits. Batch.batch contains the indices that map which hit belongs to which event.

Returns

fpcdict

Dictionary containing the components of the first principal component and the corresponding eigenvalue for each event. The keys of the dictionary are ‘x’, ‘y’, ‘z’, and ‘eval’.

caloutils.variables.response(batch: <Mock name='mock.Batch' id='140552768441696'>) → <Mock name='mock.Tensor' id='140552768372112'>

Computes the energy response for each event in a batch. The energy response is calculated as the ratio of the total detected energy (sum of energy from all hits in an event) to the true energy of the event.

Parameters

batchBatch

A Batch object from the PyTorch Geometric library that contains the point cloud representation of the events.

Returns

torch.Tensor

A tensor of the energy response for each event in the batch.

caloutils.variables.sphereratio(batch: <Mock name='mock.Batch' id='140552768441696'>) → dict[str, <Mock name='mock.Tensor' id='140552768372112'>]

Computes energy fractions within a sphere around the center of energy for each event in a batch, and returns the ratios of these energy fractions.

The function calculates the energy fractions within two spheres (small and large) around the center of energy for each event in a batch. The centers are calculated as a weighted mean of the point coordinates, where the weights are the energies of the points.

Parameters

batchBatch

A Batch object from the PyTorch Geometric library that contains the point cloud representation of the events.

Returns

dict

A dictionary with keys ‘small’, ‘large’, and ‘ratio’, where:

• ‘small’ corresponds to the tensor of energy fractions within the smaller sphere for each event.

• ‘large’ corresponds to the tensor of energy fractions within the larger sphere for each event.

• ‘ratio’ is the ratio of ‘small’ to ‘large’ for each event.