Observables Module

Provides functions to calculate various observables from shower data and to add them to shower data files. This can be useful for analyzing the fidelity of generative shower models or for training two-stage models (e.g. layer-wise properties first, then point clouds).

showerdata.observables.compute_threshold_mask(showers, detector_config=None)[source]

Compute a mask for the shower points based on detector thresholds.

Parameters:

  • showers (Showers) – The showers to compute the mask for.

  • detector_config (DetectorGeometry | None) – The detector configuration.

Returns:

A boolean mask indicating which points pass the thresholds.

Return type:

NDArray[bool]

showerdata.observables.calc_num_points_per_layer(showers, num_layers=-1, detector_config=None)[source]

Calculate the number of points per layer for each shower.

Parameters:

  • showers (Showers) – The showers to calculate the number of points per layer for.

  • num_layers (int) – The number of layers to consider. Defaults to -1 (infers from data).

Returns:

A 2D array of shape (num_showers, num_layers) containing the number of

points per layer for each shower.

Return type:

NDArray[intc]

showerdata.observables.calc_energy_per_layer(showers, num_layers=-1, detector_config=None)[source]

Calculate the total energy per layer for each shower.

Parameters:

showers (Showers) – The showers to calculate the total energy per layer for.

Returns:

A 2D array of shape (num_showers, num_layers) containing the total

energy per layer for each shower.

Return type:

NDArray[single]

showerdata.observables.calc_energy_per_radial_bin(showers, bin_edges=None, detector_config=None)[source]

Calculate the total energy per radial bin for each shower.

Parameters:

  • showers (Showers) – The showers to calculate the total energy per radial bin for.

  • bin_edges (ArrayLike | None) – The edges of the radial bins. If None, defaults to 200 bins from 0 to 400 mm.

Returns:

A 2D array of shape (num_showers, num_bins) containing the total energy

per radial bin for each shower.

Return type:

NDArray[single]

showerdata.observables.calc_center_of_energy(showers, detector_config=None)[source]

Calculate the center of energy for each shower.

Parameters:

showers (Showers) – The showers to calculate the center of energy for.

Returns:

A 2D array of shape (num_showers, 3) containing the center of energy

(x, y, z) for each shower.

Return type:

NDArray[single]

class showerdata.observables.ObservableInfo(key, shape, dtype, function)[source]

Bases: object

key: str
shape: tuple[int, ...]
dtype: DTypeLike
function: Callable[[Showers], ndarray]
showerdata.observables.add_observables_to_file(path, batch_size=1000, overwrite=False, detector_config=None)[source]

Calculate and add observables to an existing HDF5 file containing shower data.

Parameters:

  • path (str | PathLike[str]) – The path to the HDF5 file.

  • batch_size (int) – The number of showers to process in each batch. Defaults to 1000.

  • overwrite (bool) – Whether to overwrite existing observables. Defaults to False.

Return type:

None

showerdata.observables.save_observables_to_file(path, observables, overwrite=False)[source]

Save observables to an HDF5 file.

Parameters:

  • path (str | PathLike[str]) – The path to the HDF5 file.

  • observables (dict[str, ndarray]) – A dictionary containing the observables to save.

  • overwrite (bool) – Whether to overwrite the file if it exists. Defaults to False.

Return type:

None

showerdata.observables.read_observables_from_file(path, observables=None, start=0, stop=None)[source]

Read observables from an HDF5 file. The default observables are:

  • num_points_per_layer

  • energy_per_layer

  • energy_per_radial_bin

  • center_of_energy

  • total_energy

  • total_num_points

  • incident_energies

  • incident_pdg

  • incident_directions

  • shower_ids

Parameters:

  • file (str) – The HDF5 file to read from.

  • observables (list[str] | None) – The list of observables to read.

  • start (int) – The starting index of the showers to read. Defaults to 0.

  • stop (int | None) – The stopping index of the showers to read. If None, reads until the end. Defaults to None.

Returns:

A dictionary containing the observables.

Return type:

dict[str, ndarray]

showerdata.observables.read_point_energies(path, start=0, stop=None)[source]

Read point energies from an HDF5 file.

Parameters:

  • path (str | PathLike[str]) – The HDF5 file to read from.

  • start (int) – The starting index of the showers to read. Defaults to 0.

  • stop (int | None) – The stopping index of the showers to read. If None, reads until the end. Defaults to None.

Returns:

A 1D array containing the point energies of all showers in the

specified range.

Return type:

NDArray[single]

showerdata.observables.save(path, observables, overwrite=False)

Alias for save_observables_to_file().

Return type:

None

showerdata.observables.load(path, observables=None, start=0, stop=None)

Alias for read_observables_from_file().

Return type:

dict[str, ndarray]