HltEfficiencyChecker docs update for MooreAnalysis!134

doc/tutorials/hltefficiencychecker.rst

@@ -10,7 +10,7 @@ high level trigger, you might like to study the efficiencies, rates and overlaps
 or subset of lines. ``HltEfficiencyChecker`` is a package designed to help you do just that.
 
 In earlier sections of this documentation, you've seen how to run ``Moore`` on some MC samples.
-``HltEfficiencyChecker`` extends this functionality and writes the trigger decisions to a ROOT ntuple.
+``HltEfficiencyChecker`` extends this functionality and writes the trigger decisions to a ROOT nTuple.
 The package then also provides configurable analysis scripts that take the tuple and give you information
 on the rates, efficiencies and overlaps of the line(s) you're interested in. In the case of efficiencies, some MC truth
 information of the kinematics of each event will have also been saved, allowing a configurable
@@ -27,6 +27,14 @@ In this tutorial we will first see how to set up the package in addition to the
 is followed by a set of examples, which increase in complexity. All of these examples are closely based on scripts
 that live in the directory ``MooreAnalysis/HltEfficiencyChecker/options/``.
 
+.. note::
+
+    ``HltEfficiencyChecker`` is best suited to running either a single trigger line, or a small group of
+    lines. If you wish to run more than O(100) lines, the tool will become slow and the amount of output
+    overwhelming. In some cases, it may even `fail <https://gitlab.cern.ch/lhcb/MooreAnalysis/-/issues/33>`_
+    with so many lines. If you wish to do studies of the status of the entire trigger, please take a look at
+    the `UpgradeRateTest <https://lhcbpr-hlt.web.cern.ch/UpgradeRateTest/>`_.
+
 .. note::
 
     Since late July 2020, ``HltEfficiencyChecker`` uses ``Allen`` as the default HLT1 option, to reflect the trigger
@@ -385,6 +393,8 @@ We'll this time follow the example decay of |jpsiPhi-decay|, which has an exampl
         input_raw_format: 4.3
         lines_from: Hlt2Conf.lines.starterkit.bs_to_jpsiphi
         hlt2_configuration: fastest
+        use_old_calo_raw_banks: True
+        muon_decoding_version: 2
         options:
             - $HLTEFFICIENCYCHECKERROOT/options/options_template.py.jinja  # first rendered with jinja2
     analysis:
@@ -403,7 +413,9 @@ thus don't need a decay descriptor.
 
 This time, we need to specify a non-default ``input_raw_format``, and instead of listing a script that configures the lines, we use the
 ``lines_from`` key, which is only supported for HLT2 and does the same job. A HLT2 reconstruction configuration has been chosen
-via the ``hlt2_configuration`` key, which is described more below. Finally, ``script`` now gives the path to the script
+via the ``hlt2_configuration`` key, which is described more below. The ``upgrade_minbias_hlt1_filtered`` sample is quite old (made in 2018-19),
+and the specification of ``use_old_calo_raw_banks`` and ``muon_decoding_version`` is needed to support this older sample - more on this below.
+Finally, ``script`` now gives the path to the script
 that calculates rates, and we inform that script what the input rate of the sample is, which depends on if any filtering (e.g. by HLT1) was
 applied during the creation of the sample. The different input rates you can expect to put here is explained :ref:`below <rate_defns>`).
 ``json`` is the name of a ``.json`` to which the rate will be saved.
@@ -421,6 +433,17 @@ applied during the creation of the sample. The different input rates you can exp
     conditions/expectations. If you wish, you could also use the (very old!) ``Brunel`` reconstruction stored in a ``LDST`` file by
     providing the ``reco_from_file`` key as ``True``, in which case you should not provide the ``hlt2_configuration`` line in the above example.
 
+.. note::
+
+    ``use_old_calo_raw_banks`` asks the HLT2 calorimeter reconstruction to use an old format of the CALO raw banks. MC samples
+    produced with the CondDB tag ``sim-20220614-vc-mu100`` or later (see date in the tag) were produced with the new CALO raw banks.
+    If you have such a sample, just omit the line ``use_old_calo_raw_banks: True`` entirely, and the reconstruction will know to use the
+    new banks by default. Similarly, the ``muon_decoding_version`` has been updated over the years, and is (as of December 2023) at
+    version ``3`` by default. Most older samples require version ``2``. If you provide the wrong version, the muon decoding will crash
+    at runtime, so you will know to add this option. On the other hand, if your file has old CALO raw banks and you do not provide
+    ``use_old_calo_raw_banks: True``, the calorimeter reconstruction will not find the banks - therefore do no CALO reco - **but will not fail**.
+    It's therefore important to get this right if you are reconstructing signals reliant on the calorimeters, for example electrons.
+
 If the above code is put into a script with the path ``MooreAnalysis/HltEfficiencyChecker/options/hlt2_rate_example.yaml``, we can run as
 before::
 
@@ -638,8 +661,8 @@ and an options file defining the input:
     from RecoConf.calorimeter_reconstruction import make_digits
     make_digits.global_bind(calo_raw_bank=False)
 
-    from RecoConf.calorimeter_reconstruction import make_digits
-    make_digits.global_bind(calo_raw_bank=False)
+    from RecoConf.hlt1_muonid import make_muon_hits
+    make_muon_hits.global_bind(geometry_version=2)
 
     from RecoConf.global_tools import stateProvider_with_simplified_geom
     with reconstruction.bind(from_file=False), hlt2_reconstruction.bind(
@@ -701,8 +724,8 @@ The rate of this line can be calculated by first configuring a minimum bias run
     from RecoConf.calorimeter_reconstruction import make_digits
     make_digits.global_bind(calo_raw_bank=False)
 
-    from RecoConf.calorimeter_reconstruction import make_digits
-    make_digits.global_bind(calo_raw_bank=False)
+    from RecoConf.hlt1_muonid import make_muon_hits
+    make_muon_hits.global_bind(geometry_version=2)
 
     from RecoConf.global_tools import stateProvider_with_simplified_geom
     with reconstruction.bind(from_file=False), hlt2_reconstruction.bind(
@@ -1066,7 +1089,6 @@ to ``utils.py`` will define the new denominator. In the "wizard" case, use the `
         script: $HLTEFFICIENCYCHECKERROOT/scripts/hlt_line_efficiencies.py
         args:
             input: *NTUPLE
-            level: Hlt1
             reconstructible_children: muplus,muminus,Kplus,Kminus
             legend_header: "B^{0}_{s} #rightarrow J/#psi #phi"
             make_plots: true