9.2. Analysis Manager Classes

9.2. Analysis Manager Classes
	Chapter 9. Analysis

The analysis manager classes provide uniform interfaces to the g4tools package and hide the differences between use of g4tools classes for the supported output formats (ROOT, AIDA XML, CSV and HBOOK).

An analysis manager class is available for each supported output format:

G4CsvAnalysisManger
G4RootAnalysisManger
G4XmlAnalysisManger
ExG4HbookAnalysisManger

All these manager classes implement:

the common interfaces defined in the G4VAnalysisManager base class
specific access functions (with a return type specific to the output format)
the singleton access method Instance()

In order to avoid a dependence of the Geant4 kernel libraries on CERNLIB the ExG4HbookAnalysisManger class is not included in the Geant4 analysis class category but in examples/extended/common/analysis together with all necessary configuration files for its build with the CERNLIB libraries.

The G4AnalysisMessenger class implements commands for creating histograms and setting histograms properties.

9.2.1. Histograms

9.2.1.1. Basic Histograms

An example of use of analysis manager classes is provided in basic example B4, in the B4RunAction and B4EventAction classes. The code for handling histograms given in the following example is extracted from these classes.

Example 9.1. Example with Histograms

#include "B4Analysis.hh"

void B4RunAction::BeginOfRunAction(const G4Run* run) 
{ 
  // Get/create analysis manager
  G4AnalysisManager* man = G4AnalysisManager::Instance();
  
  // Open an output file
  man->OpenFile("B4");
  man->SetFirstHistoId(1);

  // Create histogram(s)
  man->CreateH1("1","Edep in absorber", 100, 0., 800*MeV);
  man->CreateH1("2","Edep in gap", 100, 0., 100*MeV);
}

void B4aEventAction::EndOfEventAction(const G4Run* aRun)
{
  // Fill histograms
  G4AnalysisManager* man = G4AnalysisManager::Instance();
  man->FillH1(1, fEnergyAbs);
  man->FillH1(2, fEnergyGap);
}

void B4RunAction::EndOfRunAction(const G4Run* aRun)
{
  // Save histograms
  G4AnalysisManager* man = G4AnalysisManager::Instance();
  man->Write();
  man->CloseFile();
  // Complete clean-up
  delete G4AnalysisManager::Instance();
}

The code specific to the output format is hidden in B4Analysis.hh where the selection of the output format takes place.

#ifndef B4Analysis_h
#define B4Analysis_h 1

#include "g4root.hh"
//#include "g4xml.hh"
//#include "g4csv.hh"   // can be used only with ntuples

#endif

If a file extension is not specified in the call to G4AnalysisManager::OpenFile(), it is automatically completed according to a selected output format.

9.2.1.2. Histogram Identifiers

The histogram names "1", "2" were kept as they are defined in the analogous example in extended/analysis/AnaEx01. They have no relation to the histogram ID which is used afterwords in histograms fill. The histogram ID is automatically generated when a histogram is created by G4AnalysisManager::CreateH1(), and its value is returned from this function. The default start value 0 is in this example changed to 1 with the G4AnalysisManager->SetFirstHistoId(G4int) method.

9.2.1.3. Histogram Objects

It is also possible to access directly the histogram objects by the manager class. The concrete histogram type is hidden behind a selected namespace. In example B4, the histogram functions mean() and rms() are called:

  G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
  if ( analysisManager->GetH1(1) ) {
    G4cout << "\n ----> print histograms statistic \n" << G4endl;
    G4cout << " EAbs : mean = " << analysisManager->GetH1(1)->mean() 
           << " rms = " << analysisManager->GetH1(1)->rms(), 
           << G4endl;
    // ...           
  }

9.2.1.4. Activation of Histograms

The activation option allows the user to activate only selected histograms. When this option is activated, only the histograms marked as activated are returned, filled or saved in a file. This feature is intensively used in extended/electromagnetic examples where all histograms are first created inactivated:

  G4AnalysisManager* analysisManager = G4AnalysisManager::Instance();
  analysisManager->SetActivation(true);
  // define histogram parameters name, title, nbins, vmin, vmax
  G4int id = analysisManager->CreateH1(name, title, nbins, vmin, vmax);
  analysisManager->SetActivation(G4VAnalysisManager::kH1, id, false);

and then selected histograms are activated in macros, using the analysis "set" command:

/analysis/h1/set 1 100 0   50 cm        #track length of primary
/analysis/h1/set 2 100 0  300 none      #nb steps of primary

When no parameters need to be changed a histogram can be activated using "setActivation" command:

/analysis/h1/setActivation 1 true
/analysis/h1/setActivation 2 true

9.2.1.5. Histograms Properties

The following properties, additional to those defined in g4tools, can be added to histograms via G4AnalysisManager:

Unit: if a histogram is defined with a unit, all filled values are automatically converted to this defined unit and the unit is added to the histogram axis title.
Function: if a histogram is defined with a function, the function is automatically executed on the filled values and its name is added to the histogram axis title. When a histogram is defined with both unit and function the unit is applied first. The available functions: log, log10, exp .
Activation: see previous section.
ASCII option: if activated the histogram is also printed in an ASCII file when G4AnalysisManager::Write() function is called.

9.2.2. Analysis Messenger

The G4AnalysisMessenger class implements the commands for creating histograms and setting histograms properties described below.

The commands for handling files, directories and general options:

/analysis/setFileName name           # Set name for the histograms and ntuple file
/analysis/setHistoDirName name       # Set name for the histograms directory
/analysis/setNtupleDirName name      # Set name for the histograms directory
/analysis/setActivation true|false   # Set activation option
/analysis/verbose level              # Set verbose level

The commands to create or define 1D histogram:

/analysis/h1/create 
   name title [nbin min max] [unit] [fcn]       # Create 1D histogram
/analysis/h1/set id nbin min max [unit] [fcn]   # Set parameters for the 1D histogram of #id :

The commands to create or define 2D histogram:

/analysis/h2/create                             # Create 2D histogram
  name title [nxbin xmin xmax xunit xfcn nybin ymin ymax yunit yfcn] 
/analysis/h2/set                                # Set parameters for the 2D histogram of #id
  id nxbin xmin xmax xunit xfcn nybin ymin ymax yunit yfcn

The commands for 1D, 2D histogram control:

/analysis/h1/setAscii id true|false             # Print 1D histogram of #id on ascii file.
/analysis/h1/setTitle id title                  # Set title for the 1D histogram of #id
/analysis/h1/setXaxis id title                  # Set x-axis title for the 1D histogram of #id
/analysis/h1/setYaxis id title                  # Set y-axis title for the 1D histogram of #id
/analysis/h1/setActivation id true|false        # Set activation for the 1D histogram of #id
/analysis/h1/setActivationToAll  true|false     # Set activation to all 1D histograms.

The same set of commands is available for 2D histograms, under "/analysis/h2" directory.

9.2.3. Ntuples

In the following example the code for handling ntuples extracted from basic example B4, from the B4RunAction and B4EventAction classes, is presented.

Example 9.2. Example with Ntuple

#include "B4Analysis.hh"

void B4RunAction::BeginOfRunAction(const G4Run* run) 
{ 
  // Get/create analysis manager
  G4AnalysisManager* man = G4AnalysisManager::Instance();
  
  // Open an output file
  man->OpenFile("B4");

  // Create ntuple
  man->CreateNtuple("B4", "Edep and TrackL");
  man->CreateNtupleDColumn("Eabs");
  man->CreateNtupleDColumn("Egap");
  man->FinishNtuple();
}

void N4EventAction::EndOfEventAction(const G4Run* aRun)
{
  G4AnalysisManager* man = G4AnalysisManager::Instance();
  man->FillNtupleDColumn(0, fEnergyAbs);
  man->FillNtupleDColumn(1, fEnergyGap);
  man->AddNtupleRow();  
}

In a similar way as for histogram ID, the ntuple column ID is automatically generated when the ntuple column is created by G4AnalysisManager::CreateNtupleTColumn(), and its value is returned from this function. The default start value 0 can be again changed with the G4AnalysisManager::SetFirstNtupleId(G4int) method. The ntuple column ID is specific to each ntuple column type. If the third ntuple column of a different type than double (int or float) is created, its ID will have the value equal 0.

9.2.4. Coexistence of Several Managers

The specific manager classes are singletons and so it is not possible to create more than one instance of an analysis manager of one type, eg. G4RootAnalysisManager. However two analysis manager objects of different types can coexist. Then instead of G4AnalysisManager typedef from g4analysis_defs.hh the concrete type of each manager has to be given explicitly.

Example 9.3. Example with two analysis manager instances

#include "G4CsvManager.hh"
#include "G4XmlManager.hh"

G4CsvManager* csvManager = G4CsvManager::Instance();
G4XmlManager* xmlManager = G4XmlManager::Instance();

Or:

#include "g4analysis_defs.hh"

G4Csv::G4AnalysisManager* csvManager = G4Csv::G4AnalysisManager::Instance();
G4Xml::G4AnalysisManager* xmlManager = G4Xml::G4AnalysisManager::Instance();

9.2.5. Supported Features and Limitations

The first version of the analysis category based on g4tools is provided with certain limitations that can be reduced according to the feedback from Geant4 users and developers.

Below is a summary of currently supported features and limitations in manager classes:

Histogram types: H1, H2 of double
Ntuple column types: int, float, double
Only one ntuple can be created/handled.
No limitation for the number of histograms
Direct access to the ntuple object is not provided.
The directory structure in the output file is fixed to one directory for histograms and one for an ntuple, users can change the names of these directories.
G4CsvAnalysisManager can be used only with ntuples.

Supported features and limitations in g4tools:

Histogram types: H1, H2, H3 of double
Profile types: P1, P2 of double
Ntuple column types: int, float, double
Csv classes can be used only with ntuples.