jets

`jets`#

Jet energy corrections and jet resolution smearing.

Summary#

`get_evaluators`(correction_set, names)	Helper function to get a list of correction evaluators from a `correctionlib.highlevel.CorrectionSet` object given a list of names.
`ak_evaluate`(evaluator, *args)	Evaluate a `correctionlib.highlevel.Correction` using one or more as inputs.
`jec`(*args[, requires_func, setup_func, ...])

Functions#

get_evaluators(correction_set, names)[source]#

Helper function to get a list of correction evaluators from a correctionlib.highlevel.CorrectionSet object given a list of names. The names can refer to either simple or compound corrections.

Parameters:

correction_set (CorrectionSet) – evaluator provided by correctionlib
names (list[str]) – List of names of corrections to be applied

Raises:

RuntimeError – If a requested correction in names is not available

Return type:

list[Any]

Returns:

List of compounded corrections, see correctionlib.highlevel.CorrectionSet

ak_evaluate(evaluator, *args)[source]#

Evaluate a correctionlib.highlevel.Correction using one or more as inputs.

Parameters:: evaluator (Correction) – Evaluator instance
Raises:: ValueError – If no are provided
Return type:: float
Returns:: The correction factor derived from the input arrays

Calibrators#

class jets(*args, requires_func=<law.util.NoValue object>, setup_func=<law.util.NoValue object>, sandbox=<law.util.NoValue object>, call_force=<law.util.NoValue object>, inst_dict=None, **kwargs)[source]#

Bases: Calibrator

call_func(events, **kwargs)#

Instance of Calibrator that does all relevant calibrations for jets, i.e. JEC and JER. For more information, see jec() and jer().

Parameters:: events (Array) – awkward array containing events to process
Return type:: Array

data_only = False#

get_jec_config = None#

get_jec_file = None#

get_jer_config = None#

get_jer_file = None#

init_func()#

Return type:: None

mc_only = False#

nominal_only = False#

produces = {<class 'columnflow.calibration.cms.jets.jec'>, <class 'columnflow.calibration.cms.jets.jer'>}#

propagate_met = None#

shifts_only = None#

uses = {<class 'columnflow.calibration.cms.jets.jec'>, <class 'columnflow.calibration.cms.jets.jer'>}#

class jec(*args, requires_func=<law.util.NoValue object>, setup_func=<law.util.NoValue object>, sandbox=<law.util.NoValue object>, call_force=<law.util.NoValue object>, inst_dict=None, **kwargs)[source]#

Bases: Calibrator

call_func(events, min_pt_met_prop=15.0, max_eta_met_prop=5.2, **kwargs)#

Performs the jet energy corrections and uncertainty shifts using the correctionlib, optionally propagating the changes to the MET.

Requires an external file in the config under jet_jerc:

cfg.x.external_files = DotDict.wrap({
    "jet_jerc": "/afs/cern.ch/user/m/mrieger/public/mirrors/jsonpog-integration-f018adfb/POG/JME/2017_UL/jet_jerc.json.gz",
})

get_jec_file can be adapted in a subclass in case it is stored differently in the external files

The jec configuration should be an auxiliary entry in the config, specifying the correction details under “jec”:

cfg.x.jec = {
    "campaign": "Summer19UL17",
    "version": "V5",
    "jet_type": "AK4PFchs",
    "levels": ["L1L2L3Res"],  # or individual correction levels
    "levels_for_type1_met": ["L1FastJet"],
    "uncertainty_sources": [
        "Total",
        "CorrelationGroupMPFInSitu",
        "CorrelationGroupIntercalibration",
        "CorrelationGroupbJES",
        "CorrelationGroupFlavor",
        "CorrelationGroupUncorrelated",
    ]
}

get_jec_config can be adapted in a subclass in case it is stored differently in the config.

If running on data, the datasets must have an auxiliary field jec_era defined, e.g. “RunF”, or an auxiliary field era, e.g. “F”.

This instance of Calibrator is initialized with the following parameters by default:

Parameters:

events (Array) – awkward array containing events to process
min_pt_met_prop (float, default: 15.0) – If propagate_met variable is True propagate the updated jet values to the missing transverse energy (MET) using propagate_met() for events where met.pt > *min_pt_met_prop*.
max_eta_met_prop (float, default: 5.2) – If propagate_met variable is True propagate the updated jet values to the missing transverse energy (MET) using propagate_met() for events where met.eta > *min_eta_met_prop*.

Return type:

Array

data_only = False#

get_jec_config()#

Load config relevant to the JEC corrections.

By default, this is extracted from the current config_inst:

self.config_inst.x.jec

Used in setup_func().

Return type:: DotDict
Returns:: Dictionary containing configurations for JEC callibrations

get_jec_file(external_files)#

Function to obtain external jec files.

By default, this function extracts the location of the jec correction files from the current config instance config_inst:

cfg.x.external_files = DotDict.wrap({
    "jet_jerc": "/afs/cern.ch/user/m/mrieger/public/mirrors/jsonpog-integration-f018adfb/POG/JME/2017_UL/jet_jerc.json.gz",
})

Parameters:: external_files (DotDict) – Dictionary containing the information about the file location
Return type:: str
Returns:: path or url to correction file(s)

init_func()#

Return type:: None

mc_only = False#

nominal_only = False#

produces = {'Jet.mass', 'Jet.pt', 'Jet.rawFactor'}#

propagate_met = True#

requires_func(reqs)#

Return type:: None

setup_func(reqs, inputs, reader_targets)#

Load the correct jec files using the from_string() method of the correctionlib.highlevel.CorrectionSet function and apply the corrections as needed.

The source files for the correctionlib.highlevel.CorrectionSet instance are extracted with the get_jec_file().

Uses the member function get_jec_config() to construct the required keys, which are based on the following information about the JEC:

levels

campaign

version

jet_type

A corresponding example snippet wihtin the config_inst could like something like this:

cfg.x.jec = DotDict.wrap({
    # campaign name for this JEC correctiono
    "campaign": f"Summer19UL{year2}{jerc_postfix}",
    # version of the corrections
    "version": "V7",
    # Type of jets that the corrections should be applied on
    "jet_type": "AK4PFchs",
    # relevant levels in the derivation process of the JEC
    "levels": ["L1FastJet", "L2Relative", "L2L3Residual", "L3Absolute"],
    # relevant levels in the derivation process of the Type 1 MET JEC
    "levels_for_type1_met": ["L1FastJet"],
    # names of the uncertainties to be applied
    "uncertainty_sources": [
        "Total",
        "CorrelationGroupMPFInSitu",
        "CorrelationGroupIntercalibration",
        "CorrelationGroupbJES",
        "CorrelationGroupFlavor",
        "CorrelationGroupUncorrelated",
    ],
})

Parameters:

reqs (dict) – Requirement dictionary for this Calibrator instance
inputs (dict) – Additional inputs, currently not used
reader_targets (InsertableDict) – TODO: add documentation

Return type:

None

shifts_only = None#

uncertainty_sources = None#

uses = {'Jet.eta', <Route 'Rho.fixedGridRhoFastjetAll' (tags=optional)>, 'Jet.phi', <Route 'fixedGridRhoFastjetAll' (tags=optional)>, 'Jet.mass', <class 'columnflow.production.util.attach_coffea_behavior'>, 'Jet.area', 'Jet.jetId', 'Jet.rawFactor', 'Jet.pt'}#

class jer(*args, requires_func=<law.util.NoValue object>, setup_func=<law.util.NoValue object>, sandbox=<law.util.NoValue object>, call_force=<law.util.NoValue object>, inst_dict=None, **kwargs)[source]#

Bases: Calibrator

call_func(events, **kwargs)#

Applies the jet energy resolution smearing in MC and calculates the associated uncertainty shifts using the correctionlib, following the recommendations given in https://twiki.cern.ch/twiki/bin/viewauth/CMS/JetResolution.

Requires an external file in the config under jet_jerc:

cfg.x.external_files = DotDict.wrap({
    "jet_jerc": "/afs/cern.ch/user/m/mrieger/public/mirrors/jsonpog-integration-f018adfb/POG/JME/2017_UL/jet_jerc.json.gz",
})

get_jer_file can be adapted in a subclass in case it is stored differently in the external files.

The jer configuration should be an auxiliary entry in the config, specifying the correction details under jer:

cfg.x.jer = {
    "campaign": "Summer19UL17",
    "version": "JRV2",
    "jet_type": "AK4PFchs",
},

get_jer_config can be adapted in a subclass in case it is stored differently in the config.

Throws an error if running on data.

Parameters:: events (Array) – awkward array containing events to process
Return type:: Array

data_only = False#

get_jer_config()#

Load config relevant to the JER corrections.

By default, this is extracted from the current config_inst:

self.config_inst.x.jer

Return type:: DotDict
Returns:: Dictionary containing configurations for JEC callibrations

get_jer_file(external_files)#

Function to obtain external jer files.

By default, this function extracts the location of the jec correction files from the current config instance config_inst:

cfg.x.external_files = DotDict.wrap({
    "jet_jerc": "/afs/cern.ch/user/m/mrieger/public/mirrors/jsonpog-integration-f018adfb/POG/JME/2017_UL/jet_jerc.json.gz",
})

Parameters:: external_files (DotDict) – Dictionary containing the information about the file location
Return type:: str
Returns:: path or url to correction file(s)

init_func()#

Return type:: None

mc_only = True#

nominal_only = False#

produces = {'Jet.mass', 'Jet.mass_jer_down', 'Jet.mass_jer_up', 'Jet.mass_unsmeared', 'Jet.pt', 'Jet.pt_jer_down', 'Jet.pt_jer_up', 'Jet.pt_unsmeared', 'MET.phi', 'MET.phi_jer_down', 'MET.phi_jer_up', 'MET.pt', 'MET.pt_jer_down', 'MET.pt_jer_up'}#

propagate_met = True#

requires_func(reqs)#

Return type:: None

setup_func(reqs, inputs, reader_targets)#

Load the correct jer files using the from_string() method of the correctionlib.highlevel.CorrectionSet function and apply the corrections as needed.

The source files for the correctionlib.highlevel.CorrectionSet instance are extracted with the get_jer_file().

Uses the member function get_jer_config() to construct the required keys, which are based on the following information about the JER:

campaign
version
jet_type

A corresponding example snippet within the config_inst could like something like this:

cfg.x.jer = DotDict.wrap({
    "campaign": f"Summer19UL{year2}{jerc_postfix}",
    "version": "JRV3",
    "jet_type": "AK4PFchs",
})

Parameters:

reqs (dict) – Requirement dictionary for this Calibrator instance.
inputs (dict) – Additional inputs, currently not used.
reader_targets (InsertableDict) – TODO: add documentation.

Return type:

None

shifts_only = None#

uses = {'MET.pt', 'Jet.eta', 'GenJet.phi', <Route 'Rho.fixedGridRhoFastjetAll' (tags=optional)>, 'Jet.phi', <Route 'fixedGridRhoFastjetAll' (tags=optional)>, 'Jet.mass', 'GenJet.eta', 'MET.phi', 'GenJet.pt', 'Jet.genJetIdx', <class 'columnflow.production.util.attach_coffea_behavior'>, 'Jet.pt'}#

jets

Contents

jets#

Summary#

Functions#

Calibrators#

`jets`#