This documentation shows how to use the Iguana algorithms. For more documentation, see the Documentation Front Page

Quick Links
List of Algorithms	Examples of Code
List of Action Functions	Configuring Algorithms

Example Analysis Code Using Iguana

To see Iguana algorithms used in the context of analysis code, with various languages and use cases, see:

Examples
C++ Examples	For users of `ROOT`, `clas12root`, etc.
C++ Examples	Includes guidance on how to build Iguana with your C++ code
Python examples	For users of Python tools, such as `PyROOT`
Fortran examples	See also the Fortran usage guide

In summary, the general way to use an Iguana algorithm is as follows; see examples and documentation below for more details.

Decide which algorithms you want to use
- Tip: you may use iguana::AlgorithmSequence to help run a sequence of algorithms
Check each algorithm configuration, and adjust it if you prefer
Start each algorithm, which "locks in" its configuration:
- call Start(banklist) if you use the HIPO API and Common Functions
- call Start() otherwise, i.e., if you use Action Functions
In the event loop, run the algorithm:
- call Run(...) if you use Common Functions
- call the Action Function(s) otherwise
Proceed with your analysis
- if you called Run(...), the banks will be filtered, transformed, and/or created
- if you called action functions, you will need to handle their output yourself
- in either case, see guidance on how to run algorithms for more details
After your event loop, stop each algorithm by calling Stop()

Please let the maintainers know if your use case is not covered in any examples or if you need any help.

Algorithms

An Iguana algorithm is a function that maps input HIPO bank data to output data. There are a few different types of algorithms, based on how they act on HIPO data:

Type	Description	Example
Filter	Filters rows of a bank based on a Boolean condition	`iguana::clas12::FiducialFilter`: filter particles with fiducial cuts
Transformer	Transform (mutate) elements of a bank	`iguana::clas12::MomentumCorrection`: correct particle momenta
Creator	Create a new bank	`iguana::physics::InclusiveKinematics`: calculate inclusive kinematics $x$, $Q^2$, etc.

The available algorithms are:

How to Run Algorithms

Algorithms may be run using either:

Common Functions: for users of the the HIPO API, which is likely the case if you are using C++, e.g., via clas12root
Action Functions: for all other users

The next sections describe each of these.

Important: It is highly recommended to read an algorithm's documentation carefully before using it.

Common Functions

All algorithms have the following Common Functions, which may be used in analysis code that uses the HIPO API. These functions act on hipo::bank objects, and are designed to be called at certain points in an analysis of HIPO data:

Common Functions
`iguana::Algorithm::Start`	To be called before event processing
`iguana::Algorithm::Run`	To be called for every event
`iguana::Algorithm::Stop`	To be called after event processing

The algorithms are implemented in C++ classes which inherit from the base class iguana::Algorithm; these three class methods are overridden in each algorithm.

The iguana::Algorithm::Run function should be called on every event; the general consequence, that is, how the user should handle the algorithm's results, depends on the algorithm type:

Type	How to handle the results
Filter	The involved banks will be filtered. To iterate over filtered bank rows, use the function `hipo::bank::getRowList`, rather than iterating from `0` up to `hipo::bank::getRows()`; for example, given a bank object named `particle_bank`: for(auto const& row : particle_bank.getRowList()) { // loops over only the rows which pass the filter } for(int row = 0; row < particle_bank.getRows(); row++) { // loops over ALL rows, regardless of whether they pass the filter }
Transformer	The transformed `hipo::bank` will simply have the relevant bank elements changed. For example, momentum correction algorithms typically change the particle momentum components.
Creator	Creator-type algorithms will simply create a new `hipo::bank` object, appending it to the end of the input `hipo::banklist`. An initial version is created upon calling `iguana::Algorithm::Start`, so that you may begin to reference it; it is helpful to use `hipo::getBanklistIndex` (see the examples for details).

Internally, iguana::Algorithm::Run calls Action Functions, which are described in the next section.

Action Functions

The action functions do the real work of the algorithm, and are meant to be easily callable from any analysis, even if HIPO banks are not directly used. These functions are unique to each algorithm, so view the algorithm documentation for details, or browse the full list:

List of all Action Functions

Action function parameters are supposed to be simple: numbers or lists of numbers, preferably obtainable directly from HIPO bank rows. The return type of an action function depends on the algorithm type:

Algorithm Type	Action Function Output
Filter	Returns `bool` whether or not the filter passes
Transformer	Returns the transformed parameters
Creator	Returns a simple `struct` of parameters (corresponding to a created bank row)

Some algorithms have action functions which require a number from all of the rows of a bank; this distinction motivates further classification of action functions:

Action Function Type	Description
Scalar	All inputs and outputs are scalar quantities (single values). This type of function may be used on a single bank row.
Vector	All inputs and outputs are vector quantities (lists of values). This type of action function needs values from all of the bank rows.
Mixed	Inputs and outputs are scalar or vector quantities.

To maximize compatibility with user analysis code, these functions are overloaded:

for every scalar function, there should be a vector function which calls the scalar function iteratively
not every vector function can have a corresponding scalar function, since some action functions need data from more than one bank row

Finally, it is important to note when to call action functions in the analysis code. For example, some action functions should be called once every event, while others should be called for every particle of the REC::Particle bank. Some algorithms have both of these types of functions, for example:

iguana::clas12::ZVertexFilter::PrepareEvent, which must be called first, at the beginning of an event's analysis
iguana::clas12::ZVertexFilter::Filter, which must be called on every particle, using the output of PrepareEvent in one of its input parameters

It is highly recommended to read an algorithm's documentation carefully before using it, especially if you use action functions.

Important: While algorithm developers are encouraged not to make breaking changes to their algorithms' action functions, in some cases certain changes cannot be prevented. Thus if you use an algorithm's action functions, keep up-to-date on any changes of the algorithm. We will try to announce all breaking changes in the Iguana release notes.

How to Configure Algorithms

Many algorithms are configurable. An algorithm's configuration parameters and their default values are found in the algorithm's documentation.

Iguana provides a few ways to configure algorithms; in general, you may either:

use YAML for configuration that gets applied at runtime, i.e., no need to recompile
use iguana::Algorithm::SetOption to configure an algorithm more directly, which may require recompilation, depending on how you use Iguana algorithms

The default configuration YAML files are installed in the etc/ subdirectory of the Iguana installation. If you have set the Iguana environment variables using, e.g. source this_iguana.sh, or if you are using the version of Iguana installed on ifarm, you will have the environment variable $IGUANA_CONFIG_PATH set to include this etc/ directory.

There are a few ways to configure the algorithms with YAML; see the sections below for the options

Important: While algorithm developers are encouraged not to make breaking changes to their algorithms or configuration, in some cases certain changes cannot be prevented. Thus if you have your own algorithm configurations, keep up-to-date on any changes of the algorithm. We will try to announce all breaking changes in the Iguana release notes.

Option 1: Write your own YAML file

Start your own YAML file by first copying the default YAML configurations from each algorithm that you want to use. See algorithm documentation or the Config.yaml files installed in $IGUANA_CONFIG_PATH for the algorithms' default YAML configurations.

Be mindful of indentation in your YAML file
- The top level (no indentation) contains the algorithm names
- Under each algorithm name is its configuration (one indentation level)
- Further indentation levels or lists of configurations may be used within; see each algorithm's documentation for more information
Note that excluding a configuration option in your YAML file means that the default value will be used.

For example, suppose you want to use algorithms which have the following YAML configurations:

### default configuration file 1
physics::AlgorithmA
  cuts: [-1, 1]

### default configuration file 2
physics::AlgorithmB
  valueA: 3
  valueB: 0.14
  reptiles:
    reptileA: gecko
    reptileB: tuatara

Custom YAML file, with some changes such as widening AlgorithmA's cuts:

### custom YAML file
physics::AlgorithmA
  cuts: [-2, 2]
 
physics::AlgorithmB
  valueA: 5
  valueB: 0.14
  reptiles:
    reptileA: alligator
    reptileB: caiman

Once you have a YAML file, you just need to tell each algorithm to use it:

use iguana::Algorithm::SetConfigFile on each algorithm
if you use iguana::AlgorithmSequence, use iguana::AlgorithmSequence::SetConfigFileForEachAlgorithm to use this file for each algorithm in the algorithm sequence

Option 2: Copy the default directory, and modify

First, copy the default configuration directory to your work area, or to your analysis source code; we'll call the copied directory my_iguana_config, as an example. If $IGUANA_CONFIG_PATH is the default configuration directory (i.e. you have not set or modified this variable yourself), you may run:

cp -rv $IGUANA_CONFIG_PATH my_iguana_config

You may then freely modify any configuration file within my_iguana_config/.

To use this directory in your algorithms, you may do any one of the following:

Since $IGUANA_CONFIG_PATH allows multiple paths, delimited by colons (:), prepend my_iguana_config/ to $IGUANA_CONFIG_PATH; the safest way is to use an absolute path:
export IGUANA_CONFIG_PATH=`pwd`/my_iguana_config:$IGUANA_CONFIG_PATH # bash or zsh

setenv IGUANA_CONFIG_PATH `pwd`/my_iguana_config:$IGUANA_CONFIG_PATH # tcsh or csh

The algorithms will then search my_iguana_config for the configuration before searching the default paths. You may add multiple paths, if needed. Paths which appear first in $IGUANA_CONFIG_PATH will be prioritized when the algorithm searches for configuration parameters; this behavior is similar to that of $PATH or $LD_LIBRARY_PATH.
Use iguana::Algorithm::SetConfigDirectory instead of prepending $IGUANA_CONFIG_PATH (and if you use an algorithm sequence, use iguana::AlgorithmSequence::SetConfigDirectoryForEachAlgorithm)