Back to home page

Project CMSSW displayed by LXR

 
 

    


File indexing completed on 2024-04-06 12:25:31

0001 #ifndef __FASTJET_BACKGROUND_EXTRACTOR_HH__
0002 #define __FASTJET_BACKGROUND_EXTRACTOR_HH__
0003 
0004 #include <fastjet/ClusterSequenceAreaBase.hh>
0005 #include <fastjet/RangeDefinition.hh>
0006 #include <iostream>
0007 
0008 namespace fastjet {
0009 
0010   /// \class BackgroundEstimator
0011   /// Class to estimate the density of the background per unit area
0012   ///
0013   /// The default behaviour of this class is to compute the global
0014   /// properties of the background as it is done in ClusterSequenceArea.
0015   /// On top of that, we provide methods to specify an explicit set of
0016   /// jets to use or a list of jets to exclude.
0017   /// We also provide all sorts of additional information regarding
0018   /// the background estimation like the jets that have been used or
0019   /// the number of pure-ghost jets.
0020   ///
0021   /// Default behaviour:
0022   ///   by default the list of included jets is the inclusive jets from
0023   ///   the given ClusterSequence; the list of explicitly excluded jets
0024   ///   is empty; we use 4-vector area
0025   ///
0026   /// Beware:
0027   ///   by default, to correctly handle partially empty events, the
0028   ///   class attempts to calculate an "empty area", based
0029   ///   (schematically) on
0030   ///
0031   ///          range.total_area() - sum_{jets_in_range} jets.area()
0032   ///
0033   ///   For ranges with small areas, this can be innacurate (particularly
0034   ///   relevant in dense events where empty_area should be zero and ends
0035   ///   up not being zero).
0036   ///
0037   ///   This calculation of empty area can be avoided if you supply a
0038   ///   ClusterSequenceArea class with explicit ghosts
0039   ///   (ActiveAreaExplicitGhosts). This is _recommended_!
0040   ///
0041   class BackgroundEstimator {
0042   public:
0043     /// default ctor
0044     /// \param csa      the ClusterSequenceArea to use
0045     /// \param range    the range over which jets will be considered
0046     BackgroundEstimator(const ClusterSequenceAreaBase &csa, const RangeDefinition &range);
0047 
0048     /// default dtor
0049     ~BackgroundEstimator();
0050 
0051     // retrieving information
0052     //-----------------------
0053 
0054     /// get the median rho
0055     double median_rho() {
0056       _recompute_if_needed();
0057       return _median_rho;
0058     }
0059 
0060     /// synonym for median rho [[do we have this? Both?]]
0061     double rho() { return median_rho(); }
0062 
0063     /// get the sigma
0064     double sigma() {
0065       _recompute_if_needed();
0066       return _sigma;
0067     }
0068 
0069     /// get the median area of the jets used to actually compute the background properties
0070     double mean_area() {
0071       _recompute_if_needed();
0072       return _mean_area;
0073     }
0074 
0075     /// get the number of jets used to actually compute the background properties
0076     unsigned int n_jets_used() {
0077       _recompute_if_needed();
0078       return _n_jets_used;
0079     }
0080 
0081     /// get the number of jets (within the given range) that have been
0082     /// explicitly excluded when computing the background properties
0083     unsigned int n_jets_excluded() {
0084       _recompute_if_needed();
0085       return _n_jets_excluded;
0086     }
0087 
0088     /// get the number of empty jets used when computing the background properties;
0089     /// (it is deduced from the empty area with an assumption about the average
0090     /// area of jets)
0091     double n_empty_jets() {
0092       _recompute_if_needed();
0093       return _n_empty_jets;
0094     }
0095 
0096     /// returns the estimate of the area (within Range) that is not occupied
0097     /// by the jets (excluded jets are removed from this count)
0098     double empty_area() {
0099       _recompute_if_needed();
0100       return _empty_area;
0101     }
0102 
0103     // configuring behaviour
0104     //----------------------
0105 
0106     /// reset to default values
0107     /// set the list of included jets to the inclusive jets and clear the excluded ones
0108     void reset();
0109 
0110     /// specify if one uses the scalar or 4-vector area
0111     ///  \param use_it             whether one uses the 4-vector area or not (true by default)
0112     void set_use_area_4vector(bool use_it = true) { _use_area_4vector = use_it; }
0113 
0114     /// set the list of included jets
0115     ///  \param included_jets      the list of jets to include
0116     ///  \param all_from_included  when true, we'll assume that the cluster sequence inclusive jets
0117     ///                            give all the potential jets in the range. In practice this means
0118     ///                            that the empty area will be computed from the inclusive jets rather
0119     ///                            than from the 'included_jets'. You can overwrite the default value
0120     ///                            and send it to 'false' e.g. when the included_jets you provide are
0121     ///                            themselves a list of inclusive jets.
0122     void set_included_jets(const std::vector<PseudoJet> &included_jets, bool all_from_inclusive = true) {
0123       _included_jets = included_jets;
0124       _all_from_inclusive = all_from_inclusive;
0125       _uptodate = false;
0126     }
0127 
0128     /// set the list of explicitly excluded jets
0129     ///  \param excluded_jets      the list of jets that have to be explicitly excluded
0130     void set_excluded_jets(const std::vector<PseudoJet> &excluded_jets) {
0131       _excluded_jets = excluded_jets;
0132       _uptodate = false;
0133     }
0134 
0135   private:
0136     /// do the actual job
0137     void _compute();
0138 
0139     /// check if the properties need to be recomputed
0140     /// and do so if needed
0141     void _recompute_if_needed() {
0142       if (!_uptodate)
0143         _compute();
0144       _uptodate = true;
0145     }
0146 
0147     // the information needed to do the computation
0148     const ClusterSequenceAreaBase &_csa;    ///< cluster sequence to get jets and areas from
0149     const RangeDefinition &_range;          ///< range to compute the background in
0150     std::vector<PseudoJet> _included_jets;  ///< jets to be used
0151     std::vector<PseudoJet> _excluded_jets;  ///< jets to be excluded
0152     bool _all_from_inclusive;               ///< when true, we'll assume that the incl jets are the complete set
0153     bool _use_area_4vector;
0154 
0155     // the actual results of the computation
0156     double _median_rho;             ///< background estimated density per unit area
0157     double _sigma;                  ///< background estimated fluctuations
0158     double _mean_area;              ///< mean area of the jets used to estimate the background
0159     unsigned int _n_jets_used;      ///< number of jets used to estimate the background
0160     unsigned int _n_jets_excluded;  ///< number of jets that have explicitly been excluded
0161     double _n_empty_jets;           ///< number of empty (pure-ghost) jets
0162     double _empty_area;             ///< the empty (pure-ghost/unclustered) area!
0163 
0164     // internal variables
0165     bool _uptodate;  ///< true when the background computation is up-to-date
0166   };
0167 
0168 }  // namespace fastjet
0169 
0170 #endif