update docs

docs/object-performance.md

@@ -1,14 +1,14 @@
 # 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
   this [TWiki page](https://twiki.cern.ch/twiki/bin/view/CMS/PhaseIIL1TriggerMenuTools).
 
   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 <path_to_config>
   ```
 
-  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/<PLT_CONFIG>.yaml 
+  object_performance <path_to_config>
   ```
 
-### Reference config files
-
-  The following config files (`<PLT_CONFIG>.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/<VERSION>` directory, where `<VERSION>` 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/<VERSION>`:

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/<VERSION>/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"
+```

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/<version>/object_performance/scalings/`.