cafe::Stat Class Reference
[CAF Environment (Cafe)]

#include <Stat.hpp>

Inheritance diagram for cafe::Stat:

Detailed Description

Class to collect selections statistics and print efficiencies.

The Stat processor is designed to handle the event selection efficiencies and events weights applied during the cut flow. To calculate the efficiency one must add "Stat(stname)" call in the beginning of the instruction "cafe.Run: ...". Than add following lines to the selection code (see, e.g. caf_util/src/ TopologicalSelector.cpp):

 #include "cafe/Stat.hpp" 
 StatPointer stat ; 
 event.get("StatPointer", stat) ; 
 
 ... Selection 1 ...
 
 stat->EventSelected("Selection 1 name") ;
 
 ... Selection 2 ....
 
 stat->EventSelected("Selection 2 name") ;

For each cut the efficiency is calculated as "number of events after cut" divided by "number of events before cut". The total selection efficiency is calculated as "number of events after cut" divided by "initial number of events", where "initial number of events" corresponds to the position of the "Stat(stname)" call in the "cafe.Run: ..." event flow. The best place for adding this processor is after "FindDuplicateEvents" processor, but before a first selector. The output efficiencies and corresponding statistical errors will be printed in the html and tex file. These efficiencies as well as the number of events after each cut available via Stat class accessors.

One can also apply the event weights at the any place in the cut flow. For this add the following instruction to the code (see e.g. caf_eff_utils/src/ MuonCorr.cpp):

 stat.applyWeight(weight_name, weight) ;

Individual weights are saved in the Stat class and the global event weight calculated as the product of all individual event weights applied up to the current selection. The average weights are printed in the output html file as well as the efficiency corrected by the global event weight. One should note the the product of the average individual event weights are not equal to the average global weight, because the averaging is done at the different selection stage and depends on the event sample selected at this stage. All individual weights and the global event weight available via Stat accessors. For example, to correct the histogram with the global event weight, one could add following lines to the code:

 #include "cafe/Stat.hpp" 
 StatPointer stat ; 
 event.get("StatPointer", stat) ; 

 Stat* statptr = stat.pointer() ;
 double weight = 0.0 ; // or any error value you want
 if (statptr) {
    try {
    weight = statptr->eventWeight("global"); 
    } catch (cafe::StatWeightNotFoundException& ex) {
    // you can do something different here, or just ignore the exception
      err() << "Processor [" << name()
            <<"]: weight not found " << ex._weight_name ;
            << endl ;
      exit(1) ;
    }
}

 hist->Fill(x,weight);

To make the histogram of the individual event weight one could use following example:

 float weight = statptr->eventWeight("individual_weight_name"); 
 hist->Fill(weight) ;

If you process several different samples in one job, Stat processor can handle with situation and keep efficiencies and weights for each sample separately. First, one need to specify sample names using the Sample configuration option, e.g.

 stname.Sample: sample_name1, sample_name2.

If no sample specified, the default sample with name equal to the Stat class name will be created. Than the event tags to tag different samples should be specified:

 sample_name1.UseTag: tag1 
 sample_name2.UseTag: tag2

If tag is not specified all selected events will be added to a sample. One event can be counted in the several samples.

Finally one should tag the events in the very beginning acording to the sample flavor (before Stat processor in the "cafe.Run: ..." instruction). For this you need a special processor. Such processor could compare the file name with the given mask and assign a tag according to the file name. An example of a processor could be found in the tt_emu_caf package (see TagFileName processor).

All accessors in the Stat class have an option to specify the sample name when you acess efficiencies and weights.

The Stat processor also can handle the systematics errors. If systematics errors come from the uncertainties in the event weight than it is sufficient to specify weights with systematics shift together with the nominal event weight:

 stat.applyWeight(weight_name, weight, weight_positly_shifted, weight_negatively_shifted) ;

The errors for the average event weight in the output html table will contains corresponding positive and negative systematics.

If the systematics change the selection parameter (e.g. JES will affect the jet pT cut efficiency), one need to create different selection chains (samples) for nominal value, positively and negatively shifted values. See caf_util/configs/ testJES.config
First you should declared your systematics sample in the Stat processor. For example for the systematics named "JES":

 stname.Systematics: JES

Than you define your 3 processing chain for nominal, positively and negatively shifted values:

 cafe.Run: Stat(stname)
 ...
 +cafe.Run: Fork(jes)
 jes.Run: Group(jespos) Group(jesneg) Group(jesmain)

Here "jesmain" chain will use the nominal value, "jespos" and "jesneg" will shift all jet energies before applying standard selection (see caf_util/configs/ testJES.config for details). Each processing chain must be tagged with appropriated tags. The appropriate tag for the systematics called "JES" will be "JES" for the nominal value, "JES_pos" for the positively shifted value and "JES_neg" for the negatively shifted one. Than you should tag your events accordingly:

 cafe.Tag: JES JES_pos JES_neg
 jes.Untag: JES JES_pos  JES_neg
 jespos.Tag: JES_pos
 jesneg.Tag: JES_neg
 jesmain.Tag: JES

Please, note that in the beginning of the event processing you must tag the event with all 3 tags, than after Fork processor (in fact using the Fork processor interfaces) you must remove all these tags and tag each branch with the corresponding tag. The systematics table will be printed in the end of the html or tex output file.

Configuration options:

.Output: output file name without extension [default: efficiencies]

.Sample: data or MC sample name [default: processor name]
SampleName.UseTag: tag1, tag2 [default: no tag, all events will be used]

.InitialTag: tag1,tag2 tag all events with following tags [default: events are not tagged]

.TexTitle: if this option is specified the output tex file will be created with name OutputFilename.tex and title in the file will be set to TexTitle [default: ""]

.Precision: the presecion parameter for html and text output streams (number of numbers after the floating point) [default: 3]

.IgnoreAutoRecords: ignore records made automatically (with "PROCESSOR" keyword) [default: 0 (false)]

.Update: n specify number of event to make and updated statistic files. 0 means no update, sttaistcs will be printed after end of the job [default: 0]

.Systematics: specify the list of the systematics names. The samples to study this systematics (posistive and negative) will be added to the stat object. User must additionally tag events for these samples with tags name, name_pos and name_neg, where name if the systematics name.

.PrintSystematics: print the output html selection table for the systematics samples [default:false]

Author:: Viatcheslav Shary (shary@fnal.gov)

Definition at line 240 of file Stat.hpp.

Public Member Functions

Stat (const char *name)

What everyone else should use.

Stat (const char *name, bool duplicate_ok)

Use if you are trying to keep more than one around at once.

~Stat ()

double eventWeight (const std::string &name="global", const std::string sample_name="not_specified") const

Return event weight by name. Return global event weight for the first sample by default. If weight with specified name was not found or sample with name sample_name does not exist return -1.0.

Collection< EventWeight > ListEventWeights (const std::string sample_name="not_specified") const

Return a Collection of event weights available. The global event weight comes first.

double nevents (const std::string &name="Initial", const std::string &sample_name="not_specified") const

Return number of events by selection name.

double efficiencyCorrected (const std::string &sample_name="not_specified") const

return efficiency corrected by the global event weight

double efficiency (const std::string &sample_name="not_specified") const

return global efficiency

double syst_pos (const std::string &name, const std::string &sample_name="not_specified") const

return positive systematics with name "name" for the sample sample_name if systematics is a weight, the statistical errors on the weight will be added to systematics

double syst_neg (const std::string &name, const std::string &sample_name="not_specified") const

return negative systematics with name "name" for the sample sample_name if systematics is a weight, the statistical errors on the weight will be added to systematics

double systerr_pos (const std::string &name, const std::string &sample_name="not_specified") const

return error for the positive systematics with name name for the sample sample_name

double systerr_neg (const std::string &name, const std::string &sample_name="not_specified") const

return error for the positive systematics with name name for the sample sample_name

std::vector< const cafe::StatSample * > get_samples () const

retun list of samples

std::vector< const cafe::Syst * > get_syst () const

retun list of systematics samples

void begin ()

initialization

void finish ()

Print efficiencies.

bool processEvent (cafe::Event &event)

increase number of events before any selection

void EventSelected (const std::string &selection_name)

Increase number of event selected. If such selection does not exist it will be added.

void applyWeight (const std::string &weight_name, double weight, double weight_pos=-1.0, double weight_neg=-1.0)

apply weight to efficiency calculation.

void eventEnd ()

make clean in the end of the event

StatSample & add_sample (const std::string &name)

Add sample and return reference to it.

void add_syst (const std::string &name, StatSample *sample=0)

Add samples for the systematics (with name "name") study. If sample == 0, systematics samples will be added to all existing samples .

void tag (const std::vector< std::string > &tags)

these tags will be added to the list to event tag in the begining ProcessEvent

ostream & print_html (ostream &os) const

output operator

ostream & print_tex (ostream &os, const std::string title="Efficiency") const

output operator

void chain (void)

void unchain (void)

void inheritWeights ()

Get a list of all applied weights from the parent and apply them down here.

ClassDef (Stat, 0)

Private Member Functions

double syst_pos (std::vector< Syst >::const_iterator jt) const

return positive systematics only from Syst samples

double syst_neg (std::vector< Syst >::const_iterator jt) const

return negative systematics only from Syst samples

double systerr_pos (std::vector< Syst >::const_iterator jt) const

return error for the positive systematics only from Syst samples

double systerr_neg (std::vector< Syst >::const_iterator jt) const

return error for the positive systematics only from Syst samples

Private Attributes

std::vector< StatSample > _samples

std::vector< Syst > _syst

cafe::Event * _event

std::vector< std::string > _tags

bool _ignoreauto

int _precision

unsigned long int _update

std::string _output_name

std::string _title

Stat * _parent_stat

Pointer to the paretn Stat object if we are chained.

Constructor & Destructor Documentation

cafe::Stat::Stat ( const char * name )

What everyone else should use.
If we are the first one, we establish ourselves as the primere dude. Otherwise, we don't do anything. Errors will occur further down if the user tries to do two Stat at once without some careful shuffling.
Definition at line 31 of file Stat.cpp.
References cafe::Processor::name(), and STAT.

cafe::Stat::Stat ( const char * name,

bool duplicate_ok

)

Use if you are trying to keep more than one around at once.

Definition at line 45 of file Stat.cpp.
References cafe::Processor::name(), and STAT.

cafe::Stat::~Stat ( )

Definition at line 57 of file Stat.cpp.

Member Function Documentation

StatSample& cafe::Stat::add_sample ( const std::string & name ) [inline]

Add sample and return reference to it.

Definition at line 335 of file Stat.hpp.
References _samples.

void cafe::Stat::add_syst ( const std::string & name,

StatSample * sample = 0

)

Add samples for the systematics (with name "name") study. If sample == 0, systematics samples will be added to all existing samples .

Definition at line 654 of file Stat.cpp.
References _samples, _syst, and cafe::StatSample::AddAndTags().
Referenced by begin().

void cafe::Stat::applyWeight ( const std::string & weight_name,

double weight,

double weight_pos = -1.0,

double weight_neg = -1.0

)

apply weight to efficiency calculation.

Definition at line 237 of file Stat.cpp.
References _event, _samples, and _syst.
Referenced by cafe::StatPointer::applyWeight(), inheritWeights(), and cafe::EventMultiSplitter::processPermutation().

void cafe::Stat::begin ( ) [virtual]

initialization
add systematics
Reimplemented from cafe::Processor.
Definition at line 109 of file Stat.cpp.
References _ignoreauto, _output_name, _precision, _samples, _title, _update, add_syst(), cafe::Config::get(), cafe::Config::getVString(), cafe::Processor::name(), and tag().
Referenced by cafe::EventMultiSplitter::EventMultiSplitter().

void cafe::Stat::chain ( void )

We can't chain if we are already in the chain!
Definition at line 59 of file Stat.cpp.
References _parent_stat, and STAT.
Referenced by cafe::EventMultiSplitter::processEvent().

cafe::Stat::ClassDef ( Stat ,

0

)

double cafe::Stat::efficiency ( const std::string & sample_name = "not_specified" ) const

return global efficiency

Definition at line 603 of file Stat.cpp.
References _samples.

double cafe::Stat::efficiencyCorrected ( const std::string & sample_name = "not_specified" ) const

return efficiency corrected by the global event weight

Definition at line 593 of file Stat.cpp.
References _samples.

void cafe::Stat::eventEnd ( )

make clean in the end of the event

Definition at line 171 of file Stat.cpp.
References _event, _samples, and _syst.
Referenced by cafe::EventBase::clear(), and cafe::EventMultiSplitter::processPermutation().

void cafe::Stat::EventSelected ( const std::string & selection_name )

Increase number of event selected. If such selection does not exist it will be added.

Definition at line 219 of file Stat.cpp.
References _event, _ignoreauto, _samples, and _syst.
Referenced by cafe::StatPointer::EventSelected(), cafe::Processor::incEventCount(), inheritWeights(), and cafe::Trigger::processEvent().

double cafe::Stat::eventWeight ( const std::string & name = "global",

const std::string sample_name = "not_specified"

) const

Return event weight by name. Return global event weight for the first sample by default. If weight with specified name was not found or sample with name sample_name does not exist return -1.0.

Definition at line 613 of file Stat.cpp.
References _samples.

void cafe::Stat::finish ( ) [virtual]

Print efficiencies.

Reimplemented from cafe::Processor.
Definition at line 155 of file Stat.cpp.
References _output_name, _precision, _title, print_html(), and print_tex().
Referenced by cafe::EventMultiSplitter::finish(), and processEvent().

vector< const StatSample * > cafe::Stat::get_samples ( ) const

retun list of samples

Definition at line 771 of file Stat.cpp.
References _samples.
Referenced by inheritWeights().

vector< const Syst * > cafe::Stat::get_syst ( ) const

retun list of systematics samples

Definition at line 778 of file Stat.cpp.
References _syst.

void cafe::Stat::inheritWeights ( void )

Get a list of all applied weights from the parent and apply them down here.
Use only the first stat sample to do the weight mapping.
Definition at line 82 of file Stat.cpp.
References _parent_stat, applyWeight(), EventSelected(), cafe::StatSample::eventSelection(), get_samples(), cafe::StatSelection::isWeight(), cafe::StatSelection::name(), cafe::StatSample::size(), STAT, cafe::StatWeight::weight(), cafe::StatWeight::weight_neg(), and cafe::StatWeight::weight_pos().
Referenced by cafe::EventMultiSplitter::processPermutation().

Collection< EventWeight > cafe::Stat::ListEventWeights ( const std::string sample_name = "not_specified" ) const

Return a Collection of event weights available. The global event weight comes first.

Definition at line 625 of file Stat.cpp.
References _samples.

double cafe::Stat::nevents ( const std::string & name = "Initial",

const std::string & sample_name = "not_specified"

) const

Return number of events by selection name.

Definition at line 638 of file Stat.cpp.
References _samples.

ostream & cafe::Stat::print_html ( ostream & os ) const

output operator

Definition at line 255 of file Stat.cpp.
References _samples, _syst, cafe::Config::get(), cafe::StatSelection::isWeight(), cafe::Processor::name(), cafe::StatSelection::name(), syst_neg(), syst_pos(), systerr_neg(), systerr_pos(), cafe::StatWeight::weight_average(), cafe::StatWeight::weight_average_neg(), and cafe::StatWeight::weight_average_pos().
Referenced by finish().

ostream & cafe::Stat::print_tex ( ostream & os,

const std::string title = "Efficiency"

) const

output operator

Definition at line 555 of file Stat.cpp.
References _samples, _syst, syst_neg(), syst_pos(), systerr_neg(), and systerr_pos().
Referenced by finish().

bool cafe::Stat::processEvent ( cafe::Event & event ) [virtual]

increase number of events before any selection

Reimplemented from cafe::Processor.
Definition at line 184 of file Stat.cpp.
References _event, _samples, _syst, _tags, _update, cafe::Processor::err(), cafe::Processor::eventCount(), finish(), cafe::EventBase::get(), cafe::Processor::name(), cafe::EventBase::put(), and cafe::EventBase::tag().
Referenced by cafe::EventMultiSplitter::processPermutation().

double cafe::Stat::syst_neg ( const std::string & name,

const std::string & sample_name = "not_specified"

) const

return negative systematics with name "name" for the sample sample_name if systematics is a weight, the statistical errors on the weight will be added to systematics

Definition at line 733 of file Stat.cpp.
References _samples, _syst, cafe::StatWeight::err(), cafe::Processor::err(), cafe::StatSelection::isWeight(), syst_neg(), cafe::StatWeight::weight_average(), and cafe::StatWeight::weight_average_neg().

double cafe::Stat::syst_neg ( std::vector< Syst >::const_iterator jt ) const [private]

return negative systematics only from Syst samples

Definition at line 720 of file Stat.cpp.
Referenced by print_html(), print_tex(), and syst_neg().

double cafe::Stat::syst_pos ( const std::string & name,

const std::string & sample_name = "not_specified"

) const

return positive systematics with name "name" for the sample sample_name if systematics is a weight, the statistical errors on the weight will be added to systematics

Definition at line 682 of file Stat.cpp.
References _samples, _syst, cafe::StatWeight::err(), cafe::Processor::err(), cafe::StatSelection::isWeight(), syst_pos(), cafe::StatWeight::weight_average(), and cafe::StatWeight::weight_average_pos().

double cafe::Stat::syst_pos ( std::vector< Syst >::const_iterator jt ) const [private]

return positive systematics only from Syst samples

Definition at line 669 of file Stat.cpp.
Referenced by print_html(), print_tex(), and syst_pos().

double cafe::Stat::systerr_neg ( const std::string & name,

const std::string & sample_name = "not_specified"

) const

return error for the positive systematics with name name for the sample sample_name

Definition at line 762 of file Stat.cpp.
References _syst, and systerr_neg().

double cafe::Stat::systerr_neg ( std::vector< Syst >::const_iterator jt ) const [private]

return error for the positive systematics only from Syst samples

Definition at line 725 of file Stat.cpp.
Referenced by print_html(), print_tex(), and systerr_neg().

double cafe::Stat::systerr_pos ( const std::string & name,

const std::string & sample_name = "not_specified"

) const

return error for the positive systematics with name name for the sample sample_name

Definition at line 710 of file Stat.cpp.
References _syst, and systerr_pos().

double cafe::Stat::systerr_pos ( std::vector< Syst >::const_iterator jt ) const [private]

return error for the positive systematics only from Syst samples

Definition at line 674 of file Stat.cpp.
Referenced by print_html(), print_tex(), and systerr_pos().

void cafe::Stat::tag ( const std::vector< std::string > & tags )

these tags will be added to the list to event tag in the begining ProcessEvent

Definition at line 648 of file Stat.cpp.
References _tags.
Referenced by begin().

void cafe::Stat::unchain ( void )

Can't unchain if we aren't in a chain!
Definition at line 69 of file Stat.cpp.
References _parent_stat, and STAT.
Referenced by cafe::EventMultiSplitter::processEvent().

Member Data Documentation

cafe::Event* cafe::Stat::_event [private]

Definition at line 244 of file Stat.hpp.
Referenced by applyWeight(), eventEnd(), EventSelected(), and processEvent().

bool cafe::Stat::_ignoreauto [private]

Definition at line 246 of file Stat.hpp.
Referenced by begin(), and EventSelected().

std::string cafe::Stat::_output_name [private]

Definition at line 249 of file Stat.hpp.
Referenced by begin(), and finish().

Stat* cafe::Stat::_parent_stat [private]

Pointer to the paretn Stat object if we are chained.

Definition at line 265 of file Stat.hpp.
Referenced by chain(), inheritWeights(), and unchain().

int cafe::Stat::_precision [private]

Definition at line 247 of file Stat.hpp.
Referenced by begin(), and finish().

std::vector<StatSample> cafe::Stat::_samples [private]

Definition at line 242 of file Stat.hpp.
Referenced by add_sample(), add_syst(), applyWeight(), begin(), efficiency(), efficiencyCorrected(), eventEnd(), EventSelected(), eventWeight(), get_samples(), ListEventWeights(), nevents(), print_html(), print_tex(), processEvent(), syst_neg(), and syst_pos().

std::vector<Syst> cafe::Stat::_syst [private]

Definition at line 243 of file Stat.hpp.
Referenced by add_syst(), applyWeight(), eventEnd(), EventSelected(), get_syst(), print_html(), print_tex(), processEvent(), syst_neg(), syst_pos(), systerr_neg(), and systerr_pos().

std::vector<std::string> cafe::Stat::_tags [private]

Definition at line 245 of file Stat.hpp.
Referenced by processEvent(), and tag().

std::string cafe::Stat::_title [private]

Definition at line 250 of file Stat.hpp.
Referenced by begin(), and finish().

unsigned long int cafe::Stat::_update [private]

Definition at line 248 of file Stat.hpp.
Referenced by begin(), and processEvent().

The documentation for this class was generated from the following files:

Generated on Thu Apr 3 04:14:28 2008 for CAF by

1.3.4


Public Member Functions
	Stat (const char *name)
	What everyone else should use.
	Stat (const char *name, bool duplicate_ok)
	Use if you are trying to keep more than one around at once.
	~Stat ()
double	eventWeight (const std::string &name="global", const std::string sample_name="not_specified") const
	Return event weight by name. Return global event weight for the first sample by default. If weight with specified name was not found or sample with name sample_name does not exist return -1.0.
Collection< EventWeight >	ListEventWeights (const std::string sample_name="not_specified") const
	Return a Collection of event weights available. The global event weight comes first.
double	nevents (const std::string &name="Initial", const std::string &sample_name="not_specified") const
	Return number of events by selection name.
double	efficiencyCorrected (const std::string &sample_name="not_specified") const
	return efficiency corrected by the global event weight
double	efficiency (const std::string &sample_name="not_specified") const
	return global efficiency
double	syst_pos (const std::string &name, const std::string &sample_name="not_specified") const
	return positive systematics with name "name" for the sample sample_name if systematics is a weight, the statistical errors on the weight will be added to systematics
double	syst_neg (const std::string &name, const std::string &sample_name="not_specified") const
	return negative systematics with name "name" for the sample sample_name if systematics is a weight, the statistical errors on the weight will be added to systematics
double	systerr_pos (const std::string &name, const std::string &sample_name="not_specified") const
	return error for the positive systematics with name name for the sample sample_name
double	systerr_neg (const std::string &name, const std::string &sample_name="not_specified") const
	return error for the positive systematics with name name for the sample sample_name
std::vector< const cafe::StatSample * >	get_samples () const
	retun list of samples
std::vector< const cafe::Syst * >	get_syst () const
	retun list of systematics samples
void	begin ()
	initialization
void	finish ()
	Print efficiencies.
bool	processEvent (cafe::Event &event)
	increase number of events before any selection
void	EventSelected (const std::string &selection_name)
	Increase number of event selected. If such selection does not exist it will be added.
void	applyWeight (const std::string &weight_name, double weight, double weight_pos=-1.0, double weight_neg=-1.0)
	apply weight to efficiency calculation.
void	eventEnd ()
	make clean in the end of the event
StatSample &	add_sample (const std::string &name)
	Add sample and return reference to it.
void	add_syst (const std::string &name, StatSample *sample=0)
	Add samples for the systematics (with name "name") study. If sample == 0, systematics samples will be added to all existing samples .
void	tag (const std::vector< std::string > &tags)
	these tags will be added to the list to event tag in the begining ProcessEvent
ostream &	print_html (ostream &os) const
	output operator
ostream &	print_tex (ostream &os, const std::string title="Efficiency") const
	output operator
void	chain (void)
void	unchain (void)
void	inheritWeights ()
	Get a list of all applied weights from the parent and apply them down here.
	ClassDef (Stat, 0)
Private Member Functions
double	syst_pos (std::vector< Syst >::const_iterator jt) const
	return positive systematics only from Syst samples
double	syst_neg (std::vector< Syst >::const_iterator jt) const
	return negative systematics only from Syst samples
double	systerr_pos (std::vector< Syst >::const_iterator jt) const
	return error for the positive systematics only from Syst samples
double	systerr_neg (std::vector< Syst >::const_iterator jt) const
	return error for the positive systematics only from Syst samples
Private Attributes
std::vector< StatSample >	_samples
std::vector< Syst >	_syst
cafe::Event *	_event
std::vector< std::string >	_tags
bool	_ignoreauto
int	_precision
unsigned long int	_update
std::string	_output_name
std::string	_title
Stat *	_parent_stat
	Pointer to the paretn Stat object if we are chained.

cafe::Stat Class Reference [CAF Environment (Cafe)]

Detailed Description

Public Member Functions

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation

cafe::Stat Class Reference
[CAF Environment (Cafe)]