Skip to content

Using Properties

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 (MyAnalysis/MyAnalysis/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" );

The new version is preferred for concision and clarity (e.g. you don't need to check separate files to see what the type of the property is and its default value).

Now let's add a print-out to initialize() in the source file of the class (MyAnalysis/Root/MyxAODAnalysis.cxx) so we can confirm that the property is correctly modified from its default value later on:

  ANA_MSG_INFO( "SampleName = " << m_sampleName );

Tip

A finite number of types are 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, which is declared in a different way than the others
  • AnaToolHandle, which is declared in a different way than the others and 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.DualUseConfig import createAlgorithm
alg = createAlgorithm( 'MyxAODAnalysis', 'AnalysisAlg',
                       SampleName = 'LQ' )

Commit your changes

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

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 from the algorithm. Note that this does not change the level globally for all algorithms (which you would not want). This is discussed in more detail below.
  • "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.

Changing the message output level

You can change the message output level of an algorithm or a tool using the "OutputLevel" property. Using the property, you can set the minimum priority level of messages to be printed to the screen.

By default, any messages with a priority of INFO or higher are printed. By setting the output level to DEBUG, all messages of the DEBUG level are printed in addition to those of a higher priority. Similarly, setting the level to VERBOSE adds VERBOSE and DEBUG to the messages that get printed. If you want, you can even set the level to WARNING to turn off INFO messages if you don't want to see them.

Each output level has an associated integer value starting with 1 for VERBOSE and 2 for DEBUG up to 6 for FATAL. However, it is usually easier to understand code if you use the appropriate keyword.

To set the level of any algorithm or tool in AnalysisBase, you need to use values from the ROOT namespace, such as ROOT.MSG.VERBOSE or ROOT.MSG.INFO. To do this, make sure you have the line

import ROOT

and then add a line such as

alg.OutputLevel = ROOT.MSG.DEBUG

after you have created the algorithm alg.

If you are using AthAnalysis, you can use the values VERBOSE, DEBUG, etc., directly.

You can find more details about ATLAS messaging in the previous ATLAS Messaging section.

⭐️ Bonus Exercise

Make an INFO, DEBUG, and VERBOSE message in your execute function. Change the output level in your configuration to print each of these levels.