Update packages:TauAnalysisTools from upstream/21.2 to upstream/master via pseudo-merge (ATLTAU-1727)

Migrating R21.2 TauTruthMatchingTool to R22, including other changes in TauAnalysisTools:

• Updates to HelperFunctions including functions used in 2019-summer recommendations.
• TauTruthMathcingTool: getTruthParticleType function moved to using R21.2 HelperFunctions version
• TauTauTrackTruthMatchingTool checked for consistency with R21.2.
• BuildTruthTaus is in tauRecTools (21.2) and TauAnalysisTools (master), checked for consistency and no changes needed.
• DiTauTruthMatchingTools to be migrated at a later stage.

PhysicsAnalysis/TauID/TauAnalysisTools/Root/HelperFunctions.cxx

 /*
-  Copyright (C) 2002-2017 CERN for the benefit of the ATLAS collaboration
+  Copyright (C) 2002-2020 CERN for the benefit of the ATLAS collaboration
 */
 
 #include <fstream>
 
 // local include(s)
 #include "TauAnalysisTools/HelperFunctions.h"
+#include "TruthUtils/PIDHelpers.h"
 #include "TF1.h"
 
 #ifdef XAODTAU_VERSIONS_TAUJET_V3_H
@@ -14,6 +15,16 @@ xAOD::TauJetParameters::PanTauDetails PANTAU_DECAYMODE=xAOD::TauJetParameters::P
 xAOD::TauJetParameters::PanTauDetails PANTAU_DECAYMODE=xAOD::TauJetParameters::pantau_CellBasedInput_DecayMode;
 #endif
 
+
+#ifdef ASGTOOL_ATHENA
+#include "CLHEP/Units/SystemOfUnits.h"
+using CLHEP::GeV;
+#else
+#define GeV 1000
+#endif
+
+
+
 using namespace TauAnalysisTools;
 
 //______________________________________________________________________________
@@ -131,6 +142,34 @@ double TauAnalysisTools::tauAbsEta(const xAOD::TauJet& xTau)
   return std::abs(xTau.eta());
 }
 
+//______________________________________________________________________________
+double TauAnalysisTools::finalTauPt(const xAOD::TauJet& xTau)
+{
+  // return MVA based tau pt in GeV
+  return xTau.ptFinalCalib()/GeV;
+}
+
+//______________________________________________________________________________
+double TauAnalysisTools::finalTauEta(const xAOD::TauJet& xTau)
+{
+  // return MVA based tau eta
+  return xTau.etaFinalCalib();
+}
+
+//______________________________________________________________________________
+double TauAnalysisTools::finalTauAbsEta(const xAOD::TauJet& xTau)
+{
+  // return MVA based absolute tau eta
+  return std::abs(xTau.etaFinalCalib());
+}
+
+//______________________________________________________________________________
+double TauAnalysisTools::finalTauP(const xAOD::TauJet& xTau)
+{
+  // return tau P in GeV
+  return xTau.p4(xAOD::TauJetParameters::FinalCalib).P()/GeV;
+}
+
 //______________________________________________________________________________
 double TauAnalysisTools::tauLeadTrackEta(const xAOD::TauJet& xTau)
 {
@@ -148,6 +187,123 @@ double TauAnalysisTools::tauLeadTrackEta(const xAOD::TauJet& xTau)
   return dTrackEta;
 }
 
+//______________________________________________________________________________
+double TauAnalysisTools::truthTauPt(const xAOD::TauJet& xTau)
+{
+  // return truth tau Pt in GeV
+  const xAOD::TruthParticle* xTruthTau = getTruth(xTau);
+
+  // if there is a truth tau return pT, otherwise return 0 (getTruth will print an error)
+  if (xTruthTau!=nullptr && xTruthTau->auxdata<char>("IsHadronicTau"))
+    return xTruthTau->pt()/GeV;
+  else
+    return 0.;
+}
+
+//______________________________________________________________________________
+double TauAnalysisTools::truthTauAbsEta(const xAOD::TauJet& xTau)
+{
+  // return truth tau absolute eta
+  const xAOD::TruthParticle* xTruthTau = getTruth(xTau);
+
+  // if there is a truth tau return absolute eta, otherwise return -5 (getTruth will print an error)
+  if (xTruthTau!=nullptr && xTruthTau->auxdata<char>("IsHadronicTau"))
+    return xTruthTau->eta();
+  else
+    return -5.;
+}
+
+//______________________________________________________________________________
+double TauAnalysisTools::truthDecayMode(const xAOD::TauJet& xTau)
+{
+  // return truth tau decay mode.
+  int iDecayMode = getTruthDecayMode(xTau);
+  return static_cast<double>(iDecayMode);
+}
+
+//______________________________________________________________________________
+const xAOD::TruthParticle* TauAnalysisTools::getTruth(const xAOD::TauJet& xTau)
+{
+  typedef ElementLink< xAOD::TruthParticleContainer > Link_t;
+  if (!xTau.isAvailable< Link_t >("truthParticleLink"))
+  {
+    Error("TauAnalysisTools::getTruth", "No truth match information available. Please run TauTruthMatchingTool first");
+  }
+
+  static SG::AuxElement::Accessor<Link_t> accTruthParticleLink("truthParticleLink");
+  const Link_t xTruthTauLink = accTruthParticleLink(xTau);
+  const xAOD::TruthParticle* xTruthTau = xTruthTauLink.cachedElement();
+
+  return xTruthTau;
+}
+
+
+//______________________________________________________________________________
+xAOD::TauJetParameters::DecayMode TauAnalysisTools::getTruthDecayMode(const xAOD::TauJet& xTau)
+{
+  const xAOD::TruthParticle* xTruthTau = getTruth(xTau);
+
+  if (xTruthTau!=nullptr && xTruthTau->auxdata<char>("IsHadronicTau"))
+    return getTruthDecayMode(*xTruthTau);
+  else
+    return xAOD::TauJetParameters::Mode_Error;
+}
+
+//______________________________________________________________________________
+xAOD::TauJetParameters::DecayMode TauAnalysisTools::getTruthDecayMode(const xAOD::TruthParticle& xTruthTau)
+{
+  if (!(xTruthTau.isAvailable<size_t>("numCharged")))
+  {
+    Warning("TauAnalysisTools::getTruthDecayMode", "passed truth particle is not a truth tau, return Mode_Error");
+    return xAOD::TauJetParameters::Mode_Error;
+  }
+
+  int iCharged = getNTauDecayParticles(xTruthTau,MC::PID::PIPLUS, true) + getNTauDecayParticles(xTruthTau,MC::PID::KPLUS, true);
+  int iNeutral = getNTauDecayParticles(xTruthTau,MC::PID::PI0, true);
+  if (iCharged == 1)
+  {
+    if (iNeutral == 0) return xAOD::TauJetParameters::DecayMode::Mode_1p0n;
+    if (iNeutral == 1) return xAOD::TauJetParameters::DecayMode::Mode_1p1n;
+    if (iNeutral >= 2) return xAOD::TauJetParameters::DecayMode::Mode_1pXn;
+  }
+  else if (iCharged == 3)
+  {
+    if (iNeutral == 0) return xAOD::TauJetParameters::DecayMode::Mode_3p0n;
+    if (iNeutral >= 1) return xAOD::TauJetParameters::DecayMode::Mode_3pXn;
+  }
+
+  if (iCharged == 2 or iCharged == 4 or iCharged == 5)
+    return xAOD::TauJetParameters::DecayMode::Mode_Other;
+  if (iCharged == 0 or iCharged >=6)
+    return xAOD::TauJetParameters::DecayMode::Mode_NotSet;
+
+  // if you got here, something should have gone wrong
+  return xAOD::TauJetParameters::DecayMode::Mode_Error;
+}
+
+//______________________________________________________________________________
+int TauAnalysisTools::getNTauDecayParticles(const xAOD::TruthParticle& xTruthTau, int iPdgId, bool bCompareAbsoluteValues)
+{
+  int iNum = 0;
+  if (!xTruthTau.isAvailable<std::vector<int>>("DecayModeVector"))
+  {
+    Warning("TauAnalysisTools::getNTauDecayParticles", "passed truth particle is not a truth tau, return 0");
+    return 0;
+  }
+
+  static SG::AuxElement::ConstAccessor<std::vector<int> > accDecayModeVector("DecayModeVector");
+  for(auto iPdgId2 : accDecayModeVector(xTruthTau))
+    if (!bCompareAbsoluteValues)
+    {
+      if (iPdgId2 == iPdgId) iNum++;
+    }
+    else
+    {
+      if (std::abs(iPdgId2) == std::abs(iPdgId)) iNum++;
+    }
+  return iNum;
+}
+
 //______________________________________________________________________________
 bool TauAnalysisTools::testFileForEOFContainsCharacters(std::string sFileName)
 {
@@ -376,3 +532,149 @@ void TauAnalysisTools::correctedPi0Vectors(const xAOD::TauJet* xTau, std::vector
 
 }
 
+//______________________________________________________________________________
+void TauAnalysisTools::truthHadrons(const xAOD::TruthParticle* xTruthTau, std::vector<const xAOD::TruthParticle*>& vChargedHadrons, std::vector<const xAOD::TruthParticle*>& vNeutralHadrons)
+{
+  vChargedHadrons.clear();
+  vNeutralHadrons.clear();
+
+  // skip this tau if it has no decay vertex
+  if ( !xTruthTau->hasDecayVtx() )
+  {
+    Warning("TauAnalysisTools::truthHadrons", "Passed truth particle has no decay vertex.");
+    return;
+  }
+
+  // get vertex and check if it is valid
+  const xAOD::TruthVertex* xDecayVertex = xTruthTau->decayVtx();
+  if (!xDecayVertex)
+  {
+    Warning("TauAnalysisTools::truthHadrons", "Passed truth particle has no valid decay vertex.");
+    return;
+  }
+
+  // loop over outgoing particles 
+  for ( size_t iOutgoingParticle = 0; iOutgoingParticle < xDecayVertex->nOutgoingParticles(); ++iOutgoingParticle )
+  {
+
+    const xAOD::TruthParticle* xTruthDaughter = xDecayVertex->outgoingParticle(iOutgoingParticle);
+    if (!xTruthDaughter)
+    {
+      Warning("TauAnalysisTools::truthHadrons", "Truth daughter of tau decay was not found. Please ensure that this container has the full tau decay information or produce the TruthTaus container in AtlasDerivation.\nInformation on how to do this can be found here:\nhttps://twiki.cern.ch/twiki/bin/viewauth/AtlasProtected/TauPreRecommendations2015#Accessing_Tau_Truth_Information");
+      return;
+    }
+
+    // if tau decays into tau this is not a proper tau decay
+    if ( xTruthDaughter->isTau() )
+    {
+      Warning("TauAnalysisTools::truthHadrons", "Tau decays into a tau itself. Skip this decay");
+      return;
+    }
+
+    // ignore electrons, muons and neutrinos
+    if (xTruthDaughter->isElectron() or xTruthDaughter->isMuon() or xTruthDaughter->isNeutrino())
+      continue;
+
+    if (xTruthDaughter->isCharged())
+      vChargedHadrons.push_back(xTruthDaughter);
+    else 
+      vNeutralHadrons.push_back(xTruthDaughter);
+  }
+
+  return;
+  
+}
+
+//______________________________________________________________________________
+void TauAnalysisTools::truthHadrons(const xAOD::TauJet* xTau, std::vector<const xAOD::TruthParticle*>& vChargedHadrons, std::vector<const xAOD::TruthParticle*>& vNeutralHadrons)
+{
+
+  vChargedHadrons.clear();
+  vNeutralHadrons.clear();
+
+  // check if reco tau is a truth hadronic tau
+  typedef ElementLink< xAOD::TruthParticleContainer > Link_t;
+  if (!xTau->isAvailable< Link_t >("truthParticleLink"))
+  {
+    Error("TauAnalysisTools::truthHadrons", "No truth match information available. Please run TauTruthMatchingTool first");
+  }
+
+  static SG::AuxElement::Accessor<Link_t> accTruthParticleLink("truthParticleLink");
+  const Link_t xTruthTauLink = accTruthParticleLink(*xTau);
+  const xAOD::TruthParticle* xTruthTau = xTruthTauLink.cachedElement();
+
+  if (xTruthTau!=nullptr && xTruthTau->auxdata<char>("IsHadronicTau"))
+  {
+    truthHadrons(xTruthTau, vChargedHadrons, vNeutralHadrons);
+  }
+
+  return;  
+}
+
+//______________________________________________________________________________
+e_TruthMatchedParticleType TauAnalysisTools::getTruthParticleType(const xAOD::TauJet& xTau)
+{
+  typedef ElementLink< xAOD::TruthParticleContainer > Link_t;
+  if (!xTau.isAvailable< Link_t >("truthParticleLink"))
+    Error("TauAnalysisTools::getTruthParticleType", "No truth match information available. Please run TauTruthMatchingTool first.");
+
+  const xAOD::TruthParticle* xTruthParticle = xAOD::TauHelpers::getTruthParticle(&xTau);
+  if (xTruthParticle)
+  {
+    if (xTruthParticle->isTau())
+    {
+      static SG::AuxElement::ConstAccessor<char> accIsHadronicTau("IsHadronicTau");
+      if ((bool)accIsHadronicTau(*xTruthParticle))
+        return TruthHadronicTau;
+      else
+        return TruthLeptonicTau;
+    }
+    if (xTruthParticle->isMuon())
+      return TruthMuon;
+    if (xTruthParticle->isElectron())
+      return TruthElectron;
+  }
+  
+  // TODO: use const xAOD::Jet* xTruthJet = xAOD::TauHelpers::getLink<xAOD::Jet>(&xTau, "truthJetLink");
+  // currently it is unavailable as templated class is not in icc file
+  static SG::AuxElement::ConstAccessor< ElementLink< xAOD::JetContainer > > accTruthJetLink("truthJetLink");
+  const ElementLink< xAOD::JetContainer > lTruthParticleLink = accTruthJetLink(xTau);
+  if (lTruthParticleLink.isValid())
+    return TruthJet;
+
+  return Unknown;
+}
+
+//______________________________________________________________________________
+// Migrate DiTau tools pending in R22
+/*
+e_TruthMatchedParticleType TauAnalysisTools::getTruthParticleType(const xAOD::DiTauJet& xDiTau)
+{
+  if (!xDiTau.isAvailable<char>("IsTruthHadronic"))
+    Error("TauAnalysisTools::getTruthParticleType", "No truth match information available. Please run DiTauTruthMatchingTool first");
+  static SG::AuxElement::Accessor<char> accIsTruthHadronic("IsTruthHadronic");
+
+  e_TruthMatchedParticleType eTruthMatchedParticleType = Unknown;
+
+  if (accIsTruthHadronic(xDiTau))
+    eTruthMatchedParticleType = TruthHadronicDiTau;
+
+  return eTruthMatchedParticleType;
+}
+*/
+// This double is needed to save the average/actual mu for the y-axis in CommonEfficiencyTool.
+// The new trigger systematics (from tag 00-03-14 onwards) use mu dependent values.
+// The functions average_mu() and set_mu() are also needed to support this.
+double l_Mu;
+
+//______________________________________________________________________________
+double TauAnalysisTools::average_mu(const xAOD::TauJet& /*xTau*/)
+{
+  return l_Mu;
+}
+
+//______________________________________________________________________________
+void TauAnalysisTools::set_mu(unsigned int mu)
+{
+  l_Mu=mu;
+}