Belle II Software  development
Manager Class Reference

Global list of available variables. More...

#include <Manager.h>

Collaboration diagram for Manager:

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 VargetVariable (std::string name)
 Get the variable belonging to the given key. More...
 
const VargetVariable (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.
 
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 ManagerInstance ()
 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 import TLorentzVector
someParticle = Belle2.Particle(TLorentzVector(1.0, 0, 0, 0), 321)
print(variables.evaluate('E', someParticle))
Class to store reconstructed particles.
Definition: Particle.h:74
Abstract base class for different kinds of events.

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 405 of file Manager.cc.

406 {
407  auto varIter = m_deprecated.find(name);
408 
409  if (varIter == m_deprecated.end())
410  return;
411  else {
412  bool make_fatal = varIter->second.first;
413  std::string message = varIter->second.second;
414  if (make_fatal)
415  B2FATAL("Variable " << name << " is deprecated. " << message);
416  else
417  B2WARNING("Variable " << name << " is deprecated. " << message);
418  }
419 }
std::map< std::string, std::pair< bool, std::string > > m_deprecated
List of deprecated variables.
Definition: Manager.h:295

◆ 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 438 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: