HEPTopTagger

Introduction

The HEPTopTagger is a substructure based boosted-top tagger. This twiki focuses on the implementation and usage of the HTT algorithm in the atlas software. Description and features of the algorithm should be read up elsewhere:

References:

• Stop Reconstruction with Tagged Tops arXiv:1006.2833 [hep-ph] - HTT pheno paper 1
• Resonance Searches with an Updated Top Tagger arXiv:1503.05921 [hep-ph] - HTT pheno paper 2
• Tagging highly boosted top quarks arXiv:1308.0540 - Run 1 top tagging performance paper
• Performance of Top Quark and W Boson Tagging in Run 2 with ATLAS ATLAS-CONF-2017-064 - Run 2 top/W tagging conf note

Implementation of HEPTopTagger in ATLAS Rel21

todo: update links

The HEPTopTagger code is split into several classes and tools that not only implement the core algorithm and interfaces to it, but also provide extra functionality that has been used in past analysis together with the HEPTopTagger. Since these extra tools are integrated into the HEPTopTagger implementation, they will be described here. Usage instructions are given in the next section.

The core implementation of the HEPTopTagger algorithm for can be found in JetSubStructureUtils/HEPTopTaggerImpl. The algorithm runs on fastjet::Pseudojets and not only returns a binary tagging decision but also various substructure variables that are calculated to reach this decision. The main difference to the algorithm described and provided by the pheno papers, is that the present version allows to calibrate the fastjet::Pseudojet subjets used to reconstruct the HTT substructure variables. In order to keep this core implementation completely ATLAS software independent an abstract interface class, JetSubStructureUtils/IPseudoJetCalibrationTool, is introduced for this purpose.

The main ATLAS interface to use HTT is provided by the JetModifier tool JetSubStructureMomentTools/HEPTopTaggerMomentsTool. A concrete implementation of a IPseudoJetCalibrationTool to calibrate the HTT fastjet::Pseudojet subjets is provided by in the same package by JetSubStructureMomentTools/VariableRPseudoJetCalTool. The HEPTopTaggerMoments tool can be run on a xAOD::Jet or a xAOD::JetContainer. It stores the HEPTopTagger result by setting corresponding jet attributes. For a list of stored attributes, either consider the code itself or have them print()'ed on runtime. Both the HEPTopTaggerMomentsTool and the VariableRPseudoJetCalTool are highly configurable and to make application simpler, default configurations are hard coded into the tools themselves. For a list of all configurable parameters, best consider the code itself.

The VariableRPseudoJetCalTool holds various JetCalibrationTools to calibrate jets with different radius parameters, as they occur in in the HEPTopTagger algorithm. The user can either provide a radius parameter together with the PseudoJet to be calibrated (for inclusively reclustered jets) or have the tool estimate a jet radius (to calibrate also exclusively reclustered jets).

The HEPTopTaggerMomentsTool does not only run the HEPTopTagger on large-R jets and decorate them with the result but it also allows to calibrate and groom the input jets.The reason for this is that the HEPTopTagger, which performs Pileup suppression internally via filtering, is typically run on ungroomed jets which also don't need to be calibrated, since subjet calibration is performed in the HEPTopTagger. To calibrate the large-R jets, a JetCalibrationTool, to groom them, a general IJetGroomer can be provided. Inspired by the subjet calibration performed in the HEPTopTagger to better reconstruct HTT substructure variables a grooming tool, the JetRec/JetSJCalibrationGroomer, which allows to filter or trim a large-R jet and calibrate it by calibrating the small-R reclustered jets was implemented as the default jet grooming tool used by the HEPTopTaggerMomentsTool.

In principle, the HEPTopTagger can be run on any jet with associated clusters. However, for best performance it is to be run on Cambridge/Aachen jets. In ATLAS it has been run on C/A R=1.5 jets. For reclustering of small-R jets inside the HEPTopTagger, per default also the C/A algorithm is used, but other algorithms (kt or anti-kt) can be specified.

How To Use HEPTopTagger

The following instructions have been tested with AnalysisTop, 21.2,1.

Configuring and Running the HEPTopTaggerMomentsTool

The HEPTopTaggerMomentsTool can be run on any xAOD::Jet with the associated clusters stored in the DAOD.

In your analysis, declare:

  HEPTopTaggerMomentsTool* m_newHTTTool; //!

and initialize:

  // new tool
  m_newHTTTool = new HEPTopTaggerMomentsTool( "HEPTopTaggerMomentsTool" );

  // calibrate fatjet ?
  m_newHTTTool->setProperty( "CalibrateFatjet",    true );
  m_newHTTTool->setProperty( "FatjetCalibTool", "MyLargeRJetCalibrationTool" );

  // groom fatjet?
  m_newHTTTool->setProperty( "GroomFatjet",               true            );
  m_newHTTTool->setProperty( "FatjetGroomer",             "MyIJetGroomer" );
  m_newHTTTool->setProperty( "GroomedFatjetName",         "MyGroomedJet"  ); // groomed jet collection and link name
  // Alternatively, to use the JetSJCalibrationGroomer you can configure it via the HEPTopTaggerMomentsTool and let 
  // a corresponding tool be instantiated internally. 
  // NB: in this case, the jet calibration tool will be taken from the VariableRPseudoJetCalTool, see below
  // newHTTTool->setProperty( "FatjetGroomerFilterR",  0.2  ); 
  // newHTTTool->setProperty( "FatjetGroomerNSubjets", 0    );
  // newHTTTool->setProperty( "FatjetGroomerFracPt",   0.05 ); 
  // newHTTTool->setProperty( "JetFromPseudojetTool", "JetFromPseudojetTool"); // you need a JetFromPj tool for this!

  // configure HTT, NB: if the MyVariableRPseudoJetCalTool does not exist, a default tool is instantiated!
  m_newHTTTool->setProperty( "HTT_VarRPseudoJetCalTool", "MyVariableRPseudoJetCalTool");
  m_newHTTTool->setProperty( "JetFromPseudojetTool",     "JetFromPseudojetTool")); // you need a JetFromPj tool for this!

  m_newHTTTool->setProperty( "StoreFullHTTResult",       true); // store auxiliary HTT output variables
  m_newHTTTool->setProperty( "HTT_storeUntagged",        true); // store HTT variables for untagged jets
  m_newHTTTool->setProperty( "AttrLinkUserPrefix",       "" );  // define a custom prefix, if "" it is HTT{conf}_

  // you can use a predefined configuration, there are:
  // def==mOrd --> chose top candidate with min( |m_cand - m_top| )
  // pTOrd         --> larges pT
  // AOrd           --> smallest 1D A-shape cut variable
  // mOrdAShapeFirst, pTOrdAShapeFirst -> only consider candidates passing A-shape cuts for sorting
  // defOtimalR==mOrdOtimalR, pTOrdOtimalR, AOrdOtimalR --> run optimal R tagger
  // mOrdAShapeFirstOtimalR, pTOrdAShapeFirstOtimalR       --> run optimal R, select from candidates passing A-shape only
  m_newHTTTool->setProperty( "PredefHTTConf", "def" );

  // or change default HTT properties by hand:
  // m_newHTTTool->setProperty( "HTT_minFatjetPt", 200000.);
  // ... and many more, for a list of configurables see HEPTopTaggerMomentsTool.cxx
  // WARNING: I do not recommend doing this AND setting PredefHTTConf
  //          as the PredefHTTConf will override some, but not all
  //          of the HTT settings

  // initialize the tool, print() will tell you about the variables it attribute the input jets with!
  m_newHTTTool->initialize();
  m_newHTTTool->print();

to execute the tool you can run it on a xAOD::Jet or xAOD::JetCollection:

  m_newHTTTool->modify( jet );
  // m_newHTTTool->modify( jetCollection );

Configuring a VariableRPseudoJetCalTool

  VariableRPseudoJetCalTool* newVarRPJCalTool = new VariableRPseudoJetCalTool( "VariableRPseudoJetCalTool" );
  // you can either provide a config file with calibration factors for all jet radii
  // and configure the underlying JetCalibrationTools indirectly
  newVarRPJCalTool->setProperty("ConfigFile",    "CamKt_JES_HTT.config");
  newVarRPJCalTool->setProperty("IsData",        false);
  newVarRPJCalTool->setProperty("JetAlgorithm",  "CamKt" );
  newVarRPJCalTool->setProperty("JetInputs",     "LCTopo" );
  newVarRPJCalTool->setProperty("CalibSequence", "Origin_EtaJES");
  std::vector<int> calRadii =  {20, 25, 30, 35, 40, 45, 50, 55, 60};
  newVarRPJCalTool->setProperty("JetRadiusVec", calRadii);
  // or you can provide a  ToolHandleArray<IJetCalibrationTool> JetCalibrationTools set up elsewhere
  // in that case you have to provide a jet radius array matching the JetCalibrationTools!
  // newVarRPJCalTool->setProperty("JetRadiusVec", calRadii);
  // newVarRPJCalTool->setProperty("CustomVarRJetCalibTools", customVarRJetCalibToolsArray );
  newVarRPJCalTool->initialize();

Configuring a JetSJCalibrationGroomer

  newSJCalTrimmer = new JetSJCalibrationGroomer( "JetSJCalibrationTrimmer" );
  newSJCalTrimmer->setProperty("RClus",     0.3 );
  newSJCalTrimmer->setProperty("PTFrac",    0.05);
  newSJCalTrimmer->setProperty("NFiltJets", 0   );
  newSJCalTrimmer->setProperty("ReclustAlgo", 1); // 0 kt, 1 CA, 2 AntiKt
  newSJCalTrimmer->setProperty("JetFromPseudojetTool", "JetFromPseudojetTool");
  newSJCalTrimmer->setProperty("SubjetCalTool", "HTTJetCalibToolCamKt030LCTopo");
  newSJCalTrimmer->initialize();
  newSJCalTrimmer->print();

  newSJCalFilter = new JetSJCalibrationGroomer( "JetSJCalibrationFilter" );
  newSJCalFilter->setProperty("RClus",     0.3);
  newSJCalFilter->setProperty("PTFrac",    0.0);
  newSJCalFilter->setProperty("NFiltJets", 5  );
  newSJCalFilter->setProperty("ReclustAlgo", 1); // 0 kt, 1 CA, 2 AntiKt
  newSJCalFilter->setProperty("JetFromPseudojetTool", "JetFromPseudojetTool");
  newSJCalFilter->setProperty("SubjetCalTool", "HTTJetCalibToolCamKt030LCTopo");
  newSJCalFilter->initialize();
  newSJCalFilter->print();

Running HEPTopTaggerMomentsTool as Part of a JetRecTool

initialize:

  MSG::Level  msgLevel            = MSG::INFO;
  
  // Step 1: Create PseudoJet builder
  ToolHandleArray<IPseudoJetGetter> pjetGetterArray;
  PseudoJetGetter* newLCTopoPJGetter = new PseudoJetGetter("lcget");
  newLCTopoPJGetter->setProperty("InputContainer",     "CaloCalTopoClusters");
  newLCTopoPJGetter->setProperty("OutputContainer",    "PseudoJetLCTopo");
  newLCTopoPJGetter->setProperty("Label",              "LCTopo");
  newLCTopoPJGetter->setProperty("SkipNegativeEnergy", true);
  newLCTopoPJGetter->setProperty("GhostScale",         0.0);
  newLCTopoPJGetter->initialize();
  pjetGetterArray.push_back( ToolHandle<IPseudoJetGetter>(newLCTopoPJGetter) );

  // Step 2: get JetFromPseudojetTool, if not available, create
  JetFromPseudojet* jetFromPJ = new JetFromPseudojet( "JetFromPseudojetTool" );
  // std::vector<std::string> areatts = {"ActiveArea", "ActiveAreaFourVector"}; what was this for?
  // jetFromPJ->setProperty("Attributes", areatts);
  jetFromPJ->msg().setLevel(msgLevel);
  jetFromPJ->initialize();

  // Step 3: Create Jet ca15JetFinder
  JetFinder* ca15JetFinder = new JetFinder("CamKt15Finder");
  ca15JetFinder->setProperty("JetAlgorithm", "CamKt");
  ca15JetFinder->setProperty("JetRadius",    1.5);
  ca15JetFinder->setProperty("PtMin",        50000.0);
  ca15JetFinder->setProperty("GhostArea",    0.0);
  ca15JetFinder->setProperty("RandomOption", 1);
  ca15JetFinder->setProperty("JetBuilder",   ToolHandle<IJetFromPseudojet>( jetFromPJ ));
  ca15JetFinder->msg().setLevel(msgLevel);
  ca15JetFinder->initialize();

  // Step 4: add your HTT jet modifier tool
  ToolHandleArray<IJetModifier> modArray;
  modArray.push_back( ToolHandle<IJetModifier>( m_newHTTTool ));
  m_jetRecTool = new JetRecTool("FullJetRecTool");
  m_jetRecTool->setProperty("OutputContainer",  m_jetOutputContainer );
  m_jetRecTool->setProperty("PseudoJetGetters", pjetGetterArray);
  m_jetRecTool->setProperty("JetFinder",        ToolHandle<IJetFinder>(ca15JetFinder));
  m_jetRecTool->setProperty("JetModifiers",     modArray);
  m_jetRecTool->msg().setLevel(msgLevel);
  m_jetRecTool->initialize();

execute:

  m_jetRecTol->execute();

Access HTT Jet Attributes from Jets:

  bool           isTagged = jet->getAttribute<bool>( HTTprefix+"isTagged" );
  TLorentzVector topCand  = jet->getAttribute< TLorentzVector >( HTTprefix+"topCandidate" );

-- ArthurEugenBolz - 2017-10-02