Using the PANDORA Reconstruction (last updated on Friday 28th November 2014)


The PANDORA event reconstruction provides a chain of pattern recognition algorithms that builds 3D proto-particles from LAr TPC 2D hits. The software has been integrated into the LBNE and LArSoft frameworks, and is separated into the following components: the underlying PANDORA package is distributed with NuSoft; the LAr-specific code lives in the larpandora repository of LArSoft; and the LBNE-specific code is committed to the LArPandora package of lbnecode. The sections below describe these components, and the reconstruction chain developed for the LBNE 35t detector. Instructions are also provided for running the code in the ART/LArSoft/MRB framework.


The reconstruction software is divided between the packages listed below.

  • PandoraPFA Software Development Kit (distributed with NuSoft): The PANDORA SDK houses the lightweight framework that runs the PANDORA pattern recognition algorithms and performs memory management operations. The SDK also supplies design-pattern algorithms and helper functions that are used in the LBNE 35t reconstruction chain.
  • LArPandoraInterface Package in LArSoft (larpandora repository): The LArPandoraInterface package contains the interface between ART/LArSoft and the PANDORA SDK. The central component is an ART Producer module that reads recob::Hit objects from the ART framework, passes them to PANDORA for pattern recognition, and then writes the reconstructed proto-particles back to the ART framework. In LArSoft, a new object called recob::PFParticle has been created to hold the reconstructed particles. A set of recob::Cluster and recob::SpacePoint objects are also written out into the ART framework, along their ART associations to the recob::PFParticles - see diagram below for the current data flow. The LArPandoraInterface package holds additional Producer and Analyzer modules that manipulate and analyse the recob::PFParticle objects.
  • LArPandoraAlgorithms Package in LArSoft (larpandora repository): This package houses all the LAr-specific tools and pattern recognition algorithms, which have been assembled using the PANDORA toolkit. Note that this package only depends on the PandoraPFA package and so can exist both inside and outside LArSoft.
  • LArPandora package in lbnecode: This package contains .fcl scripts for running the reconstruction chain within ART, along with the .xml steering script that defines which PANDORA algorithms should be run in the chain. I plan to move all the LBNE-specific code into this package (and also give the package a less generic name!)

The output of the PANDORA pattern recognition is a set of reconstructed particles. In principle, there should be one reconstructed particle for every true particle in the event. The PANDORA algorithms distinguish between track-like and shower-like particles, and also identify the parent/daughter associations between particles. This information is written out into the ART data stream.

PANDORA reconstruction chain for LBNE 35t Detector.

Starting from the disambiguated 2D recob::Hit objects, there are currently three stages of reconstruction, which are run by the following three ART Producer modules.

  • Pattern recognition (LBNE35tPandora Producer): This is the main pattern recognition module, and is run separately on the recob::Hits from the short and long drift modules. The outputs are recob::PFParticles, recob::Clusters, recob::SpacePoints and their ART associations. (Notes on these associations: each recob::PFParticle has only one cluster per TPC per view; each 3D recob::SpacePoint is associated to a 2D recob::Hit).
  • Stitching (PFParticleStitcher Producer): This combines together the reconstructed particles from the short and long drift volumes by stitching together the track-like particles across the boundary between the two volumes. It has been written generically, so that it can be extended to the LBNE Far Detector. The output of the stitching module is a new set of recob::PFParticles and new ART associations to the previous recob::SpacePoints, recob::Clusters and recob::Hits.
  • Track-building (PFParticleTrackMaker Producer): This module turns the reconstructed track-like particles into recob::Track objects, based on the parameterisation of their recob::SpacePoints. Note: this module a placeholder for a track-fitter.

The diagram below shows the current reconstruction chain for the 35t detector (Note: this chain is still under development!):

Running the reconstruction chain

In this section, I'll go through the steps for simulating and reconstructing single-particle events in the LBNE 35t detector. I'll assume some knowledge of ART, LArSoft and the MRB framework, but not very much. For more details on the underlying ART/LArSoft/MRB framework, please review these pages:

At the time of writing, the most recent version of LArSoft is v03_04_03, so I'll use this as my base release.

Step 1: Set up your working area

First, set up the LBNE software:

source /grid/fermiapp/lbne/software/

Create a new working area if you don't already have one (inserting your own directory name into the example below):

mkdir -p ${my_installation}

Now set up LArSoft:

setup larsoft ${my_version} -q ${my_type}:${my_compiler}

Set up a test release in your work area, then grab and build the latest versions of larpandora and lbnecode:

cd ${my_installation}
mrb newDev 
source localProducts_larsoft_${my_version}_${my_type}_${my_compiler}/setup
mrb g larpandora
mrb g lbnecode 
mrb install -j4

Aside: at the time of writing, both larpandora and lbnecode need to be checked out from their develop branches. In addition, a patched lardata is needed to correctly reconstruct hits from the short drift volume, since the current conversion between ticks and X always always assumes a negative drift direction. I've committed my version of this patch to a branch of lardata called blake_convertTicksToX.

Step 2: Generate a sample of events

We'll use the single-particle generator to simulate a sample of events in the 35t detector. This uses the GEANT4 Particle Gun to inject particles into the 35t detector. By default, the single muons are simulated with an energy of 6 GeV and a direction along the z-axis. Note: injecting particles into the simulation along the beam direction is not completely appropriate for the LBNE 35t detector - although it's important for future accelerator neutrino physics to understand the detector response along this direction.

The single-particle generator can be run as follows:

lar -c prodsingle_lbne35t.fcl -n50 # generate 50 single-muon events
ls -ltr # see the file that you made, single35t_gen.root, containing the simulated events

Step 3: Reconstruct the events

The LArPandora package in lbnecode contains a script "runpandora_lbne.fcl" that can be used to process these events. This script cheats the hit reconstruction and disambiguation, runs the pattern recognition, and then outputs some analysis trees. It is run as follows:

lar -c runpandora_lbne35t.fcl single35t_gen.root
ls -ltr # see the file that you made, ntuple.root, containing the analysis trees

For completeness, I've pasted the current version of the runpandora_lbne35t.fcl file in full below.

#include "services_lbne.fcl" 
#include "caldata_lbne.fcl" 
#include "hitfindermodules_lbne.fcl" 
#include "pandoramodules_lbne.fcl" 
#include "anatreemodule.fcl" 

process_name: LBNE35tPandora

  # Load the service that manages root files for histograms.
  TFileService: { fileName: "ntuple.root" }
  Timing:       {}
  SimpleMemoryCheck:     { ignoreTotal: 1 } # default is one
  user:         @local::lbne35t_services

### Define input file format
  module_type: RootInput

### Define output file format
   module_type: RootOutput
   fileName:    "standard_reco.root" #default file name, can override from command line with -o or --output

### Define the modules and create chains
    caldata:           @local::lbne35t_calwire
    hitcheat:          @local::lbne35t_hitcheater
    pandora:           @local::lbne35t_pandora
    particlestitcher:  @local::lbne35t_particlestitcher
    particletracks:    {module_type: PFParticleTrackMaker}



    pandorana:         {module_type: PFParticleAnalysis}
    pandoramonitoring: {module_type: PFParticleMonitoring}
    analysistree:      @local::anatree_anatree

  ### Set up a chain of Producer modules
  reco: [ caldata, hitcheat, pandora, particlestitcher, particletracks ]

  ### Set up a chain of Analyzer modules
  ana: [ pandorana, pandoramonitoring, analysistree  ]

  ### Set up the output stream
  stream1: [ out1 ]

  ### Set up the trigger paths (these are the modules that modify the event) 
  trigger_paths: [ reco ] 

  ### Set up the end paths (these are the modules that do not modify the event)
  end_paths: [ ana, stream1 ]

### Configure the Producer modules
physics.producers.pandora.HitFinderModuleLabel: "hitcheat" 
physics.producers.particlestitcher.PFParticleModuleLabel: "pandora" 
physics.producers.particlestitcher.UseXCoordinate: false
physics.producers.particletracks.PFParticleModuleLabel: "particlestitcher" 
physics.producers.particletracks.SpacePointModuleLabel: "pandora" 

### Configure the Pandora Analyzer modules
physics.analyzers.pandoramonitoring.UseDaughterPFParticles:  true
physics.analyzers.pandoramonitoring.HitFinderModule: "hitcheat" 
physics.analyzers.pandoramonitoring.SpacePointModule: "pandora" 
physics.analyzers.pandoramonitoring.PFParticleModule: "particlestitcher" 
physics.analyzers.pandorana.PFParticleModule: "particlestitcher" 

### Configure the Analysis Tree module
physics.analyzers.analysistree.TrackModuleLabel: "particletracks" 
physics.analyzers.analysistree.ClusterModuleLabel: "particlestitcher" 
physics.analyzers.analysistree.HitsModuleLabel: "hitcheat" 
physics.analyzers.analysistree.SimulationLabel: "largeant" 

Step 3: Plotting the output

The ROOT file outputted by this job contains three analysis trees: "pandorana", which is a dump of all the reconstructed recob::PFParticles; "pandoramonitoring", which contains a set of reconstruction performance metrics based on comparison with MC truth information; and "analysistree", which is the current standard analysis tuple for LBNE. To view the content of these trees, start by opening the ROOT file (root -l ntuple.root).

First, let's look in the pandoramonitoring tree. This tree has one entry per true particle per event. For this sample of single-particle muons, there should only be one true particle per event, and ideally one reconstructed primary particle per event (where "primary" particles are the parent muons, with daughter delta rays not included). The number of reconstructed particles per event can be plotted as follows:

pandora->Draw("nPrimaryPfos","index==0 && nMCParticles>0"); // plot this quantity once per event, and require a true particle in the event. 

Here is my version of this plot:

This is indeed peaked at one - good! In my sample of 50 events, there are no events without a reconstructed particle (i.e. the reconstruction efficiency is 100 percent). A handful of events have two reconstructed particles rather than one, which generally happens because a delta ray has been reconstructed as a primary particle, rather than identified as the daughter particle of a primary muon.

To study reconstruction performance, we currently use the "completeness" metric, which is defined as the number of hits from the true particle that are included in the reconstructed particle. Ideally, the distribution of completeness should be peaked towards unity. This distribution can be plotted as follows:

pandora->Draw("completeness","nMCHits>0"); // require that are some true hits!

Here is my version of this plot:

This is also peaked at unity, although some hits are not currently being associated to the primary track (for a variety of reasons).

One LBNE 35t analysis task is to develop new performance metrics!

Finally, let's take a look inside the analysis tree. As an example, try plotting the direction of the reconstructed tracks:

gDirectory->cd("../analysistree"); // Sorry, I'm not very good at navigating around these tree structures!

Here is my version of this plot:

So, the events are reconstructed along the z-axis - which matches the simulation (rather well...?)


Hope this helps. If you have any questions, please ask Andy B