From 69e31b1cfc29d78129dcaab958031d97cf60e4ee Mon Sep 17 00:00:00 2001 From: Daniel Hundhausen Date: Wed, 27 Mar 2024 13:31:20 +0100 Subject: [PATCH] update docs --- docs/object-performance.md | 47 +++++++++++++------------------------- docs/objects.md | 40 ++++++++++++++++++++++++++++++++ docs/rate_table.md | 4 ++++ 3 files changed, 60 insertions(+), 31 deletions(-) create mode 100644 docs/objects.md diff --git a/docs/object-performance.md b/docs/object-performance.md index eb202bff..dfacfec9 100644 --- a/docs/object-performance.md +++ b/docs/object-performance.md @@ -1,6 +1,6 @@ # Object Performance Tools - The tools present in this folder allow the user to produce + The object performance tools allow the user to produce matching efficiency, turn-on curves, and scaling plots for the various L1 objects under test. The definition of each object to be tested is detailed in @@ -8,7 +8,7 @@ A detailed description of each step, together with instructions on how to set up the configuration files for the cache and plotting steps, is given in [the Wiki pages](https://github.com/cms-l1-dpg/Phase2-L1MenuTools/wiki). - The following presents the minimal set of commands to be run to produce the standard set of validation plots (cf. [these slides](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf)). + The following presents the commands to be run to produce the standard set of validation plots (cf. [these slides](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf)). ## Table of content @@ -23,46 +23,31 @@ This is done by running: ``` - ./src/cache_objects.py cfg_caching/V22.yaml + cache_objects ``` - This step needs to be run only once per configuration (unless changes in the input L1 ntuples occur) and the `.parquet` files generated by the code can be used for all the subsequent steps of the workflow, without having to open the `.root` files and load the objects every time the framework is run. + An example for a caching config can be found at `configs/V29/caching.yaml`. + The output of this step is saved to `cache`. The repository by default includes a symlink to a directory which should already contain most of the desireable object caches. + This step needs to be run only once per configuration (unless changes in the input L1 ntuples occur) and the `.parquet` files generated by the code can be used for all the subsequent steps of the workflow, + without having to open the `.root` files and load the objects every time the framework is run. ## Efficiency and Scalings - The `plotter.py` script can be used to produce matching efficiencies, turn-on curves, and L1 scaling plots. It can be run with + To produce matching efficiencies, turn-on curves, and L1 scalings run ``` - ./src/plotter.py cfg_plots/.yaml + object_performance ``` -### Reference config files - - The following config files (`.yaml`) are available in the `cfg_plots` folder: - - * `electron_iso.yaml`: to produce trigger [efficiency vs L1 isolation plots](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf#page=57) for electrons. Plot used to estimate EG working points. - - * `electron_matching.yaml` and `electron_matching_eta.yaml`: to produce [electrons matching efficiency plots](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf#page=21) as a function of transverse momentum (in barrel and endcaps) and pseudorapidity (in low and high-transverse momentum range). - - * `electron_trigger.yaml`: to produce [trigger efficiency (turn-on) plots](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf#page=22) for electrons (EGamma objects). - - * `muon_matching.yaml` and `muon_matching_eta.yaml`: to produce [muons matching efficiency plots](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf#page=21) as a function of transverse momentum (in barrel and endcaps) and pseudorapidity (in low and high-transverse momentum range). + The production of the scalings is a prerequisite for the generation of + offline rate plots as well as the rate table. It is possible to use + wildcards (e.g. `*_trigger.yaml`) to run multiple configs in succession. - * `muon_trigger.yaml`: to produce [trigger efficiency (turn-on) plots](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf#page=22) for muons. - - * `tau_matching.yaml`: to produce [tau matching efficiency plots](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf#page=26) as a function of transverse momentum (in barrel and endcaps). - - * `tau_matching_GG_VBF.yaml`: to produce [tau matching efficiency plots](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf#page=26) as a function of transverse momentum (in barrel and endcaps) for HH and H taus. - - * `tau_trigger.yaml`: to produce [trigger efficiency (turn-on) plots](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf#page=27) for taus. - - * `jets_matching_eta.yaml`: to produce [jets matching efficiency plots](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf#page=31) as a function of transverse pseudorapidity (in low and high-transverse momentum range). - - * `jets_trigger.yaml`: to produce [trigger efficiency (turn-on) plots](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf#page=32) for jets. +### Reference config files - * `met_ht_mht_trigger.yaml`: to produce [trigger efficiency (turn-on) plots](https://twiki.cern.ch/twiki/pub/CMS/PhaseIIL1TriggerMenuTools/Phase2Menu_validation123x-3.pdf#page=36) for MHT, HT, and MET. + Default configuration files are contained in `configs` and should be used as + templates for custom configurations. - When the plotter is run with the `*_trigger.yaml` config files as input, scaling plots will be produced in addition to the L1 turn-on efficiency plots. - The points used for the calculation of the scalings correspond to the list of threshold cuts defined in [`scaling_thresholds`](https://github.com/bonanomi/Phase2-L1MenuTools/blob/main/objectPerformance/cfg_plots/scaling_thresholds.yaml). + The points used for the calculation of the scalings correspond to the list of threshold cuts defined in [`scaling_thresholds`](https://github.com/cms-l1-dpg/Phase2-L1MenuTools/blob/main/configs/scaling_thresholds.yaml). The outputs will be written to the `outputs/` directory, where `` is the version of the ntuples used for the plots as specified in the `.yaml` config file (more details on the config file are given below). In the current version of the code, the plots will be saved in three folders under `outputs/`: diff --git a/docs/objects.md b/docs/objects.md new file mode 100644 index 00000000..e0ad8508 --- /dev/null +++ b/docs/objects.md @@ -0,0 +1,40 @@ +# Objects + +The objects for both the performance and the rate studies are defined +centrally, by default at + +``` +configs//objects +``` + +All objects found in yaml files in this directory will be found by +the code. + +## Object configuration +Below is an example for an object definition. The outermost key (`gmtMuon`) +references the name of the object in the NTuples. Then `ids` can be defined. +All other key-value pairs at the top level of the definition (`label`, +`match_dR` etc.) are merely defaults that are overwritten by whatever is +defined in a specific id. In addition `eta_ranges` defines the detector regions +on which `cuts` can be defined in the `ids`, e.g. the `oldRateID` applies a cut +on `quality` only in the `overlap` region, which is defined in `eta_ranges`. +A default ID is also defined in the example below, which does not add any +cuts or criteria to the default values. + +```yaml +gmtMuon: + label: "GMT Muon" + match_dR: 0.3 + eta_ranges: + inclusive: [0, 7] + barrel: [0, 0.83] + overlap: [0.83, 1.24] + endcap: [1.24, 2.4] + ids: + default: {} + oldRateID: + label: "GMT Muon, Qual>=12 in OMTF" + cuts: + overlap: + - "{quality} >= 12" +``` diff --git a/docs/rate_table.md b/docs/rate_table.md index fba04fa7..4bf85414 100644 --- a/docs/rate_table.md +++ b/docs/rate_table.md @@ -18,3 +18,7 @@ table_fname: "rates_full_Final" For an example on how to construct the menu configuration file, see `configs/V29/rate_table/v29_WITHMUONS_Final_clean_cfg.yml`. + +The scalings for the objects in the menu table are applied automatically +and assume that the have been produced by running `object_performance`, which +saves them to `outputs//object_performance/scalings/`.