fastjet::BackgroundEstimator Class Reference

#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 41 of file BackgroundEstimator.h.

Constructor & Destructor Documentation

BackgroundEstimator()

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.

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

References reset().

~BackgroundEstimator()

BackgroundEstimator::~BackgroundEstimator

(

)

default dtor

Definition at line 30 of file BackgroundEstimator.cc.

{}

Member Function Documentation

_compute()

void BackgroundEstimator::_compute ( )

private

do the actual job

Definition at line 55 of file BackgroundEstimator.cc.

                                   {
  //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.empty()) {
    _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;
}

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, relativeConstraints::error, mps_fire::i, createfilelist::int, dqmiolumiharvest::j, and mathSSE::sqrt().

Referenced by _recompute_if_needed().

_recompute_if_needed()

void fastjet::BackgroundEstimator::_recompute_if_needed ( )

inlineprivate

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

Definition at line 141 of file BackgroundEstimator.h.

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

References _compute(), and _uptodate.

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

empty_area()

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 98 of file BackgroundEstimator.h.

                        {
      _recompute_if_needed();
      return _empty_area;
    }

References _empty_area, and _recompute_if_needed().

mean_area()

double fastjet::BackgroundEstimator::mean_area ( )

inline

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

Definition at line 70 of file BackgroundEstimator.h.

                       {
      _recompute_if_needed();
      return _mean_area;
    }

References _mean_area, and _recompute_if_needed().

median_rho()

double fastjet::BackgroundEstimator::median_rho ( )

inline

get the median rho

Definition at line 55 of file BackgroundEstimator.h.

                        {
      _recompute_if_needed();
      return _median_rho;
    }

References _median_rho, and _recompute_if_needed().

Referenced by rho().

n_empty_jets()

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 91 of file BackgroundEstimator.h.

                          {
      _recompute_if_needed();
      return _n_empty_jets;
    }

References _n_empty_jets, and _recompute_if_needed().

n_jets_excluded()

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 83 of file BackgroundEstimator.h.

                                   {
      _recompute_if_needed();
      return _n_jets_excluded;
    }

References _n_jets_excluded, and _recompute_if_needed().

n_jets_used()

unsigned int fastjet::BackgroundEstimator::n_jets_used ( )

inline

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

Definition at line 76 of file BackgroundEstimator.h.

                               {
      _recompute_if_needed();
      return _n_jets_used;
    }

References _n_jets_used, and _recompute_if_needed().

reset()

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 34 of file BackgroundEstimator.cc.

                                {
  // 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;
}

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().

rho()

double fastjet::BackgroundEstimator::rho ( )

inline

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

Definition at line 61 of file BackgroundEstimator.h.

{ return median_rho(); }

References median_rho().

Referenced by Lepton.Lepton::absIsoFromEA(), Muon.Muon::absIsoWithFSR(), and VirtualJetProducer::writeJets().

set_excluded_jets()

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 130 of file BackgroundEstimator.h.

                                                                      {
      _excluded_jets = excluded_jets;
      _uptodate = false;
    }

References _excluded_jets, and _uptodate.

Referenced by VirtualJetProducer::writeJets().

set_included_jets()

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 122 of file BackgroundEstimator.h.

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

References _all_from_inclusive, _included_jets, and _uptodate.

set_use_area_4vector()

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 112 of file BackgroundEstimator.h.

{ _use_area_4vector = use_it; }

References _use_area_4vector.

Referenced by reset().

sigma()

double fastjet::BackgroundEstimator::sigma ( )

inline

get the sigma

Definition at line 64 of file BackgroundEstimator.h.

                   {
      _recompute_if_needed();
      return _sigma;
    }

References _recompute_if_needed(), and _sigma.

Referenced by VirtualJetProducer::writeJets().

Member Data Documentation

_all_from_inclusive

bool fastjet::BackgroundEstimator::_all_from_inclusive

private

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

Definition at line 152 of file BackgroundEstimator.h.

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

_csa

const ClusterSequenceAreaBase& fastjet::BackgroundEstimator::_csa

private

cluster sequence to get jets and areas from

Definition at line 148 of file BackgroundEstimator.h.

Referenced by _compute(), and reset().

_empty_area

double fastjet::BackgroundEstimator::_empty_area

private

the empty (pure-ghost/unclustered) area!

Definition at line 162 of file BackgroundEstimator.h.

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

_excluded_jets

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

private

jets to be excluded

Definition at line 151 of file BackgroundEstimator.h.

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

_included_jets

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

private

jets to be used

Definition at line 150 of file BackgroundEstimator.h.

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

_mean_area

double fastjet::BackgroundEstimator::_mean_area

private

mean area of the jets used to estimate the background

Definition at line 158 of file BackgroundEstimator.h.

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

_median_rho

double fastjet::BackgroundEstimator::_median_rho

private

background estimated density per unit area

Definition at line 156 of file BackgroundEstimator.h.

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

_n_empty_jets

double fastjet::BackgroundEstimator::_n_empty_jets

private

number of empty (pure-ghost) jets

Definition at line 161 of file BackgroundEstimator.h.

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

_n_jets_excluded

unsigned int fastjet::BackgroundEstimator::_n_jets_excluded

private

number of jets that have explicitly been excluded

Definition at line 160 of file BackgroundEstimator.h.

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

_n_jets_used

unsigned int fastjet::BackgroundEstimator::_n_jets_used

private

number of jets used to estimate the background

Definition at line 159 of file BackgroundEstimator.h.

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

_range

const RangeDefinition& fastjet::BackgroundEstimator::_range

private

range to compute the background in

Definition at line 149 of file BackgroundEstimator.h.

Referenced by _compute().

_sigma

double fastjet::BackgroundEstimator::_sigma

private

background estimated fluctuations

Definition at line 157 of file BackgroundEstimator.h.

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

_uptodate

bool fastjet::BackgroundEstimator::_uptodate

private

true when the background computation is up-to-date

Definition at line 165 of file BackgroundEstimator.h.

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

_use_area_4vector

bool fastjet::BackgroundEstimator::_use_area_4vector

private

Definition at line 153 of file BackgroundEstimator.h.

Referenced by _compute(), and set_use_area_4vector().