TrkQual: Difference between revisions

From Mu2eWiki
Jump to navigation Jump to search
No edit summary
No edit summary
Line 2: Line 2:
This will be filled out soon!
This will be filled out soon!


= What is TrkQual? =
= Introduction =
TrkQual is an artificial neural network (ANN) that evaluates the reconstruction quality of tracks. It uses certain reconstructed parameters of the track (e.g. number of hits) to separate "good" tracks from "bad" tracks and is trained on a simulation sample.


= How To Use TrkQual =
There are two classes of users:
== In A TrkAna Tree ==
* '''analyzers''': people who use the result of TrkQual in their analyses; and,
Use leaf dequal.TrkQual or branch detrkqual
* '''trainers''': people who train and calibrate the TrkQual ANN.


== In An Art Module ==
This wiki page tries to guide both groups to accomplish the tasks they need. If this wiki page is lacking (or out of date), then additional help can be found in the usual places (hypernews, Slack, DocDB etc.).


= How To Train TrkQual =
= For Everyone =
== Without Changing Training Parameters ==
There may be a few different trainings of TrkQual available. Questions to ask:
* what simulation sample was it trained on?
* what input variables are used?
* what definition of good quality and bad quality was used?
* has the output been calibrated?


== With Changing Training Parameters ==
Calibration
=== Removing a Variable ===


=== Adding a Variable ===
= For Analyzers... =
== ...Using A TrkAna Tree ==  
If you are using a [[TrkAna]] tree for your analysis, then there are two useful leaves that you can apply cuts to:
* '''dequal.TrkQual'''
* '''dequal.TrkQualCalib'''
which are the uncalibrated and calibrated output values respectively. Note that it is probably best to use the calibrated value, since the effect of this ''should'' stay the same even if the underlying training changes.


== A Worked Example ==
If you have configured the TrackAnalysisReco module correctly, then you may also have the branch:
For a worked example see [[TrkAna_Tutorial_Session#Exercise_3:_Retraining_TrkQual|this TrkAna tutorial exercise]]
* '''detrkqual'''
which contains all the input variables that were available to be trained on. Note that it is possible for some trainings to "comment-out" input variables and so it is best not to assume that ''all'' the input variables seen in this branch were used...


== How To Calibrate TrkQual ==
== ...Using An Art Module... ==
If you are using an art module for your analysis, then there are two data products you can use:
* '''RecoQual''', which contains the uncalibrated and calibrated output values; or,
* '''TrkQual''', which contains the values of the input variables and the uncalibrated output value.
 
Note that <code>RecoQual</code> is a general data product that can exist for other ANNs too (e.g. [[TrkPID]])
 
=== ...And RecoQual Collection ===
You can grab the <code>RecoQualCollection</code> like so:
<nowiki>auto recoQualCollsH = event.getValidHandle<RecoQualCollection>(_inputTag);
</nowiki>
 
where <code>_inputTag</code> is the <code>art::InputTag</code> for the module that produced the <code>RecoQualCollection</code> (e.g. <code>TrkQualDeM</code>).
 
You can then get the output value for each RecoQual object like this:
<nowiki>for(const auto& i_recoQual : *recoQualCollsH) {
  std::cout << "TrkQual Uncalibrated Output = " << i_trkQual._value << std::endl;
  std::cout << "TrkQual Calibrated Output = " << i_trkQual._calib << std::endl;
}
</nowiki>
Note that this is the ''uncalibrated'' output value.
=== ...And TrkQualCollection ===
You can grab the <code>TrkQualCollection</code> like so:
<nowiki>auto trkQualCollsH = event.getValidHandle<TrkQualCollection>(_inputTag);
</nowiki>
 
where <code>_inputTag</code> is the <code>art::InputTag</code> for the module that produced the <code>TrkQualCollection</code> (e.g. <code>TrkQualDeM</code>).
 
You can then get the output value for each TrkQual object like this:
<nowiki>for(const auto& i_trkQual : *trkQualCollsH) {
  std::cout << "TrkQual Output = " << i_trkQual.MVAOutput() << std::endl;
}
</nowiki>
Note that this is the ''uncalibrated'' output value.
 
= For Trainers =
 
Note that there is a worked example in [[TrkAna_Tutorial_Session#Exercise_3:_Retraining_TrkQual|this TrkAna tutorial exercise]]
== ...Who Are Retraining TrkQual ==
 
== ...Who Are Training a New TrkQual and... ==
=== ...Are Removing Variables ===
 
=== ...Are Adding Variables ===
 
=== ...Are Other Parameters ===
 
== ...Who Are Calibrating ==

Revision as of 18:30, 10 April 2020

Under Construction

This will be filled out soon!

Introduction

TrkQual is an artificial neural network (ANN) that evaluates the reconstruction quality of tracks. It uses certain reconstructed parameters of the track (e.g. number of hits) to separate "good" tracks from "bad" tracks and is trained on a simulation sample.

There are two classes of users:

  • analyzers: people who use the result of TrkQual in their analyses; and,
  • trainers: people who train and calibrate the TrkQual ANN.

This wiki page tries to guide both groups to accomplish the tasks they need. If this wiki page is lacking (or out of date), then additional help can be found in the usual places (hypernews, Slack, DocDB etc.).

For Everyone

There may be a few different trainings of TrkQual available. Questions to ask:

  • what simulation sample was it trained on?
  • what input variables are used?
  • what definition of good quality and bad quality was used?
  • has the output been calibrated?

Calibration

For Analyzers...

...Using A TrkAna Tree

If you are using a TrkAna tree for your analysis, then there are two useful leaves that you can apply cuts to:

  • dequal.TrkQual
  • dequal.TrkQualCalib

which are the uncalibrated and calibrated output values respectively. Note that it is probably best to use the calibrated value, since the effect of this should stay the same even if the underlying training changes.

If you have configured the TrackAnalysisReco module correctly, then you may also have the branch:

  • detrkqual

which contains all the input variables that were available to be trained on. Note that it is possible for some trainings to "comment-out" input variables and so it is best not to assume that all the input variables seen in this branch were used...

...Using An Art Module...

If you are using an art module for your analysis, then there are two data products you can use:

  • RecoQual, which contains the uncalibrated and calibrated output values; or,
  • TrkQual, which contains the values of the input variables and the uncalibrated output value.

Note that RecoQual is a general data product that can exist for other ANNs too (e.g. TrkPID)

...And RecoQual Collection

You can grab the RecoQualCollection like so:

auto recoQualCollsH = event.getValidHandle<RecoQualCollection>(_inputTag);
 

where _inputTag is the art::InputTag for the module that produced the RecoQualCollection (e.g. TrkQualDeM).

You can then get the output value for each RecoQual object like this:

for(const auto& i_recoQual : *recoQualCollsH) {
  std::cout << "TrkQual Uncalibrated Output = " << i_trkQual._value << std::endl;
  std::cout << "TrkQual Calibrated Output = " << i_trkQual._calib << std::endl;
}
 

Note that this is the uncalibrated output value.

...And TrkQualCollection

You can grab the TrkQualCollection like so:

auto trkQualCollsH = event.getValidHandle<TrkQualCollection>(_inputTag);
 

where _inputTag is the art::InputTag for the module that produced the TrkQualCollection (e.g. TrkQualDeM).

You can then get the output value for each TrkQual object like this:

for(const auto& i_trkQual : *trkQualCollsH) {
  std::cout << "TrkQual Output = " << i_trkQual.MVAOutput() << std::endl;
}
 

Note that this is the uncalibrated output value.

For Trainers

Note that there is a worked example in this TrkAna tutorial exercise

...Who Are Retraining TrkQual

...Who Are Training a New TrkQual and...

...Are Removing Variables

...Are Adding Variables

...Are Other Parameters

...Who Are Calibrating