Using Properties With AnaAlgorithms

Last update: 14 Nov 2022 [History] [Edit]

Properties are configurable parameters that can be set for your job at runtime. They are handled in the same way in EventLoop and in Athena. This consists of two steps:

  • Declare a Gaudi::Property as a member of your algorithm class
  • Set the value of the property in your submission script/macro or jobOptions, to set/override it.

Declaring/Using properties

We will declare a single std::string property for now. Add the following to your class header (MyxAODAnalysis.h):

#include <AsgTools/PropertyWrapper.h>
...
private:
  /// Sample name
  Gaudi::Property<std::string> m_sampleName {this, "SampleName", "", "My Sample Name"};

The template constructor for Gaudi::Property is:

Gaudi::Property<class T> m_property {this, "property name", defaultValue, "title"};

Pick a variable name and property name that are descriptive of the property you are using this for. The names we are using here are simply examples of good practice.

tip You will likely come across code that uses an older (no longer recommended) method of declaring and creating properties. This includes declaring a class variable in the header:

private:
  /// Sample name property
  std::string m_sampleName;

and then calling declareProperty(...) in the algorithm class constructor:

declareProperty( "SampleName", m_sampleName = "Unknown",
                 "Descriptive name for the processed sample" );

Now let’s add a print-out to initialize() so we can confirm that the property is correctly modified from its default value later on:

  ANA_MSG_INFO( "SampleName = " << m_sampleName );

warning There is a finite number of types supported as algorithm properties. In general try to use as simple properties as possible. The current list of supported types is:

  • int;
  • float;
  • double;
  • std::string;
  • std::vector of the previous types.
  • ToolHandle. This is declared in a different way than the others.
  • AnaToolHandle. This is declared in a different way than the others and its use is discouraged.

Setting algorithm properties

The main purpose of algorithm properties is to be able to customize them during the configuration step. Using the python configuration this is straightforward.

Go back to the ATestRun_eljob.py macro (or ATestRun_jobOptions.py in Athena) that you created earlier. In it you create an algorithm object called alg. You can set properties on that object with:

alg.SampleName = 'LQ'

tip You may also come across instances of properties being set directly when the algorithm is created in the EventLoop python macro:

from AnaAlgorithm.AnaAlgorithmConfig import AnaAlgorithmConfig
alg = AnaAlgorithmConfig( 'MyxAODAnalysis/AnalysisAlg',
                          SampleName = 'LQ' )

Pre-existing algorithm properties

The EL::AnaAlgorithm base class declares some properties of its own. The most important ones that you should be aware of are:

  • “OutputLevel”: The minimum level for the printed messages. This property allows you to either turn on DEBUG / VERBOSE messages for an algorithm, or to possibly turn off its INFO messages, if you don’t want to see those. You should set it either from simple integers (1: VERBOSE, 2: DEBUG, etc.), using the ROOT.MSG.VERBOSE, ROOT.MSG.DEBUG, etc. values (in EventLoop jobs), or using the VERBOSE, DEBUG, etc. variables (in Athena jobs). More details are available in ATLAS Messaging.
  • “RootStreamName”: The name of the stream to create ntuples/histograms in. In Athena this controls both the destination of histograms and trees, while in EventLoop it only controls the destination of the trees. By default it is set to “ANALYSIS”, meaning that you need to create output streams with that name in your jobs in most cases.

Commit your changes

When you are happy that your code is working as expected, commit and push your changes.