Global list of available variables. More...

#include <Manager.h>

Collaboration diagram for Manager:

[legend]

Classes
struct	MetaVar
	A variable taking string arguments returning a variable. More...

struct	ParameterVar
	A variable taking additional floating-point arguments to influence the behaviour. More...

struct	Var
	A variable returning a floating-point value for a given Particle. More...

struct	VarBase
	Base class for information common to all types of variables. More...

Public Types
enum	VariableDataType { c_double = 0 , c_int = 1 , c_bool = 2 }
	data type of variables

typedef std::variant< double, int, bool >	VarVariant
	NOTE: the python interface is documented manually in analysis/doc/Variables.rst (because we use ROOT to expose this in python rather than boost::python). More...

typedef std::function< VarVariant(const Particle *)>	FunctionPtr
	functions stored take a const Particle* and return VarVariant.

typedef std::function< VarVariant(const Particle *, const std::vector< double > &)>	ParameterFunctionPtr
	parameter functions stored take a const Particle*, const std::vector<double>& and return VarVariant.

typedef std::function< FunctionPtr(const std::vector< std::string > &)>	MetaFunctionPtr
	meta functions stored take a const std::vector<std::string>& and return a FunctionPtr.

typedef Particle	Object
	Typedef for the cut, that we use Particles as our base objects.

Public Member Functions
const Var *	getVariable (std::string name)
	Get the variable belonging to the given key. More...

const Var *	getVariable (const std::string &functionName, const std::vector< std::string > &functionArguments)
	Get Meta and Parameter Variables for a function call which is already parsed into name and arguments. More...

std::vector< const Belle2::Variable::Manager::Var * >	getVariables (const std::vector< std::string > &variables)
	Get variables belonging to the given keys.

bool	addAlias (const std::string &alias, const std::string &variable)
	Add alias Return true if the alias was successfully added.

void	printAliases ()
	Print existing aliases.

void	clearAliases ()
	Clear existing aliases.

std::string	resolveAlias (const std::string &alias)
	Resolve alias Return original variable name.

bool	addCollection (const std::string &collection, const std::vector< std::string > &variables)
	Add collection Return true if the collection was successfully added.

std::vector< std::string >	getCollection (const std::string &collection)
	Get Collection Returns variable names corresponding to the given collection.

std::vector< std::string >	resolveCollections (const std::vector< std::string > &variables)
	Resolve Collection Returns variable names corresponding to the given collection or if it is not a collection just the variable itself.

std::vector< const Belle2::Variable::Manager::VarBase * >	getVariables () const
	Return list of all variables (in order registered).

void	setVariableGroup (const std::string &groupName)
	All variables registered after VARIABLE_GROUP(groupName) will be added to this group.

void	registerVariable (const std::string &name, const Manager::FunctionPtr &f, const std::string &description, const Manager::VariableDataType &v, const std::string &unit="")
	Register a variable.

void	registerVariable (const std::string &name, const Manager::ParameterFunctionPtr &f, const std::string &description, const Manager::VariableDataType &v, const std::string &unit="")
	Register a variable that takes floating-point arguments (see Variable::Manager::ParameterFunctionPtr).

void	registerVariable (const std::string &name, const Manager::MetaFunctionPtr &f, const std::string &description, const Manager::VariableDataType &v)
	Register a meta-variable that takes string arguments and returns a variable(see Variable::Manager::MetaFunctionPtr).

void	deprecateVariable (const std::string &name, bool make_fatal, const std::string &version, const std::string &description)
	Make a variable deprecated.

void	checkDeprecatedVariable (const std::string &name)
	Check if a variable is deprecated. More...

double	evaluate (const std::string &varName, const Particle *p)
	evaluate variable 'varName' on given Particle. More...

std::vector< std::string >	getNames () const
	Return list of all variable names (in order registered).

std::vector< std::string >	getAliasNames () const
	Return a list of all variable alias names (in reverse order added).

void	assertValidName (const std::string &name)
	Abort with B2FATAL if name is not a valid name for a variable.

Static Public Member Functions
static Manager &	Instance ()
	get singleton instance.

Private Member Functions
	Manager (const Manager &)
	Copy constructor disabled (not defined).

bool	createVariable (const std::string &name)
	Creates and registers a concrete variable (Var) from a MetaVar, ParameterVar or numeric constant.

bool	createVariable (const std::string &fullname, const std::string &functionName, const std::vector< std::string > &functionArguments)
	Creates and registers a MetaVar, ParameterVar Called by the corresponding getVariable(const std::string&, const std::vector<std::string>&) to register non-existing variables The fullname of the function call is also passed for alias resolving.

Private Attributes
std::string	m_currentGroup
	Group last set via VARIABLE_GROUP().

std::vector< const VarBase * >	m_variablesInRegistrationOrder
	List of variables in registration order.

std::map< std::string, std::string >	m_alias
	List of registered aliases.

std::map< std::string, std::vector< std::string > >	m_collection
	List of registered collections.

std::map< std::string, std::shared_ptr< Var > >	m_variables
	List of registered variables.

std::map< std::string, std::shared_ptr< ParameterVar > >	m_parameter_variables
	List of registered parameter variables.

std::map< std::string, std::shared_ptr< MetaVar > >	m_meta_variables
	List of registered meta variables.

std::map< std::string, std::pair< bool, std::string > >	m_deprecated
	List of deprecated variables.

Detailed Description

Global list of available variables.

Each variable has an associated unique string key through which it can be accessed. The Manager can be used to get an instance of the Variable class for this key. All ordinary variables take a const Particle* and return a double.

List of available variables

To simply get a list of all variables registered in the main analysis library, run basf2 analysis/scripts/variables.py .

Parameter variables

Parameter variables take a const Particle* and a const std::vector<double>&. They return a double. If a Parameter Variable is accessed via the VariableManager::getVariable a ordinary variable is dynamically registered which calls the Parameter variable with the correct parameters.

Meta variables

Meta variables take a const std::vector<std::string>& and return a pointer to a ordinary variable function. If a Meta Variable is accessed via the VariableManager::getVariable a ordinary variable is dynamically registered which calls the function returned by the meta variable.

There are a number of meta-variables that can be combined with existing variables to do more powerful calculations:

abs(varName): Return absolute value of variable varName.
daughter(N, varName): Calculate variable varName for Nth daughter
daughterProductOf(varName): Calculate variable varName for each daughter, and return product of values
daughterSumOf(varName): Calculate variable varName for each daughter, and return sum of values
extraInfo(extraInfoName): Return value of extra info 'extraInfoName' from Particle (see Particle::getExtraInfo()).

So, if you wanted to get the momentum of the first daughter, you can use "daughter(1, p)" anywhere where variable names are accepted. Nesting is also possible, e.g. "daughter(1, abs(extraInfo(SignalProbability)))" can be used.

Adding variables

Variables will automatically register themselves when the library that contains them is loaded. They only need to be put in a .cc file, with a call to REGISTER_VARIABLE() in the global scope to set a name and description. Newly registered variables will be added to the group defined by the last call to VARIABLE_GROUP(), please search the list of variables (see 'List of available variables' section) for a matching group before adding your own.

Example:

double particleFlavorType(const Particle* part)
{
  return part->getFlavorType();
}
REGISTER_VARIABLE("flavor", particleFlavorType, "flavor type of decay (0=unflavored, 1=flavored)");

This registers the variable "flavor" with the given function and description. Note that only alphanumeric characters (0-9, a-Z) plus '_' are permitted in variable names.

Variables can then be accessed using getVariable(name) and getVariables().

Python interface

This class is exported to Python, and can be used to use variables in Python basf2 modules:

from variables import variables
 
from ROOT.Math import PxPyPzEVector
someParticle = Belle2.Particle(PxPyPzEVector(1.0, 0, 0, 1.0), 321)
print(variables.evaluate('E', someParticle))

Definition at line 101 of file Manager.h.

Member Typedef Documentation

◆ VarVariant

typedef std::variant<double, int, bool> VarVariant

NOTE: the python interface is documented manually in analysis/doc/Variables.rst (because we use ROOT to expose this in python rather than boost::python).

Please also keep that up-to-date with any modifications. Typedef for variable return type, can either be double, int or bool in std::variant

Definition at line 111 of file Manager.h.

Member Function Documentation

◆ checkDeprecatedVariable()

void checkDeprecatedVariable ( const std::string & name )

Check if a variable is deprecated.

If it is marked as deprecated a warning is issued or a B2FATAL aborts the event loop. Which action is taken depends on the depreciation setting.

Definition at line 443 of file Manager.cc.

 {
   auto varIter = m_deprecated.find(name);
  
   if (varIter == m_deprecated.end())
     return;
   else {
     bool make_fatal = varIter->second.first;
     std::string message = varIter->second.second;
     if (make_fatal)
       B2FATAL("Variable " << name << " is deprecated. " << message);
     else
       B2WARNING("Variable " << name << " is deprecated. " << message);
   }
 }

◆ evaluate()

double evaluate	(	const std::string &	varName,
		const Particle *	p
	)

evaluate variable 'varName' on given Particle.

Mainly provided for the Python interface. For performance critical code, it is recommended to use getVariable() once and keep the Var* pointer around.

Throws exception if variable isn't found. Assumes 'p' is != NULL.

Definition at line 476 of file Manager.cc.

◆ getVariable() [1/2]

const Variable::Manager::Var * getVariable	(	const std::string &	functionName,
		const std::vector< std::string > &	functionArguments
	)

Get Meta and Parameter Variables for a function call which is already parsed into name and arguments.

Used by FunctionNode because there we already have the MetaVariable in parsed form

Returns NULL if name not found

Definition at line 31 of file Manager.cc.

◆ getVariable() [2/2]

const Variable::Manager::Var * getVariable ( std::string name )

Get the variable belonging to the given key.

Returns NULL if name not found.

Definition at line 57 of file Manager.cc.

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

analysis/VariableManager/include/Manager.h
analysis/VariableManager/src/Manager.cc

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes