#include <BackgroundEstimator.h>

Public Member Functions
	BackgroundEstimator (const ClusterSequenceAreaBase &csa, const RangeDefinition &range)

double	empty_area ()

double	mean_area ()
	get the median area of the jets used to actually compute the background properties More...

double	median_rho ()
	get the median rho More...

double	n_empty_jets ()

unsigned int	n_jets_excluded ()

unsigned int	n_jets_used ()
	get the number of jets used to actually compute the background properties More...

void	reset ()

double	rho ()
	synonym for median rho [[do we have this? Both?]] More...

void	set_excluded_jets (const std::vector< PseudoJet > &excluded_jets)

void	set_included_jets (const std::vector< PseudoJet > &included_jets, bool all_from_inclusive=true)

void	set_use_area_4vector (bool use_it=true)

double	sigma ()
	get the sigma More...

	~BackgroundEstimator ()
	default dtor More...

Private Member Functions
void	_compute ()
	do the actual job More...

void	_recompute_if_needed ()

Private Attributes
bool	_all_from_inclusive
	when true, we'll assume that the incl jets are the complete set More...

const ClusterSequenceAreaBase &	_csa
	cluster sequence to get jets and areas from More...

double	_empty_area
	the empty (pure-ghost/unclustered) area! More...

std::vector< PseudoJet >	_excluded_jets
	jets to be excluded More...

std::vector< PseudoJet >	_included_jets
	jets to be used More...

double	_mean_area
	mean area of the jets used to estimate the background More...

double	_median_rho
	background estimated density per unit area More...

double	_n_empty_jets
	number of empty (pure-ghost) jets More...

unsigned int	_n_jets_excluded
	number of jets that have explicitly been excluded More...

unsigned int	_n_jets_used
	number of jets used to estimate the background More...

const RangeDefinition &	_range
	range to compute the background in More...

double	_sigma
	background estimated fluctuations More...

bool	_uptodate
	true when the background computation is up-to-date More...

bool	_use_area_4vector

Detailed Description

Class to estimate the density of the background per unit area

The default behaviour of this class is to compute the global properties of the background as it is done in ClusterSequenceArea. On top of that, we provide methods to specify an explicit set of jets to use or a list of jets to exclude. We also provide all sorts of additional information regarding the background estimation like the jets that have been used or the number of pure-ghost jets.

Default behaviour: by default the list of included jets is the inclusive jets from the given ClusterSequence; the list of explicitly excluded jets is empty; we use 4-vector area

Beware: by default, to correctly handle partially empty events, the class attempts to calculate an "empty area", based (schematically) on

   range.total_area() - sum_{jets_in_range} jets.area()

For ranges with small areas, this can be innacurate (particularly relevant in dense events where empty_area should be zero and ends up not being zero).

This calculation of empty area can be avoided if you supply a ClusterSequenceArea class with explicit ghosts (ActiveAreaExplicitGhosts). This is recommended!

Definition at line 42 of file BackgroundEstimator.h.

Constructor & Destructor Documentation

BackgroundEstimator::BackgroundEstimator	(	const ClusterSequenceAreaBase &	csa,
		const RangeDefinition &	range
	)

default ctor

Parameters

csa	the ClusterSequenceArea to use
range	the range over which jets will be considered

Definition at line 24 of file BackgroundEstimator.cc.

References reset().

   : _csa(csa), _range(range){
   reset();
 }

BackgroundEstimator::~BackgroundEstimator ( )

default dtor

Definition at line 30 of file BackgroundEstimator.cc.

                                          {
 
 }

Member Function Documentation

void BackgroundEstimator::_compute ( )

private

do the actual job

Definition at line 58 of file BackgroundEstimator.cc.

References _all_from_inclusive, _csa, _empty_area, _excluded_jets, _included_jets, _mean_area, _median_rho, _n_empty_jets, _n_jets_excluded, _n_jets_used, _range, _sigma, _uptodate, _use_area_4vector, error, i, j, python.multivaluedict::sort(), and mathSSE::sqrt().

Referenced by _recompute_if_needed().

                                   {
   //TODO: check that the alg is OK for median computation
   //_check_jet_alg_good_for_median();
 
   // fill the vector of pt/area with the jets 
   //  - in included_jets
   //  - not in excluded_jets
   //  - in the range
   vector<double> pt_over_areas;
   double total_area  = 0.0;
   
   _n_jets_used = 0;
   _n_jets_excluded = 0;
 
   for (unsigned i = 0; i < _included_jets.size(); i++) {
     const PseudoJet & current_jet = _included_jets[i];
 
     // check that the jet is not explicitly excluded
     // we'll compare them using their cluster_history_index
     bool excluded = false;
     int ref_idx = current_jet.cluster_hist_index();
     for (unsigned int j = 0; j < _excluded_jets.size(); j++)
       excluded |= (_excluded_jets[j].cluster_hist_index() == ref_idx);
 
     // check if the jet is in the range
     if (_range.is_in_range(current_jet)){
       if (excluded){
     // keep track of the explicitly excluded jets
     _n_jets_excluded++;
       } else {
     double this_area = (_use_area_4vector) 
       ? _csa.area_4vector(current_jet).perp()
       : _csa.area(current_jet); 
     
     pt_over_areas.push_back(current_jet.perp()/this_area);
     total_area  += this_area;
     _n_jets_used++;
       }
     }
   }
   
   // there is nothing inside our region, so answer will always be zero
   if (pt_over_areas.size() == 0) {
     _median_rho = 0.0;
     _sigma      = 0.0;
     _mean_area  = 0.0;
     return;
   }
 
   // get median (pt/area) [this is the "old" median definition. It considers
   // only the "real" jets in calculating the median, i.e. excluding the
   // only-ghost ones; it will be supplemented with more info below]
   sort(pt_over_areas.begin(), pt_over_areas.end());
 
   // determine the number of empty jets
   _empty_area = 0.0;
   _n_empty_jets = 0.0;
   if (_csa.has_explicit_ghosts()) {
     _empty_area = 0.0;
     _n_empty_jets = 0;
   } else if (_all_from_inclusive) {
     _empty_area = _csa.empty_area(_range);
     _n_empty_jets = _csa.n_empty_jets(_range);
   } else {
     _empty_area = _csa.empty_area_from_jets(_included_jets, _range);
     _mean_area = total_area / _n_jets_used; // temporary value
     _n_empty_jets = _empty_area / _mean_area;
   }
 
   double total_njets = _n_jets_used + _n_empty_jets;
   total_area  += _empty_area;
 
 
   // now get the median & error, accounting for empty jets
   // define the fractions of distribution at median, median-1sigma
   double posn[2] = {0.5, (1.0-0.6827)/2.0};
   double res[2];
 
   for (int i = 0; i < 2; i++) {
     double nj_median_pos = (total_njets-1)*posn[i] - _n_empty_jets;
     double nj_median_ratio;
     if (nj_median_pos >= 0 && pt_over_areas.size() > 1) {
       int int_nj_median = int(nj_median_pos);
       nj_median_ratio =
         pt_over_areas[int_nj_median] * (int_nj_median+1-nj_median_pos)
         + pt_over_areas[int_nj_median+1] * (nj_median_pos - int_nj_median);
     } else {
       nj_median_ratio = 0.0;
     }
     res[i] = nj_median_ratio;
   }
 
   // store the results
   double error  = res[0] - res[1];
   _median_rho = res[0];
   _mean_area  = total_area / total_njets;
   _sigma      = error * sqrt(_mean_area);
 
   // record that the computation has been performed  
   _uptodate = true;
 }

void fastjet::BackgroundEstimator::_recompute_if_needed ( )

inlineprivate

check if the properties need to be recomputed and do so if needed

Definition at line 144 of file BackgroundEstimator.h.

References _compute(), and _uptodate.

Referenced by empty_area(), mean_area(), median_rho(), n_empty_jets(), n_jets_excluded(), n_jets_used(), and sigma().

                              {
     if (!_uptodate)
       _compute();
     _uptodate = true;
   }

double fastjet::BackgroundEstimator::empty_area ( )

inline

returns the estimate of the area (within Range) that is not occupied by the jets (excluded jets are removed from this count)

Definition at line 99 of file BackgroundEstimator.h.

References _empty_area, and _recompute_if_needed().

                      {
     _recompute_if_needed();
     return _empty_area;
   }

double fastjet::BackgroundEstimator::mean_area ( )

inline

get the median area of the jets used to actually compute the background properties

Definition at line 71 of file BackgroundEstimator.h.

References _mean_area, and _recompute_if_needed().

                     {
     _recompute_if_needed();
     return _mean_area;
   }

double fastjet::BackgroundEstimator::median_rho ( )

inline

get the median rho

Definition at line 56 of file BackgroundEstimator.h.

References _median_rho, and _recompute_if_needed().

Referenced by rho().

                      { 
     _recompute_if_needed();
     return _median_rho;
   }

double fastjet::BackgroundEstimator::n_empty_jets ( )

inline

get the number of empty jets used when computing the background properties; (it is deduced from the empty area with an assumption about the average area of jets)

Definition at line 92 of file BackgroundEstimator.h.

References _n_empty_jets, and _recompute_if_needed().

                        {
     _recompute_if_needed();
     return _n_empty_jets;
   }

unsigned int fastjet::BackgroundEstimator::n_jets_excluded ( )

inline

get the number of jets (within the given range) that have been explicitly excluded when computing the background properties

Definition at line 84 of file BackgroundEstimator.h.

References _n_jets_excluded, and _recompute_if_needed().

                                 {
     _recompute_if_needed();
     return _n_jets_excluded;
   }

unsigned int fastjet::BackgroundEstimator::n_jets_used ( )

inline

get the number of jets used to actually compute the background properties

Definition at line 77 of file BackgroundEstimator.h.

References _n_jets_used, and _recompute_if_needed().

                             {
     _recompute_if_needed();
     return _n_jets_used;
   }

void BackgroundEstimator::reset ( void )

reset to default values set the list of included jets to the inclusive jets and clear the excluded ones

Definition at line 36 of file BackgroundEstimator.cc.

References _all_from_inclusive, _csa, _empty_area, _excluded_jets, _included_jets, _mean_area, _median_rho, _n_empty_jets, _n_jets_excluded, _n_jets_used, _sigma, _uptodate, and set_use_area_4vector().

Referenced by BackgroundEstimator().

                                {
   // set the list of included jets to the inclusive jets 
   _included_jets = _csa.inclusive_jets();
   _all_from_inclusive = true;
   //set_included_jets(_csa.inclusive_jets());
 
   // clear the list of explicitly excluded jets
   _excluded_jets.clear();
   //set_excluded_jets(vector<PseudoJet>());
 
   // set the remaining default parameters
   set_use_area_4vector();  // true by default
 
   // reset the computed values
   _median_rho = _sigma = _mean_area = 0.0;
   _n_jets_used = _n_jets_excluded = _n_empty_jets = 0;
   _empty_area = 0.0;
   _uptodate = false;
 }

double fastjet::BackgroundEstimator::rho ( )

inline

synonym for median rho [[do we have this? Both?]]

Definition at line 62 of file BackgroundEstimator.h.

References median_rho().

Referenced by VirtualJetProducer::writeJets().

62 {return median_rho();}

fastjet::BackgroundEstimator::median_rho

double median_rho()

get the median rho

Definition: BackgroundEstimator.h:56

void fastjet::BackgroundEstimator::set_excluded_jets ( const std::vector< PseudoJet > & excluded_jets )

inline

set the list of explicitly excluded jets

Parameters

excluded_jets the list of jets that have to be explicitly excluded

Definition at line 133 of file BackgroundEstimator.h.

References _excluded_jets, and _uptodate.

Referenced by VirtualJetProducer::writeJets().

                                                                    {
     _excluded_jets = excluded_jets;
     _uptodate = false;  
   }

void fastjet::BackgroundEstimator::set_included_jets	(	const std::vector< PseudoJet > &	included_jets,
		bool	all_from_inclusive = `true`
	)

inline

set the list of included jets

Parameters

included_jets	the list of jets to include
all_from_included	when true, we'll assume that the cluster sequence inclusive jets give all the potential jets in the range. In practice this means that the empty area will be computed from the inclusive jets rather than from the 'included_jets'. You can overwrite the default value and send it to 'false' e.g. when the included_jets you provide are themselves a list of inclusive jets.

Definition at line 125 of file BackgroundEstimator.h.

References _all_from_inclusive, _included_jets, and _uptodate.

                                                                                                    {
     _included_jets = included_jets;
     _all_from_inclusive = all_from_inclusive;
     _uptodate = false;
   }

void fastjet::BackgroundEstimator::set_use_area_4vector ( bool use_it = true )

inline

specify if one uses the scalar or 4-vector area

Parameters

use_it whether one uses the 4-vector area or not (true by default)

Definition at line 113 of file BackgroundEstimator.h.

References _use_area_4vector.

Referenced by reset().

                                                {
     _use_area_4vector = use_it;
   }

double fastjet::BackgroundEstimator::sigma ( )

inline

get the sigma

Definition at line 65 of file BackgroundEstimator.h.

References _recompute_if_needed(), and _sigma.

Referenced by VirtualJetProducer::writeJets().

                  {
     _recompute_if_needed();
     return _sigma;
   }

Member Data Documentation

bool fastjet::BackgroundEstimator::_all_from_inclusive

private

when true, we'll assume that the incl jets are the complete set

Definition at line 155 of file BackgroundEstimator.h.

Referenced by _compute(), reset(), and set_included_jets().

const ClusterSequenceAreaBase& fastjet::BackgroundEstimator::_csa

private

cluster sequence to get jets and areas from

Definition at line 151 of file BackgroundEstimator.h.

Referenced by _compute(), and reset().

double fastjet::BackgroundEstimator::_empty_area

private

the empty (pure-ghost/unclustered) area!

Definition at line 165 of file BackgroundEstimator.h.

Referenced by _compute(), empty_area(), and reset().

std::vector<PseudoJet> fastjet::BackgroundEstimator::_excluded_jets

private

jets to be excluded

Definition at line 154 of file BackgroundEstimator.h.

Referenced by _compute(), reset(), and set_excluded_jets().

std::vector<PseudoJet> fastjet::BackgroundEstimator::_included_jets

private

jets to be used

Definition at line 153 of file BackgroundEstimator.h.

Referenced by _compute(), reset(), and set_included_jets().

double fastjet::BackgroundEstimator::_mean_area

private

mean area of the jets used to estimate the background

Definition at line 161 of file BackgroundEstimator.h.

Referenced by _compute(), mean_area(), and reset().

double fastjet::BackgroundEstimator::_median_rho

private

background estimated density per unit area

Definition at line 159 of file BackgroundEstimator.h.

Referenced by _compute(), median_rho(), and reset().

double fastjet::BackgroundEstimator::_n_empty_jets

private

number of empty (pure-ghost) jets

Definition at line 164 of file BackgroundEstimator.h.

Referenced by _compute(), n_empty_jets(), and reset().

unsigned int fastjet::BackgroundEstimator::_n_jets_excluded

private

number of jets that have explicitly been excluded

Definition at line 163 of file BackgroundEstimator.h.

Referenced by _compute(), n_jets_excluded(), and reset().

unsigned int fastjet::BackgroundEstimator::_n_jets_used

private

number of jets used to estimate the background

Definition at line 162 of file BackgroundEstimator.h.

Referenced by _compute(), n_jets_used(), and reset().

const RangeDefinition& fastjet::BackgroundEstimator::_range

private

range to compute the background in

Definition at line 152 of file BackgroundEstimator.h.

Referenced by _compute().

double fastjet::BackgroundEstimator::_sigma

private

background estimated fluctuations

Definition at line 160 of file BackgroundEstimator.h.

Referenced by _compute(), reset(), and sigma().

bool fastjet::BackgroundEstimator::_uptodate

private

true when the background computation is up-to-date

Definition at line 168 of file BackgroundEstimator.h.

Referenced by _compute(), _recompute_if_needed(), reset(), set_excluded_jets(), and set_included_jets().

bool fastjet::BackgroundEstimator::_use_area_4vector

private

Definition at line 156 of file BackgroundEstimator.h.

Referenced by _compute(), and set_use_area_4vector().

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation