TrkAnaTutorial: Difference between revisions
No edit summary |
No edit summary |
||
Line 79: | Line 79: | ||
'''Track Quality''' | '''Track Quality''' | ||
We want a simple way to determine how well-reconstructed the tracks are. We use an artificial neural network (ANN) called TrkQual that takes various properties of the track and is trained to give each track a trkqual value between 0 (poorly-reconstructed) and 1 (well-recosntructed). In this exercise, we add the TrkQual modules to the trigger path and TrkAna writes out the output value to <code>trk.trkqual</code>. TrkQual is explored in more detail in Advanced Exercise #3. | We want a simple way to determine how well-reconstructed the tracks are. We use an artificial neural network (ANN) called TrkQual that takes various properties of the track and is trained to give each track a trkqual value between 0 (poorly-reconstructed) and 1 (well-recosntructed). In this exercise, we add the TrkQual modules to the trigger path and TrkAna writes out the output value to <code>trk.trkqual</code>. There is one TrkQualCollection for each KalSeedCollection. TrkQual is explored in more detail in Advanced Exercise #3. | ||
'''The Exercise''' | '''The Exercise''' | ||
Line 85: | Line 85: | ||
Now onto the exercise: | Now onto the exercise: | ||
<ol style="list-style-type:lower-alpha"> | <ol style="list-style-type:lower-alpha"> | ||
<li>Create a TrkAna tree with CeEndpoint-mix tracks and include the | <li>Create a TrkAna tree with CeEndpoint-mix tracks and include the <code>genCountLogger</code>, <code>PBIWeight</code> and <code>TrkQual</code> modules</li> | ||
<nowiki> mu2e -c $TUTORIAL_BASE/TrkAna/fcl/TrkAnaTutEx02.fcl -S $TUTORIAL_BASE/TrkAna/filelists/mcs.mu2e.CeEndpoint-mix-cat.MDC2018h.1-file.lst</nowiki> | <nowiki> mu2e -c $TUTORIAL_BASE/TrkAna/fcl/TrkAnaTutEx02.fcl -S $TUTORIAL_BASE/TrkAna/filelists/mcs.mu2e.CeEndpoint-mix-cat.MDC2018h.1-file.lst</nowiki> | ||
You can read the file to see how the modules are added (Note: some of this hidden away in $MU2E_BASE_RELEASE/TrkDiag/fcl/prolog.fcl). | |||
<li>Run this example ROOT macro that plots the track momentum onto a histogram with 0.5 MeV wide bins</li> | |||
<nowiki> root -l $TUTORIAL_BASE/TrkAna/scripts/TrkAnaTutEx02.C </nowiki> | |||
<li>Change the bin width to 0.05 MeV</li> | |||
<li> | |||
<nowiki> root -l | |||
<li>Add the following signal cuts to the Draw function</li> | <li>Add the following signal cuts to the Draw function</li> | ||
<ol style="list-style-type:lower-roman"> | <ol style="list-style-type:lower-roman"> | ||
<li>the fit is successful (trk.status > 0)</li> | <li>the fit is successful (<code>trk.status > 0</code>)</li> | ||
<li>the track is in the time window of 700 ns -- 1695 ns (trk.t0)</li> | <li>the track is in the time window of 700 ns -- 1695 ns (<code>trk.t0</code>)</li> | ||
<li>the tan-dip of the track is consistent with coming from the target 0.577350 -- 1.000 (trkent.td)</li> | <li>the tan-dip of the track is consistent with coming from the target: 0.577350 -- 1.000 (<code>trkent.td</code>)</li> | ||
<li>the impact | <li>the impact parameter of the track is consistent with coming from the target: -80 mm -- 105 mm (<code>trkent.d0</code>)</li> | ||
<li>the maximum radius of the track is OK 450 mm -- 680 mm (trkent.d0 + 2./trkent.om)</li> | <li>the maximum radius of the track is OK: 450 mm -- 680 mm (<code>trkent.d0 + 2./trkent.om</code>)</li> | ||
<li>the track is of good quality (trk.trkqual > 0.8)</li> | <li>the track is of good quality (<code>trk.trkqual > 0.8</code>)</li> | ||
</ol> | </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> | <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> | ||
Line 106: | Line 104: | ||
<li>Now we can count the number of tracks that pass all these cuts</li> | <li>Now we can count the number of tracks that pass all these cuts</li> | ||
<nowiki> hRecoMom->Integral() </nowiki> | <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) | <li>We can also integrate in the momentum signal region with the same function. Be careful TH1F::Integral takes bin numbers as its arguments and not x-values. Some hints:</li> | ||
<li>To calculate the efficiency you need to know the number of events generated for this simulation | <ol style="list-style-type:lower-roman"> | ||
<li>calculate the Ce efficiency</li> | <li>You can find a bin for a given x-value with hist->GetXaxis()->FindBin(x-value)</li> | ||
<li> | <li>Make sure you aren't off by one bin by checking the bin low edeges and bin high edges with TAxis::GetBinLowEdge() and TAxis::GetBinUpEdge().</li> | ||
</ol> | |||
<li>(Optional): | <li>To calculate the efficiency you need to know the number of events generated for this simulation. This is stored in the output of the genCountLogger module</li> | ||
<nowiki> TH1F* hNumEvents = (TH1F*) file->Get("genCountLogger/numEvents"); | |||
double n_generated_events = hNumEvents->GetBinContent(1);</nowiki> | |||
<li>Now you can calculate the absolute Ce efficiency. What's the answer?</li> | |||
<li>(Optional): Make the plot prettier by:</li> | |||
<ol style="list-style-type:lower-roman"> | |||
<li>adding appropriate axis labels</li> | |||
<li>writing the Ce efficiency on the plot with a TLatex</li> | |||
<li>adding dashed lines to show the momentum window with TLines (extra bonus: have the lines move when the momentum window values change)</li> | |||
</ol> | |||
<li>(Optional): Add a second momentum plot but with a higher track quality cut. Include a TLegend.</li> | |||
</ol> | </ol> | ||
=== Exercise 3: Adding MC truth === | === Exercise 3: Adding MC truth === | ||
In this exercise, we will add MC truth information to the TrkAna tree and see how close our reconstruction matches the truth. | |||
<ol style="list-style-type:lower-alpha"> | <ol style="list-style-type:lower-alpha"> | ||
<li> | <li>Create a TrkAna tree with CeEndpoint-mix tracks and include the MC truth information:</li> | ||
< | <nowiki>mu2e -c $TUTORIAL_BASE/TrkAna/fcl/TrkAnaTutEx03.fcl -S $TUTORIAL_BASE/TrkAna/filelists/mcs.mu2e.CeEndpoint-mix-cat.MDC2018h.1-file.lst</nowiki> | ||
<li> | If you look in the fcl file, you will notice that there is a global switch <code>fillMCInfo</code> and a local switch for the candidate track <code>candidate.fillMC</code>. This will be important when we add supplemental tracks in Exercise 5. | ||
<li>Run this example ROOT macro that plots the intrinsic tracker momentum for tracks that pass our signal cuts</li> | |||
<nowiki> root -l $TUTORIAL_BASE/TrkAna/scripts/TrkAnaTutEx03.C </nowiki> | |||
<li>Using what you learned in Exercise 2, what is the number of events above +3 MeV?</li> | |||
<li>(Optional): Change the trkqual cut. How does the number of events above +3 MeV change?</li> | |||
<li>(Optional): Do the same comparison at the middle or exit of the tracker</li> | |||
<li>(Optional): Perform a fit to a double-sided crystal ball function. This function is a Gaussian with polynomial tails. The function can be found here: $TUTORIAL_BASE/TrkAna/scripts/dscb.h. You will need to create your own TF1 ([https://root.cern.ch/doc/v614/classTF1.html#F4 hint]) and use the TH1::Fit() function ([https://root.cern.ch/doc/master/classTH1.html#a7e7d34c91d5ebab4fc9bba3ca47dabdd hint]). What is the core resolution?</li> | |||
</ol> | </ol> | ||
=== Exercise 4: Following genealogy === | === 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 | Can also see the important steps in the genealogy (run on a different MDC2018 sample?). Explain difference between primary and gen branches | ||
'''Primary'''' | |||
This is | |||
'''Gen''' | |||
<ol style="list-style-type:lower-alpha"> | <ol style="list-style-type:lower-alpha"> | ||
<li>something</li> | <li>something</li> |
Revision as of 23:08, 29 May 2019
Under Construction!
This tutorial is currently being written
Tutorial Session Goal
A TrkAna tree is a ROOT 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
In this exercise, we will create a simple TrkAna tree and investigate it with the ROOT command line.
- First, run
mu2e
on a single CeEndpoint-mix reco art file:
> mu2e -c $TUTORIAL_BASE/TrkAna/fcl/TrkAnaTutEx01.fcl -S $TUTORIAL_BASE/TrkAna/filelists/mcs.mu2e.CeEndpoint-mix-cat.MDC2018h.1-file.lst
- Now let's have a look at the TrkAna tree with the ROOT command line > root -l trkana-ex01.root root[n]: TrkAnaEx01->cd() root[n]: trkana->Print() You will see the TrkAna tree structure. Here is a brief description of the branches:
-
evtinfo
: event level information (e.g. event ID of the event this track is from) -
hcnt
: hit count of different types of hit (e.g. number that pass certain collections) -
tcnt
: track count of different track types -
trk
: global fit information for the track (e.g. fit status, ranges of validity, number of hits, track quality) -
trk(ent/mid/xit)
: local fit information for the track at the enttrance of the tracker, the middle of the tracker and exit of the tracker (e.g. fit momentum, pitch angle) -
trktch
: calorimeter hit information for the calorimeter function associated to the track (tch = TrkCaloHit) -
crvinfo
: information of associated hits in the CRV - Now we can plot some simple things:
- the track momentum at the tracker entrance root[n]: trkana->Draw("trkent.mom")
- the calorimeter cluster energy root[n]: trkana->Draw("trktch.edep")
- 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
trktch.active
flag (0 = there is no TrkCaloHit, 1 = there is TrkCaloHit):
root[n]: trkana->Draw("trktch.edep", "trktch.active==1")
- 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: 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 In order, these lines:
- import an example TrkAna module configuration (you can find it in $MU2E_BASE_RELEASE/TrkDiag/fcl/prolog.fcl);
- define the input KalSeedCollection that we want a TrkAna tree for (KFFDeM = KalFinalFit Downstream eMinus);
- configure the name of the output branches;
- set TrkAna to use the lowest diagnostic level (0 = simple list of tracks, 1 = hit level diagnostics); and,
- make sure we are not touching the MC truth
- (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?
- (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
Note that the "trk" parts of the branch names are configurable -- you will see this is a minute
Exercise 2: Calculating the Ce efficiency
Now that we can create a TrkAna tree, let's calculate how efficient we are at reconstructed conversion electrons with some signal cuts. Before starting this exercise, a quick note about event counting, event weighting, and track quality.
Event Counting
In the simulation, we generate a certain number of events. However, in order to save space, we only write out events that will produce a reconstructed tracks. We have various ways of filtering events but the result is the same -- the number of events in the output art files do not correspond to the number of events that were generated, which is what we need to calculate absolute efficiencies. To account for this, we keep track of the number of events that were generated by creating a GenEventCount
object. Then we can run the genCountLogger
module to read the actual number of generated events.
Event Weighting
In each "mixed" event, we add a single "primary" particle onto a set of "background frames", which represent the background hits from other processes. We want to simulate the variable intensity of the proton beam at the production target and so we scale the number of background hits when we create the mixed event. However, we still only add a single primary particle and so we record the scale factor used in a ProtonBunchIntensity
object for use later. In this exercise, we will add a new module to the trigger path (PBIWeight
), which translates the scale factor used for the proton bunch intensity into an EventWeight
object. The TrackAnalysisReco then writes out these event weight values to a new branch (evtwt.PBIWeight
). Event weighting is explored in more detail in Advanced Exercise #2.
Track Quality
We want a simple way to determine how well-reconstructed the tracks are. We use an artificial neural network (ANN) called TrkQual that takes various properties of the track and is trained to give each track a trkqual value between 0 (poorly-reconstructed) and 1 (well-recosntructed). In this exercise, we add the TrkQual modules to the trigger path and TrkAna writes out the output value to trk.trkqual
. There is one TrkQualCollection for each KalSeedCollection. TrkQual is explored in more detail in Advanced Exercise #3.
The Exercise
Now onto the exercise:
- Create a TrkAna tree with CeEndpoint-mix tracks and include the
genCountLogger
,PBIWeight
andTrkQual
modules
mu2e -c $TUTORIAL_BASE/TrkAna/fcl/TrkAnaTutEx02.fcl -S $TUTORIAL_BASE/TrkAna/filelists/mcs.mu2e.CeEndpoint-mix-cat.MDC2018h.1-file.lst
You can read the file to see how the modules are added (Note: some of this hidden away in $MU2E_BASE_RELEASE/TrkDiag/fcl/prolog.fcl).
- Run this example ROOT macro that plots the track momentum onto a histogram with 0.5 MeV wide bins root -l $TUTORIAL_BASE/TrkAna/scripts/TrkAnaTutEx02.C
- Change the bin width to 0.05 MeV
- Add the following signal cuts to the Draw function
- the fit is successful (
trk.status > 0
) - the track is in the time window of 700 ns -- 1695 ns (
trk.t0
) - the tan-dip of the track is consistent with coming from the target: 0.577350 -- 1.000 (
trkent.td
) - the impact parameter of the track is consistent with coming from the target: -80 mm -- 105 mm (
trkent.d0
) - the maximum radius of the track is OK: 450 mm -- 680 mm (
trkent.d0 + 2./trkent.om
) - the track is of good quality (
trk.trkqual > 0.8
) - 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: evtwt.PBIWeight*(cuts)
- Now we can count the number of tracks that pass all these cuts hRecoMom->Integral()
- We can also integrate in the momentum signal region with the same function. Be careful TH1F::Integral takes bin numbers as its arguments and not x-values. Some hints:
- You can find a bin for a given x-value with hist->GetXaxis()->FindBin(x-value)
- Make sure you aren't off by one bin by checking the bin low edeges and bin high edges with TAxis::GetBinLowEdge() and TAxis::GetBinUpEdge().
- To calculate the efficiency you need to know the number of events generated for this simulation. This is stored in the output of the genCountLogger module TH1F* hNumEvents = (TH1F*) file->Get("genCountLogger/numEvents"); double n_generated_events = hNumEvents->GetBinContent(1);
- Now you can calculate the absolute Ce efficiency. What's the answer?
- (Optional): Make the plot prettier by:
- adding appropriate axis labels
- writing the Ce efficiency on the plot with a TLatex
- adding dashed lines to show the momentum window with TLines (extra bonus: have the lines move when the momentum window values change)
- (Optional): Add a second momentum plot but with a higher track quality cut. Include a TLegend.
Exercise 3: Adding MC truth
In this exercise, we will add MC truth information to the TrkAna tree and see how close our reconstruction matches the truth.
- Create a TrkAna tree with CeEndpoint-mix tracks and include the MC truth information: mu2e -c $TUTORIAL_BASE/TrkAna/fcl/TrkAnaTutEx03.fcl -S $TUTORIAL_BASE/TrkAna/filelists/mcs.mu2e.CeEndpoint-mix-cat.MDC2018h.1-file.lst If you look in the fcl file, you will notice that there is a global switch
- Run this example ROOT macro that plots the intrinsic tracker momentum for tracks that pass our signal cuts root -l $TUTORIAL_BASE/TrkAna/scripts/TrkAnaTutEx03.C
- Using what you learned in Exercise 2, what is the number of events above +3 MeV?
- (Optional): Change the trkqual cut. How does the number of events above +3 MeV change?
- (Optional): Do the same comparison at the middle or exit of the tracker
- (Optional): Perform a fit to a double-sided crystal ball function. This function is a Gaussian with polynomial tails. The function can be found here: $TUTORIAL_BASE/TrkAna/scripts/dscb.h. You will need to create your own TF1 (hint) and use the TH1::Fit() function (hint). What is the core resolution?
fillMCInfo
and a local switch for the candidate track candidate.fillMC
. This will be important when we add supplemental tracks in Exercise 5.
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
Primary'
This is
Gen
- something
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)
- run with supplemental tracks
- look for reflected tracks? compare DeM to DmuM?
- check for CRV coincidence?
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?
Exercise 6: TrkAnaLoop?
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)