General validation tools for common tracking.

Author: Andreas.Salzburger -at- cern.ch, Sebastian.Fleischmann -at- cern.ch, Wolfgang.Liebig -at- cern.ch

Introduction

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.

Validation ntuple scheme

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.

Class Overview

The TrkValTools package contains the following classes:

Trk::DirectTrackNtupleWriterTool : Tool to write an ntuple record about a track on the fly to a tree, using the same set of Trk::IValidationNtupleHelperTool s like the Trk::TrackValidationNtupleWriter has.
Trk::PerigeeParametersNtupleTool : Tool to fill a track/trackparticle's parameters and error matrix at the origin, includes possibility to write corresponding truth parameters and pulls.
Trk::TrackInformationNtupleTool : Tool to fill a track/trackparticle's basic information
Trk::MeasurementVectorNtupleTool : Tool to fill a track/trackparticle's hit pattern and parameter trajectory.
Trk::ResidualValidationNtupleHelper : Helper tool for Trk::BasicValidationNtupleTool which writes residual and pull information for Pixels, SCT and TRT using the Trk::ResidualPullCalculator.
Trk::HitPositionNtupleHelper : Helper tool for Trk::BasicValidationNtupleTool which writes statistics about measurement and surface positions.
Trk::TrackPositionNtupleHelper : Helper tool for Trk::BasicValidationNtupleTool which writes info about track positions.
Trk::BremPositionNtupleHelper : Helper tool for Trk::BasicValidationNtupleTool which writes additional info about track states with brem-like material effects.
Trk::DAF_ValidationNtupleHelper : Helper tool for Trk::BasicValidationNtupleTool which writes data from Trk::CompetingRIOsOnTrack.
Trk::TruthNtupleTool : Tool to fill basic information about the truth record. It is called directly by the ntuple writer but provides information also for particles which have failed to be reconstructed. Furthermore it manages indices to link to ntuple entries of the associated reconstructed particles.
Trk::JetTruthNtupleTool : Tool to fill basic information about truth jets. It has link indices to the truth ntuple tree.
Trk::PrimaryTruthClassifier : modular concept to define certain categories of truth particles, this one labels primary, secondary and truncated tracks.
Trk::InDetReconstructableSelector : modular concept of selecting truth particles for the truth tree and efficiency calculation. This one selects generated particles which leave a detectable trace in the Inner Detector.
Trk::GenParticleJetFinder : track-based Durham jet finder, this one acting on truth particles.
Trk::TrackDiff : Tool to compare two tracks (e.g. simulated and reconstructed track). Differences in the Trk::TrackStateOnSurface are listed in the messages and a summary for each track is written to a ntuple.

How to use the tools

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.

jobOptions of the Trk::BasicValidationNtupleTool

BookNewNtuple

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

NtupleFileName

filename handler of the ntuple, only applicable if BookNewNtupl is True. Default: /NTUPLES/FILE1

NtupleDirectoryName

directory to be created or used in the ntuple file, only applicable if BookNewNtupl is Tru\ e. Default: FitterValidation

NtupleTreeName

ntuple tree, only applicable if BookNewNtupl is Tru\ e. Default: Validation

UseROTwithMaxAssgnProb

in the case of Trk::CompetingRIOsOnTrack: shall the included RIO_OnTrack with the maximum assignment probability be used for calculations? Default: True

IgnoreMissingTrackCovarianceForPulls

shall the pull be calculated when no covariance matrix for the track state is available? Default: False

UpdatorTool

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

ExtrapolatorTool

tool and instance name of the IExtrapolator, aimed at getting Perigee parameters for tracks which do not have it. Default: Trk::Extrapolator/InDetExtrapolator

HoleSearchTool

tool and instance name of the ITrackHoleSearchTool for analysis of track holes and assignment efficiencies. Default: InDet::InDetTrackHoleSearchTool/InDetHoleSearchTool

DoHoleSearch

flag toggling the search for holes and filling of associated variables. Default: true

PixelNtupleHelperTools

list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the Pixels. Default: empty

SCTNtupleHelperTools

list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the SCT. Default: empty

TRTNtupleHelperTools

list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the TRT. Default: empty

MDTNtupleHelperTools

list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the MDT. Default: empty

CSCNtupleHelperTools

list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the CSC. Default: empty

RPCNtupleHelperTools

list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the RPC. Default: empty

TGCNtupleHelperTools

list of Trk::IValidationNtupleHelperTool to be called if measurement is identified to be in the TGC. Default: empty

GeneralNtupleHelperTools

list of Trk::IValidationNtupleHelperTool to be called for every measurement independent from detector technology. Default: empty

DoTruth

flag to toggle truth access, allowing validation of tracks on real data with the same ntuple framework. Default: true

jobOptions of the Trk::ResidualValidationNtupleHelper

IgnoreMissingTrackCovariance shall the pull be calculated when no covariance matrix for the track state is available? Default: False

jobOptions of the Trk::DAF_ValidationNtupleHelper

IgnoreMissingTrackCovarianceForPulls shall the pull be calculated when no covariance matrix for the track state is available? Default: False

jobOptions of Trk::TrackDiff

NtupleFileName

filename handler of the ntuple. Default: /NTUPLES

NtupleDirectoryName

directory to be created or used in the ntuple file. Default: TrackValidation

NtupleTreeName

ntuple tree. Default: TrackDiff

CompareOutliers

Shall Trk::TrackStateOnSurface of type Outlier be used in the comparison? Default: True

CompareAllTSoS

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.

WriteNtuple

Shall data be written into a ntuple? Default: True

WriteCompetingROTdata

Shall data about Trk::TrkCompetingRIOsOnTrack be written? Default: False

List of the Ntuple variables

This paragraph gives a short overview of the ntuple variables provided by the different tools

Ntuple variables of the Trk::BasicValidationNtupleTool

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

Ntuple variables of the Trk::ResidualValidationNtupleHelper

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.

Ntuple variables of the Trk::HitPositionNtupleHelper

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>

Ntuple variables of the Trk::DAF_ValidationNtupleHelper

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.

Ntuple variables of Trk::TrackDiff

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.

TrackPlotter

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.