TrkAna

From Mu2eWiki
Jump to navigation Jump to search

Overview

TrkAna is a track-based ROOT TTree that can be used to help with analysis. Each entry in the TTree corresponds to a single fitted track and contains reconstructed information from the tracker, calorimeter and CRV. There is also the option to write out Monte Carlo truth information and additional information for other track types that might be important to an analysis.

How to Get Help

Feel free to send any questions to the #trkana Slack channel, or the 'Is It Me Or A Bug?' hypernews forum.

There is also a tutorial that is a few years old and will be updated soon.

How to Build

TrkAna is built within the Muse environment.

Once you log in:

setup mu2e

In your working directory, the only required package is Offline so either clone your fork Offline repository, or link an already existing Offline build to your Muse working directory:

git clone git@github.com:<Your GitHub Username>/Offline.git

or,

muse link Offline vXX_YY_ZZ

Then you can clone your fork of the TrkAna repository into your Muse working directory:

git clone git@github.com:<Your GitHub Username>/TrkAna.git

And finally you can set up and build everything:

muse setup
muse build -j4 --mu2eCompactPrint

How To Run

Reco Datasets

There is an example fcl configuration in the TrkAna repository that runs on reco files (see e.g. MDC2018 reco datasets).

mu2e -c TrkAna/fcl/TrkAnaReco.fcl -s mcs.art --TFileName trkana.root

This runs two instances of the TrackAnalysisReco module. One for negative tracks (TrkAnaNeg) and one for positive tracks (TrkAnaPos). Each tree has the same structure as shown below.

Ensemble Datasets

If you are running on the MDC2018 ensemble datasets, then you can use the fcl files:

  • TrkAna/fcl/TrkAnaRecoEnsemble-Data.fcl, and
  • TrkAna/fcl/TrkAnaRecoEnsemble-MC.fcl.

How To Use

with ROOT

You can use the trkana tree like you would any other ROOT TTree: with the ROOT command line for data exploration, with ROOT macros to make plots etc.

with Python

The best way to open ROOT files in Python is to use the uproot package. It does not require a working installation of ROOT, so it allows to read a ROOT file on basically any platform that supports Python (e.g. Colaboratory). It also provides a more pythonic bridge between ROOT and Numpy/pandas.

In order to open a ROOT TTree with uproot it's sufficient to write:

import uproot

file = uproot.open("trkana.root")
trkananeg = file["TrkAnaNeg"]["trkana"] # opens the 'trkana' tree in the 'TrkAnaNeg' folder

Now, if we want to store, for example, the reconstructed momentum in a Numpy array we can do:

deent_mom = trkananeg["deent.mom"].array()

Instead of using Numpy arrays it is possible to convert a ROOT TTree in a pandas dataframe with:

df = trkananeg.pandas.df(flatten=False)

The flatten=False is required to manage branches with vectors or arrays of variable size (e.g. crvinfo). Once your data is stored in a pandas dataframe or in a numpy array you can plot it with the many plotting libraries available (matplotlib, plot.ly, etc.). This example shows how to plot an histogram with matplotlib:

import uproot
import matplotlib.pyplot as plt

file = uproot.open("trkana.root")
trkananeg = file["TrkAnaNeg"]["trkana"] 
df = trkananeg.pandas.df(flatten=False)

fig, ax = plt.subplots(1,1)
n, bins, patches = ax.hist(df["deent.mom"],
                           bins=60, 
                           range=(95,110), 
                           label="Reco. momentum")

A class that allows you to query the dataframe and plot manipulated variables can be found at https://github.com/soleti/mu2e_plotter.

Tree Structure

Here is a very rough description of the tree branches and where to find leaf definitions in the repository:

evtinfo
information about the event (TrkAna/inc/EventInfo.hh)
hcnt
count of various hit types (TrkAna/inc/HitCount.hh)
tcnt
count of various track types (TrkAna/inc/TrkCount.hh)
de
global fit information for downstream electron track (TrkAna/inc/TrkInfo.hh)
deent
local fit information for downstream electron track at tracker entrance (TrkAna/inc/TrkInfo.hh)
demid
local fit information for downstream electron track at middle of tracker (TrkAna/inc/TrkInfo.hh)
dexit
local fit information for downstream electron track at tracker exit (TrkAna/inc/TrkInfo.hh)
detch
calorimeter cluster information for cluster used in downstream electron track fit (tch = TrkCaloHit, TrkAna/inc/TrkCaloHitInfo.hh)
dequal
the output values of the TrkQual and TrkPID ANNs
uetch
calorimeter cluster information for cluster used in upstream electron track fit (tch = TrkCaloHit, TrkAna/inc/TrkCaloHitInfo.hh)
ue
global fit information for upstream electron track (TrkAna/inc/TrkInfo.hh)
dm
global fit information for downstream muon track (TrkAna/inc/TrkInfo.hh)
trigbits
unsigned int of the triggers
crvinfo
information about CRV coincidences (Offline/CRVAnalysis/inc/CrvHitInfoReco.hh)
bestcrv
element in crvinfo array that is the best
demc
MC information about particle that created downstream track (TrkAna/inc/TrkInfo.hh)
demcgen
MC information about particle that started the simulation (TrkAna/inc/GenInfo.hh)
demcpri
MC information about particle that would have ultimately created the GenParticle (TrkAna/inc/GenInfo.hh)
demcent
MC information about step of particle that created downstream track as it enters the tracker (TrkAna/inc/TrkInfo.hh)
demcmid
MC information about step of particle that created downstream track as it passes the middle of the tracker (TrkAna/inc/TrkInfo.hh)
demcxit
MC information about step of particle that created downstream track as it leaves the tracker (TrkAna/inc/TrkInfo.hh)
crvinfomc
MC information about CRV coincidences (Offline/CRVAnalysis/inc/CrvHitInfoMC.hh)
detchmc
MC information about calorimeter cluster used in the downstream electron fit (TrkAna/inc/CaloClusterInfoMC.hh)
uetchmc
MC information about calorimeter cluster used in the upstream electron fit (TrkAna/inc/CaloClusterInfoMC.hh)
detshmc
MC information about the straw hits used in the downstream electron fit (need diagLevel > 0, TrkAna/inc/TrkStrawHitInfo.hh)
detrkqual
the input variables and output value of the track quality artificial neural network (TrkAna/inc/TrkQualInfo.hh)
evtwt
the values of all EventWeight objects that were in the art even (e.g. proton bunch intensity = PBIWeight)

By setting the diagLevel to 2, you can get hit level informationTrkAna

detsh
reconstructed straw hit information for downstream electron track fit (TrkDiag/inc/TrkStrawHitInfo.hh)
detsm
information about straw materials that the downstream electron track fit goes through (TrkAna/inc/TrkStrawMatInfo.hh)

Future Developments

We're always looking for input from developers and analyzers to keep TrkAna up-to-date! Get in touch on the #trkana Slack channel, or with Andy Edmonds directly with any thoughts / comments you have