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.

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