FastJet 3.0.4
JHTopTagger.hh
00001 #ifndef __FASTJET_JH_TOP_TAGGER_HH__
00002 #define __FASTJET_JH_TOP_TAGGER_HH__
00003 
00004 //STARTHEADER
00005 // $Id: JHTopTagger.hh 2689 2011-11-14 14:51:06Z soyez $
00006 //
00007 // Copyright (c) 2005-2011, Matteo Cacciari, Gavin P. Salam and Gregory Soyez
00008 //
00009 //----------------------------------------------------------------------
00010 // This file is part of FastJet.
00011 //
00012 //  FastJet is free software; you can redistribute it and/or modify
00013 //  it under the terms of the GNU General Public License as published by
00014 //  the Free Software Foundation; either version 2 of the License, or
00015 //  (at your option) any later version.
00016 //
00017 //  The algorithms that underlie FastJet have required considerable
00018 //  development and are described in hep-ph/0512210. If you use
00019 //  FastJet as part of work towards a scientific publication, please
00020 //  include a citation to the FastJet paper.
00021 //
00022 //  FastJet is distributed in the hope that it will be useful,
00023 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
00024 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00025 //  GNU General Public License for more details.
00026 //
00027 //  You should have received a copy of the GNU General Public License
00028 //  along with FastJet. If not, see <http://www.gnu.org/licenses/>.
00029 //----------------------------------------------------------------------
00030 //ENDHEADER
00031 
00032 
00033 #include <fastjet/tools/TopTaggerBase.hh>
00034 #include <fastjet/CompositeJetStructure.hh>
00035 #include <fastjet/LimitedWarning.hh>
00036 
00037 FASTJET_BEGIN_NAMESPACE
00038 
00039 class JHTopTagger;
00040 class JHTopTaggerStructure;
00041 
00042 //----------------------------------------------------------------------
00043 /// @ingroup tools_taggers
00044 /// \class JHTopTagger
00045 /// Class that helps perform boosted top tagging using the "Johns Hopkins"
00046 /// method from arXiv:0806.0848 (Kaplan, Rehermann, Schwartz
00047 /// and Tweedie)
00048 ///
00049 ///The tagger proceeds as follows:
00050 ///  - start from a jet J obtained with the Cambridge/Aachen algorithm
00051 ///  - undo the last iteration j -> j_1,j_2 (with pt_1>pt_2) until the
00052 ///    two subjets satisfy pt_1 > delta_p pt_J (with pt_J the pt of
00053 ///    the original jet) and |y_1 - y_2| + |phi_1 - phi_2| > delta_r.
00054 ///  - if one of these criteria is not satisfied, carry on the
00055 ///    procedure with j_1 (discarding j_2)
00056 ///  - for each of the subjets found, repeat the procedure. If some
00057 ///    new substructure is found, keep these 2 new subjets, otherwise
00058 ///    keep the original subjet (found during the first iteration)
00059 ///  - at this stage, one has at most 4 subjets. If one has less than
00060 ///    3, the tagger has failed.
00061 ///  - reconstruct the W from the 2 subjets with a mass closest to the
00062 ///    W mass
00063 ///  - impose that the W helicity angle be less than a threshold
00064 ///    cos_theta_W_max.
00065 ///
00066 /// \section input Input conditions
00067 /// 
00068 ///  - the original jet must have an associated (and valid)
00069 ///    ClusterSequence
00070 ///  - the tagger is designed to work with jets formed by the
00071 ///    Cambridge/Aachen (C/A) algorithm; if a non-C/A jet is passed to
00072 ///    the tagger, a warning will be issued
00073 ///
00074 /// \section Example
00075 ///
00076 /// A  JHTopTagger can be used as follows:
00077 ///
00078 /// \code
00079 ///    double delta_p = 0.10; // subjets must carry at least this fraction of the original jet's p_t
00080 ///    double delta_r = 0.19; // subjets must be separated by at least this Manhattan distance
00081 ///    double cos_theta_W_max = 0.7; // the maximal allowed value of the W helicity angle
00082 ///    JHTopTagger top_tagger(delta_p, delta_r, cos_theta_W_max);
00083 ///    // indicate the acceptable range of top, W masses (default: no limits)
00084 ///    top_tagger.set_top_selector(SelectorMassRange(150,200));
00085 ///    top_tagger.set_W_selector  (SelectorMassRange( 65, 95));
00086 ///    // now try and tag a jet
00087 ///    PseudoJet top_candidate = top_tagger(jet);  // jet should come from a Cambridge/Aachen clustering
00088 ///    if (top_candidate != 0) { // successful tagging
00089 ///      double top_mass = top_candidate.m();
00090 ///      double W_mass   = top_candidate.structure_of<JHTopTagger>().W().m();
00091 ///    }
00092 /// \endcode
00093 ///
00094 /// The full set of information available from the structure_of<JHTopTagger>() 
00095 /// call is
00096 ///
00097 /// - PseudoJet W()    : the W subjet of the top candidate
00098 /// - PseudoJet non_W(): non-W subjet(s) of the top candidate (i.e. the b)
00099 /// - double cos_theta_W(): the W helicity angle
00100 /// - PseudoJet W1(): the harder of the two prongs of the W
00101 /// - PseudoJet W2(): the softer of the two prongs of the W
00102 ///
00103 /// The structure of the top_candidate can also be accessed through its
00104 /// pieces() function:
00105 ///
00106 /// - top_candidate.pieces()[0]: W
00107 /// - top_candidate.pieces()[1]: non_W
00108 ///
00109 /// The W itself has two pieces (corresponding to W1, W2). 
00110 ///
00111 /// The existence of the first two of the structural calls (W(),
00112 /// non_W()) and the fact that the top is made of two pieces (W,
00113 /// non_W) are features that should be common to all taggers derived
00114 /// from TopTaggerBase.
00115 ///
00116 /// See also \subpage Example13 for a full usage example.
00117 ///
00118 class JHTopTagger : public TopTaggerBase {
00119 public:
00120   /// default ctor
00121   /// The parameters are the following:
00122   ///  \param delta_p          fractional pt cut imposed on the subjets
00123   ///                          (computed as a fraction of the original jet)
00124   ///  \param delta_r          minimal distance between 2 subjets
00125   ///                          (computed as |y1-y2|+|phi1-phi2|)
00126   ///  \param cos_theta_W_max  the maximal value for the polarisation 
00127   ///                          angle of the W
00128   ///  \param mW               the W mass
00129   ///
00130   /// The default values of all these parameters are taken from
00131   /// arXiv:0806:0848
00132   JHTopTagger(const double delta_p=0.10, const double delta_r=0.19, 
00133               double cos_theta_W_max=0.7, double mW=80.4)
00134     : _delta_p(delta_p), _delta_r(delta_r),
00135       _cos_theta_W_max(cos_theta_W_max), _mW(mW){};
00136 
00137   /// returns a textual description of the tagger
00138   virtual std::string description() const;
00139 
00140   /// runs the tagger on the given jet and
00141   /// returns the tagged PseudoJet if successful, or a PseudoJet==0 otherwise
00142   /// (standard access is through operator()).
00143   ///  \param jet   the PseudoJet to tag
00144   virtual PseudoJet result(const PseudoJet & jet) const;
00145 
00146   // the type of the associated structure
00147   typedef JHTopTaggerStructure StructureType;
00148 
00149 protected:
00150   /// runs the Johns Hopkins decomposition procedure
00151   std::vector<PseudoJet> _split_once(const PseudoJet & jet_to_split,
00152                                      const PseudoJet & reference_jet) const;
00153 
00154   double _delta_p, _delta_r, _cos_theta_W_max, _mW;
00155   static LimitedWarning _warnings_nonca;
00156 };
00157 
00158 
00159 //------------------------------------------------------------------------
00160 /// @ingroup tools_taggers
00161 /// \class JHTopTaggerStructure
00162 /// the structure returned by the JHTopTagger transformer.
00163 ///
00164 /// See the JHTopTagger class description for the details of what
00165 /// is inside this structure
00166 ///
00167 class JHTopTaggerStructure : public CompositeJetStructure, public TopTaggerBaseStructure {
00168 public:
00169   /// ctor with pieces initialisation
00170   JHTopTaggerStructure(std::vector<PseudoJet> pieces_in,
00171                  const JetDefinition::Recombiner *recombiner = 0) :
00172     CompositeJetStructure(pieces_in, recombiner), _cos_theta_w(0.0){}
00173 
00174   /// returns the W subjet
00175   inline const PseudoJet & W() const{ 
00176     return _pieces[0];
00177   }
00178 
00179   /// returns the first W subjet (the harder)
00180   inline PseudoJet W1() const{
00181     assert(W().pieces().size()>0);
00182     return W().pieces()[0];
00183   }
00184   
00185   /// returns the second W subjet
00186   inline PseudoJet W2() const{
00187     assert(W().pieces().size()>1);
00188     return W().pieces()[1];
00189   }
00190 
00191   /// returns the non-W subjet
00192   /// It will have 1 or 2 pieces depending on whether the tagger has
00193   /// found 3 or 4 pieces
00194   inline const PseudoJet & non_W() const{ 
00195     return _pieces[1];
00196   }
00197 
00198   /// returns the W helicity angle
00199   inline double cos_theta_W() const {return _cos_theta_w;}
00200 
00201 //  /// returns the original jet (before tagging)
00202 //  const PseudoJet & original() const {return _original_jet;}
00203 
00204 
00205 protected:
00206   double _cos_theta_w;      ///< the W helicity angle
00207   //PseudoJet _W;             ///< the tagged W
00208   //PseudoJet _non_W;         ///< the remaining pieces
00209 //  PseudoJet _original_jet;  ///< the original jet (before tagging)
00210 
00211   // allow the tagger to set these
00212   friend class JHTopTagger;
00213 };
00214 
00215 
00216 
00217 FASTJET_END_NAMESPACE
00218 
00219 #endif  //  __FASTJET_JH_TOP_TAGGER_HH__
00220 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends