FastJet 3.0.5
GridMedianBackgroundEstimator.hh
00001 #ifndef __GRID_MEDIAN_BACKGROUND_ESTIMATOR_HH__
00002 #define __GRID_MEDIAN_BACKGROUND_ESTIMATOR_HH__
00003 
00004 //STARTHEADER
00005 // $Id: GridMedianBackgroundEstimator.hh 2580 2011-09-13 17:25:43Z salam $
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/BackgroundEstimatorBase.hh"
00034 
00035 FASTJET_BEGIN_NAMESPACE      // defined in fastjet/internal/base.hh
00036 
00037 /// @ingroup tools_background
00038 /// \class GridMedianBackgroundEstimator
00039 /// 
00040 /// Background Estimator based on the median pt/area of a set of grid
00041 /// cells. 
00042 ///
00043 /// Description of the method:
00044 ///   This background estimator works by projecting the event onto a
00045 ///   grid in rapidity and azimuth. In each grid cell, the scalar pt
00046 ///   sum of the particles in the cell is computed. The background
00047 ///   density is then estimated by the median of (scalar pt sum/cell
00048 ///   area) for all cells.
00049 ///
00050 /// Parameters:
00051 ///   The class takes 2 arguments: the absolute rapidity extent of the 
00052 ///   cells and the size of the grid cells. Note that the size of the cell
00053 ///   will be adjusted in azimuth to satisfy the 2pi periodicity and
00054 ///   in rapidity to match the requested rapidity extent.
00055 ///
00056 /// Rescaling:
00057 ///   It is possible to use a rescaling profile. In this case, the
00058 ///   profile needs to be set before setting the particles and it will
00059 ///   be applied to each particle (i.e. not to each cell). 
00060 ///   Note also that in this case one needs to call rho(jet) instead of
00061 ///   rho() [Without rescaling, they are identical]
00062 ///
00063 class GridMedianBackgroundEstimator : public BackgroundEstimatorBase {
00064 public:
00065   /// @name  constructors and destructors
00066   //\{
00067   //----------------------------------------------------------------
00068   ///   \param ymax   maximal absolute rapidity extent of the grid
00069   ///   \param requested_grid_spacing   size of the grid cell. The
00070   ///            "real" cell size could differ due e.g. to the 2pi
00071   ///             periodicity in azimuthal angle (size, not area)
00072   GridMedianBackgroundEstimator(double ymax, double requested_grid_spacing) :
00073     _ymin(-ymax), _ymax(ymax), 
00074     _requested_grid_spacing(requested_grid_spacing),
00075     _has_particles(false){setup_grid();}
00076   //\}
00077 
00078 
00079   /// @name setting a new event
00080   //\{
00081   //----------------------------------------------------------------
00082 
00083   /// tell the background estimator that it has a new event, composed
00084   /// of the specified particles.
00085   void set_particles(const std::vector<PseudoJet> & particles);
00086 
00087   //\}
00088 
00089   /// @name  retrieving fundamental information
00090   //\{
00091   //----------------------------------------------------------------
00092 
00093   /// returns rho, the median background density per unit area
00094   double rho() const;
00095 
00096   /// returns sigma, the background fluctuations per unit area; must be
00097   /// multipled by sqrt(area) to get fluctuations for a region of a
00098   /// given area.
00099   double sigma() const;
00100 
00101   /// returns rho, the background density per unit area, locally at the
00102   /// position of a given jet. Note that this is not const, because a
00103   /// user may then wish to query other aspects of the background that
00104   /// could depend on the position of the jet last used for a rho(jet)
00105   /// determination.
00106   double rho(const PseudoJet & jet);
00107 
00108   /// returns sigma, the background fluctuations per unit area, locally at
00109   /// the position of a given jet. As for rho(jet), it is non-const.
00110   double sigma(const PseudoJet & jet);
00111 
00112   /// returns true if this background estimator has support for
00113   /// determination of sigma
00114   bool has_sigma() {return true;}
00115 
00116   /// returns the area of the grid cells (all identical, but
00117   /// referred to as "mean" area for uniformity with JetMedianBGE).
00118   double mean_area() const {return _cell_area;}
00119   //\}
00120 
00121   /// @name configuring the behaviour
00122   //\{
00123   //----------------------------------------------------------------
00124 
00125   /// Set a pointer to a class that calculates the rescaling factor as
00126   /// a function of the jet (position). Note that the rescaling factor
00127   /// is used both in the determination of the "global" rho (the pt/A
00128   /// of each jet is divided by this factor) and when asking for a
00129   /// local rho (the result is multiplied by this factor).
00130   ///
00131   /// The BackgroundRescalingYPolynomial class can be used to get a
00132   /// rescaling that depends just on rapidity.
00133   ///
00134   /// Note that this has to be called BEFORE any attempt to do an
00135   /// actual computation
00136   virtual void set_rescaling_class(const FunctionOfPseudoJet<double> * rescaling_class);
00137 
00138   //\}
00139 
00140   /// @name description
00141   //\{
00142   //----------------------------------------------------------------
00143 
00144   /// returns a textual description of the background estimator
00145   std::string description() const;
00146 
00147   //\}
00148 
00149 
00150 private:
00151   /// configure the grid
00152   void setup_grid();
00153 
00154   /// retrieve the grid cell index for a given PseudoJet
00155   int igrid(const PseudoJet & p) const;
00156 
00157   /// verify that particles have been set and throw an error if not
00158   void verify_particles_set() const;
00159 
00160   // information about the grid
00161   double _ymin, _ymax, _dy, _dphi, _requested_grid_spacing, _cell_area;
00162   int _ny, _nphi, _ntotal;
00163 
00164   // information abotu the event
00165   std::vector<double> _scalar_pt;
00166   bool _has_particles;
00167 
00168   // various warnings to let people aware of potential dangers
00169   LimitedWarning _warning_rho_of_jet;
00170   LimitedWarning _warning_rescaling;
00171 };
00172 
00173 FASTJET_END_NAMESPACE        // defined in fastjet/internal/base.hh
00174 
00175 #endif // __GRID_MEDIAN_BACKGROUND_ESTIMATOR_HH__
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends