TrkAna

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

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.

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.

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