Data Module

The spine.data module defines the shared data structures used across the SPINE pipeline, from detector-level input records to reconstructed and truth object hierarchies.

Data structures and containers.

This module defines all core data structures used throughout the SPINE package, from low-level detector data to high-level physics objects.

Core namespaces:

  • larcv for detector-level and generator-level input objects.

  • out for high-level reconstructed and truth objects.

  • batch for batched tensor, edge-index, and index containers.

  • list for generic list-backed containers.

Key features:

  • Shared base classes with merged docstrings and validation helpers.

  • Units metadata through the field_units interface.

  • Serialization support for I/O and analysis workflows.

  • Conditional batch helpers when PyTorch is available.

Example

from spine.data import Particle, TensorBatch

particle = Particle(id=0, pid=13, momentum=[1.2, 0.5, 2.1])
batch = TensorBatch(data_list, batch_size=32)

Overview

The canonical namespaces inside spine.data are:

  • LArCV data structures under spine.data.larcv for detector records, generator truth, and metadata imported from LArCV-style sources

  • Output data structures under spine.data.out for reconstructed and truth fragments, particles, and interactions

  • Batch data structures under spine.data.batch for tensor, edge-index, and index batching in ML workflows

  • Generic list containers under spine.data.list for lightweight container utilities

CRT, optical, trigger, run-information, and image-metadata classes are part of the LArCV-facing namespace in SPINE. They are detector or acquisition records, but they are not a separate top-level category outside spine.data.larcv.

LArCV Data Structures

These classes provide the low-level inputs and metadata that enter the reconstruction chain. They live canonically under spine.data.larcv and are re-exported from spine.data for convenience.

larcv.Particle(units, id, parent_id, ...)

Particle truth information.

larcv.Neutrino(units, id, interaction_id, ...)

Neutrino truth information.

larcv.CRTHit(units, id, plane, ts0_s, ...)

CRT hit information.

larcv.Flash(units, id, volume_id, frame, ...)

Optical flash information.

larcv.Trigger([id, type, time_s, time_ns, ...])

Trigger information.

larcv.Meta

larcv.RunInfo([run, subrun, event])

Run information related to a specific event.

Output Data Structures

These classes represent the high-level object hierarchy produced by construction and refined by post-processing. Each object family has reconstructed and truth variants with shared metadata, units, and enum-aware fields inherited from common bases.

Fragment Objects

Fragments represent clusters of energy depositions that may correspond to intermediate objects in the reconstruction hierarchy.

out.RecoFragment(is_truth, units, id, ...)

Reconstructed fragment information.

out.TruthFragment(orig_id, is_truth, ...)

Truth fragment information.

Particle Objects

Particles represent individual particles with full kinematic and identification information.

out.RecoParticle(is_truth, units, id, ...)

Reconstructed particle information.

out.TruthParticle(orig_id, is_truth, ...)

Truth particle information.

Interaction Objects

Interactions represent complete neutrino interactions with all associated particles.

out.RecoInteraction(is_truth, units, id, ...)

Reconstructed interaction information.

out.TruthInteraction(orig_id, is_truth, ...)

Truth interaction information.

Batch Data Structures

These containers support model-facing batching and unbatching for tensors, graph edges, and index collections.

batch.TensorBatch(data[, counts, ...])

Batched tensor with the necessary methods to slice it.

batch.EdgeIndexBatch(data, counts, spans, ...)

Batched edge index with the necessary methods to slice it.

batch.IndexBatch(data, spans[, counts, ...])

Batched index with the necessary methods to slice it.

Other Data Structures

Additional generic containers defined directly under spine.data.

ObjectList(object_list, default)

List with a default object used to type it when it is empty.