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.

For Analyzers

How To Create a TrkAna Tree

You can use the TrkAna Musing like so:

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

where mcs.art contains the result of the Mu2e reconstruction.

In the trkana.root file, you will see two different TrkAna-related folders:

  • TrkAnaNeg contains the results of the negatively-charged tracks, and
  • TrkAnaPos contains the results of the positively-charged tracks.

TrkAna is designed to be flexibile so if this does not produce the type of tree you want, then there are fcl parameters that can be changed. A few examples are available here: https://github.com/Mu2e/TrkAna/tree/main/fcl and are given in the table below. Also, you can always ask for help on the #trkana channel on Slack

fcl file module label candidate supplements notes
TrkAnaReco.fcl TrkAnaNeg downstream e-minus upstream e-minus, downstream mu-minus
TrkAnaPos downstream e-plus upstream e-plus, downstream mu-plus
CrvExpert.fcl TrkAnaNeg downstream e-minus upstream e-minus, downstream mu-minus adds crvinfo, crvinfomc, crvsummary, crvsummarymc, and crvinfomcplane branches
TrkAnaPos downstream e-plus upstream e-plus, downstream mu-plus
TrkAnaReco_Upstream.fcl TrkAnaNeg upstream e-minus downstream e-minus, upstream mu-minus
TrkAnaPos upstream e-plus downstream e-plus, upstream mu-plus
TrkAnaReco_ceSimReco.fcl TrkAnaNeg downstream e-minus none for use with reco files generated with ceSimReco.fcl
fcl files below are flagged for updating / removal
TrkAnaRecoEnsemble-MC.fcl TrkAnaNeg downstream e-minus upstream e-minus, downstream mu-minus for use with MDC2018 Ensemble datasets
TrkAnaPos downstream e-plus upstream e-plus, downstream mu-plus
TrkAnaRecoEnsemble-Data.fcl TrkAnaNeg downstream e-minus upstream e-minus, downstream mu-minus for use with MDC2018 Ensemble datasets, no MC information
TrkAnaPos downstream e-plus upstream e-plus, downstream mu-plus
TrkAnaReco_wTrkQualFilter.fcl TrkAnaNeg downstream e-minus upstream e-minus, downstream mu-minus an art filter module is run before creating the TrkAna tree
TrkAnaPos downstream e-plus upstream e-plus, downstream mu-plus
TrkAnaReco_MultipleTrkQual.fcl TrkAnaNeg downstream e-minus upstream e-minus, downstream mu-minus an additional TrkQual algorithm is used for each track
TrkAnaPos downstream e-plus upstream e-plus, downstream mu-plus

How to Analyze a TrkAna Tree

Each of these contain TTrees that you can use ROOT or python

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

  • Note: the below is for the latest version of uproot4

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
trkananeg = uproot.open("trkana.root:TrkAnaNeg/trkana") # opens the 'trkana' tree in the 'TrkAnaNeg' folder

Now, if we want to store, for example, the deent branch in the dataframe:

df = tree.arrays(filter_name=['deent*'],library="pd")


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

trkananeg = uproot.open("trkana.root:TrkAnaNeg/trkana")
df = trkananeg(filter_name=['deent*'],library="pd")
plt.hist(df["deent.mom"], bins=60, range=(95,110))

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

For Developers

If you will be contributing to the development of TrkAna, then you can fork TrkAna on GitHub and build it within Muse Like so:

Once you log in:

setup mu2e
cd /your/working/directory
git clone git@github.com:<Your GitHub Username>/Offline.git (or muse backing Offline vXX_YY_ZZ)
git clone git@github.com:<Your GitHub Username>/TrkAna.git
muse setup
muse build -j4 --mu2eCompactPrint

Then you can make your developments and put in a pull request.

Version History / TrkAna Musings

This is the list of TrkAna Musings. The top row corresponds to the "current" version.

TrkAna Musing TrkAna tag muse backings muse stub notes
v03_00_00 v03_00_00 N/A breaking changes: branch names now three characters; uses KinKal fits
v02_03_00 v02_03_00 N/A
v02_02_00 v02_02_00 SimJob MDC2020v --> Offline v10_20_00 sl7-prof-e20-p035
v02_01_00 v02_01_00 SimJob MDC2020u --> Production v00_10_00 --> Offline v10_18_00 sl7-prof-e20-p033
v02_00_01 v02_00_01 SimJob MDC2020t --> Production v00_09_11 --> Offline v10_17_00 sl7-prof-e20-p026
(not built) v02_00_00 N/A N/A failed build due to incompatible KinKal version
v01_01_00 v01_01_00 SimJob MDC2020r --> Production v00_09_02 --> Offline v10_15_01 sl7-prof-e20-p023 adds TrkAnaUtils
(not built) v01_00_01 N/A N/A resolves MDC2020r incompatibility
v01_00_00a v01_00_00 Production v00_07_00 --> Offline v10_11_00 sl7-prof-e20-p021 updated for muse 1-path/2-path change
v01_00_00 v01_00_00 Production v00_06_00 --> Offline v10_10_01 sl7-prof-e20-p018 uses deprecated "muse link"

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