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:
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.no_value, setup_func=law.util.no_value, sandbox=law.util.no_value, call_force=law.util.no_value, max_chunk_size=law.util.no_value, pick_cached_result=law.util.no_value, 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#
gen_jet_name = 'GenJet'#
get_jec_config = None#
get_jec_file = None#
get_jer_config = None#
get_jer_file = None#
init_func()#
Return type:

None

jet_name = 'Jet'#
mc_only = False#
nominal_only = False#
produces = {<class 'columnflow.calibration.cms.jets.jer'>, <class 'columnflow.calibration.cms.jets.jec'>}#
propagate_met = None#
shifts_only = None#
skip_func()#
static update_cls_dict(cls_name, cls_dict, get_attr)#
uses = {<class 'columnflow.calibration.cms.jets.jer'>, <class 'columnflow.calibration.cms.jets.jec'>}#
class jec(*args, requires_func=law.util.no_value, setup_func=law.util.no_value, sandbox=law.util.no_value, call_force=law.util.no_value, max_chunk_size=law.util.no_value, pick_cached_result=law.util.no_value, 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 (JECs) and uncertainty shifts using the correctionlib, optionally propagating the changes to the MET.

The jet_name should be set to the name of the NanoAOD jet collection to calibrate (default: Jet, i.e. AK4 jets).

Requires an external file in the config pointing to the JSON files containing the JECs. The file key can be specified via an optional external_file_key in the jec config entry. If not given, the file key will be determined automatically based on the jet collection name: jet_jerc for Jet (AK4 jets), fat_jet_jerc for``FatJet`` (AK8 jets). A full set of JSON files can be specified as:

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

For more file-grained control, the 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”. Separate configs should be given for each jet collection to calibrate, using the jet collection name as a subkey. An example of a valid configuration for correction AK4 jets with JEC is:

cfg.x.jec = {
    "Jet": {
        "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 jet energy corrections (JEC).

By default, this is extracted from the current config_inst, assuming the JEC configurations are stored under the ‘jec’ aux key. Separate configurations should be specified for each jet collection, using the collection name as a key. For example, the configuration for the default jet collection Jet will be retrieved from the following config entry:

self.config_inst.x.jec.Jet

Used in setup_func().

Return type:

DotDict

Returns:

Dictionary containing configuration for jet energy calibration

get_jec_file(external_files)#

Function to obtain external correction files for JEC and/or JER.

By default, this function extracts the location of the jec correction files from the current config instance config_inst. The key of the external file depends on the jet collection. For Jet (AK4 jets), this resolves to jet_jerc, and for FatJet it is resolved to fat_jet_jerc.

cfg.x.external_files = DotDict.wrap({
    "jet_jerc": "/afs/cern.ch/work/m/mrieger/public/mirrors/jsonpog-integration-9ea86c4c/POG/JME/2017_UL/jet_jerc.json.gz",
    "fat_jet_jerc": "/afs/cern.ch/work/m/mrieger/public/mirrors/jsonpog-integration-9ea86c4c/POG/JME/2017_UL/fatJet_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

jet_name = 'Jet'#
mc_only = False#
met_name = 'MET'#
nominal_only = False#
propagate_met = True#
raw_met_name = 'RawMET'#
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({
    "Jet": {
        # 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#
static update_cls_dict(cls_name, cls_dict, get_attr)#
uses = {<Route 'Rho.fixedGridRhoFastjetAll' (tags=optional)>, <Route 'fixedGridRhoFastjetAll' (tags=optional)>, <class 'columnflow.production.util.attach_coffea_behavior'>}#
class jer(*args, requires_func=law.util.no_value, setup_func=law.util.no_value, sandbox=law.util.no_value, call_force=law.util.no_value, max_chunk_size=law.util.no_value, pick_cached_result=law.util.no_value, 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.

The jet_name and gen_jet_name should be set to the name of the NanoAOD jet and gen jet collections to use as an input for JER smearing (default: Jet and GenJet, respectively, i.e. AK4 jets).

Requires an external file in the config pointing to the JSON files containing the JER information. The file key can be specified via an optional external_file_key in the jer config entry. If not given, the file key will be determined automatically based on the jet collection name: jet_jerc for Jet (AK4 jets), fat_jet_jerc for``FatJet`` (AK8 jets). A full set of JSON files can be specified as:

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

For more fine-grained control, the get_jer_file can be adapted in a subclass in case it is stored differently in the external files.

The JER smearing configuration should be an auxiliary entry in the config, specifying the input JER to use under “jer”. Separate configs should be given for each jet collection to smear, using the jet collection name as a subkey. An example of a valid configuration for smearing AK4 jets with JER is:

cfg.x.jer = {
    "Jet": {
        "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.

The nominal JER smearing is performed on nominal jets as well as those varied as a result of jet energy corrections. For this purpose, get_jec_config and jec_uncertainty_sources can be defined to control the considered variations. Consequently, the matching of jets to gen jets which depends on pt values of the former is subject to a choice regarding which pt values to use. If gen_jet_matching_nominal is True, the nominal pt values are used, and the jec varied pt values otherwise.

Throws an error if running on data.

Parameters:

events (Array) – awkward array containing events to process

Return type:

Array

data_only = False#
deterministic_seed_index = -1#
gen_jet_matching_nominal = False#
gen_jet_name = 'GenJet'#
get_jec_config()#

Load config relevant to the jet energy corrections (JEC).

By default, this is extracted from the current config_inst, assuming the JEC configurations are stored under the ‘jec’ aux key. Separate configurations should be specified for each jet collection, using the collection name as a key. For example, the configuration for the default jet collection Jet will be retrieved from the following config entry:

self.config_inst.x.jec.Jet

Used in setup_func().

Return type:

DotDict

Returns:

Dictionary containing configuration for jet energy calibration

get_jer_config()#

Load config relevant to the jet energy resolution (JER) smearing.

By default, this is extracted from the current config_inst, assuming the JER configurations are stored under the ‘jer’ aux key. Separate configurations should be specified for each jet collection, using the collection name as a key. For example, the configuration for the default jet collection Jet will be retrieved from the following config entry:

self.config_inst.x.jer.Jet

Used in setup_func().

Return type:

DotDict

Returns:

Dictionary containing configuration for JER smearing

get_jer_file(external_files)#

Function to obtain external correction files for JEC and/or JER.

By default, this function extracts the location of the jec correction files from the current config instance config_inst. The key of the external file depends on the jet collection. For Jet (AK4 jets), this resolves to jet_jerc, and for FatJet it is resolved to fat_jet_jerc.

cfg.x.external_files = DotDict.wrap({
    "jet_jerc": "/afs/cern.ch/work/m/mrieger/public/mirrors/jsonpog-integration-9ea86c4c/POG/JME/2017_UL/jet_jerc.json.gz",
    "fat_jet_jerc": "/afs/cern.ch/work/m/mrieger/public/mirrors/jsonpog-integration-9ea86c4c/POG/JME/2017_UL/fatJet_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

jec_uncertainty_sources = None#
jet_name = 'Jet'#
mc_only = True#
met_name = 'MET'#
nominal_only = False#
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({
    "Jet": {
        "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#
static update_cls_dict(cls_name, cls_dict, get_attr)#
uses = {<Route 'Rho.fixedGridRhoFastjetAll' (tags=optional)>, <Route 'fixedGridRhoFastjetAll' (tags=optional)>, <class 'columnflow.production.util.attach_coffea_behavior'>}#