.rst .pdf

analysis.classes.ui module

class analysis.classes.ui.FullChainPredictor(data_blob, result, cfg, predictor_cfg={}, deghosting=False, enable_flash_matching=False, flash_matching_cfg='', opflash_keys=[])

Bases: object

User Interface for full chain inference.

Usage Example:

model = Trainer._net.module entry = 0 # batch id predictor = FullChainPredictor(model, data_blob, res, cfg) pred_seg = predictor._fit_predict_semantics(entry)

1) To avoid confusion between different quantities, the label namings under iotools.schema must be set as follows:

schema:

input_data:

• parse_sparse3d_scn

• sparse3d_pcluster

2. By default, unwrapper must be turned ON under trainval:

   trainval:

   unwrapper: unwrap_3d_mink

3) Some outputs needs to be listed under trainval.concat_result. The predictor will run through a checklist to ensure this condition

4. Does not support deghosting at the moment. (TODO)

__init__(data_blob, result, cfg, predictor_cfg={}, deghosting=False, enable_flash_matching=False, flash_matching_cfg='', opflash_keys=[])

Initialize self. See help(type(self)) for accurate signature.

__repr__()

Return repr(self).

get_flash_matches(entry, use_true_tpc_objects=False, volume=None, use_depositions_MeV=False, ADC_to_MeV=1.0, interaction_list=[])

If flash matches has not yet been computed for this volume, then it will be run as part of this function. Otherwise, flash matching results are cached in self.flash_matches per volume.

If interaction_list is specified, no caching is done.

Parameters

• entry (int) –

• use_true_tpc_objects (bool, default is False) – Whether to use true or predicted interactions.

• volume (int, default is None) –

• use_depositions_MeV (bool, default is False) – If using true interactions, whether to use true MeV depositions or reconstructed charge.

• ADC_to_MEV (double, default is 1.) – If using reconstructed interactions, this defines the conversion in OpT0Finder. OpT0Finder computes the hypothesis flash using light yield and deposited charge in MeV.

• interaction_list (list, default is []) – If specified, the interactions to match will be whittle down to this subset of interactions. Provide list of interaction ids.

Returns

Return type

list of tuple (Interaction, larcv::Flash, flashmatch::FlashMatch_t)

_run_flash_matching(entry, use_true_tpc_objects=False, volume=None, use_depositions_MeV=False, ADC_to_MeV=1.0, interaction_list=[])

Parameters

• entry (int) –

• use_true_tpc_objects (bool, default is False) – Whether to use true or predicted interactions.

• volume (int, default is None) –

_fit_predict_ppn(entry)

Method for predicting ppn predictions.

Inputs:

• entry: Batch number to retrieve example.

Returns

pandas dataframe of ppn points, with x, y, z, coordinates, Score, Type, and sample index.

Return type

• df (pd.DataFrame)

_fit_predict_semantics(entry)

Method for predicting semantic segmentation labels.

Inputs:

• entry: Batch number to retrieve example.

Returns

1D numpy integer array of predicted segmentation labels.

Return type

• labels

_fit_predict_gspice_fragments(entry)

Method for predicting fragment labels (dense clustering) using graph spice.

Inputs:

• entry: Batch number to retrieve example.

Returns

1D numpy integer array of predicted fragment labels. The labels only range over classes which were designated to be processed in GraphSPICE.

• G: networkx graph representing the current entry

• subgraph: same graph in torch_geometric.Data format.

Return type

• pred

static randomize_labels(labels)

Simple method to randomize label order (useful for plotting)

is_contained(points, threshold=30)

Parameters

• points (np.ndarray) – Shape (N, 3). Coordinates in voxel units.

• threshold (float or np.ndarray) – Distance (in voxels) from boundaries beyond which an object is contained. Can be an array if different threshold must be applied in x, y and z (shape (3,)).

Returns

Return type

bool

_fit_predict_fragments(entry)

Method for obtaining voxel-level fragment labels for full image, including labels from both GraphSPICE and DBSCAN.

“Voxel-level” means that the label tensor has the same length as the full point cloud of the current image (specified by entry #)

If a voxel is not assigned to any fragment (ex. low E depositions), we assign -1 as its fragment label.

Inputs:

• entry: Batch number to retrieve example.

Returns

1D numpy integer array of predicted fragment labels.

Return type

• new_labels

_fit_predict_groups(entry)

Method for obtaining voxel-level group labels.

If a voxel does not belong to any particle (ex. low E depositions), we assign -1 as its group (particle) label.

Inputs:

• entry: Batch number to retrieve example.

Returns

1D numpy integer array of predicted group labels.

Return type

• labels

_fit_predict_interaction_labels(entry)

Method for obtaining voxel-level interaction labels for full image.

If a voxel does not belong to any interaction (ex. low E depositions), we assign -1 as its interaction (particle) label.

Inputs:

• entry: Batch number to retrieve example.

Returns

1D numpy integer array of predicted interaction labels.

Return type

• new_labels

_fit_predict_pids(entry)

Method for obtaining voxel-level particle type (photon, electron, muon, …) labels for full image.

If a voxel does not belong to any particle (ex. low E depositions), we assign -1 as its particle type label.

Inputs:

• entry: Batch number to retrieve example.

Returns

1D numpy integer array of predicted particle type labels.

Return type

• labels

_fit_predict_vertex_info(entry, inter_idx)

Method for obtaining interaction vertex information given entry number and interaction ID number.

Inputs:

• entry: Batch number to retrieve example.

• inter_idx: Interaction ID number.

If the interaction specified by <inter_idx> does not exist in the sample numbered by <entry>, function will raise a ValueError.

Returns

(x,y,z) coordinate of predicted vertex

Return type

• vertex_info

_get_entries(entry, volume)

Make a list of actual entries in the batch ids. This accounts for potential virtual batch ids in case we used volume boundaries to process several volumes separately.

Parameters

• entry (int) – Which entry of the original dataset you want to access.

• volume (int or None) – Which volume you want to access. None means all of them.

Returns

List of integers = actual batch ids in the tensors (potentially virtual batch ids).

Return type

list

_check_volume(volume)

Basic sanity check that the volume given makes sense given the config.

Parameters

volume (int or None) –

Returns

Return type

Nothing

_translate(voxels, volume)

Go from 1-volume-only back to full volume coordinates

Parameters

• voxels (np.ndarray) – Shape (N, 3)

• volume (int) –

Returns

Shape (N, 3)

Return type

np.ndarray

_untranslate(voxels, volume)

Go from full volume to 1-volume-only coordinates

Parameters

• voxels (np.ndarray) – Shape (N, 3)

• volume (int) –

Returns

Shape (N, 3)

Return type

np.ndarray

get_fragments(entry, only_primaries=False, min_particle_voxel_count=- 1, attaching_threshold=2, semantic_type=None, verbose=False, true_id=False, volume=None) → List[analysis.classes.Particle.Particle]

Method for retriving fragment list for given batch index.

The output fragments will have its ppn candidates attached as attributes in the form of pandas dataframes (same as _fit_predict_ppn)

Method also performs startpoint prediction for shower fragments.

Parameters

• entry (int) – Batch number to retrieve example.

• only_primaries (bool, default False) –

• min_particle_voxel_count (int, default -1) –

• attaching_threshold (float, default 2) – threshold distance to attach ppn point to particle.

• semantic_type (int, default None) – If True, only ppn candiates with the same predicted semantic type will be matched to its corresponding particle.

• verbose (bool, default False) –

• true_id (bool, default False) –

• volume (int, default None) –

Returns

List of <Particle> instances (see Particle class definition).

Return type

list

get_particles(entry, only_primaries=True, min_particle_voxel_count=- 1, attaching_threshold=2, volume=None) → List[analysis.classes.Particle.Particle]

Method for retriving particle list for given batch index.

The output particles will have its ppn candidates attached as attributes in the form of pandas dataframes (same as _fit_predict_ppn)

Method also performs endpoint prediction for tracks and startpoint prediction for showers.

1) If a track has no or only one ppn candidate, the endpoints will be calculated by selecting two voxels that have the largest separation distance. Otherwise, the two ppn candidates with the largest separation from the particle coordinate centroid will be selected.

2) If a shower has no ppn candidates, <get_shower_startpoint> will raise an Exception. Otherwise it selects the ppn candidate with the closest Hausdorff distance to the particle point cloud (smallest point-to-set distance)

Note

Particle id is unique only within volume.

Parameters

• entry (int) – Batch number to retrieve example.

• only_primaries (bool, default True) – If set to True, only retrieve predicted primaries.

• min_particle_voxel_count (int, default -1) –

• attaching_threshold (int, default 2) –

• volume (int, default None) –

Returns

List of <Particle> instances (see Particle class definition).

Return type

list

get_interactions(entry, drop_nonprimary_particles=True, volume=None, compute_vertex=True) → List[analysis.classes.Interaction.Interaction]

Method for retriving interaction list for given batch index.

The output particles will have its constituent particles attached as attributes as List[Particle].

Method also performs vertex prediction for each interaction.

Note

Interaction ids are only unique within a volume.

Parameters

• entry (int) – Batch number to retrieve example.

• drop_nonprimary_particles (bool (optional)) – If True, all non-primary particles will not be included in the output interactions’ .particle attribute.

• volume (int) –

• compute_vertex (bool, default True) –

• Returns –

  • out: List of <Interaction> instances (see particle.Interaction).

fit_predict_labels(entry, volume=None)

Predict all labels of a given batch index <entry>.

We define <labels> to be 1d tensors that annotate voxels.

fit_predict(**kwargs)

Predict all samples in a given batch contained in <data_blob>.

After calling fit_predict, the prediction information can be accessed as follows:

• self._labels[entry]: labels dict (see fit_predict_labels) for

batch id <entry>.

• self._particles[entry]: list of particles for batch id <entry>.

• self._interactions[entry]: list of interactions for batch id <entry>.

__dict__ = mappingproxy({'__module__': 'analysis.classes.ui', '__doc__': '\n    User Interface for full chain inference.\n\n    Usage Example:\n\n        model = Trainer._net.module\n        entry = 0   # batch id\n        predictor = FullChainPredictor(model, data_blob, res, cfg)\n        pred_seg = predictor._fit_predict_semantics(entry)\n\n    Instructions\n    -----------------------------------------------------------------------\n\n    1) To avoid confusion between different quantities, the label namings under\n    iotools.schema must be set as follows:\n\n        schema:\n            input_data:\n                - parse_sparse3d_scn\n                - sparse3d_pcluster\n\n    2) By default, unwrapper must be turned ON under trainval:\n\n        trainval:\n            unwrapper: unwrap_3d_mink\n\n    3) Some outputs needs to be listed under trainval.concat_result.\n    The predictor will run through a checklist to ensure this condition\n\n    4) Does not support deghosting at the moment. (TODO)\n    ', '__init__': <function FullChainPredictor.__init__>, '__repr__': <function FullChainPredictor.__repr__>, 'get_flash_matches': <function FullChainPredictor.get_flash_matches>, '_run_flash_matching': <function FullChainPredictor._run_flash_matching>, '_fit_predict_ppn': <function FullChainPredictor._fit_predict_ppn>, '_fit_predict_semantics': <function FullChainPredictor._fit_predict_semantics>, '_fit_predict_gspice_fragments': <function FullChainPredictor._fit_predict_gspice_fragments>, 'randomize_labels': <staticmethod object>, 'is_contained': <function FullChainPredictor.is_contained>, '_fit_predict_fragments': <function FullChainPredictor._fit_predict_fragments>, '_fit_predict_groups': <function FullChainPredictor._fit_predict_groups>, '_fit_predict_interaction_labels': <function FullChainPredictor._fit_predict_interaction_labels>, '_fit_predict_pids': <function FullChainPredictor._fit_predict_pids>, '_fit_predict_vertex_info': <function FullChainPredictor._fit_predict_vertex_info>, '_get_entries': <function FullChainPredictor._get_entries>, '_check_volume': <function FullChainPredictor._check_volume>, '_translate': <function FullChainPredictor._translate>, '_untranslate': <function FullChainPredictor._untranslate>, 'get_fragments': <function FullChainPredictor.get_fragments>, 'get_particles': <function FullChainPredictor.get_particles>, 'get_interactions': <function FullChainPredictor.get_interactions>, 'fit_predict_labels': <function FullChainPredictor.fit_predict_labels>, 'fit_predict': <function FullChainPredictor.fit_predict>, '__dict__': <attribute '__dict__' of 'FullChainPredictor' objects>, '__weakref__': <attribute '__weakref__' of 'FullChainPredictor' objects>, '__annotations__': {}})

__module__ = 'analysis.classes.ui'

__weakref__

list of weak references to the object (if defined)

class analysis.classes.ui.FullChainEvaluator(data_blob, result, cfg, processor_cfg={}, **kwargs)

Bases: analysis.classes.ui.FullChainPredictor

Helper class for full chain prediction and evaluation.

Usage:

model = Trainer._net.module entry = 0 # batch id predictor = FullChainEvaluator(model, data_blob, res, cfg) pred_seg = predictor.get_true_label(entry, mode=’segmentation’)

To avoid confusion between different quantities, the label namings under iotools.schema must be set as follows:

schema:

input_data:

• parse_sparse3d_scn

• sparse3d_pcluster

segment_label:

• parse_sparse3d_scn

• sparse3d_pcluster_semantics

cluster_label:

• parse_cluster3d_clean_full

#- parse_cluster3d_full - cluster3d_pcluster - particle_pcluster #- particle_mpv - sparse3d_pcluster_semantics

particles_label:

• parse_particle_points_with_tagging

• sparse3d_pcluster

• particle_corrected

kinematics_label:

• parse_cluster3d_kinematics_clean

• cluster3d_pcluster

• particle_corrected

#- particle_mpv - sparse3d_pcluster_semantics

particle_graph:

• parse_particle_graph_corrected

• particle_corrected

• cluster3d_pcluster

particles_asis:

• parse_particles

• particle_pcluster

• cluster3d_pcluster

The FullChainEvaluator share the same methods as FullChainPredictor, with additional methods to retrieve ground truth information for each abstraction level.

LABEL_TO_COLUMN = {'charge': 4, 'fragment': 5, 'group': 6, 'interaction': 7, 'nu': 8, 'pdg': 9, 'segment': -1}

__init__(data_blob, result, cfg, processor_cfg={}, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

get_true_label(entry, name, schema='cluster_label', volume=None)

Retrieve tensor in data blob, labelled with schema.

Parameters

• entry (int) –

• name (str) – Must be a predefined name within [‘segment’, ‘fragment’, ‘group’, ‘interaction’, ‘pdg’, ‘nu’, ‘charge’].

• schema (str) – Key for dataset schema to retrieve the info from.

• volume (int, default None) –

Returns

Return type

np.array

get_predicted_label(entry, name, volume=None)

Returns predicted quantities to label a plot.

Parameters

• entry (int) –

• name (str) – Must be a predefined name within [‘segment’, ‘fragment’, ‘group’, ‘interaction’, ‘pdg’, ‘nu’].

• volume (int, default None) –

Returns

Return type

np.array

get_true_fragments(entry, verbose=False, volume=None) → List[analysis.classes.TruthParticleFragment.TruthParticleFragment]

Get list of <TruthParticleFragment> instances for given <entry> batch id.

get_true_particles(entry, only_primaries=True, verbose=False, volume=None) → List[analysis.classes.TruthParticle.TruthParticle]

Get list of <TruthParticle> instances for given <entry> batch id.

The method will return particles only if its id number appears in the group_id column of cluster_label.

Each TruthParticle will contain the following information (attributes):

points: N x 3 coordinate array for particle’s full image. id: group_id semantic_type: true semantic type interaction_id: true interaction id pid: PDG type (photons: 0, electrons: 1, …) fragments: list of integers corresponding to constituent fragment

id number

p: true momentum vector

__module__ = 'analysis.classes.ui'

get_true_interactions(entry, drop_nonprimary_particles=True, min_particle_voxel_count=- 1, volume=None, compute_vertex=True) → List[analysis.classes.Interaction.Interaction]

get_true_vertices(entry, volume=None)

Parameters

• entry (int) –

• volume (int, default None) –

Returns

Keys are true interactions ids, values are np.array of shape (N, 3) with true vertices coordinates.

Return type

dict

match_particles(entry, only_primaries=False, mode='pred_to_true', volume=None, **kwargs)

Returns (<Particle>, None) if no match was found

Parameters

• entry (int) –

• only_primaries (bool, default False) –

• mode (str, default 'pred_to_true') – Must be either ‘pred_to_true’ or ‘true_to_pred’

• volume (int, default None) –

match_interactions(entry, mode='pred_to_true', drop_nonprimary_particles=True, match_particles=True, return_counts=False, volume=None, compute_vertex=True, **kwargs)

Parameters

• entry (int) –

• mode (str, default 'pred_to_true') – Must be either ‘pred_to_true’ or ‘true_to_pred’.

• drop_nonprimary_particles (bool, default True) –

• match_particles (bool, default True) –

• return_counts (bool, default False) –

• volume (int, default None) –

Returns

List of tuples, indicating the matched interactions.

Return type

List[Tuple[Interaction, Interaction]]

analysis.classes.particle module analysis.decorator module