TrkAnaTutorial: Difference between revisions

From Mu2eWiki
Jump to navigation Jump to search
No edit summary
No edit summary
 
(96 intermediate revisions by 2 users not shown)
Line 1: Line 1:
==Under Construction!==
The TrkAna tutorial is hosted within the GitHub repo [https://github.com/Mu2e/TrkAna/blob/main/tutorial/README.md here]
This tutorial is currently being written
 
== Tutorial Session Goal ==
A [[TrkAna]] tree is a ROOT [https://root.cern.ch/doc/master/classTTree.html TTree] where each entry in the tree represents a single track. The TrkAna tree is created by the TrackAnalysisReco module of Mu2e Offline which runs over a KalSeedCollection.
 
In this tutorial you will:
* create [[TrkAna]] trees using the Mu2e Offline software; and,
* analyze them using the ROOT command line and ROOT macros.
 
== Session Prerequisites ==
This tutorial should be useful for anyone starting out with TrkAna tree analysis
 
Before starting this tutorial you should:
* know about the physics of Mu2e;
* have the appropriate docker container set up; and,
* know how to run the Mu2e Offline software and ROOT
 
== Basic Exercises ==
=== Exercise 1: Creating a simple TrkAna tree ===
<ol style="list-style-type:lower-alpha">
<li>First, let's create a simple TrkAna tree by running on a single CeEndpoint-mix reco art file:</li>
<nowiki> > mu2e -c $TUTORIAL_BASE/TrkAna/fcl/TrkAnaTutEx01.fcl -S $TUTORIAL_BASE/TrkAna/filelists/mcs.mu2e.CeEndpoint-mix-cat.MDC2018h.1-file.lst </nowiki>
<li> Now let's have a look at the TrkAna tree with the ROOT command line</li>
<nowiki> > root -l trkana-ex01.root
root[n]: TrkAnaEx01->cd()
root[n]: trkana->Print()</nowiki>
You will see the TrkAna tree structure. Here is a brief description of the branches:
<ol style="list-style-type:lower-roman">
  <li> <code>evtinfo</code>: '''ev'''en'''t''' level information (e.g. event ID of the event this track is from) </li>
  <li> <code>hcnt</code>: '''h'''it '''c'''ou'''nt''' of different types of hit (e.g. number that pass certain collections) </li>
  <li> <code>tcnt</code>: '''t'''rack '''c'''ou'''nt''' of different track types </li>
  <li> <code>trk</code>: global fit information for the track (e.g. fit status, ranges of validity, number of hits, track quality) </li>
  <li> <code>trk(ent/mid/xit)</code>: local fit information for the track at the '''ent'''trance of the tracker, the '''mid'''dle of the tracker and e'''xit''' of the tracker (e.g. fit momentum, pitch angle) </li>
  <li> <code>trktch</code>: calorimeter hit information for the calorimeter function associated to the track (tch = '''T'''rk'''C'''alo'''H'''it)</li>
  <li> <code>crvinfo</code>: information of associated hits in the CRV </li>
  </ol>
Note that the "trk" parts of the branch names are configurable -- you will see this is a minute
<li> Now we can plot some simple things:
<ol style="list-style-type:lower-roman">
  <li> the track momentum at the tracker entrance </li>
  <nowiki>root[n]: trkana->Draw("trkent.mom")</nowiki>
  <li> the calorimeter cluster energy </li>
  <nowiki>root[n]: trkana->Draw("trktch.edep")</nowiki>
  <li> With this last command you will see some entries at -1000. This means that there is no associated calorimeter cluster for this track. To exclude these we want to want to add a cut on the <code>trktch.active</code> flag (0 = there is no TrkCaloHit, 1 = there is TrkCaloHit):</li>
  <nowiki>root[n]: trkana->Draw("trktch.edep", "trktch.active==1")</nowiki>
</ol>
<li> Let's take a quick look at the fcl file to see how the TrackAnalysisReco module has been configured. Open it up in your favourite text editor and look at these important lines: </li>
<nowiki>TrkAnaEx01 : { @table::TrackAnalysisReco }
physics.analyzers.TrkAnaEx01.candidate.input : "KFFDeM"
physics.analyzers.TrkAnaEx01.candidate.branch : "trk"
physics.analyzers.TrkAnaEx01.diagLevel : 0
physics.analyzers.TrkAnaEx01.FillMCInfo : false</nowiki>
In order, these lines:
<ol style="list-style-type:lower-roman">
  <li>import an example TrkAna module configuration (you can find it in $MU2E_BASE_RELEASE/TrkDiag/fcl/prolog.fcl);</li>
  <li>define the input KalSeedCollection that we want a TrkAna tree for (KFFDeM = '''K'''al'''F'''inal'''F'''it '''D'''ownstream '''eM'''inus);</li>
  <li>configure the name of the output branches;</li>
  <li>set TrkAna to use the lowest diagnostic level (0 = simple list of tracks, 1 = hit level diagnostics); and,</li>
  <li>make sure we are not touching the MC truth</li>
</ol>
<li> (Optional): Run on a CeplusEndpoint-mix file ($TUTORIAL_BASE/TrkAna/filelist/mcs.mu2e.CeplusEndpoint-mix-cat.MDC2018h.1-file.lst) and get a list of positively-charged tracks. What is the momentum of these tracks? </li>
<li> (Optional): Create a second instance of the TrackAnalysisReco module. Have one instance set to look at negatively-charged tracks and the other set to look at positively charged tracks. Run on muplusgamma-mix ($TUTORIAL_BASE/TrkAna/filelist/mcs.mu2e.flatmugamma-mix-cat.MDC2018h.1-file.lst) and count how many tracks of each type are found</li>
</ol>
 
=== Exercise 2: Calculating the Ce efficiency ===
Now that you can create a trkana tree, let's calculate something! (Will need to explain PBI weight)
<ol style="list-style-type:lower-alpha">
<li>Create a TrkAna tree with CeEndpoint-mix and add PBI weight</li>
<nowiki> mu2e -c TrkDiag/fcl/TrkAnaTutEx02.fcl -S mcs.mu2e.CeEndpoint-mix.lst </nowiki>
This fcl file has added the following line:
<nowiki>physics.TrkAnaTrigPath : [ @sequence::TrkAnaReco.TrigSequence ]</nowiki>
You can search for that parameter in TrkDiag/fcl/prolog.fcl but simply it adds the PBIEventWeight module (PBI = '''P'''roton'''B'''unch'''I'''ntensity) and TrkQual outputs
<li>here is an example ROOT macro that plots the track momentum onto a histogram with 0.5 MeV wide bins</li>
<nowiki> root -l TrkDiag/test/TrkAnaTutEx02.C </nowiki>
<li>Add the following signal cuts to the Draw function</li>
<ol style="list-style-type:lower-roman">
  <li>the fit is successful (trk.status > 0)</li>
  <li>the track is in the time window of 700 ns -- 1695 ns (trk.t0)</li>
  <li>the tan-dip of the track is consistent with coming from the target 0.577350 -- 1.000 (trkent.td)</li>
  <li>the impact parameters of the track is consistent with coming from the target -80 mm -- 105 mm (trkent.d0)</li>
  <li>the maximum radius of the track is OK 450 mm -- 680 mm (trkent.d0 + 2./trkent.om)</li>
  <li>the track is of good quality (trk.trkqual > 0.8)</li>
</ol>
<li>Because we simulated each event with a different proton bunch intensity, each track should be weighted by the PBIWeight. To do this you will want to modify the cut command to add the event weighting:</li>
<nowiki> evtwt.PBIWeight*(cuts) </nowiki>
<li>Now we can count the number of tracks that pass all these cuts</li>
<nowiki> hRecoMom->Integral() </nowiki>
<li>We can also integrate in the momentum signal region. Be careful TH1F::Integral takes bin numbers as its arguments and not x-values. You can find a bin for a given x-value with hist->GetXaxis()->FindBin(x-value). Be sure to make sure you don't go one bin too high!</li>
<li>To calculate the efficiency you need to know the number of events generated for this simulation: genCountLogger</li>
<li>calculate the Ce efficiency</li>
<li>An example solution macro can be found in TrkDiag/test/TrkAnaTutEx02Soln.C</li>
<li>(Optional): plot results and TLines on momentum plot, can you change cut and lines follow</li>
<li>(Optional): run two instances of TrackAnalysisReco for positive and negative tracks and plot the momentum distribution of both on the same set of axes with different colours</li>
<li>(Optional): make a cut flow plot with a TrkAna loop
</ol>
 
=== Exercise 3: Adding MC truth ===
Because we are running on simulated data, we know the truth of what happened. How well is our detector doing?
<ol style="list-style-type:lower-alpha">
<li>run TrkAnaReco.fcl to add MC truth</li>
<li>plot reco - truth for momentum or something</li>
<li>do a double-sided crystal ball fit</li>
</ol>
 
=== Exercise 4: Following genealogy ===
Can also see the important steps in the genealogy(run on a different MDC2018 sample?). Explain difference between primary and gen branches
<ol style="list-style-type:lower-alpha">
<li>something</li>
</ol>
 
For any other intermediate steps in the genealogy, you will need to run Offline.
 
=== Exercise 5: Adding supplemental tracks ===
There might be other tracks that are important to your analysis (e.g. upstream going tracks)
<ol style="list-style-type:lower-alpha">
<li>run with supplemental tracks</li>
<li>look for reflected tracks? compare DeM to DmuM?</li>
<li>check for CRV coincidence? </li>
</ol>
 
=== Conclusion ===
This last exercise created a TrkAna tree that is the same the one created in TrkAnaReco.fcl
 
== Advanced Exercises ==
=== Exercise 1: Hit level diagnostics? ===
 
=== Exercise 2: TrkQual? ===
 
=== Exercise 3: Event weighting? ===
Run on flateminus-mix with DIO weights and plot that
 
=== Exercise 4: Running reconstruction? ===
 
=== Exercise 5: Retraining TrkQual? ===
 
== Reference Materials ==
* Use this place to add links to reference materials.
* [[TrkAna]] wiki page
 
=== A Useful Glossary ===
; ROOT : data analysis framework developed at CERN
; KalSeed : data product that represents a track
; CeEndpoint-mix : dataset name for CeEndpoint (i.e. mono-energetic electrons) with background frames mixed in
; CeplusEndpoint-mix : dataset name for CeplusEndpoint (i.e. mono-energetic positrons) with background frames mixed in
; flatmugamma-mix : dataset name for flatmugamma (i.e. flate energy photons generated at muon stopping positions) with background frames mixed in
; KalFinalFit : the module name for the final stage of the Kalman filter fit for the track
; TrkQual : an artificial neural network (ANN) that takes parameters from the track and outputs a value between 0 (poorly reconstructed) and 1 (well-reconstructed)

Latest revision as of 18:21, 7 October 2023

The TrkAna tutorial is hosted within the GitHub repo here

Retrieved from "http://mu2ewiki.fnal.gov/w/index.php?title=TrkAnaTutorial&oldid=23335"