Commit ce65585c authored by Nils Erik Krumnack's avatar Nils Erik Krumnack
Browse files

Merge branch '21.2-JetRecDocs' into '21.2'

JetRec(Tools) documentation

See merge request atlas/athena!13972

Former-commit-id: 188443d0c68cc4b9d86f778038697fd442ae157f
parents 0699078b dbadeb20
# JetRecTools: Support classes for jet reconstruction
## Package overview
This package exists to provide classes that contribute additional functionality to the basic jet reconstruction capabilities in `Reconstruction/Jet/JetRec`. These support classes are broadly of three types:
* Additional `PseudoJetGetter` classes for the following classes, or that require special selection or four-vector handling (e.g. because they are do not inherit from `IParticle`).
* Constituent modification classes that allow operations to be applied to the jet inputs (e.g. topoclusters, PFOs) prior to jet building, for example origin corrections and pileup suppression
* Others
### Custom PseudoJetGetters
* TrackPseudoJetGetter -- handles `TrackParticle`, optionally applying a vertex association restriction.
* PFlowPseudoJetGetter -- handles `ParticleFlowObject`, applying a vertex association restriction and some special selection for 0 pt objects.
*Note that `MuonSegment` anomalously has a custom PseudoJetGetter in `JetRec`*
### Constituent modifier classes
* JetConstitModSequence -- the top-level constituent modification scheduler for tools inheriting from `JetConstitModifierBase` (all subsequent tools in this list), which takes an input container (of topoclusters, PFOs, ...) and generates shallow copies to be modified by a sequence of individual tools. The updated four-vector is set as the default four-momentum, such that downstream tools can simply use the `IParticle::p4()` interface.
* CaloClusterConstituentsOrigin -- updates `CaloCluster` four-momenta to point to the nominal hard scatter primary vertex, rather than to the detector origin.
* ClusterAtEMScaleTool -- updates `CaloCluster` default four-vector to be the EM scale four-vector w/o changing signal state (ordinarily this is the LC-calibrated four-vector).
* CorrectPFOTool -- applies four-vector modifications to `PFO` constituents. For charged PFOs: weights to address EM scale response and disabling of cell subtraction in high energy density regions. For neutral PFOs: pointing of the four-vector to the nominal hard scatter vertex, rather than to the detector origin.
* ChargedHadronSubtractionTool -- marks `PFO` constituents as being from the hard scatter vertex or not, for subsequent selection.
* ConstitTimeCutTool -- Applies timing cuts to constituents.
* ConstituentSubtractorTool -- Applies constituent subtraction (see [arxiv:1403.3108](https://arxiv.org/abs/1403.3108)) to constituents.
* PuppiWeightTool -- Applies the PUPPI algorithm (see [arxiv:1407.6013](https://arxiv.org/abs/1407.6013)) to constituents.
* SoftKillerWeightTool -- Applies SoftKiller (see [arxiv:1407.0408](https://arxiv.org/abs/1407.0408)) to constituents.
* VoronoiWeightTool -- Applies Voronoi subtraction (rho subtraction assuming Voronoi areas), spreading or filtering to constituents.
### Other tools
* JetInputElRemovalTool -- Removes clusters matched to electrons from the cluster collection
* JetTrackSelectionTool -- Uses the ID track selection tool to generate a preselected track collection, mainly for building track jets, and can also be used by jet modifiers to select tracks.
* SimpleJetTrackSelectionTool -- Track selection tool with manually-implemented cuts.
* TrackVertexAssociationTool -- Creates a JetTrackVertexAssociation object
> Written with [StackEdit](https://stackedit.io/).
\ No newline at end of file
......@@ -103,13 +103,13 @@ def getPseudoJetGetter(label,pjname):
def getEventDensityTool(pjg):
label = pjg.Label.replace('Topo','TopoOrigin')
toolname = "Kt4"+label+"EventShape"
from AthenaCommon.AppMgr import ToolSvc
if hasattr(ToolSvc,toolname):
return getattr(ToolSvc,toolname)
from EventShapeTools.EventDensityConfig import configEventDensityTool
edtool = configEventDensityTool("Kt4"+label+"EventShape", pjg, 0.4)
from AthenaCommon.AppMgr import ToolSvc
ToolSvc += edtool
return edtool
......@@ -117,7 +117,7 @@ def getJetFinder(inputtype,label,pjname,modkey):
from JetRec.JetRecStandard import jtm
pjg = getPseudoJetGetter(label,pjname)
jetsname = "AntiKt4"+label+"Jets"
getterbase = inputtype.lower()+"_ungroomed"
getterbase = inputtype.lower()+"_reduced"
jtm.gettersMap[pjname] = [pjg]+list(jtm.gettersMap[getterbase])[1:]
finder = jtm.addJetFinder(jetsname, "AntiKt", 0.4, pjname, modkey,
......
# JetRecTools modules
## Module list
* `ConstModHelpers.py` -- Helper functions for setting up jet/MET reco with constituent modifications
* `ScheduleClusterOriginCorrection.py` -- Scheduler for topocluster origin correction
* `JetRecToolsConfig.py` -- Tool manager for constituent modifiers
* `DefaultTools.py` -- [Unused] from an attempt to modularise jet tool configurations
## Module descriptions
### `ConstModHelpers.py`
* This module provides helper functions for reconstructing jet collections and/or MET with modified constituents as inputs, making use of the `ctm` and `jtm` helper classes defined in `JetRecTools/python/JetRecToolsConfig.py` (see below) and `JetRec/python/JetToolSupport.py`.
### `ScheduleClusterOriginCorrection.py`
* This module provides the `applyClusterOriginCorrection` function, which schedules origin correction operations on topoclusters at a given scale. The algs will only be activated if the collections to be produced are absent from the input file.
### `JetRecToolsConfig.py`
* This module is a configuration helper for tools in this package, primarily for constituent modifiers via the `ConstituentToolManager` helper class. The `ctm` accumulates tools providing constituent modification capabilities, and generates a configured `JetConstitModSequence` tool applying a sequence of constituent modifications to a given collection via its function `buildConstitModSequence`. The tool returned can then be placed in a `JetAlgorithm`.
### `DefaultTools.py`
* [Unused] This module was intended to take over core jet reconstruction configuration code from the `JetRec/python/JetRecStandardTools.py` module, placing the default configurations closer to the package in which the tools are defined. However, this has been superseded by other developments.
> Written with [StackEdit](https://stackedit.io/).
import AthenaPoolCnvSvc.ReadAthenaPool
############################################################################
# Set up detector description and magnetic field service
# This is needed for track extrapolation when computing
# isolation variables in MET track cleaning
from AthenaCommon.GlobalFlags import globalflags
globalflags.DetGeo = 'atlas'
from RecExConfig.InputFilePeeker import inputFileSummary
#print inputFileSummary
if inputFileSummary['evt_type'][0] == 'IS_DATA':
globalflags.DataSource = 'data'
else:
globalflags.DataSource = 'geant4'
from AthenaCommon.DetFlags import DetFlags
DetFlags.detdescr.all_setOff()
DetFlags.detdescr.Calo_setOn()
if hasattr(DetFlags,'BField_on'): DetFlags.BField_setOn()
from TrkDetDescrSvc.AtlasTrackingGeometrySvc import AtlasTrackingGeometrySvc
AtlasTrackingGeometrySvc = svcMgr.AtlasTrackingGeometrySvc
from AtlasGeoModel import SetGeometryVersion, GeoModelInit
GeoModelSvc = ServiceMgr.GeoModelSvc
GeoModelSvc.AtlasVersion = inputFileSummary['metadata']['/TagInfo']['GeoAtlas']
include('RecExCond/AllDet_detDescr.py')
############################################################################
# Set up the jet & MET collections
from JetRecTools import ConstModHelpers
from JetRec.JetRecFlags import jetFlags
jetFlags.useTruth.set_Value_and_Lock(False)
# Define the chains of constituent modifiers here
modsequences = [
["SK"],
["CS","SK"],
["Vor","SK"]
]
# Set up lists of tools that need to be run
from JetRec.JetRecStandard import jtm
constmodseqs = [jtm.JetConstitSeq_EMOrigin,jtm.JetConstitSeq_LCOrigin]
edtools = []
jetfinders = []
metalgs = []
metoutputs = []
# Define some dicts to help with generating collections in a loop
pjbase = {"EMTopo":"em",
"LCTopo":"lc",
"EMPFlow":"pf"}
modkeys = {"EMTopo":"emtopo_constpu","EMPFlow":"pflow_constpu"}
# Remove the truth jet association tool from the moment tool list
jtm.modifiersMap["emtopo_constpu"] = [ tool for tool in jtm.modifiersMap["emtopo_ungroomed"] if tool != "truthassoc" ]
jtm.modifiersMap["pflow_constpu"] = [ tool for tool in jtm.modifiersMap["pflow_ungroomed"] if tool != "truthassoc" ]
# Loop over input types: cluster & PFlow, different modifier chains
# and fill the lists of builder tools
for inputtype in pjbase.keys():
for modseq in modsequences:
# This generates the modifier sequence
cms = ConstModHelpers.getConstModSeq(modseq,inputtype)
constmodseqs.append(cms)
# Strip out underscores for jet naming
modseqshort = "".join(modseq)
if not "LC" in inputtype: # LC clusters needed just for MET (CST)
label = inputtype+modseqshort
pjname = pjbase[inputtype]+modseqshort.lower()
jf = ConstModHelpers.getJetFinder(inputtype,label,pjname,modkeys[inputtype])
jetfinders.append(jf)
pjg = ConstModHelpers.getPseudoJetGetter(label,pjname)
ed = ConstModHelpers.getEventDensityTool(pjg)
edtools.append(ed)
metalg,metout = ConstModHelpers.getConstModMETAlg(modseqshort, "PFlow" in inputtype)
metalgs.append(metalg)
metoutputs.append(metout)
############################################################################
# Put all of the tools defined above into algorithms
from AthenaCommon.AlgSequence import AlgSequence
topSequence = AlgSequence()
preptools = [jtm.tracksel, jtm.tvassoc, jtm.trackselloose_trackjets]
jtm += CfgMgr.JetToolRunner("jetrunskconstit",
Tools=preptools+constmodseqs)
topSequence += CfgMgr.JetAlgorithm("jetalgskconstit",Tools=[jtm.jetrunskconstit])
jtm += CfgMgr.JetToolRunner("jetruneventshape",
EventShapeTools=edtools)
topSequence += CfgMgr.JetAlgorithm("jetalgeventshape",Tools=[jtm.jetruneventshape])
for finder in jetfinders:
topSequence += CfgMgr.JetAlgorithm("jetalg"+finder.name(),Tools=[finder])
for metalg in metalgs:
topSequence += metalg
############################################################################
# Define the output stream content
from OutputStreamAthenaPool.MultipleStreamManager import MSMgr
xaodStream = MSMgr.NewPoolRootStream( "StreamAOD", "xAOD.PFSKJetMET.pool.root" )
xaodStream.AddItem('xAOD::EventInfo#EventInfo')
xaodStream.AddItem('xAOD::EventAuxInfo#EventInfoAux.')
xaodStream.AddItem('xAOD::VertexContainer#PrimaryVertices')
xaodStream.AddItem('xAOD::VertexAuxContainer#PrimaryVerticesAux.')
xaodStream.AddItem('xAOD::ElectronContainer#Electrons')
xaodStream.AddItem('xAOD::ElectronAuxContainer#ElectronsAux.')
xaodStream.AddItem('xAOD::PhotonContainer#Photons')
xaodStream.AddItem('xAOD::PhotonAuxContainer#PhotonsAux.')
xaodStream.AddItem('xAOD::MuonContainer#Muons')
xaodStream.AddItem('xAOD::MuonAuxContainer#MuonsAux.')
xaodStream.AddItem('xAOD::TauJetContainer#TauJets')
xaodStream.AddItem('xAOD::TauJetAuxContainer#TauJetsAux.')
xaodStream.AddItem('xAOD::JetContainer#AntiKt4EMTopoJets')
xaodStream.AddItem('xAOD::JetAuxContainer#AntiKt4EMTopoJetsAux.')
xaodStream.AddItem('xAOD::JetContainer#AntiKt4EMPFlowJets')
xaodStream.AddItem('xAOD::JetAuxContainer#AntiKt4EMPFlowJetsAux.')
xaodStream.AddItem('xAOD::JetContainer#AntiKt4TruthJets')
xaodStream.AddItem('xAOD::JetAuxContainer#AntiKt4TruthJetsAux.')
xaodStream.AddItem('xAOD::MissingETContainer#MET_Core_AntiKt4EMTopo')
xaodStream.AddItem('xAOD::MissingETAuxContainer#MET_Core_AntiKt4EMTopoAux.')
xaodStream.AddItem('xAOD::MissingETAssociationMap#METAssoc_AntiKt4EMTopo')
xaodStream.AddItem('xAOD::MissingETAuxAssociationMap#METAssoc_AntiKt4EMTopoAux.')
xaodStream.AddItem('xAOD::MissingETContainer#MET_Core_AntiKt4EMPFlow')
xaodStream.AddItem('xAOD::MissingETAuxContainer#MET_Core_AntiKt4EMPFlowAux.')
xaodStream.AddItem('xAOD::MissingETAssociationMap#METAssoc_AntiKt4EMPFlow')
xaodStream.AddItem('xAOD::MissingETAuxAssociationMap#METAssoc_AntiKt4EMPFlowAux.')
xaodStream.AddItem('xAOD::MissingETContainer#MET_Reference_AntiKt4EMTopo')
xaodStream.AddItem('xAOD::MissingETAuxContainer#MET_Reference_AntiKt4EMTopoAux.')
xaodStream.AddItem('xAOD::MissingETContainer#MET_Truth')
xaodStream.AddItem('xAOD::MissingETAuxContainer#MET_TruthAux.')
xaodStream.AddItem('xAOD::EventShape#Kt4*EventShape')
xaodStream.AddItem('xAOD::EventShapeAuxInfo#Kt4*EventShapeAux.')
for jf in jetfinders:
xaodStream.AddItem('xAOD::JetContainer#'+jf.name())
xaodStream.AddItem('xAOD::JetAuxContainer#'+jf.name()+'Aux.')
for outputdict in metoutputs:
for cont,name in outputdict.iteritems():
xaodStream.AddItem('{0}#{1}'.format(cont,name))
#ServiceMgr.StoreGateSvc.Dump=True
svcMgr += CfgMgr.AthenaEventLoopMgr(EventPrintoutInterval=1000)
import AthenaPoolCnvSvc.ReadAthenaPool
############################################################################
# Set up the jet & MET collections
from JetRecTools import ConstModHelpers
from JetRec.JetRecFlags import jetFlags
jetFlags.useTruth.set_Value_and_Lock(False)
# Define the chains of constituent modifiers here
modsequences = [
["SK"],
["CS","SK"],
["Vor","SK"]
]
# Set up lists of tools that need to be run
from JetRec.JetRecStandard import jtm
constmodseqs = [jtm.JetConstitSeq_EMOrigin,jtm.JetConstitSeq_LCOrigin]
edtools = []
jetfinders = []
# Define some dicts to help with generating collections in a loop
pjbase = {"EMTopo":"em",
"LCTopo":"lc",
"EMPFlow":"pf"}
modkeys = {"EMTopo":"emtopo_constpu","EMPFlow":"pflow_constpu"}
# Remove the truth jet association tool from the moment tool list
jtm.modifiersMap["emtopo_constpu"] = [ tool for tool in jtm.modifiersMap["emtopo_ungroomed"] if tool != "truthassoc" ]
jtm.modifiersMap["pflow_constpu"] = [ tool for tool in jtm.modifiersMap["pflow_ungroomed"] if tool != "truthassoc" ]
# Loop over input types: cluster & PFlow, different modifier chains
# and fill the lists of builder tools
for inputtype in pjbase.keys():
for modseq in modsequences:
# This generates the modifier sequence
cms = ConstModHelpers.getConstModSeq(modseq,inputtype)
constmodseqs.append(cms)
# Strip out underscores for jet naming
modseqshort = "".join(modseq)
if not "LC" in inputtype: # LC clusters needed just for MET (CST)
label = inputtype+modseqshort
pjname = pjbase[inputtype]+modseqshort.lower()
jf = ConstModHelpers.getJetFinder(inputtype,label,pjname,modkeys[inputtype])
jetfinders.append(jf)
pjg = ConstModHelpers.getPseudoJetGetter(label,pjname)
ed = ConstModHelpers.getEventDensityTool(pjg)
edtools.append(ed)
############################################################################
# Put all of the tools defined above into algorithms
from AthenaCommon.AlgSequence import AlgSequence
topSequence = AlgSequence()
preptools = [jtm.tracksel, jtm.tvassoc, jtm.trackselloose_trackjets]
jtm += CfgMgr.JetToolRunner("jetrunskconstit",
Tools=preptools+constmodseqs)
topSequence += CfgMgr.JetAlgorithm("jetalgskconstit",Tools=[jtm.jetrunskconstit])
jtm += CfgMgr.JetToolRunner("jetruneventshape",
EventShapeTools=edtools)
topSequence += CfgMgr.JetAlgorithm("jetalgeventshape",Tools=[jtm.jetruneventshape])
for finder in jetfinders:
topSequence += CfgMgr.JetAlgorithm("jetalg"+finder.name(),Tools=[finder])
############################################################################
# Define the output stream content
from OutputStreamAthenaPool.MultipleStreamManager import MSMgr
xaodStream = MSMgr.NewPoolRootStream( "StreamAOD", "xAOD.PFSKJetMET.pool.root" )
xaodStream.AddItem('xAOD::EventInfo#EventInfo')
xaodStream.AddItem('xAOD::EventAuxInfo#EventInfoAux.')
xaodStream.AddItem('xAOD::VertexContainer#PrimaryVertices')
xaodStream.AddItem('xAOD::VertexAuxContainer#PrimaryVerticesAux.')
xaodStream.AddItem('xAOD::JetContainer#AntiKt4EMTopoJets')
xaodStream.AddItem('xAOD::JetAuxContainer#AntiKt4EMTopoJetsAux.')
xaodStream.AddItem('xAOD::JetContainer#AntiKt4EMPFlowJets')
xaodStream.AddItem('xAOD::JetAuxContainer#AntiKt4EMPFlowJetsAux.')
xaodStream.AddItem('xAOD::JetContainer#AntiKt4TruthJets')
xaodStream.AddItem('xAOD::JetAuxContainer#AntiKt4TruthJetsAux.')
xaodStream.AddItem('xAOD::EventShape#Kt4*EventShape')
xaodStream.AddItem('xAOD::EventShapeAuxInfo#Kt4*EventShapeAux.')
for jf in jetfinders:
xaodStream.AddItem('xAOD::JetContainer#'+jf.name())
xaodStream.AddItem('xAOD::JetAuxContainer#'+jf.name()+'Aux.')
#ServiceMgr.StoreGateSvc.Dump=True
svcMgr += CfgMgr.AthenaEventLoopMgr(EventPrintoutInterval=1000)
import AthenaPoolCnvSvc.ReadAthenaPool
############################################################################
# Set up the jet & MET collections
from JetRecTools import ConstModHelpers
from JetRec.JetRecFlags import jetFlags
jetFlags.useTruth.set_Value_and_Lock(False)
# Define the chains of constituent modifiers here
modsequences = [
["SK"],
["CS","SK"],
["Vor","SK"]
]
# Set up lists of tools that need to be run
from JetRec.JetRecStandard import jtm
constmodseqs = [jtm.JetConstitSeq_EMOrigin,jtm.JetConstitSeq_LCOrigin]
edtools = []
jetfinders = []
# Define some dicts to help with generating collections in a loop
pjbase = {"EMTopo":"em",
"LCTopo":"lc",
"EMPFlow":"pf"}
# Loop over input types: cluster & PFlow, different modifier chains
# and fill the lists of builder tools
for inputtype in pjbase.keys():
for modseq in modsequences:
# This generates the modifier sequence
cms = ConstModHelpers.getConstModSeq(modseq,inputtype)
constmodseqs.append(cms)
# Strip out underscores for jet naming
modseqshort = "".join(modseq)
############################################################################
# Put all of the tools defined above into algorithms
from AthenaCommon.AlgSequence import AlgSequence
topSequence = AlgSequence()
preptools = [jtm.tracksel, jtm.tvassoc, jtm.trackselloose_trackjets]
jtm += CfgMgr.JetToolRunner("jetrunskconstit",
Tools=preptools+constmodseqs)
topSequence += CfgMgr.JetAlgorithm("jetalgskconstit",Tools=[jtm.jetrunskconstit])
############################################################################
# Define the output stream content
from OutputStreamAthenaPool.MultipleStreamManager import MSMgr
xaodStream = MSMgr.NewPoolRootStream( "StreamAOD", "xAOD.ConstitMods.pool.root" )
xaodStream.AddItem('xAOD::EventInfo#EventInfo')
xaodStream.AddItem('xAOD::EventAuxInfo#EventInfoAux.')
xaodStream.AddItem('xAOD::CaloClusterContainer#*TopoClusters')
xaodStream.AddItem('xAOD::CaloClusterAuxContainer#*TopoClustersAux.')
xaodStream.AddItem('xAOD::PFOContainer#*ParticleFlowObjects')
xaodStream.AddItem('xAOD::PFOAuxContainer#*ParticleFlowObjectsAux.')
svcMgr += CfgMgr.AthenaEventLoopMgr(EventPrintoutInterval=1000)
# JetRecTools jobOptions
## JO list
* `BuildModifiedConstits.py` -- Example for reading in an AOD file and writing out an xAOD containing topoclusters and PFOs with constituent modifications (SoftKiller). Makes use of `JetRecTools/python/ConstModHelpers.py`
* `BuildConstitModJets.py` -- Example for reading in an AOD file and writing out an xAOD containing jets reconstructed from topoclusters and PFOs with constituent modifications (SoftKiller). Makes use of `JetRecTools/python/ConstModHelpers.py`
* `BuildConstitModJetMET.py` -- Example for reading in an AOD file and writing out an xAOD containing jets and MET reconstructed from topoclusters and PFOs with constituent modifications (SoftKiller). Makes use of `JetRecTools/python/ConstModHelpers.py`
## Executing jobOptions
The JOs in this package make use of the "modern" approach to supplying input files, i.e. command line arguments. They can be called with e.g.:
`athena BuildModifiedConstituents.py --filesInput [comma-separated list of files] --evtMax [number of events to run]`
It is recommended to use an AthDerivation 21.2 release to execute these JOs. AthAnalysis can in principle be used for `BuildModifiedConstits.py` and `BuildConstitModJets.py`, provided the necessary packages are installed.
## Outdated JO
* `JetTowerBuilder_jobOptions.py` -- Builds topotowers (towers from cells in topoclusters) and jets from the topotowers. Requires cell access.
* `runJetReco_topOptions.py` -- [Outdated] Calls `JetTowerBuilder_jobOptions.py`, then writes jets to CBNT.
* `samp.wt.CT7.py` -- [Outdated] Sampling weights for calibration?
* `samp.wt.CTfTC7.py` -- [Outdated] Sampling weights for calibration?
* `samp.wt.TC7.py` -- [Outdated] Sampling weights for calibration?
> Written with [StackEdit](https://stackedit.io/).
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment