Merge pull request cms-sw#20 from cms-trackeralign/jetHtDevelopment

Implementation for JetHT validation
henriettepetersen · May 26, 2021 · e17bbfd · e17bbfd
2 parents f79cedc + 76d718f
commit e17bbfd
Show file tree

Hide file tree

Showing 21 changed files with 4,373 additions and 1 deletion.
diff --git a/Alignment/OfflineValidation/README.md b/Alignment/OfflineValidation/README.md
@@ -112,3 +112,247 @@ The python file returns a list of jobs to the `validateAligments.py` which final
    - make dry and local options (i.e. just don't run any condor command)
 (list from mid-January)
 
+## JetHT validation
+
+### Validation analysis - JetHT_cfg.py
+
+The vast majority of the time in the JetHT validation goes to running the actual validation analysis. This is done with cmsRun using the JetHT_cfg.py configuration file. To configure the analysis in the all-in-one framework, the following parameters can be set in the json/yaml configuration file:
+
+```
+All-in-one:
+
+validations
+    JetHT
+        single
+            myDataset
+```
+
+Variable | Default value | Explanation
+-------- | ------------- | -----------
+dataset | Single test file | A file list containing all analysis files.
+alignments | None | An array of alignment sets for which the validation is run.
+trackCollection     | "ALCARECOTkAlMinBias" | Track collection used for the analysis.
+maxevents     | 1 | Maximum number of events before cmsRun terminates.
+iovListFile  | "nothing" | File containing a list of IOVs one run boundary each line.
+iovListList     | [0,500000] | If iovListFile is not defined, the IOV run boundaries are read from this array.
+triggerFilter    | "nothing" | HLT trigger filter used to filter the events selected for the analysis.
+printTriggers    | false | Print all available triggers to console. Set true only for local tests.
+mc | false | Flag for Monte Carlo. Use true for MC and false for data.
+profilePtBorders | [3,5,10,20,50,100] | List for pT borders used in wide pT bin profiles. Also the trend plots are calculated using these pT borders. If changed from default, the variable widePtBinBorders for the jetHtPlotter needs to be changed accordingly to get legends for trend plots correctly and avoid segmentation violations. This is done automatically by the all-in-one configuration.
+TrackerAlignmentRcdFile | "nothing" | Local database file from which the TrackerAlignmentRcd is read. Notice that usual method to set this is reading from the database for each alignment.
+TrackerAlignmentErrorFile | "nothing" | Local database file from which the TrackerAlignmentExtendedErrorRcd is read. Notice that usual method to set this is reading from the database for each alignment.
+
+### File merging - addHistograms.sh
+
+The addHistograms.sh script is used to merge the root files for jetHT validation. Merging is fast and can easily be done locally in seconds, but the tool is fully integrated to the all-in-one configuration for automated processing.
+
+The instructions for standalone usage are:
+
+```
+addHistograms.sh [doLocal] [inputFolderName] [outputFolderName] [baseName]
+doLocal = True: Merge local files. False: Merge files on CERN EOS
+inputFolderName = Name of the folder where the root files are
+outputFolderName = Name of the folder to which the output is transferred
+baseName = Name given for the output file without .root extension
+```
+
+In use with all-in-one configuration, the following parameters can be set in the json/yaml configuration file:
+
+```
+All-in-one:
+
+validations
+    JetHT
+        merge
+            myDataset
+```
+
+Any number of datasets can be defined.
+
+Variable | Default value | Explanation
+-------- | ------------- | -----------
+singles    | None | An array of single job names that must be finished before plotting can be run.
+alignments | None | An array of alignment names for which the files are merged within those alignments. Different alignments are kept separate.
+
+
+### Plotting - jetHtPlotter
+
+The tool is originally designed to be used standalone, since the plotting the histograms locally does not take more that tens of second at maximum. But the plotter works also together with the all-in-one configuration. The only difference for user is the structure of the configuration file, that changes a bit between standalone and all-in-one usage.
+
+Below are listed all the variables that can be configured in the json file for the jetHtPlotter macro. If the value is not given in the configuration, the default value is used instead.
+
+```
+Standalone:              All-in-one:
+
+jethtplot                alignments
+    alignments               myAlignment
+        myAlignment
+```
+
+Up to four different alignments can be added for plotting. If more than four alignments are added, only first four are plotted.
+
+Variable | Default value | Explanation
+-------- | ------------- | -----------
+inputFile   |  None | File containing the jetHT validation histograms for myAlignment. All-in-one config automatically uses default file name for merge job. Must be given if using plotter standalone.
+legendText  | "AlignmentN" | Name with which the alignment is referred to in the legend of the drawn figures. For all-in-one configuration, this variable is called "title" instead of "legendText".
+color       | Varies | Marker color used with this alignment
+style       | 20 | Marker style used with this alignment
+
+```
+Standalone:               All-in-one:
+
+jethtplot                 validations
+    drawHistograms            JetHT
+                                  plot
+                                      myDataset
+                                          jethtplot
+                                              drawHistograms      
+```
+
+Select histograms to be drawn for each alignment.
+
+Variable | Default value | Explanation
+-------- | ------------- | -----------
+drawDz       | false |  Draw probe track dz distributions
+drawDzError  | false |  Draw probe track dz error distributions
+drawDxy      | false |  Draw probe track dxy distributions
+drawDxyError | false |  Draw probe track dxy error distributions
+
+```
+Standalone:               All-in-one:
+
+jethtplot                 validations
+    drawProfiles              JetHT
+                                  plot
+                                      myDataset
+                                          jethtplot
+                                              drawProfiles      
+```
+
+Select profile histograms to be drawn for each alignment.
+
+Variable | Default value | Explanation
+-------- | ------------- | -----------
+drawDzErrorVsPt      | false | Draw dz error profiles as a function of pT
+drawDzErrorVsPhi     | false | Draw dz error profiles as a function of phi
+drawDzErrorVsEta     | false | Draw dz error profiles as a function of eta
+drawDzErrorVsPtWide  | false | Draw dz error profiles as a function of pT in wide pT bins
+drawDxyErrorVsPt     | false | Draw dxy error profiles as a function of pT
+drawDxyErrorVsPhi    | false | Draw dxy error profiles as a function of phi
+drawDxyErrorVsEta    | false | Draw dxy error profiles as a function of eta
+drawDxyErrorVsPtWide | false | Draw dxy error profiles as a function of pT in wide pT bins
+
+```
+Standalone:               All-in-one:
+
+jethtplot                 validations
+    profileZoom               JetHT
+                                  plot
+                                      myDataset
+                                          jethtplot
+                                              profileZoom     
+```
+
+Axis zooms for profile histograms.
+
+Variable | Default value | Explanation
+-------- | ------------- | -----------
+minZoomPtProfileDz       | 28 | Minimum y-axis zoom value for dz error profiles as a function of pT
+maxZoomPtProfileDz       | 60 | Maximum y-axis zoom value for dz error profiles as a function of pT
+minZoomPhiProfileDz      | 45 | Minimum y-axis zoom value for dz error profiles as a function of phi
+maxZoomPhiProfileDz      | 80 | Maximum y-axis zoom value for dz error profiles as a function of phi
+minZoomEtaProfileDz      | 30 | Minimum y-axis zoom value for dz error profiles as a function of eta
+maxZoomEtaProfileDz      | 95 | Maximum y-axis zoom value for dz error profiles as a function of eta
+minZoomPtWideProfileDz   | 25 | Minimum y-axis zoom value for dz error profiles as a function of pT in wide pT bins
+maxZoomPtWideProfileDz   | 90 | Maximum y-axis zoom value for dz error profiles as a function of pT in wide oT bins
+minZoomPtProfileDxy      | 7 | Minimum y-axis zoom value for dxy error profiles as a function of pT
+maxZoomPtProfileDxy      | 40 | Maximum y-axis zoom value for dxy error profiles as a function of pT
+minZoomPhiProfileDxy     | 40 | Minimum y-axis zoom value for dxy error profiles as a function of phi
+maxZoomPhiProfileDxy     | 70 | Maximum y-axis zoom value for dxy error profiles as a function of phi
+minZoomEtaProfileDxy     | 20 | Minimum y-axis zoom value for dxy error profiles as a function of eta
+maxZoomEtaProfileDxy     | 90 | Maximum y-axis zoom value for dxy error profiles as a function of eta
+minZoomPtWideProfileDxy  | 20 | Minimum y-axis zoom value for dxy error profiles as a function of pT in wide pT bins
+maxZoomPtWideProfileDxy  | 80 | Maximum y-axis zoom value for dxy error profiles as a function of pT in wide pT bins
+
+```
+Standalone:               All-in-one:
+
+jethtplot                 validations
+    drawTrends                JetHT
+                                  plot
+                                      myDataset
+                                          jethtplot
+                                              drawTrends     
+```
+
+Select trend histograms to be drawn for each alignment.
+
+Variable | Default value | Explanation
+-------- | ------------- | -----------
+drawDzError  | false | Draw the trend plots for dz errors
+drawDxyError | false | Draw the trend plots for dxy errors
+
+```
+Standalone:               All-in-one:
+
+jethtplot                 validations
+    trendZoom                 JetHT
+                                  plot
+                                      myDataset
+                                          jethtplot
+                                              trendZoom     
+```
+
+Axis zooms for trend histograms.
+
+Variable | Default value | Explanation
+-------- | ------------- | -----------
+minZoomDzTrend   | 20 | Minimum y-axis zoom value for dz error trends
+maxZoomDzTrend   | 95 | Maximum y-axis zoom value for dz error trends
+minZoomDxyTrend  | 10 | Minimum y-axis zoom value for dxy error trends
+maxZoomDxyTrend  | 90 | Maximum y-axis zoom value for dxy error trends
+
+```
+Standalone:               All-in-one:
+
+jethtplot                 validations
+                              JetHT
+                                  plot
+                                      myDataset
+                                          jethtplot    
+```
+
+All the remaining parameters
+
+Variable | Default value | Explanation
+-------- | ------------- | -----------
+drawTrackQA            | false | Draw the track QA plots (number of vertices, tracks per vertex, track pT, track phi, and track eta).
+drawYearLines          | false | Draw vertical lines to trend plot marking for example different years of data taking.
+runsForLines           | [0] | List of run numbers to which the vertical draws in the trend plots are drawn.
+lumiPerIovFile         | "lumiPerRun_Run2.txt" | File containing integrated luminosity for each IOV.
+drawPlotsForEachIOV    | false | true: For profile plots, draw the profiles separately for each IOV defined in the lumiPerIovFile. false: Only draw plots integrated over all IOVs.
+nIovInOnePlot          | 1 | Number of successive IOV:s drawn in a single plot is profile plots are drawn for each IOV.
+useLuminosityForTrends | true | true: For trend plots, make the width of the x-axis bin for each IOV proportional to the integrated luminosity within that IOV. false: Each IOV has the same bin width in x-axis.
+skipRunsWithNoData     | false | true: If an IOV defined in lumiPerIovFile does not have any data, do not draw empty space to the x-axis for this IOV. false: Draw empty space for IOV:s with no data.
+widePtBinBorders       | [3,5,10,20,50,100] | List for pT borders used in wide pT bin profiles. Also the trend plots are calculated using these pT borders. This needs to be set to same value as the profilePtBorders variable used in the corresponding validation analysis. The all-in-one config does this automatically for you.
+normalizeQAplots       | true | true: For track QA plots, normalize each distribution with its integral. false: No normalization for QA plots, show directly the counts.
+makeIovlistForSlides   | false | true: Create a text file to be used as input for prepareSlides.sh script for making latex presentation template with profile plots from each IOV. false: Do not do this.
+iovListForSlides       | "iovListForSlides.txt" | Name given to the above list.
+saveComment            | "" | String of text added to all saved figures.
+
+```
+All-in-one:
+
+validations
+    JetHT
+        plot
+            myDataset
+```
+
+Parameters only used in all-in-one tool. Any number of datasets can be defined.
+
+Variable | Default value | Explanation
+-------- | ------------- | -----------
+merges     | None | An array of merge job names that must be finished before plotting can be run.
+alignments | None | An array of alignment names that will be plotted.
+
diff --git a/Alignment/OfflineValidation/bin/BuildFile.xml b/Alignment/OfflineValidation/bin/BuildFile.xml
@@ -13,3 +13,4 @@
 <bin name="DMRtrends" file="DMRtrends.cc" />
 <bin name="SplitVmerge" file="SplitVmerge.cc,Options.cc" />
 <bin name="GCP" file="GCP.cc,Options.cc" />
+<bin name="jetHtPlotter" file="jetHtPlotter.cc,JetHtPlotConfiguration.cc,Options.cc" />