The key class for coordination of Analysis objects and the event loop. More...

#include <AnalysisHandler.hh>

Public Types
using	Annotations = std::map< std::string, std::string >

Public Member Functions
	AnalysisHandler (const string &runname="")
	Preferred constructor, with optional run name.

	AnalysisHandler (const AnalysisHandler &)=delete
	The copy constructor is deleted, so it can never be called.

AnalysisHandler &	operator= (const AnalysisHandler &)=delete
	The assignment operator is deleted, so it can never be called.

	~AnalysisHandler ()
	The destructor is not virtual, as this class should not be inherited from.

Run properties
string	runName () const
	Get the name of this run.

size_t	numEvents () const

double	effNumEvents () const

double	sumW () const
	Access the sum of the event weights seen.

double	sumW2 () const
	Access to the sum of squared-weights.

Event weights
const vector< string > &	weightNames () const
	Names of event weight categories.

size_t	numWeights () const
	Are any of the weights non-numeric?

bool	haveNamedWeights () const
	Are any of the weights non-numeric?

void	setWeightNames (const GenEvent &ge)
	Set the weight names from a GenEvent.

void	setWeightNames (const vector< string > &weightNames)
	Set the weight names from a vector<string>

size_t	defaultWeightIndex () const
	Get the index of the nominal weight-stream.

vector< double >	weightSumWs () const
	Access the array of sum of the event weights seen.

void	setWeightCap (const double maxWeight)
	Set the weight cap.

void	setNominalWeightName (const std::string &name)
	Set the name of the nominal weight stream.

void	skipMultiWeights (bool skip=false)
	Ignore all weight streams other than the nominal.

void	matchWeightNames (const std::string &patterns)
	Specify weight-name patterns to accept.

void	unmatchWeightNames (const std::string &patterns)
	Specify weight-name patterns to reject.

void	setNLOSmearing (double frac)
	Set the relative width of the NLO smearing window.

Cross-sections
Estimate0DPtr	crossSection () const
	Get the cross-section known to the handler.

void	setCrossSection (const vector< pair< double, double > > &xsecs, bool isUserSupplied=false)
	Set all cross-sections for the process being generated specifically (preferred)

void	setCrossSection (const pair< double, double > &xsec, bool isUserSupplied=false)
	Set all cross-sections for the process being generated, based on nominal weight.

void	setCrossSection (double xsec, double xsecerr, bool isUserSupplied=false)
	Set the cross-section for the process being generated (alternative signature)

void	updateCrossSection ()

void	notifyEndOfFile ()
	Toggle to signal a change in HepMC input file.

double	nominalCrossSection () const
	Get the nominal cross-section.

double	nominalCrossSectionError () const
	Get the nominal cross-section.

Beams
AnalysisHandler &	setRunBeams (const ParticlePair &beams)
	Set the beam particles for this run.

const ParticlePair &	runBeams () const
	Get the beam particles for this run, usually determined from the first event.

PdgIdPair	runBeamIDs () const
	Get beam IDs for this run, usually determined from the first event.

pair< double, double >	runBeamEnergies () const
	Get beam IDs for this run, usually determined from the first event.

double	runSqrtS () const
	Get energy for this run, usually determined from the first event.

void	setCheckBeams (bool check=true)
	Option to disable analysis-compatibility checks.

Run-based annotations
Option to disable run-consistency checks
std::vector< std::string >	annotations () const

bool	hasAnnotation (const std::string &name) const
	Check if an annotation is defined.

const std::string &	annotation (const std::string &name) const
	Get an annotation by name (as a string)

const std::string &	annotation (const std::string &name, const std::string &defaultreturn) const
	Get an annotation by name (as a string) with a default in case the annotation is not found.

template<typename T >
const T	annotation (const std::string &name) const
	Get an annotation by name (copied to another type)

template<typename T >
const T	annotation (const std::string &name, T &&defaultreturn) const
	Get an annotation by name (copied to another type) with a default in case the annotation is not found.

template<typename T >
void	setAnnotation (const std::string &name, T &&value)
	Add or set an annotation by name (templated for remaining types)

void	setAnnotations (const Annotations &anns)
	Set all annotations at once.

void	rmAnnotation (const std::string &name)
	Delete an annotation by name.

void	clearAnnotations ()
	Delete an annotation by name.

AO type handling
template<typename T >
void	registerType ()
	Register an AO type handle into type map and YODA reader.

bool	copyAO (YODA::AnalysisObjectPtr src, YODA::AnalysisObjectPtr dst, const double scale=1.0)

bool	addAO (YODA::AnalysisObjectPtr src, YODA::AnalysisObjectPtr &dst, const double scale)

Analysis handling
std::vector< std::string >	analysisNames () const
	Get a list of the currently registered analyses' names.

std::vector< std::string >	stdAnalysisNames () const
	Get a list of the official analysis names for this release.

const std::map< std::string, AnaHandle > &	analysesMap () const
	Get the collection of currently registered analyses.

std::vector< AnaHandle >	analyses () const
	Get the collection of currently registered analyses.

AnaHandle	analysis (const std::string &analysisname)
	Get a registered analysis by name.

AnalysisHandler &	addAnalysis (Analysis *analysis)
	Add an analysis to the run list by object.

AnalysisHandler &	addAnalysis (const std::string &analysisname)
	Add an analysis to the run list using its name.

AnalysisHandler &	addAnalysis (const std::string &analysisname, std::map< string, string > pars)
	Add an analysis with a map of analysis options.

AnalysisHandler &	addAnalyses (const std::vector< std::string > &analysisnames)
	Add analyses to the run list using their names.

AnalysisHandler &	removeAnalysis (const std::string &analysisname)
	Remove an analysis from the run list using its name.

AnalysisHandler &	removeAnalyses (const std::vector< std::string > &analysisnames)
	Remove analyses from the run list using their names.

Main init/execute/finalise
void	init (const GenEvent &event)
	Initialize a run, with the run beams taken from the example event.

void	analyze (GenEvent &event)
	Analyze the given event by reference.

void	analyze (GenEvent *event)
	Analyze the given event by pointer.

void	finalize ()

Histogram / data object access
void	collapseEventGroup ()

void	readData (std::istream &istr, const string &fmt, bool preload=true)
	Read analysis plots into the histo collection from the given stream.

void	readData (const std::string &filename, bool preload=true)
	Read analysis plots into the histo collection (via addData) from the named file.

vector< YODA::AnalysisObjectPtr >	getYodaAOs (const bool includeraw=false, const bool mkinert=true) const

vector< YODA::AnalysisObjectPtr >	getRawAOs () const
	Get all raw YODA analysis objects (across all weights)

vector< std::string >	getRawAOPaths () const
	Get all raw YODA analysis object paths (across all weights)

const YODA::AnalysisObjectPtr	getPreload (const string &path) const

void	writeData (std::ostream &ostr, const string &fmt) const
	Write all analyses' plots (via getData) to the given stream.

void	writeData (const string &filename) const
	Write all analyses' plots (via getData) to the named file.

void	setFinalizePeriod (const string &dumpfile, int period)
	Configure the AnalysisObject dump rate and destination.

void	setNoFinalizePeriod ()
	Configure the AnalysisObject dump rate and destination.

void	setBootstrapFilename (const string &filename)
	Set filename of the bootstrap file.

vector< pair< string, size_t > >	fillLayout () const
	Return a vector of (AO path, AO numBins) pairs to decode the fills layout.

vector< bool >	fillOutcomes () const
	Return a vector of the binary fill outcome (was/wasn't filled) at each fill position.

vector< double >	fillFractions () const
	Return a vector of the fill fraction at each fill position.

void	mergeYODAs (const vector< string > &aofiles, const vector< string > &delopts=vector< string >(), const vector< string > &addopts=vector< string >(), const vector< string > &matches=vector< string >(), const vector< string > &unmatches=vector< string >(), const bool equiv=false, const bool reentrantOnly=true)
	Merge the vector of YODA files, using the cross-section and weight information provided in each.

void	merge (AnalysisHandler &other)
	A method to merge another AnalysisHandler into the current one.

void	loadAOs (const vector< string > &aoPaths, const vector< double > &aoData)
	A method to prepare a re-entrant run for a given set of AO paths and serialized AO data.

MPI (de-)serialisation
vector< double >	serializeContent (bool fixed_length=false)

void	deserializeContent (const vector< double > &data, size_t nprocs=0)

Processing stage
enum class	Stage { OTHER , INIT , FINALIZE }

Stage	stage () const
	Return the current processing stage.

Detailed Description

The key class for coordination of Analysis objects and the event loop.

A class which handles a number of analysis objects to be applied to generated events. An Analysis' AnalysisHandler is also responsible for handling the final writing-out of histograms.

Member Enumeration Documentation

◆ Stage

enum class Rivet::AnalysisHandler::Stage

strong

Indicate which Rivet stage we're in. At the moment, only INIT is used to enable booking.

Member Function Documentation

◆ addAnalyses()

AnalysisHandler & Rivet::AnalysisHandler::addAnalyses ( const std::vector< std::string > & analysisnames )

Add analyses to the run list using their names.

The actual Analysis' to be used will be obtained via AnalysisHandler::addAnalysis(string), which in turn uses AnalysisLoader::getAnalysis(string). If no matching analysis is found for a given name, no analysis is added, but also no error is thrown.

◆ addAnalysis()

AnalysisHandler & Rivet::AnalysisHandler::addAnalysis ( const std::string & analysisname )

Add an analysis to the run list using its name.

The actual Analysis to be used will be obtained via AnalysisLoader::getAnalysis(string). If no matching analysis is found, no analysis is added (i.e. the null pointer is checked and discarded.

◆ addAO()

bool Rivet::AnalysisHandler::addAO	(	YODA::AnalysisObjectPtr	src,
		YODA::AnalysisObjectPtr &	dst,
		const double	scale
	)

If dst is the same subclass as src, scale the contents of src with scale and add it to dst and return true. Otherwise return false.

◆ analyze() [1/2]

void Rivet::AnalysisHandler::analyze ( GenEvent & event )

Analyze the given event by reference.

This function will call the AnalysisBase::analyze() function of all included analysis objects.

Note: Despite the event being passed as const, its units etc. may be changed, hence non-const.

◆ analyze() [2/2]

void Rivet::AnalysisHandler::analyze ( GenEvent * event )

Analyze the given event by pointer.

This function will call the AnalysisBase::analyze() function of all included analysis objects, after checking the event pointer validity.

◆ annotation() [1/2]

template<typename T >

const T Rivet::AnalysisHandler::annotation ( const std::string & name ) const

inline

Get an annotation by name (copied to another type)

Note: Templated on return type

◆ annotation() [2/2]

template<typename T >

const T Rivet::AnalysisHandler::annotation	(	const std::string &	name,
		T &&	defaultreturn
	)		const

inline

Get an annotation by name (copied to another type) with a default in case the annotation is not found.

Note: Templated on return type

◆ collapseEventGroup()

void Rivet::AnalysisHandler::collapseEventGroup ( )

After all subevents in an event group have been processed, push all histo fills to the relevant histograms.

◆ copyAO()

bool Rivet::AnalysisHandler::copyAO	(	YODA::AnalysisObjectPtr	src,
		YODA::AnalysisObjectPtr	dst,
		const double	scale = `1.0`
	)

If dst is the same subclass as src, copy the contents of src into dst and return true. Otherwise return false.

◆ effNumEvents()

double Rivet::AnalysisHandler::effNumEvents ( ) const

inline

Get the effective number of events seen. Should only really be used by external steering code or analyses in the finalize phase.

N.B. This only reports the count for the last collapsed event group and hence ignores any additional sub-events seen so far.

References defaultWeightIndex().

◆ finalize()

void Rivet::AnalysisHandler::finalize ( )

Finalize a run. This function calls the AnalysisBase::finalize() functions of all included analysis objects.

◆ getPreload()

const YODA::AnalysisObjectPtr Rivet::AnalysisHandler::getPreload ( const string & path ) const

inline

Get a pointer to a preloaded yoda object with the given path, or null if path is not found.

◆ getYodaAOs()

vector< YODA::AnalysisObjectPtr > Rivet::AnalysisHandler::getYodaAOs	(	const bool	includeraw = `false`,
		const bool	mkinert = `true`
	)		const

Get all YODA analysis objects (across all weights, optionally including RAW)

Note: We'll live with the mixed-case "Yoda" here, since the consistent all-caps would be worse!

◆ loadAOs()

void Rivet::AnalysisHandler::loadAOs	(	const vector< string > &	aoPaths,
		const vector< double > &	aoData
	)

A method to prepare a re-entrant run for a given set of AO paths and serialized AO data.

The unscale parameter multiplies fillable objects with sumW/xsec to counteract the cross-section scaling in finalize() when merging different processes (non-equiv)

◆ mergeYODAs()

void Rivet::AnalysisHandler::mergeYODAs	(	const vector< string > &	aofiles,
		const vector< string > &	delopts = `vector< string >()`,
		const vector< string > &	addopts = `vector< string >()`,
		const vector< string > &	matches = `vector< string >()`,
		const vector< string > &	unmatches = `vector< string >()`,
		const bool	equiv = `false`,
		const bool	reentrantOnly = `true`
	)

Merge the vector of YODA files, using the cross-section and weight information provided in each.

Each file in aofiles is assumed to have been produced by Rivet. By default the files are assumed to contain different processes (or the same processs but mutually exclusive cuts), but if equiv if true, the files are assumed to contain output of completely equivalent (but statistically independent) Rivet runs. The corresponding analyses will be loaded and their analysis objects will be filled with the merged result. finalize() will be run on each relevant analysis. The resulting YODA file can then be written out by writeData().

If delopts is non-empty, it is assumed to contain names of different options to be merged into the same analysis objects.

◆ numEvents()

size_t Rivet::AnalysisHandler::numEvents ( ) const

inline

Get the number of events seen. Should only really be used by external steering code or analyses in the finalize phase.

N.B. This only reports the count for the last collapsed event group and hence ignores any additional sub-events seen so far.

References defaultWeightIndex().

◆ readData()

void Rivet::AnalysisHandler::readData	(	std::istream &	istr,
		const string &	fmt,
		bool	preload = `true`
	)

Read analysis plots into the histo collection from the given stream.

Use the fmt flag to specify the YODA output format (yoda, yoda.gz, yoda.h5, ...)

◆ setAnnotation()

template<typename T >

void Rivet::AnalysisHandler::setAnnotation	(	const std::string &	name,
		T &&	value
	)

inline

Add or set an annotation by name (templated for remaining types)

Note: Templated on arg type, but stored as a string.

◆ setFinalizePeriod()

void Rivet::AnalysisHandler::setFinalizePeriod	(	const string &	dumpfile,
		int	period
	)

inline

Configure the AnalysisObject dump rate and destination.

Tell Rivet to dump intermediate result to a file named dumpfile every period'th event. If period is not positive, no periodic finalization will be done.

Referenced by setNoFinalizePeriod().

◆ sumW()

double Rivet::AnalysisHandler::sumW ( ) const

inline

Access the sum of the event weights seen.

This is the weighted equivalent of the number of events. It should only be used by external steering code or analyses in the finalize phase.

References defaultWeightIndex().

◆ updateCrossSection()

void Rivet::AnalysisHandler::updateCrossSection ( )

Update the internal cross-section average when running over multiple files

Note: This method should only be called when switching HepMC file mid-run.

◆ writeData()

void Rivet::AnalysisHandler::writeData	(	std::ostream &	ostr,
		const string &	fmt
	)		const

Write all analyses' plots (via getData) to the given stream.

Use the fmt flag to specify the YODA output format (yoda, yoda.gz, yoda.h5, ...)

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

/Users/chrisg/software/rivet/include/Rivet/AnalysisHandler.hh

Public Types

Public Member Functions

Processing stage

Detailed Description

Member Enumeration Documentation

◆ Stage

Member Function Documentation

◆ addAnalyses()

◆ addAnalysis()

◆ addAO()

◆ analyze() [1/2]

◆ analyze() [2/2]

◆ annotation() [1/2]

◆ annotation() [2/2]

◆ collapseEventGroup()

◆ copyAO()

◆ effNumEvents()

◆ finalize()

◆ getPreload()

◆ getYodaAOs()

◆ loadAOs()

◆ mergeYODAs()

◆ numEvents()

◆ readData()

◆ setAnnotation()

◆ setFinalizePeriod()

◆ sumW()

◆ updateCrossSection()

◆ writeData()