LUCiDDataset

class LUCiDDataset(data_root, split='', transform=None, modalities=('sensor',), dataset_name='wc', output_mode='response', include_labels=True, pe_threshold=0.0, min_segments=0, max_len=-1, loop=1, test_mode=False, test_cfg=None)

Bases: Dataset

Water Cherenkov detector dataset over co-indexed LUCiD HDF5 files.

Reads PMT sensor response and/or 3D track segments from event-aligned shard families (sensor/ and/or seg/) and emits flat dicts for the pimm transform/collation pipeline. The public keys depend on output_mode for the sensor modality: "response" emits one entry per PMT with coord (3D PMT position or a 1D sensor index), energy (total PE) and time; "labels" emits sparse per-particle entries with coord, energy, segment (category) and instance (particle index); "separate" keeps the raw reader keys (pmt_coord, pmt_pe, pp_*). After collation a batch adds offset. Registered as LUCiDDataset – use as type under data.train/data.val/data.test.

Parameters:

• data_root (str) – Root directory holding seg/ and/or sensor/ subdirectories.

• split (str) – Split name used for shard discovery. Defaults to "".

• transform (list[dict]) – List of transform configs (NOT a prebuilt Compose). Defaults to None.

• modalities (tuple[str]) – Which modalities to load, any of "sensor", "seg". Defaults to ("sensor",).

• dataset_name (str) – Shard filename prefix (e.g. "wc" for wc_seg_0000.h5). Defaults to "wc".

• output_mode (str) – Sensor output contract, one of "response", "labels", "separate" (see above). Defaults to "response".

• include_labels (bool) – Whether the sensor reader loads the per-particle decomposition (needed for output_mode="labels"). Defaults to True.

• pe_threshold (float) – Minimum PE used to sparsify per-particle PE. Defaults to 0.0.

• min_segments (int) – Minimum segments per event (seg reader filter). Defaults to 0.

• max_len (int) – Cap on event count before the loop multiplier (-1 = no cap). Defaults to -1.

• loop (int) – Train-time epoch multiplier. Defaults to 1.

• test_mode (bool) – Emit voxelized/augmented test fragments and force loop = 1. Defaults to False.

• test_cfg (object) – Test config (voxelize, crop, post_transform, aug_transform); required when test_mode. Defaults to None.

Note

The dataset length is the minimum event count across the active readers (they must be co-indexed). Loader settings (batch_size, num_worker) live at the top level of the config.

Example

>>> from pimm.datasets.builder import build_dataset
>>> # data root not in this env -> shown with doctest +SKIP
>>> ds = build_dataset(dict(type="LUCiDDataset", data_root="dataset_wc",
...     modalities=("sensor",), output_mode="response",
...     transform=[]))                  
>>> sample = ds[0]                       
>>> # output_mode="response" sample keys: coord (N, 3 PMT pos, or N, 1
>>> #   sensor index), energy (N, 1 total PE), time (N, 1), name, split
>>> # output_mode="labels": coord, energy, segment (category),
>>> #   instance (particle idx), time, name, split
>>> # output_mode="separate": raw reader keys (pmt_coord, pmt_pe, pp_*)
>>> #   + name, split

get_data(idx)

Load one event and choose the public output contract by modality.

get_data_name(idx)

Return a stable shard/event name for logging and prediction files.

prepare_test_data(idx)

Build augmented and voxelized fragments for test-time inference.

prepare_train_data(idx)

Load one event and apply the train transform pipeline.