spine.utils.particles

Particle truth information post-processors.

They add/correct information stored in LArCV particles.

Functions

get_coords(position)

Gets the coordinates of a larcv.Vertex object.

get_group_primary_ids(particles[, valid_mask])

Gets the group primary status of particle fragments.

get_inter_primary_ids(particles[, valid_mask])

Gets the interaction primary ID for each particle.

get_interaction_ids(particles[, valid_mask])

Gets the interaction ID of each particle.

get_nu_ids(particles, group_ids, interaction_ids)

Gets the neutrino-like ID of each partcile

get_particle_ids(particles[, valid_mask])

Gets a particle species ID (PID) for each particle.

get_valid_mask(particles)

Gets a mask corresponding to particles with valid labels.

process_particle_event(particle_event[, ...])

Corrects/fetches attributes for a larcv.EventParticle object.

process_particles(particles, particle_event)

Process Particle object list to add/correct attributes in place.
spine.utils.particles.process_particles(particles, particle_event, particle_mpv_event=None, neutrino_event=None)[source]

Process Particle object list to add/correct attributes in place.

Does the following: - Checks that the group ID and parent ID are valid, assign -1 if not - Checks that the ancestor track ID is valid, assign -1 if not - Adds interaction ID information if it is not provided - Adds the true neutrino ID this particle came from - Adds a simplified enumerated particle species ID - Adds a flag as to whether a particle is a primary within its interaction - Adds a flag as to whether a particle is a primary within its group

Notes

Generic (v04) files may have invalid parent IDs, interaction IDs (INVAL_IDX) or ancestor track IDs (INVAL_TID). ICARUS and SBND files may have invalid parent IDs, interaction IDs (INVAL_ID) or ancestor track IDs (INVAL_TID). DUNE-ND and 2x2 files may have invalid group IDs (INVAL_ID).

Parameters:

  • particles (List[Particle]) –

    1. List of true particle instances

  • particle_event (larcv.EventParticle) –

    1. List of true particle instances

  • particle_mpv_event (larcv.EventParticle, optional) –

    1. List of true MPV particle instances

  • neutrino_event (larcv.EventNeutrino, optional) –

    1. List of true neutrino instances

spine.utils.particles.process_particle_event(particle_event, particle_mpv_event=None, neutrino_event=None)[source]

Corrects/fetches attributes for a larcv.EventParticle object.

Does the following: - Checks that the group ID and parent ID are valid, assign -1 if not - Checks that the ancestor track ID is valid, assign -1 if not - Builds the interaction ID information if it is not provided - Gets the true neutrino ID this particle came from - Gets a simplified enumerated particle species ID - Gets a flag as to whether a particle is a primary within its interaction - Gets a flag as to whether a particle is a primary within its group

Notes

Generic (v04) files may have invalid parent IDs, interaction IDs (INVAL_IDX) or ancestor track IDs (INVAL_TID). ICARUS and SBND files may have invalid parent IDs, interaction IDs (INVAL_ID) or ancestor track IDs (INVAL_TID). DUNE-ND and 2x2 files may have invalid group IDs (INVAL_ID).

Parameters:

  • particle_event (larcv.EventParticle) –

    1. List of true particle instances

  • particle_mpv_event (larcv.EventParticle, optional) –

    1. List of true MPV particle instances

  • neutrino_event (larcv.EventNeutrino, optional) –

    1. List of true neutrino instances

Returns:

  • group_ids (np.ndarray) –

    1. List of group IDs, one per true particle instance

  • parent_ids (np.ndarray) –

    1. List of parent IDs, one per true particle instance

  • ancestor_ids (np.ndarray) –

    1. List of ancestor IDs, one per true particle instance

  • interaction_ids (np.ndarray) –

    1. List of interaction IDs, one per true particle instance

  • nu_ids (np.ndarray) –

    1. List of neutrino IDs, one per true particle instance

  • group_primary_ids (np.ndarray) –

    1. List of particle group primary IDs, one per true particle instance

  • inter_primary_ids (np.ndarray) –

    1. List of particle primary IDs, one per true particle instance

  • pids (np.ndarray) –

    1. List of particle IDs, one per true particle instance

spine.utils.particles.get_valid_mask(particles)[source]

Gets a mask corresponding to particles with valid labels.

This function checks that the particle labels have been filled properly at the Supera level. It checks that the ancestor track ID of each particle is not an invalid number and that the ancestor creation process is filled.

Parameters:

  • particles (List[larcv.Particle]) –

    1. List of true particle instances

  • Results

  • -------

  • np.ndarray –

    1. Boolean list of validity, one per true particle instance

spine.utils.particles.get_interaction_ids(particles, valid_mask=None)[source]

Gets the interaction ID of each particle.

If the interaction_id attribute of the Particle class is filled, it simply uses that quantity.

Otherwise, it leverages shared ancestor position as a basis for interaction building and sets the interaction ID to -1 for particles with invalid ancestor track IDs.

Parameters:

  • particles (List[larcv.Particle]) –

    1. List of true particle instances

  • valid_mask (np.ndarray, optional) –

    1. Particle label validity mask

  • Results

  • -------

  • np.ndarray –

    1. List of interaction IDs, one per true particle instance

spine.utils.particles.get_nu_ids(particles, group_ids, interaction_ids, particles_mpv=None, neutrinos=None)[source]

Gets the neutrino-like ID of each partcile

Convention: -1 for non-neutrinos, neutrino index for others

If a list of multi-particle vertex (MPV) particles or neutrinos is provided, that information is leveraged to identify which interactions are neutrino-like and which are not.

If particles_mpv and neutrinos are not specified, it assumes that only neutrino-like interactions have more than one true primary particle in a single interaction.

Parameters:

  • particles (List[larcv.Particle]) –

    1. List of true particle instances

  • group_ids (np.ndarray) –

    1. List of group IDs, one per true particle instance

  • interaction_ids (np.ndarray) –

    1. Array of interaction ID values, one per true particle instance

  • particles_mpv (List[larcv.Particle], optional) –

    1. List of true MPV particle instances

  • neutrinos (list(larcv.Neutrino), optional) –

    1. List of true neutrino instances

  • Results

  • -------

  • np.ndarray –

    1. List of neutrino IDs, one per true particle instance

spine.utils.particles.get_group_primary_ids(particles, valid_mask=None)[source]

Gets the group primary status of particle fragments.

This could be handled somewhere else (e.g. Supera).

Parameters:

  • particles (List[larcv.Particle]) –

    1. List of true particle instances

  • valid_mask (np.ndarray, optional) –

    1. Particle label validity mask

  • Results

  • -------

  • np.ndarray –

    1. List of particle group primary IDs, one per true particle instance

spine.utils.particles.get_inter_primary_ids(particles, valid_mask=None)[source]

Gets the interaction primary ID for each particle.

Parameters:

  • particles (List[larcv.Particle]) –

    1. List of true particle instances

  • valid_mask (np.ndarray, optional) –

    1. Particle label validity mask

  • Results

  • -------

  • np.ndarray –

    1. List of particle primary IDs, one per true particle instance

spine.utils.particles.get_particle_ids(particles, valid_mask=None)[source]

Gets a particle species ID (PID) for each particle.

All shower daughters are labeled the same as their primary so that an electron primary is not overruled by its photon daughters in a voxel-wise majority vote. That special case is handled downstream with the high-purity flag. Particles that are not in the target list are labeled -1.

Parameters:

  • particles (List[Particle]) –

    1. List of true particle instances

  • valid_mask (np.ndarray, optional) –

    1. Particle label validity mask

Returns:

  1. List of particle IDs, one per true particle instance

Return type:

np.ndarray

spine.utils.particles.get_coords(position)[source]

Gets the coordinates of a larcv.Vertex object.

Parameters:

position (larcv.Vertex) – Encodes the position of a point with attributes x, y, z and t

Returns:

Coordinates of the point (x, y, z)

Return type:

List[float]