[zichunhao]

Summary

• corrections.JECs builds the AK4 and AK8 jet factories of every Run 3 year (2022-2025) from the official JME correctionlib files on CVMFS (/cvmfs/cms-griddata.cern.ch/cat/metadata/JME/, dated folders pinned in cat_jerc), with the coffea 0.7 adapters of processors/jec_clib.py that 2024 and 2025 already use. No text files for Run 3: the compiled text-file JECs are read for Run 2 only.
• Versions (the newest on CVMFS):

year	before (text files)	now (correctionlib)
2022, 2022EE	Summer22(EE)_22Sep2023_V2, JER JRV1	Summer22(EE)_22Sep2023_V4, JER JRV2
2023, 2023BPix	Summer23(BPix)Prompt23_V1, JER JRV1	Summer23(BPix)Prompt23_V4, JER RunCv1234_JRV3 / RunD_JRV3
2024	Summer24Prompt24_V5, JER JRV2 (correctionlib)	unchanged
2025	Summer24Prompt25_V3, JER JRV2 (correctionlib)	unchanged

• Data: the residuals of these versions are run dependent, so jec_clib passes the run number per jet instead of picking a per-era stack by dataset name.
• MET (third and fourth commits): the Type-1 PUPPI MET is recomputed from RawPuppiMET with the re-applied AK4 PUPPI JECs, for data and MC, with its JES, JER and unclustered-energy variations (section below).
• JES/JER of the other BDT inputs (last two commits): the AK4 jets away from the bb jets and the VBF jet mass get JES/JER-shifted columns, and the shifted BDT inputs of postprocessing read them and the shifted MET (section below).

Relation to DAZSLE/hbb-run3#74

Same approach as DAZSLE/hbb-run3#74: the official JSON files with the same versions, and the compound L1L2L3Res correction fed into coffea's CorrectedJetsFactory. There the stack is coffea's CorrectionLibJECStack (newer coffea); our coffea 0.7 has no such class, so jec_clib.py provides the equivalent adapters. The data corrections take the run number as an input, which jec_clib passes per jet; the MC stack keeps the total JES uncertainty and the JER scale-factor variations.

Effect on 2022 and 2023

Jets of the first 20,000 events of a 2022 HH4b MC file, a 2022C JetHT, a 2023 HH4b (κλ = 5) MC and a 2023Cv1 JetMET0 file, corrected with the old code and the new one, with the call of bbbbSkimmer:

check	2022 MC	2022 data	2023 MC	2023 data
method: text-file JEC against correctionlib of the same version, max relative difference AK8 / AK4	3.1e-07 / 1.7e-06	1.4e-06 / 3.4e-06	3.0e-06 / 9.6e-07	3.3e-06 / 1.0e-06
JEC factor new / old, AK8	1.0000	1.0000	1.0000	1.0000
JEC factor new / old, AK4	1.0000; only 4.25 < |η| < 4.5: −0.03%	1.0000; only 4.25 < |η| < 4.5: −0.18%	1.0000	1.0000; raw pT 15-30 GeV at 1.3 < |η| < 2.5: median −1.1% (−0.6% to −1.7% per η bin)
total JES uncertainty (median), old / new	AK8 0.78% / 0.78%, AK4 2.57% / 2.57%	not applied to data	AK8 0.78% / 0.78%, AK4 2.81% / 2.81%	not applied to data
JER factor of gen-matched jets (median), old / new	AK8 1.0018 / 1.0018, AK4 1.0009 / 1.0009	not applied to data	AK8 1.0012 / 1.0012, AK4 1.0001 / 1.0001	not applied to data

• The switch of method is exact (a few 1e-6).
• The update to V4 leaves the AK8 jets unchanged in MC and data. AK4 jets move only in the most forward 2022 bin (below 0.2%) and at low pT in 2023 data (about −1%, which reaches the 25-30 GeV VBF-jet candidates). The JES uncertainty and the JER smearing are unchanged.
• So 2022, 2022EE and 2023BPix need no rerun for the JEC switch alone. The 2023 Run C v4 data do: the text-file path picked 2023_runCv4 only if Run2023Cv4 is in the dataset name, which JetMET_Run2023C-22Sep2023_v4-v1 never matches, so all Run C v4 files (56% of the 2023 pre-BPix JetMET files) got the Run C v1-3 residuals. The V4 data correction is 4.5% (raw pT 50 GeV) to 5.8% (600 GeV) higher for central AK4 jets at run 368000 (v4) than at run 367300 (v1-3); in the skims the AK8 pT is 0.956 and the AK4 pT 0.963 of the NanoAOD values (2023BPix: 1.0001). The GloParT-v3 masses come from the NanoAOD raw mass and are unaffected. With the run passed per jet this is fixed.

Type-1 PUPPI MET with the re-applied JECs

• Before: the data MET went through coffea's CorrectedMETFactory, which in coffea <= 0.7.26 (we pin 0.7.21) adds the change of the jet pT relative to the raw pT with the wrong sign. Applied on top of the Type-1 PuppiMET, it undid the Type-1 correction (data MET close to RawPuppiMET), while MC kept NanoAOD PuppiMET. NanoAOD PuppiMET itself carries the Type-1 correction of the production JECs, not of the JECs the skimmer re-applies. In the 2024C sidebands the Type-1 data MET changes the data above BDT score 0.5 by −3.9% (data-driven QCD BDT) and −2.7% (MC QCD BDT).
• Now (jec_clib.type1_puppi_met, corrections.JECs.type1_puppi_met): for the correctionlib years, i.e. all of Run 3 with this PR, the MET is recomputed from RawPuppiMET with the re-applied AK4 PUPPI JECs, as CMSSW's PFJetMETcorrInputProducer does for PUPPI: every Jet and CorrT1METJet with muon-subtracted corrected pT > 15 GeV and EM fraction < 0.9 shifts it by −(f_L1L2L3Res − f_L1) × the muon-subtracted raw pT, unsmeared, for data and MC alike. MET_pt and the new MET_phi hold it; PuppiMET_pt/phi and RawPuppiMET_pt/phi are saved as well. ttSkimmer gets the same MET.
• Variations (MC): MET_pt/MET_phi for JES_up/down, JER_up/down and UES_up/down, and the JES/JER-shifted BDT scores use the shifted MET. They are the variations of the unsmeared Type-1 MET in CMSJMECalculators (gitlab.cern.ch/cms-analysis/general/CMSJMECalculators, Type1METVariationsCalculator with isT1SmearedMET false), the same as the MET_T1 variations of nanoAOD-tools' jetmetUncertainties, for the jets of the Type-1 sum at their corrected pT (muon-subtracted part corrected, muon added back): JES up/down puts each jet (Jet and CorrT1METJet) at that pT × (1 ± the total JES uncertainty there); JER up and down are both the Type-1 MET with the Jets smeared by their nominal smearing factors (the CorrT1METJets unsmeared, as coffea's Type-1 MET does without their factors); UES up/down adds/subtracts NanoAOD PuppiMET's unclustered shift. coffea's Type-1 CorrectedMETFactory scales the jets by the JER-varied over the nominal smeared pT instead, which blows up for jets that the nominal smearing pushes to ~0 GeV (a JER_down MET shift of +724 GeV on average in 2024 ttbar). Against a per-jet loop written after CMSJMECalculators' addVariations, all variations agree to 1e-13 GeV (20,000 2022 and 2024 TTto4Q events); the mean (RMS) shifts there are JES up +0.8 GeV (1.9), JES down −0.7 GeV (1.9), JER +2.2 GeV (5.7 in 2024, 6.4 in 2022), UES ±0.2-0.3 GeV (1.3).
• Validation: with the JECs of the production, the recomputed MET reproduces NanoAOD PuppiMET (CMSSW's own Type-1 output) to 0.31 GeV RMS (2024 TTto4Q, 20,000 events) and 0.28 GeV (2022), and it is bit-identical to correct_met of Framework Updates DAZSLE/hbb-run3#74 (coffea's Type-1 CorrectedMETFactory, feat: implement CMS Type-1 MET correction in CorrectedMETFactory scikit-hep/coffea#1537) for the same JECs. With our JECs, recomputed − NanoAOD PuppiMET (mean / RMS): −1.6 / 6.7 GeV in 2024C data, −3.1 / 8.5 GeV in 2024 TTto4Q, −1.8 / 9.8 GeV in 2022C data, −0.05 / 1.7 GeV in 2023 TTto4Q. One-chunk skims of this branch run for 2024 TTto4Q, 2023 JetMET Run C v4 and 2022 TTto4Q.
• A TODO in the code: use coffea's factory once we are on coffea >= 2026.9.0 or a 0.7.x release after 0.7.31; it gives the same nominal and, with the total JES uncertainty passed as jes_uncertainties, the same JES variations, but not this JER variation.
• The MET changes the skims of every year (MET columns, BDT inputs), so it goes with the next re-skim.

JES/JER of the other BDT inputs

• Skimmer (Skimmer: JES/JER of the AK4 jets away from the bb jets and of the VBF jet mass): the skims had no JES/JER-shifted columns for the two AK4 jets away from the bb jets and none for the VBF jet mass, so in every JES/JER variation the BDT inputs H1AK4JetAway1mass and H2AK4JetAway2mass stayed nominal and the VBF dijet mass used the nominal jet masses. The MC signal-region skims now save AK4JetAway{Pt,Mass}_{JES,JER}_{up,down} and VBFJetMass_*, from the AK4 PUPPI JERC of these jets, and the skimmer's shifted BDT scores use them.
• Postprocessing (Postprocessing: JES/JER of the AK4-away jets, the VBF jet mass and the MET in the BDT inputs): hh_vars.jec_vars gets VBFJetMass, AK4JetAwayPt, AK4JetAwayMass and MET_pt, so the shifted BDT inputs (get_var_mapping) use the shifted MET of the section above as well; the v15 BDT config reads the MET through key_map. The shifted columns are loaded with the systematics where the skims have them (utils.load_samples(optional_columns=...)); for skims made before, postprocessing.fill_ak4_jec_shifts derives the shifted VBF jet mass from the shifted VBF pT (the jet factory scales pT and mass by the same factor) and keeps the AK4-away jets and the MET nominal. The unit test of load_run3_samples that checks the requested columns stubs this fill, since its fake frames have no jet columns.
• Checks: on the current 2024 VBF HH skim (114,012 events, no new columns) only VBFjjMass of the shifted inputs changes (0.15% RMS, in the 57% of events with two VBF jets) and the nominal inputs are identical; a one-chunk 2024 TTto4Q skim of this branch writes the new columns and load_run3_samples reads them (each shifted column differs from its nominal for every event with the jet); unit tests: 286 passed. For scale, shifting the MET with the jets changes the JES/JER-shifted ggF BDT score of the 2022-2025 BDT by about 0.001 (JES) and 0.002 (JER) per event on average (one-chunk 2022 and 2024 TTto4Q skims).

Archive

The Run 3 text-file JECs are no longer read, so the second commit moves jec_compiled.pkl.gz, jec_compiled_upto2023BPix.pkl.gz and their builder build_jec.py to src/HH4b/corrections/archive/, with a README on what they contain and which skims used them (e.g. 20260820_glopartv3_v15_signal). corrections/README.md now describes the correctionlib JECs (a version update is a new dated folder and tag in cat_jerc, nothing to build), and the comments that named build_jec.py point to the new path. Run 2 keeps jec_compiled_run2.pkl.gz and build_jec_run2.py; JECs(year) loads for 2022-2025 and 2018.

[zichunhao]

Superseded by #367: the same changes on top of the current main, regrouped into one commit per topic.