Warning, /acts/docs/examples/howto/analysis_apps.rst is written in an unsupported language. File is not indexed.
0001 .. _analysis_apps:
0002
0003 Analysis applications
0004 ================================
0005
0006 The ACTS examples come with a certain variety of ROOT based validation and performance writers,
0007 whose output can be use to understand various aspects of the reconstruction in more detail.
0008
0009 The building of these applications can be switched on by setting ``ACTS_BUILD_ANALYSIS_APPS=On``,
0010 which requires (on top of the Core dependencies) ROOT for the analysis code.
0011
0012 These analysis applications are steered via BOOST program options, hence a quick ``<APP> -h`` will
0013 quickly show the relevant options, they can be executed in silent mode, i.e. without opening
0014 a window, when specifying the `-s` option.
0015
0016 Material Composition Analysis
0017 -----------------------------
0018
0019 This analysis allows to inspect the output of the ``Geant4`` based material recording, and split
0020 the contained material by atomic number in predefined detector regions. For the moment, the detector
0021 regions need to be identified and constraint in the ``rz`` plane.
0022
0023 .. code-block:: console
0024
0025 *** Material Composition plotting
0026 *** Usage::
0027 -h [ --help ] Display this help message
0028 -s [ --silent ] Silent mode (without X-window/display).
0029 -i [ --input ] arg Input ROOT file containing the input TTree.
0030 -t [ --tree ] arg (=material-tracks) Input TTree name.
0031 -o [ --output ] arg Output ROOT file with histograms
0032 -b [ --bins ] arg (=60) Number of bins in eta/phi
0033 -e [ --eta ] arg (=4) Eta range.
0034 --sub-names arg Subdetector names.
0035 --sub-rmin arg Minimal radial restrictions.
0036 --sub-rmax arg Maximal radial restrictions.
0037 --sub-zmin arg Minimal z radial restrictions
0038 --sub-zmax arg Maximal z radial restrictions.
0039
0040 For the output of the material recording, of e.g. the ``OpenDateDetector``, the following command
0041 will create a material composition plot of the entire detector:
0042
0043 .. code-block:: console
0044
0045 $ <build>/bin/ActsAnalysisMaterialComposition \
0046 -i geant4_material_tracks.root \
0047 -t material-tracks \
0048 -o material_composition.root \
0049 --sub-names beampipe detector \
0050 --sub-rmin 0.:0. \
0051 --sub-rmax 30.:1100 \
0052 --sub-zmin -4000.:-4000. \
0053 --sub-zmax 4000.:4000.
0054
0055 The output file ``material_composition.root`` would then contain profile histograms versus pseudorapidity
0056 and azimuthal angle ``phi`` for the radiation length ``X0`` and the nuclear interaction length ``L0``,
0057 restricted to the given `rz` regions, in this case only for the beampipe and the entire detector.
0058
0059 The resulting file contains the following histograms:
0060
0061 .. code-block:: console
0062
0063 KEY: TProfile beampipe_x0_vs_eta_all;1 X_{0} vs. #eta
0064 KEY: TProfile beampipe_l0_vs_eta_all;1 L_{0} vs. #eta
0065 KEY: TProfile beampipe_x0_vs_phi_all;1 X_{0} vs. #phi
0066 KEY: TProfile beampipe_l0_vs_phi_all;1 L_{0} vs. #phi
0067 KEY: TProfile beampipe_x0_vs_eta_A9;1 X_{0} vs. #eta
0068 KEY: TProfile beampipe_l0_vs_eta_A9;1 L_{0} vs. #eta
0069 KEY: TProfile beampipe_x0_vs_phi_A9;1 X_{0} vs. #phi
0070 KEY: TProfile beampipe_l0_vs_phi_A9;1 L_{0} vs. #phi
0071 KEY: TProfile detector_x0_vs_eta_all;1 X_{0} vs. #eta
0072 KEY: TProfile detector_l0_vs_eta_all;1 L_{0} vs. #eta
0073 KEY: TProfile detector_x0_vs_phi_all;1 X_{0} vs. #phi
0074 KEY: TProfile detector_l0_vs_phi_all;1 L_{0} vs. #phi
0075 KEY: TProfile detector_x0_vs_eta_A9;1 X_{0} vs. #eta
0076 KEY: TProfile detector_l0_vs_eta_A9;1 L_{0} vs. #eta
0077 KEY: TProfile detector_x0_vs_phi_A9;1 X_{0} vs. #phi
0078 KEY: TProfile detector_l0_vs_phi_A9;1 L_{0} vs. #phi
0079 KEY: TProfile detector_x0_vs_eta_A12;1 X_{0} vs. #eta
0080 KEY: TProfile detector_l0_vs_eta_A12;1 L_{0} vs. #eta
0081 KEY: TProfile detector_x0_vs_phi_A12;1 X_{0} vs. #phi
0082 KEY: TProfile detector_l0_vs_phi_A12;1 L_{0} vs. #phi
0083 KEY: TProfile detector_x0_vs_eta_A13;1 X_{0} vs. #eta
0084 KEY: TProfile detector_l0_vs_eta_A13;1 L_{0} vs. #eta
0085 KEY: TProfile detector_x0_vs_phi_A13;1 X_{0} vs. #phi
0086 KEY: TProfile detector_l0_vs_phi_A13;1 L_{0} vs. #phi
0087 KEY: TProfile detector_x0_vs_eta_A27;1 X_{0} vs. #eta
0088 KEY: TProfile detector_l0_vs_eta_A27;1 L_{0} vs. #eta
0089 KEY: TProfile detector_x0_vs_phi_A27;1 X_{0} vs. #phi
0090 KEY: TProfile detector_l0_vs_phi_A27;1 L_{0} vs. #phi
0091 KEY: TProfile detector_x0_vs_eta_A28;1 X_{0} vs. #eta
0092 KEY: TProfile detector_l0_vs_eta_A28;1 L_{0} vs. #eta
0093 KEY: TProfile detector_x0_vs_phi_A28;1 X_{0} vs. #phi
0094 KEY: TProfile detector_l0_vs_phi_A28;1 L_{0} vs. #phi
0095 KEY: TProfile detector_x0_vs_eta_A48;1 X_{0} vs. #eta
0096 KEY: TProfile detector_l0_vs_eta_A48;1 L_{0} vs. #eta
0097 KEY: TProfile detector_x0_vs_phi_A48;1 X_{0} vs. #phi
0098 KEY: TProfile detector_l0_vs_phi_A48;1 L_{0} vs. #phi
0099 KEY: TProfile detector_x0_vs_eta_A64;1 X_{0} vs. #eta
0100 KEY: TProfile detector_l0_vs_eta_A64;1 L_{0} vs. #eta
0101 KEY: TProfile detector_x0_vs_phi_A64;1 X_{0} vs. #phi
0102 KEY: TProfile detector_l0_vs_phi_A64;1 L_{0} vs. #phi
0103
0104 Only histograms with non-zero contribution are written out per specified region,
0105 the following shows a resulting stacked histogram showing different components:
0106
0107 .. figure:: figures/analysis_apps/aa_mc_stacked_x0.gif
0108 :width: 500
0109
0110 The source code for this application can be found in ``Examples/Scripts/MaterialMapping``.
0111
0112
0113
0114 Tracking Performance Analysis
0115 -----------------------------
0116
0117 Two different applications are available for analysing the output of track fitting and
0118 track finding, sitting on top of the corresponding ROOT output writers from the Example
0119 applications.
0120
0121
0122 **Residuals and Pull analysis per layer**
0123
0124 To investigate the per layer residual and pull distributions, one can use the
0125 `ActsAnalysisResidualAndPulls` application, which runs on top of the ROOT file
0126 produced by the ``RootTrackStatesWriter``.
0127
0128
0129 The following options are available:
0130
0131 .. code-block:: console
0132
0133 *** ACTS Residual and Pull plotting
0134 *** Usage::
0135 -h [ --help ] Display this help message
0136 -s [ --silent ] Silent mode (without X-window/display).
0137 -i [ --input ] arg Input ROOT file containing the input TTree.
0138 -t [ --tree ] arg (=trackstates) Input TTree name.
0139 -o [ --output ] arg Output ROOT file with histograms
0140 --predicted Analyze the predicted parameters.
0141 --filtered Analyze the filtered parameters.
0142 --smoothed Analyze the smoothed parameters.
0143 --fit Fit the smoothed parameters.
0144 --save arg (=png) Output save format (to be interpreted by
0145 ROOT).
0146
0147 Again, this application is capable of running in silent mode (``-s``) without
0148 opening a dedicated screen window.
0149
0150 Originally designed for the ``Acts::KalmanFilter`` output, it is capable of
0151 producing histograms of the ``--predicted``, ``--filtered`` and ``--smoothed`` track
0152 states (i.e. track parameters) and will do so per layer and volume.
0153
0154 On request (``--fit``) the resulting distributions can be fitted for the summary plots
0155 that are created, otherwise the RMS and its mean are taken.
0156
0157 The application will (by parsing the geometry id range) automatically determine the different
0158 layers and volumes and create detailed and summary plots for all of them.
0159
0160 As a example, the pull distributions for *predicted, filtered* and *smoothed* track states
0161 is shown below.
0162
0163 .. figure:: figures/analysis_apps/aa_rp_layers.png
0164 :width: 500
0165
0166
0167 **Track summary analysis**
0168
0169 A higher level view of the track reconstruction performance is the ``ActsAnalysisTrackSummary`` application,
0170 which runs on top of the `RootTrackSummaryWriter` output of the examples code.
0171
0172 The following options are available:
0173
0174 .. code-block:: console
0175
0176 *** ACTS Perigee parameters and Track summary plotting
0177 *** Usage::
0178 -h [ --help ] Display this help message
0179 -s [ --silent ] Silent mode (without X-window/display).
0180 -n [ --events ] arg (=0) (Optionally) limit number of events to
0181 be processed.
0182 -p [ --peak-events ] arg (=0) (Optionally) limit number of events for
0183 the range peaking.
0184 -i [ --input ] arg Input ROOT file(s) containing the input
0185 TTree.
0186 -t [ --tree ] arg (=tracksummary) Input TTree/TChain name.
0187 -o [ --output ] arg Output ROOT file with histograms
0188 --hist-bins arg (=61) Number of bins for the residual/pull
0189 histograms
0190 --pull-range arg (=5) Number of sigmas for the pull range.
0191 --eta-bins arg (=10) Number of bins in eta.
0192 --eta-range MIN:MAX (=-3:3) Range for the eta bins.
0193 --phi-bins arg (=10) Number of bins in phi.
0194 --phi-range MIN:MAX (=-3.14159:3.14159)
0195 Range for the phi bins.
0196 --pt-borders arg Transverse momentum borders.
0197 --config-output arg (Optional) output histogram
0198 configuration json file.
0199 --config-input arg (Optional) input histogram
0200 configuration json file.
0201 --all Process all residual/pull and auxiliary
0202 parameters
0203 --d0 Residual/pulls for d0
0204 --z0 Residual/pulls for z0
0205 --phi0 Residual/pulls for phi0
0206 --theta0 Residual/pulls for theta0
0207 --qop Residual/pulls for qop
0208 --time Residual/pulls for time
0209 --pt Residual/pulls for pt
0210 --chi2ndf Auxiliary information for chi2ndf
0211 --measurements Auxiliary information for measurements
0212 --holes Auxiliary information for holes
0213 --outliers Auxiliary information for outliers
0214 --shared Auxiliary information for shared
0215
0216 This application is highly configurable and produces residual and pull
0217 (regional, integral and summary) plots for the fitted perigee parameters of track fitting.
0218 It can be run in ```eta,phi,pT``` bins, and as the different histograms in the various bins
0219 will require different histogram ranges, these will be automatically determined.
0220
0221 However, this process is relatively slow and makes comparisons between runs difficult,
0222 thus the range configuration can be written out by specifying a ``--config-output`` JSON file,
0223 and successively re-using it with a ``--config-input`` flag in future analysis runs.
0224
0225 For very large files, the number of entries used for range calculation (peak entries) can be set
0226 using the ``--peak-events`` option.
0227
0228 Some example histograms (transverse impact parameter ``d0`` distribution or a summary plot showing
0229 the number of detector hits, are added below).
0230
0231 .. figure:: figures/analysis_apps/aa_ts_d0.png
0232 :width: 500
0233
0234
0235 .. figure:: figures/analysis_apps/aa_ts_nhits.png
0236 :width: 500
0237
0238
0239
0240 The source code for these applications can be found in ``Examples/Scripts/TrackingPerformance``.
