 |
ATLAS Offline Software
|
|
ATLAS Offline Software
|
General validation tools for common tracking.
This package contains tools to validate track reconstruction on a common Inner Detector - Muons code basis. It includes tools to fill validation ntuples e.g. with track data. The scheme for filling the ntuple is based on track-wise entries. Every instance of the steering tool (Trk::BasicValidationNtupleTool) can fill an ntuple tree of its own (also in the same ntuple file). This allows to produce one tree e.g. with track data from pattern recognition or simplified simulation and one tree with refitted tracks to compare them with ROOT afterwards.
The ntuples created with the tools of this package can also be used by the stand-alone ROOT applications distributed with this package, namely the <nop>TrackPlotter and <nop>ResidualPulls. The <nop>TrackPlotter allows to plot the track and measurement positions in the InnerDetector to check the performance of track fitters "by hand". <nop>ResidualPulls analyses local position residuals and pulls at each measurement surface, providing a general tool to validate the measurement error calibration and material effect corrections.
The main steering of the ntuple entries is performed by the Trk::BasicValidationNtupleTool, which can book the ntuple, create the tree directory and add basic entries. This tool is also able to write the current record to the ntuple file and start a new entry. One can also use an existing ntuple tree (which has to have the same track-wise structure) and just use the Trk::BasicValidationNtupleTool to add some ntuple variables.
Every entry (track) contains the event number, a track id (numbering the tracks within one event) and an optional iteration index, which can be used if different intermediate results of a track are produced in the refit procedure (see Trk::DeterministicAnnealingFilter for an example). The track id is the same for all tracks generated within one iteration process and reset to 0 every time a new event is started. Perigee parameters and \( \chi^2 \) are filled for every track if available.
For fitter validation especially information about the measurements on the track and the related track states are needed. Therefore the total number of measurements on the track and the number of measurements within a certain sub-detector type are stored. The tool writes array variables with columns for every measurement into the ntuple.
One can give a list of Trk::IValidationNtupleHelperTool for each detector type by joboptions which are called by the Trk::BasicValidationNtupleTool if a measurement of the related detector is found on the track. Those Trk::IValidationNtupleHelperTool can add items to the ntuple and fill special data needed for validation. The Trk::IValidationNtupleHelperTool may also reside in a detector-specific namespace (e.g. InDetFitterValidation) to be able to add information which need a dynamic cast of the Trk::MeasurementBase to the implementations.
Each detector-specific helper tool list may contain several tools and some tools may even be contained in more than one list, if they fill data for different detector types. There exists also a general list, which tools are called for every type of measurement.
The TrkValTools package contains the following classes:
The most convenient way to use the validation ntuple tools is to run the Trk::TrackValidationNtupleWriter algorithm from the TrkValAlgs package, which retrieves a track collection from StoreGate and loops over all contained tracks. It needs a configured instance of the Trk::BasicValidationNtupleTool.
You can also run the Trk::BasicValidationNtupleTool directly by calling it from your own algorithm or tool to write data of complete tracks or add data of measurements successively. An example for this use case is the Trk::DeterministicAnnealingFilter.
For all purposes the python Configurables should be used, since the validation ntuple is aimed at a broad variety of applications and would easily not allow meaningful default configuration.
shall a new ntuple directory be created? If set to False no event data (event no. etc.) will be written and the calling Alg takes care of the Tree. Default: False
filename handler of the ntuple, only applicable if BookNewNtupl is True. Default: /NTUPLES/FILE1
directory to be created or used in the ntuple file, only applicable if BookNewNtupl is Tru\ e. Default: FitterValidation
ntuple tree, only applicable if BookNewNtupl is Tru\ e. Default: Validation
in the case of Trk::CompetingRIOsOnTrack: shall the included RIO_OnTrack with the maximum assignment probability be used for calculations? Default: True
shall the pull be calculated when no covariance matrix for the track state is available? Default: False
tool and instance name of the IUpdator tool to be used to get unbiased track states. If no tool is given (none) the normal track states will be used (and residuals and pulls might be too small). Default: Trk::KalmanUpdator/TrkKalmanUpdator
tool and instance name of the IExtrapolator, aimed at getting Perigee parameters for tracks which do not have it. Default: Trk::Extrapolator/InDetExtrapolator
tool and instance name of the ITrackHoleSearchTool for analysis of track holes and assignment efficiencies. Default: InDet::InDetTrackHoleSearchTool/InDetHoleSearchTool
flag toggling the search for holes and filling of associated variables. Default: true
list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the Pixels. Default: empty
list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the SCT. Default: empty
list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the TRT. Default: empty
list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the MDT. Default: empty
list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the CSC. Default: empty
list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the RPC. Default: empty
list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the TGC. Default: empty
list of Trk::IValidationNtupleHelperTool to be called for every measurement independent from detector technology. Default: empty
IgnoreMissingTrackCovariance shall the pull be calculated when no covariance matrix for the track state is available? Default: False
IgnoreMissingTrackCovarianceForPulls shall the pull be calculated when no covariance matrix for the track state is available? Default: False
filename handler of the ntuple. Default: /NTUPLES
directory to be created or used in the ntuple file. Default: TrackValidation
ntuple tree. Default: TrackDiff
Shall Trk::TrackStateOnSurface of type Outlier be used in the comparison? Default: True
Shall Trk::TrackStateOnSurface of all types be used in the comparison? Default: False
If CompareOutliers and CompareAllTSoS are both set to False only Trk::TrackStateOnSurface which are marked as Measurement are used.
Shall data be written into a ntuple? Default: True
False This paragraph gives a short overview of the ntuple variables provided by the different tools
| RunNumber | run number the track belongs to | long |
| EventNumber | event number the track belongs to | long |
| TrackID | number of the track within the current event | long |
| IterationIndex | iteration index of the track | long |
| nHits | number of measurements on the track (including outliers) | long |
| RecD0 | \( d_0 \) of the Perigee | float |
| RecZ0 | \( z_0 \) of the Perigee | float |
| RecPhi0 | \( \varphi_0 \) of the Perigee | float |
| RecTheta | \( \theta_0 \) of the Perigee | float |
| RecEta | \( \eta \) of the Perigee | float |
| RecQoverP | \( \frac{q}{p} \) of the Perigee | float |
| RecErrD0 | \( \sigma_{d_0} \) of the Perigee | float |
| RecErrZ0 | \( \sigma_{z_0} \) of the Perigee | float |
| RecErrPhi0 | \( \sigma_{\varphi_0} \) of the Perigee | float |
| RecErrTheta | \( \sigma_{\theta_0} \) of the Perigee | float |
| RecErrQoverP | \( \sigma_{\frac{q}{p}} \) of the Perigee | float |
| Chi2overNdof | \( \frac{chi^2}{n_{DoF}} \) | float |
| Ndof | \( n_{DoF} \) | float |
| pullLocX[nHits] | pull in Trk::locX (pay attention: this might be wrong for some detector types), value is set to -1000. for outliers as they usually contain no track parameters | Array<float> |
| pullLocY[nHits] | pull in Trk::locY (pay attention: this might be wrong for some detector types), value is set to -1000. if no second local coordinate exists for the measurement | Array<float> |
| residualLocX[nHits] | residual in Trk::locX (pay attention: this might be wrong for some detector types), value is set to -1000. for outliers | Array<float> |
| residualLocY[nHits] | residual in Trk::locX (pay attention: this might be wrong for some detector types), value is set to -1000. if no second local coordinate exists for the measurement and for outliers | Array<float> |
| DetectorType[nHits] | enum of the detector type | Array<long> |
| outlierFlag[nHits] | flag is set to 1, if the measurement was marked as an outlier | Array<long> |
| nPixelHits | number of measurements in the Pixels | long |
| nSCTHits | number of measurements in the SCT (without outliers) | long |
| nTRTHits | number of measurements in the TRT (without outliers) | long |
| nMDTHits | number of measurements in the MDT (without outliers) | long |
| nCSCHits | number of measurements in the SCS (without outliers) | long |
| nRPCHits | number of measurements in the RPC (without outliers) | long |
| nTGCHits | number of measurements in the TGC (without outliers) | long |
| PixPullPhi[nPixelHits] | pull in \( \varphi \) for Pixel measurements | Array<float> |
| PixPullEta[nPixelHits] | pull in \( \eta \) for Pixel measurements | Array<float> |
| PixResPhi[nPixelHits] | residual in \( \varphi \) for Pixel measurements | Array<float> |
| PixResEta[nPixelHits] | residual in \( \eta \) for Pixel measurements | Array<float> |
| SCTPull[nSCTHits] | pull for SCT measurements (perpendicular to strip direction, therefore just one-dimensional) | Array<float> |
| SCTRes[nSCTHits] | residual for SCT measurements (perpendicular to strip direction) | Array<float> |
| TRTPull[nTRTHits] | pull for TRT measurements | Array<float> |
| TRTRes[nTRTHits] | residual for TRT measurements | Array<float> |
These variables contain only measurements which are not marked as outliers.
| HitX[nHits] | x coordinate of GlobalPosition of the measurement | Array<float> |
| HitY[nHits] | y coordinate of GlobalPosition of the measurement | Array<float> |
| HitZ[nHits] | z coordinate of GlobalPosition of the measurement | Array<float> |
| HitRadius[nHits] | perp() of GlobalPosition of the measurement | Array<float> |
| HitPhi[nHits] | phi() of GlobalPosition of the measurement | Array<float> |
| HitLocal1[nHits] | Trk::locX of the local position of the measurement | Array<float> |
| HitLocal2[nHits] | Trk::locY of the local position of the measurement, value is set to -1000. if no second local coordinate exists for the measurement | Array<float> |
| HitSurfaceX[nHits] | x coordinate (GlobalPosition) of the center of the measurement surface | Array<float> |
| HitSurfaceY[nHits] | y coordinate (GlobalPosition) of the center of the measurement surface | Array<float> |
| HitSurfaceZ[nHits] | z coordinate (GlobalPosition) of the center of the measurement surface | Array<float> |
| HitSurfaceRadius[nHits] | perp() of the center of the measurement surface | Array<float> |
| HitSurfacePhi[nHits] | phi() of the center of the measurement surface | Array<float> |
| HitSurfaceTheta[nHits] | theta() of the center of the measurement surface | Array<float> |
| CompROTnContainedROTs[nHits] | number of contained ROTs in the Trk::CompetingRIOsOnTrack | Array<long> |
| CompROTindexOfMaxAssgnProb[nHits] | index of the ROT with maximum assignment probability in the Trk::CompetingRIOsOnTrack | Array<long> |
| CompROTmaxAssgnProb[nHits] | maximum assignment probability in the Trk::CompetingRIOsOnTrack | Array<float> |
| CompROTcontainedROTsAssgnProbs[nHits][maxContainedROTs] | assignment probabilities of the contained ROTs in the Trk::CompetingRIOsOnTrack | Matrix<long> |
| CompROTcontainedROTsResLocX[nHits][maxContainedROTs] | residuals in Trk::locX of the contained ROTs in the Trk::CompetingRIOsOnTrack | Matrix<long> |
| CompROTcontainedROTsResLocY[nHits][maxContainedROTs] | residuals in Trk::locY of the contained ROTs in the Trk::CompetingRIOsOnTrack, value is set to -1000. if no second local coordinate exists for the measurement | Matrix<long> |
| CompROTcontainedROTsPullLocX[nHits][maxContainedROTs] | pulls in Trk::locX of the contained ROTs in the Trk::CompetingRIOsOnTrack | Matrix<long> |
| CompROTcontainedROTsPullLocY[nHits][maxContainedROTs] | pulls in Trk::locY of the contained ROTs in the Trk::CompetingRIOsOnTrack, value is set to -1000. if no second local coordinate exists for the measurement | Matrix<long> |
All entries are zero for an index, if the measurement was not a Trk::CompetingRIOsOnTrack.
| EventNumber | Number of the event the tracks belong to | int |
| RefTrackPhi0 | Phi0 of the reference track | float |
| RefTrackEta0 | Eta0 of the reference track | float |
| nRefStates | number of reference TSoS for each detector type | int[detTypes] |
| nCompareStates | number of TSoS of the compared track (for each detector type) | int[detTypes] |
| nFakeStates | number of TSoS of the compared track which are not included in the reference track (does not include wrong types), (for each detector type) | int[detTypes] |
| nMissedStates | number of TSoS of the reference track which are not included in the compared track (does not include wrong types, (for each detector type)) | int[detTypes] |
| nWrongType | number of TSoS which have different types in the reference and the compared track (for each detector type) | int[detTypes] |
| nPRD_Mismatches | number of TSoS on the same detector surface which have different Trk::PrepRawData pointers (for each detector type) | int[detTypes] |
| nDriftCircleSignFlips | number of Trk::RIO_OnTrack in the TRT which have flipped drift radii signs | int |
| nRefTypes | number of reference TSoS for each TSoS type | int[tsosTypes] |
| nCompareTypes | number of compared TSoS for each TSoS type | int[tsosTypes] |
| nMissedTypes | number of TSoS which are not on the compared track (for each TSoS type) | int[tsosTypes] |
| nFakeTypes | number of TSoS which are not on the reference track (for each TSoS type) | int[tsosTypes] |
| nDiffs | number of differences found | int |
| DetectorType | detector type in which the difference was found | vector <int>[nDiffs] |
| IsFake | is the difference a fake state? | vector<int> [nDiffs] |
| IsMissing | is the difference a missing state? | vector<int> [nDiffs] |
| IsPRD_Mismatch | is the diff as PRD mismatch? | vector<int> [nDiffs] |
| IsFlippedSign | has the diff flipped sign? | vector<int> [nDiffs] |
| IsNoDriftTime | has the diff !NoDriftTime? | vector<int> [nDiffs] |
| RefIsMeasurement | is reference state a measurement? | vector<int> [nDiffs] |
| RefIsOutlier | is reference state an outlier? | vector<int> [nDiffs] |
| ComparedIsMeasurement | is compared state a measurement? | vector<int> [nDiffs] |
| ComparedIsOutlier | is compared state an outlier? | vector<int> [nDiffs] |
| MaxAssgnProb | just if WriteCompetingROTdata=True: maximum assignment probability of the compared state | vector<float> [nDiffs] |
| SumAssgnProb | just if WriteCompetingROTdata=True: sum of assignment probabilities of the compared state | vector<float> [nDiffs] |
All numbers contain just the Trk::TrackStateOnSurface which have the types selected in the jobOptions, i.e. in the standard configuration only Measurements and Outliers.
Stand-alone ROOT application to plot tracks. The code can be found in the subdirectory root/TrackPlotter of this package; it has to be compiled separately (see below). This application runs on the ValidationNtuple written by the Trk::BasicValidationNtupleTool (from Tracking/TrkValidation/TrkValTools) resp. Trk::TrackValidationNtupleWriter (from Tracking/TrkValidation/TrkValAlgs).
compile this tool by: cd root/TrackPlotter
make trackplotter
to run: ./trackplotter or ./trackplotter TrkValidation.root
This tool needs a correctly set up ROOT installation. If you get the message "cannot run in batch mode", please make sure you have a valid X11 connection.
As ROOT versions and installations may differ on some machines, you may need to recompile the TrackPlotter application, when getting segfaults on a certain machine. You should delete the files trackplotterDict.* (which are recreated by the compiler) and call make clean first.
The TrackPlotter has a config file (trackplotter.conf) which allows to set the ntuple directories and trees. Depending on your runtime setup you may have to change the config file. In the config file you can also activate the plotting of PrepRawData, but in this case you also have to run the related algorithms from the package InDetTrackValidation to fill the RIO data into the ntuple.
1.8.18