The Go4 Analysis Framework
Introduction V4.6

The Go4 (GSI Object Oriented On-line-Offline) Analysis Framework has been developed at GSI. It is based on the ROOT system of CERN. Therefore all functionality of ROOT can be used.

2.1.1 Go4 tasks with all communications

Go4 has two parts: the analysis framework itself and a Qt based GUI. Both can be used independently, or together. The separation of the analysis and GUI in two tasks is especially useful for on-line monitoring. The analysis runs asynchronously to the GUI which is (almost) never blocked. The same analysis can be run in batch/interactive mode or in remote GUI controlled mode. The GUI can be used stand alone as ROOT file browser and as histogram viewer for GSI standard histogram servers like MBS. Moreover, the analysis task can be run either as a client bound to one GUI (default), or can be started as an analysis server with the possibility to connect several GUIs (one controller and arbitrary number of observers with restricted commands).

gui150

2.1.2 Go4 analysis steps

The Go4 framework handles event structures, event processing, and event IO. The analysis event loop is organized in steps: Textfeld:
gui147 Each step has an input event, an output event, and an event processor. The output event calls the event processor to be filled. The event processor has also access to the input event. In the current design the analysis is data driven. A first event object (input1) is filled from some event source (input). An output event object (output1) is filled by an event processor object (process1) which has access to both, input1 and output1. Optionally the output event may be written to a file (file1). In the next step the input event object (input2) can be either the output event object (output1) from the previous step or retrieved from the file. The second output event object (output2) is filled by the second event processor object (process2) and can be optionally written to a second file.

The information needed to create the event and processor objects (which are deleted when the event loop terminates) is stored in step factories which are kept in the analysis.

The processor and output event classes have to be provided by the user. The input classes for standard GSI event sources are provided by Go4 (see chapter 3, page 10). Analysis and step factory classes are provided by Go4 or can be implemented by the user as subclasses.

gui148

For normal operation, the Go4 analysis steps are designed to run subsequently. But in addition, each analysis step has access to the output events of all other previous analysis steps, so it would be possible to let analysis steps logically run “in parallel”, all starting with the output event of the first step, and all delivering their results to the last step that may collect and combine them.

gui149

2.1.3 Other analysis functions

Outside the analysis steps the user functions UserPreLoop(), UserPostLoop(), and UserEventFunc() located in the user analysis class are executed as shown in the figure. In principle, they could be used to implement the full analysis without using the step mechanism. But for setting up a new analysis the use of steps is strongly recommended, because steps can be controlled by the GUI and offer event and IO management.

In the event loop, after processing the steps and UserEventFunc() the Go4 dynamic list processor is executed. This processor can be dynamically configured from the GUI to check conditions and/or fill histograms.

gui146

3 Go4 Analysis

The Go4 concept consists of base classes (interfaces) for event structures, algorithms, and IO, which can be implemented by user subclasses or by framework plug-ins (general service classes) delivered with Go4. Class descriptions and reference guides are available on the Go4 Website http://go4.gsi.de.

3.1 Event base classes

The interface classes provided by Go4 (a detailed description is in the reference manual) are normally not seen by the user. Starting with the examples (see chapter 4, page 21) one can better study derived working classes.

TGo4EventElement: Defines the event structure and methods to clear this structure. Input and output event structures of each step of the analysis are instantiated once at initialization. In the event loop event first cleared (via Clear() method call) and than filled by the source class, where BuildEvent function is defined.

TGo4EventSource: The source of the event data. This can be e.g. a file of a certain format, or a socket connection to an event server. The event source class has a BuildEvent(TGo4EventElement*) method, which fills event structures. In addition, CheckEventClass(TClass*) method can be implemented to check event class during initialization. The class constructor should open (connect) the source; the destructor should close (disconnect) it properly.

TGo4EventStore: An object responsible for storing the event data. This can be e.g. a local file of a certain format, but may as well be a connection to some storage device. The virtual method Store(TGo4EventElement*) is used to store the pointed event object. The class constructor should open the storage; the destructor should close it properly.

TGo4EventProcessor: An object that contains the algorithm to convert an input event object into an output event object (both of class TGo4EventElement). This is a subclass of TGo4EventSource, since it delivers the filling of the output event from the input event. The event processor implementation has to “know” the input and output event classes. Actual code of converting the data (i.e. actually performing the analysis) should be implemented in BuildEvent method.

TGo4EventFactory: Defines the actual implementations of all the above. Go4 uses a factory design pattern to create all event class objects at initialization. The virtual methods:

CreateInputEvent(), CreateOutputEvent(), CreateEventSource(TGo4EventSourceParameter*), CreateEventStore(TGo4EventStoreParameter*), CreateEventProcessor(TGo4EventProcessorParameter*) have to be defined in the user factory. They create the respective objects and return the pointer to it. The default factory provides methods
DefEventSource(classname), DefEventProcessor(objectname, classname), DefInputEvent(objectname, classname) and DefOutputEvent(objectname,classname).

Simple examples of a running Go4 analysis can be found on directories $GO4SYS/Go4ExampleSimple, $GO4SYS/Go4Example1Step, and $GO4SYS/Go4Example2Step.

3.2 Event classes, interface to MBS

Go4 offers predefined implementations of the event base classes, including an interface to the GSI data acquisition Multi Branch System MBS, the GSI list-mode files, and ROOT files.

TGo4EventElement (base class):

TGo4MbsEvent MBS event format 10-1

TGo4MbsSubEvent MBS subevent format 10-1

TGo4CompositeEvent Base class for all composite event structures

TGo4ClonesElement Clonesarray container for composite event

TGo4EventSource (base class):

TGo4MbsFile (read from *.lmd list-mode file with format 10,1)

TGo4MbsEventServer (connect to MBS event server)

TGo4MbsStream (connect to MBS stream server)

TGo4MbsTransport (connect to MBS transport server)

TGo4RevServ (connect to remote event server)

TGo4FileSource (read from *.root file from Go4 tree, i.e. one file containing one TTree per analysis step)

TGo4EventStore (base class):

TGo4FileStore (write to *.root file with Go4 tree, this file can be used as TGo4FileSource later)

TGo4BackStore Use TTree existing only in memory to view and analyze event structures.

These classes can be used directly to write simple analysis.

3.2.1 A simple event loop

Using these implementations, getting MBS event data into ROOT (without Go4 framework) could look like this:

#include "Go4EventServer/Go4EventServer.h"

#include "Go4Event/TGo4EventEndException.h"

int main() {

TGo4EventSource* input = new TGo4MbsFile("file.lmd"); // MBS list-mode file

// TGo4EventSource* input= new TGo4MbsTransport("node"); // MBS transport server

// TGo4EventSource* input= new TGo4MbsStream("node"); // MBS stream server

// TGo4EventSource* input= new TGo4MbsEventServer("node"); // MBS event server

// TGo4EventSource* input= new TGo4RevServ("node"); // Remote event server

TGo4EventStore* output = new TGo4FileStore("output",1,5); // split level, compression

TGo4MbsEvent* event = new TGo4MbsEvent();

event->SetEventSource(input);

event->Init();

Int_t eof = 0, numEvents = 0;

while(eof==0) {

try{

event->Fill(); // read event

numEvents++; // eof throws exception

output->Store(event); // write to file

}

catch(TGo4EventEndException& ex) { eof=1; } // mark end of file

catch(...) { cout << "Error" << endl; eof=2; } // any other error

}

cout << "EOF after " << numEvents << " events" << endl;

}

The events in the ROOT file can be retrieved by program, but not in tree viewers. For the use of tree viewers, a new output event object should be filled and stored.

3.3 Analysis step classes

As mentioned above a Go4 analysis is organized in steps. The information needed to instantiate a step is kept in the step factory.

TGo4EventServerFactory (base class): (contains factory methods that already know the above implementations. User step factories must inherit from this class!)

TGo4StepFactory This TGo4EventServerFactory can be used in most cases as user factory to set up the analysis steps (example 1Step).

TGo4AnalysisStep objects of this class hold the definition of an analysis step.

Each analysis step has at least an input event object, an output event object and an event processor object. Additionally, it can have an event source (e.g. TGo4FileSource) and an event store (TGo4FileStore) instance. An analysis step is set up by a TGo4EventServerFactory subclass, i.e. TGo4StepFactory or a user defined subclass.

3.4 Object management

3.4.1 Go4 objects

Textfeld:

gui151 Objects used in Go4 are organized in ROOT folders. The folder structure is sent to the GUI. Objects must be registered in the analysis to be seen in the GUI browser. Registered objects can be located in the processors. The top folders as seen in the GUI are shown on the left side. The methods to register/locate objects are (pointer to the appropriate object, optional subfolder as string, name including subfolder as string):

· AddHistogram(pointer,subfolder), GetHistogram(name)

· AddAnalysisCondition(pointer,subfolder), GetAnalysisCondition(name)

· AddParameter(pointer,subfolder), GetParameter(name)

· AddPicture(pointer,subfolder), GetPicture(name)

These methods are available in TGo4Analysis and TGo4EventProcessor subclasses. Objects created in a TGo4Analysis subclass can be located in all event processors. Objects created in event processors can be located in all subsequent event processors (steps).

Registered objects are stored/retrieved to/from the auto-save file, if enabled. Retrieval is done after creation of the analysis singleton before the creation of the steps. When an object retrieved from the auto-save file is created in a processor the retrieved object is replaced (stored data lost). When an object is created in the analysis singleton it will be replaced by the one retrieved from the auto-save file except histograms which are not retrieved in this case. This means that histograms created in the analysis singleton are always empty after startup.

3.4.2 Go4 parameters

Parameters used in the analysis are implemented by the user in classes derived from TGo4Parameter. Such objects are registered to the framework and can be edited by a generic parameter editor (see chapter 5.11.2, page 68). Parameter objects can be created in the user analysis or the event processor class. Parameter objects are loaded from an optional auto-save file after instantiation of the analysis and before instantiation of the processor objects. When created in the analysis the values set in the constructor are therefore overwritten by auto-save. To use the GUI editor, the UpdateFrom() method must be implemented to update the local (active) parameter object from the modified one delivered by the editor. In this method it is up to the user to ignore certain members or to execute whatever he wants. E.g. one could use parameters to execute commands. Parameters in the auto-save file can be edited. In the editor they can be saved/retrieved to/from files. Several mechanisms can be implemented to handle the parameter member values. The main question is how restricted the methods of modification should be.

1. Modify values only in the class constructor, then recompile. To prohibit changes by editor, the UpdateFrom() method could be just a no-op to avoid undocumented changes. The parameter object should be created and registered in the processor constructor (after possible auto-save restore). Pro: the parameter values are always strictly defined as coded. Con: the parameter values cannot be changed easily.

2. Modify values by editor, use auto-save to store. Create parameter object in analysis constructor. Auto-save must be enabled. Pro: parameter can modified by editor (UpdateFrom() method must be implemented) and changes will be restored from auto-save. Con: when the auto-save file must be deleted for some reasons. the latest values are lost.

3. Use a macro to set values. This macro must be executed in the processor constructor (after auto-save restore). UpdateFrom() could just execute the macro to avoid undocumented changes. Pro: values are kept in a text file and can be modified without recompile. Con: parameter cannot be changed by GUI editor.

4. Best combination: one can use macro saveparam.C([file],wildcard,prefix) from $GO4SYS/macros creating macros (one per parameter) to set all parameters to their current values,. The names are built from prefix and parameter name. The macro can be executed in CINT (then the parameters are taken from a file), or in the GUI or in the analysis. The parameter is created in the analysis. Values are set from macro in processor constructor. By this method parameter values can be edited by GUI, or macro can be edited. Last version will be used independently of auto-save.
Example:
root[0].x saveparam.C("myfile.root","*","setpar")
would produce macros setpar_par1.C, setpar_par2.C etc. The macros have no arguments,
e.g. setpar_par1().

3.4.3 Go4 conditions

Conditions are objects holding window limits or polygons. One or two values can be checked against the limits or the polygon, respectively. In addition the conditions have test and true counters. They can be set to return always true or false or return the inverted test result. They can be edited by the GUI (see chapter 5.8.2, page 61). They can be used to steer the analysis flow. They are saved/retrieved to/from the auto-save file, if enabled. They can be edited in the auto-save file. In the editor they can be saved/retrieved to/from files. If a mechanism like for the parameters (4) is wanted, one can use macro savecond.C([file],wildcard,prefix) from $GO4SYS/macros creating macros (one per condition) to set all conditions to their current values,. The names are built from prefix and condition name. The macro can be executed in CINT (then the conditions are taken from a file), or in the GUI or in the analysis.

Example:

root[0].x savecond.C("myfile.root","*","setcon")

would produce macros setcon_cond1.C, setcon_cond2.C etc. The macros have three arguments: restore flags, restore counters, reset counters (0=no, 1=yes), e.g. setcon_cond1(1,0,1).

3.5 Analysis base class TGo4Analysis

Once the user has defined his/her event class implementations, the analysis steps can be created and registered to the Go4 analysis framework. The actual framework consists of the TGo4Analysis class, which is a singleton (i.e. there is only one framework object in each process). This class provides all methods the user needs, it keeps and organizes the objects (histograms,...), it initializes and saves the data objects.

The user analysis is set up in a subclass of TGo4Analysis, i.e. TUserAnalysis. Constructor and destructor of this user class, in addition with the overridden virtual methods UserEventFunc(), UserPreLoop(), and UserPostLoop() specify the user analysis. If these functions are not needed, one can also use the TGo4Analysis class directly, as shown in the example Simple.

All analysis steps must be created with initial event parameters (input and output filenames) and auto-save settings. Additionally, some user objects may be created and registered here. Note that histograms created and registered here are saved to but not updated from the Go4 auto-save file. Persistent histograms of the analysis should be created in the UserPreLoop function. Existing conditions and parameters, however, are updated when the auto-save file is loaded. In the constructor of the TUserAnalysis class the analysis step objects are created, each containing instances of its user step factory. The analysis steps are registered at the TGo4Analysis framework, input and output events of subsequent steps are checked for matching. Furthermore, other objects like histograms, conditions or parameters can be created in the constructor and registered, so the framework is responsible for their persistence. Such objects can also be created in the step processors.

In addition to the event processors, the UserEventFunc() allows the user to specify analysis operations that are called once in each analysis cycle, e.g. filling certain histograms from the output events of all analysis steps. The UserEventFunc() makes it even possible to call an external analysis framework event by event without using the Go4 Analysis Steps at all, thus taking advantage of the Go4 object management and remote GUI features.

The UserPreLoop() and UserPostLoop() functions may define actions that are executed before starting, or after stopping the main analysis loop, respectively.

Once the user analysis class is defined, there are two modes of operation: The single-threaded batch mode, and the multi-threaded client mode that connects to the Go4 GUI.

3.5.1 User subclass of TGo4Analysis

Up to Go4 version 4.3 the user subclass of TGo4Analysis has been instantiated in the user main program MainUserAnalysis. In this case the arguments of the constructor could be chosen arbitrarily. With Go4 version v4.4 a standard main program (see next section) can replace the MainUserAnalysis. When using this main program the constructor of a TGo4Analysis derived user class is called with a standard argument list as it is used with main programs. The constructor of a user analysis must therefore be:

TUserAnalysis::TUserAnalysis(int argc, char** argv) : TGo4Analysis(argc, argv)

{

cout << "User analysis " << argv[0] << "created" << endl;

...

}

Note that argc is always > 0 and argv[0] is always the analysis name when called from standard main program.

Example

The user analysis could create one analysis step with input from an MBS file with the following code fragments (note that we use the standard Go4 step factory class and a fixed file name):

TUserAnalysis::TUserAnalysis(int argc, char** argv) : TGo4Analysis(argc, argv)

{

const char* userinput = “data.lmd”;

TGo4StepFactory* factory = new TGo4StepFactory("Factory");

// the objects specified here will be created by the framework later:

factory->DefEventProcessor("Proc","TUserProc");// object name, class name

factory->DefOutputEvent("Event","TUserEvent"); // object name, class name

TGo4MbsFileParameter* input = new TGo4MbsFileParameter(userinput);

TGo4AnalysisStep* step = new TGo4AnalysisStep("Analysis",factory,input,0,0);

step->SetSourceEnabled(kTRUE);

step->SetProcessEnabled(kTRUE);

AddAnalysisStep(step);

}

// Example of using the event loop functions for a trivial counting of events
// fEvents must be defined in TUserAnalysis.h:

Int_t TUserAnalysis::UserPreLoop() {

fEvents=0;

return 0;

}

Int_t TUserAnalysis::UserEventFunc() {

fEvents++;

return 0;

}

Int_t TUserAnalysis::UserPostLoop() {

cout << " Total events: " << fEvents << endl;

return 0;

}

3.6 Main analysis program

3.6.1 The go4analysis main program

Contrary to previous Go4 versions, it is no longer required to provide a user main analysis program (typically called MainUserAnalysis). Instead, the standard go4analysis program instantiates and runs user code compiled into a shared library (typically called libGo4UserAnalysis.so). Most of the functionality previously implemented in MainUserAnalysis is now in the user analysis class (subclass of TGo4Analysis), which is instatiated by go4analysis. Existing analysis codes with explicit MainUserAnalysis program are still fully supported.

3.6.2 Command line mode (batch)

The main aim of batch mode is to process event data from files or other data source without GUI intervention. To run the analysis in batch mode, go4analysis is called from shell with several optional arguments. For instance, the command:

shell> go4analysis –file test.lmd –asf histos.root

will use file test.lmd as input and store all analysis objects (histograms, graphs) in file histos.root. The full description of the argument list is:

go4analysis [RUN] [ANALYSIS] [STEP1] [STEP2] ...[USER]

RUN: configuration, relevant for application run mode

-lib name : user library to load (default: libGo4UserLibrary)

-server [name] : run analysis in server mode, name - optional analysis name

-gui name guihost guiport : run analysis in gui mode, used by GUI launch analysis

-http [port] : run analysis with web-server running,

optionally port can be specified, default 8080

-dabc master_host:port : run analysis with optional connection to dabc application,

which could receive objects from running analysis

-run : run analysis in server mode (default only run if source specified)

-norun : exclude automatical run

-number NUMBER : process NUMBER events in batch mode

-hserver [name [passwd]] : start histogram server with optional name and password

-log [filename] : enable log output into filename (default:go4logfile.txt)

-v -v0 -v1 -v2 -v3 : change log output verbosity (0 - maximum, 1 - info, 2 - warn, 3 -errors)

-rate : display rate information during run

-print [sub=N] [hex|dec] : print events, see -help print for more info

-help [topic] : show this help or for selected topic

ANALYSIS: common analysis configurations

-name name : specify analysis instance name

-asf [filename] : enable store autosave file and set autosave filename (default <Name>ASF.root)

-enable-asf [interval] : enable store of autosave file, optionally interval in seconds

-disable-asf : disable usage of asf

-prefs [filename] : load preferences (analysis configuration) from specified file (default Go4AnalysisPrefs.root)

-no-prefs : disable preferences loading

-maxtreesize value : define maximum tree size, value can be: 2g, 1900m, 1900000000

STEP: individual step configurations

-step name : select step by it's name, if not found, first step will be used

-step number : select step by it's number (first step has number 0)

-enable-step : enable step processing

-disable-step : disable step processing

-file filename : use file filename (lmd or lml) as MBS event source

-transport server : connect to MBS transport server

-stream server : connect to MBS stream server

-evserv server : connect to MBS event server

-revserv server [port] : connect to remote event server

-port number : select custom port number for event source

-retry number : select number of retries when connection to source was lost

-random : use random generator as source

-user name : create user-defined event source

-source filename : read step input from the root file

-skip num : skip num first events in mbs event source

-mbs-select first last step : select events interval from mbs source

-timeout tm : specify timeout parameter for event source

-enable-source : enable step source

-disable-source : disable step source

-store filename [split buffersize compression] : write step output into the root file

-overwrite-store : overwrite file, when store output

-append-store : append to file, when store output

-backstore name : create backstore for online tree draw

-enable-store : enable step store

-disable-store : disable step store

-enable-errstop : enable stop-on-error mode

-disable-errstop : disable stop-on-error mode

-inpevt-class name : (re)define class name of input event

-outevt-class name : (re)define class name of output event

USER: user-defined arguments

-args [userargs] : create user analysis with constructor (int argc, char** argv) signature

all following arguments will be provided as array of strings, first argument - analysis name

A list of valid arguments can be obtained by launching go4analysis without any arguments. Execution of go4analysis can be terminated by pressing Ctrl-C. The analysis will regularly close all event sources, store results of processing in output files and then exit.

3.6.3 Creating the user analysis

On startup go4analysis loads the shared user library and instantiates the user analysis. There is a possibility to pass extra configuration parameters to the user analysis constructor, calling go4analysis with -args or -x followed by a user specific parameter list. This list is passed to the analysis constructor:

Example

shell> go4analysis –name TestAna –args xxx.lmd

TUserAnalysis::TUserAnalysis(int argc, char** argv) : TGo4Analysis(argc, argv)

{

// argc is 2

// argv[0] is "TestAna"

// argv[1] is "xxx.lmd"

const char* userinput = “default.lmd”;

cout << "User analysis " << argv[0] << "created" << endl;

if (argc>1) userinput = argv[1];

TGo4MbsFileParameter* input = new TGo4MbsFileParameter(userinput);

...

}

Similar to the argument list of the main() function argc defines number of parameters and argv contains parameter values. First parameter in the list is always the analysis instance name (either set in the GUI launch panel or by
–name argument, default is Go4Analysis). When go4analysis is started without user-specific arguments, only analysis name will be in the list and argc is 1. The user argument list can also be specified in the Analysis launch panel of the GUI.

3.6.4 Default user analysis

In simple cases (only one step) it is not necessary to implement a user-specific analysis class at all. It is sufficient to implement a processor (and optionally an output event) class. In this case go4analysis will search for such classes in the loaded library and instantiate them, using the default TGo4Analysis instance and creating one default analysis step (named Analysis).

3.6.5 Analysis controlled by Go4 GUI

In the interactive GUI mode go4analysis provides all the infrastructure needed to manage the connection to the GUI. Usually, the Go4 GUI is started first and than user launches the analysis program via Launch analysis. Mainly for debugging purposes one can instead use in the GUI Prepare for client connection menu command and than start the analysis in an independent shell by command (same as it is called by GUI):

shell> go4analysis –gui SomeName guihost 5000

Here SomeName is an arbitrary analysis name, guihost is the host name where the GUI is started and 5000 is the port number (may be different, is printed when GUI starts). Same input/output arguments, as in batch mode, can be specified behind. On startup go4analysis creates the analysis framework and connects the multi-threaded analysis client to the Go4 GUI. After the connection is established, the complete analysis framework can be controlled from the GUI. In section 3.6.10, page 19 we describe in detail what is happening on startup of the analysis client and what effect the GUI control actions have.

3.6.6 Analysis as server for multiple Go4 GUIs

When started from the GUI the analysis connects only this GUI and absolutely depends from it. If something happens with GUI or GUI just closed, analysis execution will be terminated. However, it is possible to run the analysis as a server, which allows to connect many GUIs (one controlling GUI and many observer GUIs).

The analysis is started as server independently from the GUI from a shell like in the batch mode but with argument –server

shell> go4analysis –server –stream mbs-server -norun

As in batch mode, in server mode analysis will start its event loop if input was specified. To prevent this, the -norun argument can be add. To force event loop execution with default analysis parameters, -run argument should be specified. An analysis to run in server mode can also be launched via Launch analysis menu command of the Go4 GUI when selecting the mode as server.

A Go4 GUI is able to connect any such started server. Login of GUI to the analysis server may be with observer, controller, or administrator role, respectively; their passwords can be set in user analysis code with DefineServerPasswords() method. There can be only one controller or administrator, but multiple observer GUIs. Observers may only view existing objects, but may not modify them or change analysis setup and running state. Controller may view and modify objects and analysis configuration, but is not allowed to terminate analysis server. Only Administrator may shutdown the analysis server.

See section 5.3.2, page 39 for more details on connection of the GUI client.

3.6.7 Configuration of analysis

There are several methods to configure the analysis which can be combined in a defined order:

Constructor of user analysis class

In any case the constructor is called first. All steps must be created. One may set up all steps like setting input and output filenames, enable/disable steps. One may excecute a macro for that. One may use user arguments given by go4analysis command (behind –x) or in the Launch analysis panel (Args).

Go4 preferences file

When launched from GUI, or started from shell by go4analysis command with the –server or –gui option, and settings had been saved before, these settings are now loaded from the file overwriting the coded setup. Default file name is Go4AnalysisPrefs.root. With –noprefs or –prefs <file> one can disable this loading or specify a different file, respectively. In the Analysis configuration panel a different file also can be loaded.

Arguments to go4analysis

When started from shell now the arguments of go4analysis are used and overwrite the settings.

Hotstart file

When launched from GUI with hotstart file the complete setting from that file is used and overwrites the settings.

3.6.8 Support of older analysis code

In previous go4 versions up to 4.3 it was required to have a user MainUserAnalysis program which was launched via the AnalysisStart.sh script. In most cases that executable can be used as is. Since version 4.4 the GUI directly calls the MainUserAnalysis executable (or program or script as specified in the Launch Analysis panel, see section 5.3, page 38) with same argument list as before. When AnalysisStart.sh script had been modified and therefore the old launch sequence is required, one should set shell variable GO4OLDLAUNCH=yes before starting the GUI.

In many real cases the go4analysis is able to correctly instantiate the user analysis, compiled into libGo4UserAnalysis.so library even if no (int, char**) constructor signature is implemented. To facilitate new Go4 functionality and flexibility, it is recommended to move user code from MainUserAnalysis to user analysis class, (i.e. TUserAnalysis) and remove MainUserAnalysis.

3.6.9 Setting up ssh keys

For launching the analysis on remote host from the GUI, password-less ssh login on this host must be enabled. It means, when typing “ssh hostname” command in the shell, no any password shall be requested. To configure such password-less login, a private/public key pair must be created and the public key must be copied to remote host:

shell> ssh-keygen –t rsa

answer all questions by RET or yes

shell> ssh-copy-id -i ~/.ssh/id_rsa.pub hostname

Now check with “ssh hostname” again that keys are installed properly. Normally, at first time ssh will ask to add hostname into list of known hosts. Answer “yes” and try login again. Only if ssh works without prompting at all, you can run analysis on that machine via the Go4 GUI.

There is no longer necessary to configure ssh for running analysis on the same machine (localhost), while now Go4 provides possibility to run analysis directly via exec mode. This solves the nasty problem of configuring ssh and DNS on machines which are not connected to a network at all.

From historical reason there is still rudimentary support of rsh for analysis launch. rsh in no longer supported in GSI, therefore it is not so good tested as other launch methods. For use of rsh, make sure that the file .rhosts exists in user home directory and that it contains entries for the machine names you want to run the Go4 analysis client on. The file .rhosts could e.g. look like this:

node01

node02

localhost

3.6.10 Start-up of GUI controlled analysis

When starting the Go4 analysis from GUI, the following actions take place in that order:

1. The Launch Analysis GUI panel started by reads settings from file $GO4SYS/etc/go4.prefs. Based on settings in this file, the launch command is composed and executed. Depending on the analysis mode (client or server) either -server or -gui argument lists are passed to the executable.

2. TGo4Analysis or user subclass (e.g. TUserAnalysis) is instantiated and initializes the analysis framework.

3. The analysis, if in client mode, connects to the Go4 GUI. Optionally, the Go4 histogram/object server is created. Note that the analysis in server mode does not connect automatically to the starting GUI, but waits for a separate connect request with login and password from any GUI. Only after this explicit connection the GUI gets control over the analysis server!

4. The analysis settings are loaded from the default preferences file Go4AnalysisPrefs.root. A message is sent to the GUI (if successful):
“Analysis Client MyClient: Status Loaded from file Go4AnalysisPrefs.root”
Note that all settings specified before in the compiled code (auto-save file name, event sources, etc.) are overwritten if the preferences file exists.

5. The configuration settings are now changed by additional arguments, provided to go4analysis executable.

6. The analysis objects are loaded and updated from the auto-save file. The file name from the loaded analysis settings is used, if existing. Otherwise, the filename specified in the preceding user code by SetAuto-saveFile(const chart* name) is used. If successful, a message is sent to the GUI:
”Analysis Client MyClient: Objects Loaded”.
If auto-saving was disabled completely by calling
SetAutoSave(kFALSE), the auto-save file is not opened here even if it exists, and no objects are loaded! The “overwrite filename” option in the auto-save settings must be disabled to recover objects of a previous auto-save file; otherwise, all objects in an old file of the same name are lost!

7. The analysis settings are displayed on the GUI. At this moment, the analysis configuration window pops up and shows the active settings. Note that a GUI, connected to an analysis server, only in administrator mode can change the analysis configuration.

8. End of analysis start-up. A message is sent to the GUI:
“Analysis Client MyClient has finished initialization”.
Note that now the analysis itself is not yet initialized, i.e. the event and processor objects have not been created, and there are still no connections to event sources, etc.

3.6.11 Submit settings and run analysis

At any time the user may apply new settings to the analysis and start/stop the run. Note that if the GUI runs as client connected to an analysis server, these operations are permitted for controller or administrator login only. The following is happening in the described order:

1. Submit the analysis settings. The settings as displayed in the analysis configuration window are sent to the analysis client.

i. First, an already existing analysis is closed (see below).

ii. The analysis is initialized with the new settings. Objects are loaded from the new auto-save file except auto-save is disabled by SetAutoSave(kFALSE). The file name is as specified in the configuration window.

iii. The event objects are created. Event sources and stores are opened. The constructors of all user events and event processors are executed. Note that any object (histogram, parameter, etc) which is created and registered in the user event constructors might replace an object of same name that was loaded from the auto-save file before! To continue working with the loaded objects, the user should request pointer to the object by name from the framework here. Only if the object was not found it should be created anew. Since Go4 v4.4 there are methods to return references to objects which are created only if not loaded from auto-save file.

After submit, the Analysis browser can be refreshed by . When an analysis was running before, the new analysis is started immediately and the refresh is done automatically.

2. Start the analysis with :

i. The Go4 GUI will send the start command and refresh the view in the analysis browser.

ii. The UserPreLoop() function is executed once. Here transient pointers to data might be initialized, values from a user file might be read, etc.

iii. The Analysis event loop is starting. For each event the analysis steps, the dynamic list entries, and the UserEventFunc() are executed. The loop will run until the event source is at the end, an error occurs, or the stop command is applied by the user.

3. Stop the analysis with :

i. The event loop is halted. This will not close the analysis itself, i.e. all event objects still exist, event sources and -stores are still open. When restarting the analysis by , it will continue with the next event.

ii. The UserPostLoop() function is executed once. Here transient pointers should be reset to 0, user files might be written or closed, etc.

4. Save configuration settings: At any time the current settings can be saved to a preferences file. This will not affect the running analysis. Note that after changing the settings in the analysis configuration window they must first be submitted to save them!

5. Load Settings: Loading analysis settings from a preferences file will immediately close the running analysis. The closing actions are just as described below. However, the loaded settings are not initialized until they have been Submitted again from the analysis configuration window!

3.6.12 Shutdown of the analysis client

The analysis client is shut down with the button. This will take the following actions:

1. The connection between analysis and GUI is closed.

2. The destructor of the user analysis class is executed.

3. Close of the analysis (this step can be executed by button ):

i. Objects are written to the previous auto-save file, if SetAutoSave(kTRUE).

ii. The event objects are deleted. Go4 event sources (.lmd files and MBS connections) are closed. Event stores (.root files) are finally written and closed. The destructors of all user events and event processor classes are executed. All references to the event objects are deleted from the Go4 folders.

iii. The dynamic list is reset. All pointers to non existing objects are cleaned up.

4. The analysis client executable terminates. The Go4 GUI is ready to connect the next analysis client.

3.6.13 Disconnect or shutdown analysis server

The GUI may disconnect the analysis server with the button. This will neither stop the analysis nor shutdown the server task, but just close the connections to this GUI. Additionally, when connected to an analysis server, the GUI has a button in the analysis toolbar and a menu for Shutdown Analysis server. This is permitted in administrator mode only! This will take the following actions:

1. Analysis server broadcasts message about shutdown to all GUI clients connected. The GUIs will cease monitoring activities and prepare for disconnect.

2. The destructor of the user analysis class is executed.

3. Close of the analysis, see details in 3.6.12

4. The analysis server disconnects all GUI clients fast, i.e. without handshaking protocol, and terminates.

4 Analysis Examples

To begin with Go4, there are examples of analysis packages at $GO4SYS/Go4ExampleSimple, $GO4SYS/Go4Example1Step, $GO4SYS/Go4Example2Step, $GO4SYS/Go4ExampleAdvanced, $GO4SYS/Go4ExampleUserSource and $GO4SYS/Go4ExampleMesh. The differences are:

Example	Analysis	Step factories	Event objects	Steps
Simple	TGo4Analysis	TGo4StepFactory	TGo4EventElement	Analysis
1Step	TXXXAnalysis	TGo4StepFactory	TXXXEvent	Analysis
2Step	TXXXAnalysis	TXXXUnpackFact TXXXAnlFact	TXXXUnpackEvent TXXXAnlEvent	Unpack Analysis
Advanced	TXXXAnalysis	TXXXUnpackFact TXXXAnlFact	TXXXUnpackEvent TXXXAnlEvent	Unpack Analysis
UserSource	TYYYAnalysis	TYYYUnpackFact	TYYYRawEvent TYYYUnpackEvent	Unpack
Mesh	TMeshAnalysis	TGo4StepFactory		13 different

4.1 Analysis design

If one is going to develop a new analysis with Go4 it is recommended to start with one of the examples. The question is which one? To make this decision easier, here some considerations:

How many steps do I need? The usage of steps has two aspects:

ð modularity of the code: what is the natural granularity. Unpack, calibrate, filter, physics? Subdetectors?

ð design of data generations. Are there event filters?

ð storage versus computing. Are the processed data bigger than the raw? Is the analysis compute bound?

Modularity of analysis code could be achieved in a single step simply by a chain of function calls of one or several classes. However it would get complicated if one wants to disable functions because their successing function would need their data. This problem is solved by Go4 steps. The events filled by the step processors can be stored in ROOT files (trees). The steps produce data generations. These files can then be used as input for subsequent steps replacing the generating step which can be disabled. With two steps one needs at least one output event (filled and stored by first step) and processed by second step. Note that ROOT files produced by any step can be processed by stand-alone macros. In this sense there can be always a final step outside Go4 processing the files of the last step.

Therefore one should first think about data generations and structures.

4.1.1 Simple

Start with this example if you want just produce histograms from raw data. All coding is in one file. No output event file can be written. Histograms can be saved in ROOT file.

4.1.2 One step

This example has an output event which can be stored in a ROOT file which can be processed by macros. In addition it has a user analysis class where the functions UserPreLoop, UserPostLoop and UserEventFunc are implemented.

4.1.3 Two step

In addition we have here two steps. This example also demonstrates how one can configure the analysis completely by a setup macro.

4.2 Using the examples at GSI

When using Go4 at GSI where it is already installed, Go4 is set up by

. go4login

Note that there must be a space behind the dot. To see all relevant environment variables use command

go4version

The output of this command would be helpful if you report problems.

Analysis example programs are started by

go4analysis

or from the GUI which is started by

go4

4.3 Prepare the packages

Copy the content of the directory $GO4SYS/Go4Example1(2)Step to a separate location. You can directly make and run the example. The package consists of the following files:

· Readme.txt

· Makefile

· Declaration (*.h) files

· Implementation (*.cxx) files

· XXXLinkDef.h - ROOTCINT class pragma definitions

Cleanup all previously generated files by:

shell> make clean

In all examples there is one string included in all class and file names: “XXX”. It is recommended to replace this by another string more specific for user task. This is done by rename.sh script, provided together with Go4 distribution. For example, change to “Ship” can be done with:

shell> $GO4SYS/build/rename.sh "XXX" "Ship"

Note that "Ship" will be part of all class and file names, therefore do not use a string which is already in any filename!

To build example, just:

shell> make all

This will create shared library libGo4UserAnalysis.so and libGo4UserAnalysis.rootmap.

4.4 Simple example with one step

The package $GO4SYS/Go4ExampleSimple contains a simplest running Go4 analysis. It contains only one default analysis step and uses the standard Go4 analysis classes TGo4Analysis, TGo4StepFactory and TGo4EventElement. Therefore the functions UserPreLoop(), UserPostLoop(), and UserEventFunc() are not available. No data can be stored in the output event. The example uses some conditions and some parameter objects. The step is reading events from a standard MBS event source, preferably the MBS random source, filling some histograms. No output file is written. The analysis processes up to eight long word values from up to two sub events.

Analysis must be launched via library libGo4UserAnalysis.so.

4.4.1 Event processor

Processor class: TXXXProc

The analysis, analysis factory, and analysis step (all standard Go4 classes) are created in the go4analysis program automatically. The input can be specified via go4analysis input arguments. The only custom code is implemented in processor class. No user event class is used in this example. Members of TXXXProc are histograms, conditions and parameter pointers. In the constructor of TXXXProc the histograms, parameters and conditions are created. Method BuildEvent() - called event by event - gets a dummy output event pointer as argument, but cannot fill any output data. The input event pointer is retrieved from the framework. In the first part, data from the raw input MBS event are copied to arrays of TXXXProc. Two sub-events (crate 1,2) are processed. Then the histograms are filled, the 2d one with polygon conditions.

4.4.2 Parameters

Parameter class TXXXParam

In this class one can introduce parameters values and use them in all steps. Parameters can be modified from GUI.

4.4.3 Auto-save file mechanism

See also chapter 5.4.4, page 43. By default auto-save is enabled for batch, disabled with the GUI. The name of the file is built from the name of input (file, server) like <input>_AS.root. If autosave file enabled all objects are saved into this ROOT file at the end of the event loop. At startup the auto-save file is read and all objects are restored from that file. From GUI, objects are loaded from auto-save file when the Submit button is pressed. Note that histograms are not cleared. One can inspect the content of the auto-save file with the Go4 GUI.

4.4.4 Example log file

All lines with **** are from the example classes.

shell> go4analysis -random -number 100000

Event processor TXXXProc of name XXXProc

Output event TGo4EventElement of name XXXOutputEvent

GO4-*> Welcome to Go4 Analysis Framework Release v4.3.2 (build 40302) !

GO4-*> Create factory Factory

GO4-*> Analysis: Added analysis step Analysis

**** Main: starting analysis in batch mode ...

GO4-*> Opening AutoSave file Go4AutoSave.root , UPDATE mode

GO4-*> Analysis LoadObjects: Loading from autosave file Go4AutoSave.root

LoadObjects with Dirscan...

GO4-*> AutoSave file Go4AutoSave.root was closed.

GO4-*> Factory: Create input event for MBS

**** Event MbsEvent-10-1 has source Random class: TGo4MbsRandom

GO4-*> Factory: Create event processor XXXProc

**** TXXXProc: Create instance XXXProc

GO4-*> Factory: Create output event XXXOutputEvent

**** Event XXXOutputEvent has source XXXProc class: TXXXProc

GO4-*> AnalysisStepManager -- Initializing EventClasses done.

GO4-*> Analysis BaseClass -- Initializing EventClasses done.

GO4-*> Analysis loop for 100000 cycles is starting...

GO4-*> Analysis Implicit Loop has finished after 100000 cycles.

GO4-*> Opening AutoSave file Go4AutoSave.root , RECREATE mode

GO4-*> AutoSave file Go4AutoSave.root was closed.

**** TXXXProc: Delete instance

GO4-*> Analysis Step Manager -- Analysis Steps were closed.

**** Main: Done!

4.4.5 Adapting the example

Creating a new class

Provide the definition and implementation files (.h and .cxx)

Add class in XXXLinkDef.h

Then make all.

Most probably you will change TXXXParam to keep useful parameters.

Then definitely you will change TXXXProc to create your histograms, conditions, pictures, and finally write your analysis function BuildEvent().

4.5 Example with one step

The package $GO4SYS/Go4Example1Step contains a Go4 analysis with one analysis step. It uses the standard Go4 step factory TGo4StepFactory, but a user written TXXXAnalysis. In this class the functions UserPreLoop(), UserPostLoop(), and UserEventFunc() can be used. It uses some conditions and some parameter objects. The step is reading events from a standard MBS event source, preferably the MBS random source, filling some histograms and an output event. The analysis processes up to eight long word values from up to two sub events. All classes are defined and declared in two files (*.h and *.cxx). Additional descriptions are in the source files.

Analysis must be launched via library libGo4UserAnalysis.so.

4.5.1 Analysis class

Analysis class: TXXXAnalysis

In TXXXAnalysis the analysis step is created with the step factory and input and output parameters. Here the defaults are set concerning the event IO. Parameter objects of class TXXXControl also created.

4.5.2 Analysis step

Event class: TXXXEvent

Processor class: TXXXProc

The standard factory created in TXXXAnalysis keeps all information about the step. The TXXXEvent contains the data members to be filled in TXXXProc from the input event (MBS 10-1). The Clear() method must clear all these members (an array for each crate in the example). In the constructor of TXXXProc the histograms and conditions are created, and the pointers to the parameter objects (created in TXXXAnalysis) are retrieved. Function BuildEvent() - called event by event - gets the output event pointer as argument (TXXXEvent). The input event pointer is retrieved from the framework. In the first part, data from the raw input MBS event are copied to the members of output event TXXXEvent. Two sub-events (crate 1,2) are processed. Then the histograms are filled, the 2d one with polygon conditions.

4.5.3 Parameters

Parameter class TXXXControl

This class has one member "fill" which is checked in TXXXProc->BuildEvent() to fill histograms or not. The macro
setfill.C(n), n=0,1 can be used in the GUI to switch the filling on or off. It creates macro histofill.C() which is actually used to set filling on or off (in TXXXProc). You can also modify histofill.C by editor before running the analysis.

4.5.4 Auto-save file mechanism

See also chapter 5.4.4, page 43. By default auto-save is enabled for batch, disabled with GUI. The name of the file is built from the input by

<input>_AS.root

If it is enabled all objects are saved into this ROOT file at the end of the event loop. At startup the auto-save file is read and all objects are restored from that file. When TXXXAnalysis is created, the auto-save file is not yet loaded. Therefore the objects created here are overwritten by the objects from auto-save file (if any), except histograms. From GUI, objects are loaded from auto-save file when the Submit button is pressed. Note that histograms are not cleared. One can inspect the content of the auto-save file with the Go4 GUI. Note that appropriate user libraries should be loaded into GUI to access data from auto-save file (see chapter 5.2, page 37).

4.5.5 Example log file

All lines with **** are from the example classes.

shell> go4analysis -file /GSI/lea/gauss.lmd

GO4-*> Welcome to Go4 Analysis Framework Release v4.3.2 (build 40302) !

GO4-*> Create factory Factory

**** Analysis: Create file input file.lmd

GO4-*> Analysis: Added analysis step Analysis

**** Main: starting analysis in batch mode ...

GO4-*> Opening AutoSave file Go4AutoSave.root , UPDATE mode

GO4-*> Analysis LoadObjects: Loading from autosave file Go4AutoSave.root

LoadObjects with Dirscan...

GO4-*> AutoSave file Go4AutoSave.root was closed.

GO4-*> TGo4MbsFile: Open file /GSI/lea/gauss.lmd

GO4-*> Factory: Create input event for MBS

**** Event MbsEvent-10-1 has source /GSI/lea/gauss.lmd class: TGo4MbsFile

GO4-*> Factory: Create event processor XXXProc

**** TXXXProc: Create instance XXXProc

**** TXXXControl: Histogram filling enabled

**** TXXXProc: Produce histograms

**** TXXXProc: Produce conditions

**** TXXXProc: Create condition

**** TXXXProc: Produce pictures

GO4-*> Factory: Create output event XXXEvent

**** TXXXEvent: Create instance XXXEvent

**** Event XXXEvent has source XXXProc class: TXXXProc

GO4-*> AnalysisStepManager -- Initializing EventClasses done.

GO4-*> Analysis BaseClass -- Initializing EventClasses done.

**** TXXXAnalysis: PreLoop

Input file: gauss.lmd

Tapelabel: DISK

UserName: goofy

RunID:

Explanation:

Comments:

GO4-*> Analysis loop is starting...

**** TXXXProc: Skip trigger event

First event #: 1

GO4-*> End of event source TGo4MbsFile:

/GSI/lea/gauss.lmd -I-f_evt: no more event

**** TXXXAnalysis: PostLoop

Last event #: 16605 Total events: 16605

GO4-*> Go4 EventEndException appeared after 0 cycles.

**** TXXXAnalysis: Delete instance

GO4-*> Opening AutoSave file Go4AutoSave.root , RECREATE mode

GO4-*> AutoSave file Go4AutoSave.root was closed.

**** TXXXEvent: Delete instance

**** TXXXProc: Delete instance

GO4-*> Analysis Step Manager -- Analysis Steps were closed.

**** Main: Done!

4.5.6 Adapting the example

Creating a new class

Provide the definition and implementation files (.h and .cxx)

Add class in Go4UserAnalysisLinkDef.h

Then make all.

Most probably you will change TXXXParam to keep useful parameters.

Then you might change TXXXEvent to represent your event data.

Keep the Clear() method consistent with the data members!

Then definitely you will change TXXXProc to create your histograms, conditions,

pictures, and finally write your analysis function BuildEvent().

In TXXXAnalysis there are three more functions which eventually can be useful:

UserPreLoop () - called before event loop starts,

UserEventFunc() - called after each TXXXProc::BuildEvent(),

UserPostLoop () - called after event loop stopped.

4.6 Example with two steps

The package $GO4SYS/Go4Example2Step contains an unpack step and an analysis step. It uses some conditions and some parameter objects. Step one is reading events from a standard MBS event source, preferably the MBS random source, filling some histograms and an output event. Step two uses this event as input and fills another output event and some more histograms. The analysis processes up to eight long word values from up to two sub-events.

The events are read from standard GSI event sources (in the GUI one can switch to MBS or event servers). Then the first user event processor is called (Unpack). This user event processor fills some histograms and the first user event (unpacked event) from MBS input event. Then the second user event processor is called (Analysis). This user event processor fills some other histograms and the second user event (calibrated event) from the first event. The events from the first and second step can optionally be stored in ROOT files (enabled from GUI). When a ROOT file with unpacked events exists, the first step can be disabled, and this file can be selected as input for the second step (from GUI).

In TXXXAnalysis the two steps are created. Here the defaults are set concerning the event IO. Then macro setup.C is executed at the end of TXXXAnalysis. Analysis must be launched from GUI via library libGo4UserAnalysis.so.

4.6.1 Setup in setup.C

The whole step setup is done in macro setup.C. It gets two strings as argument which can be specified in command line

go4analysis –x <type> <name>

or in the GUI Launch panel in the Args field. In setup.C the type string is used to determine the type of the source, the name string is used to compose file names:

idir/name.lmd or if string starts with @ @idir/name.lml

odir/name_AS.root

odir/name_unpacked.root

odir/name_analyzed.root

idir and odir are directories for the input and output files also specified in setup.C.

If the source type specified (-random, -transport, -stream, -file) is no file, name is used as MBS node name. When started from GUI, any Go4AnalysisPrefs file overwrites the settings from setup.C. When started from shell make sure that setup.C is correct!

4.6.2 Step one: unpack

The event filled: TXXXUnpackEvent

The processor: TXXXUnpackProc

The TXXXUnpackEvent contains the data members to be filled from the input event (MBS 10,1). Only the Clear() method must be changed to clear all these members.

The unpacking code is in the event processor TXXXUnpackProc. Members are histograms, conditions, and parameter pointers used in the event method BuildEvent().. In the constructor of TXXXUnpackProc the histograms and conditions are created, and the pointers to the parameter objects (created in TXXXAnalysis) are set. BuildEvent() called event by event and gets the output event as argument. The input event is retrieved from the framework. The first eight channels of crate one and two are filled in histograms Cr1Ch01-08 … Cr2Ch01-08, respectively. His1g is filled under condition cHis1 on channel 0, His2g under condition cHis2 on channel 1. When editing conditions cHis1,2 histograms His1,2 filled by channel 0,1 will be displayed automatically to set/display the condition values. Picture condSet shows histograms His1,2 on top, His1,2g at bottom. Open the condition editor in the view panel of the picture. Conditions cHis1,2 will be selectable. They are displayed in the pad where they should be set. Both conditions are attached to the picture (see chapter 5.8.4, page 63). Histogram Cr1Ch1x2 is filled for three polygon conditions: polycon, polyconar[0], polyconar[1], all on the same values as the histogram.

4.6.3 Steering methods in processor function BuildEvent

Processing the input event and filling an output event it might be necessary to control the following behaviour:

1. Specify if the output event shall be written to output file (if enabled)

Bool_t isValid;

. . . . – code - . . .

out_evt->SetValid(isValid); // isValid must be set before to kTRUE or kFALSE

return isValid;

Note that the default calling Fill method will set the validity of out_evt to the return value! If one would have a Fill method implemented in TXXXUnpackEvent calling BuildEvent the return value could be handled differently there. A subsequent step should check at the beginning if the input event (output event from previous step) was valid. If not, it should mark its own output event also not valid and return:

Bool_t isValid=kFALSE;

if((inp_evt==0) || !inp_evt->IsValid()){ // input invalid

out_evt->SetValid(isValid); // invalid

return isValid; // return the same validity

}

isValid=kTRUE;

. . . . – code - . . .

out_evt->SetValid(isValid);

return isValid;

2. Specify if the following steps shall be skipped (optional message) by macro calls

GO4_SKIP_EVENT

GO4_SKIP_EVENT_MESSAGE("Skipped Event %d",count-1)

3. Specify if the analysis shall be stopped immediatedly by macro calls

GO4_STOP_ANALYSIS

GO4_STOP_ANALYSIS_MESSAGE("Stopped after Event %d",count-1)

4.6.4 Step two: analysis

The event filled: TXXXAnlEvent

The processor: TXXXAnlProc

The step two is build in the same way as step one.

Note that the TXXXUnpackEvent is used two times: once as output of step one, and once as input of step two.

The TXXXUnpackEvent instance can be filled by previous unpack step, or can be retrieved from input file. Step one must be disabled in the second case. The user method BuildEvent() always gets the pointer to the correct event. Histogram Sum1 is filled by first 4 channels of crate 1 and first 4 channels of crate 2. All channels are gated with condition wincon1. Histograms Sum2,3 are filled similar, but without gate, and shifted by XXXPar1,2->frP1. Histogram Sum1calib is filled like Sum1 without gate but with values calibrated by method TXXXCalibPar->Energy() of parameter calipar.

4.6.5 Parameters

With the TXXXParameter class one can store parameters, and use them in all steps. Parameters can be modified from GUI by double click. There is a macro setparam.C which sets the values. One can disable histogramming in both steps. This doubles the processing speed and is useful if one only wants to create listmode files.

4.6.6 Conditions

There are a few conditions created in TXXXUnpackProc. One (polycon) is used in XXXUnpack() for the accumulation of histogram Cr1Ch1x2. Another one (wincon1) is used in BuildEvent() of TXXXAnlProc to fill histogram Sum1. Conditions can be modified by double click in the browser. One can attach a histogram to a condition or attach conditions to picture pads to ensure that the condition is displayed/set on the proper display.

4.7 Example with some advanced tecniques

The package $GO4SYS/Go4ExampleAdvanced contains an unpack step and an analysis step. It uses some conditions and some parameter objects. Step one is reading events from a standard MBS event source, preferably the MBS random source, filling some histograms and an output event. Step two uses this event as input and fills another output event and some more histograms. The analysis processes up to eight long word values from up to two sub events.

In TXXXAnalysis the two steps are created with their factories and input and output parameters. Here the defaults are set concerning the event IO. When called with a user argument, setup.C macro is executed at the end of TXXXAnalysis.

Two parameter objects are created (TXXXParameter). They can be used in both steps.

Analysis must be launched from GUI via library libGo4UserAnalysis.so, or from shell by

go4analysis –args file

4.7.1 Step one: unpack

The event filled: TXXXUnpackEvent

The processor: TXXXUnpackProc

The TXXXUnpackEvent contains the data members to be filled from the input event (MBS 10,1). In contrast to the Go4Example2Step, we apply the TGo4CompositeEvent classes here. Details on the event structure are discussed in Chapter 8 on page 81.

4.7.2 Step two: analysis

The event filled: TXXXAnlEvent

The processor: TXXXAnlProc

The step two is build in the same way as step one.

Note that the TXXXUnpackEvent is used two times: once as output of step one, and once as input of step two.

4.7.3 Parameters

With the TXXXParameter class one can store parameters, and use them in all steps. Parameters can be modified from GUI by double click.

TXXXCalibPar is an example how to use fitters in parameters to calibrate histograms (more chapter 5.11.3, page 69). Please have a look at the Readme.txt file in this example directory for a detailled description of the calibration procedure.

4.7.4 Conditions

4.8 Example of analysis with a user defined event source

The package Go4ExampleUserSource shows a simple example of a user defined event source reading data from an ASCII text file. Like the one step example, the package can be copied to a user working environment, and the class names can be renamed replacing the “TYYY-” prefix.

To apply a user defined event source, method CreateEventSource() of the user step factory must be re-implemented to react on a TGo4UserSourceParameter when selected in the controlling GUI, or set as argument for the go4analysis batch executable . It should then create a TGo4EventSource subclass that the user implements for his purpose. Note that method CreateInputEvent() should also be overwritten to create a raw event matching to the user event source, since the default of the base class TGo4EventServerFactory always delivers a TGo4MbsEvent.

In this example the event source class TYYYEventSource is prepared to handle any ASCII file containing columns of data separated by blank spaces. Each row is read and its values are converted in order into the Double_t fdData array of the raw event class TYYYRawEvent. The array expands automatically depending on the number of columns. Lines starting with “!” or “#” characters are treated as comments and are ignored. Thus these two classes need not to be modified for input of any ASCII files of that type. However, both the unpack procedure as specified in the event processor TYYYUnpackProc , and the unpack event class TYYYUnpackEvent, are depending on the column’s meanings here and must be adjusted. Additional information can be found in the README.txt file of the example package.

4.9 Example of analysis mesh

This example on Go4ExampleMesh shows how to set up a Go4 analysis of several steps that build a mesh of parallel analysis branches with different result generations. Additionally, one can see how the improved TGo4FileSource class supports partial input from a ROOT tree.

4.9.1 Structure:

The setup of the mesh analysis is done in the constructor of the TMeshAnalysis class. As in the Go4Example1Step, the general TGo4StepFactory is used to specify the event objects by name and class name. An overall of 13 analysis steps is defined for this example. Generally, the analysis mesh consists in two different kinds of steps, the execution steps and the provider steps. The unpack step, however, is as in the other examples just delivering sample data from a TGo4MbsSource (standard Go4 gauss example).

The step structure of the example mesh is as sketched in this figure (arrows show dataflow):

4.9.2 Execution steps:

These analysis steps do the actual analysis work, i.e. they convert some input event into the output event. This is the same as in the more simple examples (2-Step). However, to realize a mesh structure, the execution steps do not work directly on their own input event as assigned from the Go4 framework, but use the input event of one or more provider steps. The execution steps can access the input event pointers of any provider step by the provider step name, using the GetInputEvent("stepname") method. Note that the native input event of the execution steps is never used here (except for the very first "Unpack" step that processes the initial MBS event directly, without a provider step). There are no histogramming actions in the execution steps. To view the result data one has to use a dynamic list histogram or perform a TTree::Draw on the output event's tree, if existing.

4.9.3 Provider steps:

These analysis steps do not perform any analysis work at all, but only make sure that their own input event is always set correctly for the following execution steps, depending on the data flow situation. Generally, there are two cases:

- the provider step reads the input event directly from a branch of a ROOT tree (TGo4FileSource). In this case, the input event remains the native input event of this step as created in the step factory.

- the provider step refers to the result event of a previous execution step.

In this case, the provider processor itself has to find the correct event pointer by name from the Go4 object management. The default Go4 framework mechanism to handle these two cases will not suffice here, since it was designed for a subsequent order of steps and not for a mesh with parallel execution branches.

To do this job, all provider steps use the TMeshProviderProc class as general event processor, and the TMeshDummyEvent class as pseudo output event. The TMeshDummyEvent is necessary, because the Go4 framework will always call the Fill() method of the step's output event to execute any action of the step. So TMeshDummyEvent::Fill() calls method TGo4ProviderProc::SetRealInput() to set the pointer to the desired input event correctly.

If the input event is not read from file (native input event of this step), the provider processor has to search for it by name using the method TGo4Analysis::GetEventStructure("name"). However, the Go4 framework so far does not offer any additional parameter to specify the name of the appropriate input for a provider step. Therefore, this example uses the trick to derive the event name search string from the name of the provider processor itself: the name of this processor (up to the "_") is the name of the required event. Note that TGo4StepFactory forbids to use same names for different objects, since the object name is used as pointer name in the ProcessLine() call; therefore the processor name can not be identical with the input event name, but must differ by the "_" extension.

Additionally, the provider steps use the new partial input feature of the TGo4FileSource class (since Go4v2.9). The name of the event structure defines the name of the TTree branch that should be read from the input file. The first three provider steps use different parts of the TMeshRawEvent each. If the input event name is set to the name of the corresponding tree branch (e.g. "RawEvent.fxSub1"), the file source will only read this branch from the tree. If the input event name is set to the full name of the raw event ("RawEvent", commented out in this example), the complete event is streamed, including the not used parts. Note that in both cases the event object must consist in the full TMeshRawEvent, although in the partial input case only one sub-event is filled. This is required for a proper event reconstruction due to the ROOT TTree mechanism. In this example, the partial event input might increase the process speed by a factor of 2 compared to the full event input.

4.9.4 Configuration:

Although the step configuration can be defined as usual from the analysis configuration GUI, not all combinations of enabled and disabled steps make sense to process a subpart of the complete analysis mesh. For example, if execution step 2 shall be processed, the corresponding provider step for its input event has to be enabled, too. Note that the standard step consistency check of the Go4 framework is disabled here to run such a mesh at all (SetStepChecking(kFALSE)). So it is user responsibility to ensure that all required event objects are available for a certain setup. Moreover, with >13 analysis steps the standard analysis configuration GUI becomes quite inconvenient.

Therefore, the example uses a Go4 parameter TMeshParameter for the easy setup of the configuration. This parameter has just a set of boolean flags to determine which execution step shall be enabled. Depending on this setup, the UpdateFrom() method of the parameter also enables or disables the required provider steps. However, the parameter does not contain the full information of the input file names for the providers yet (In a "real" application, this could be implemented in a similar way though).

Thus the configuration procedure looks like this. The TMeshParameter is edited on the GUI to enable the desired execution steps. The parameter is send to analysis and switches the steps on and off. Then the analysis configuration GUI has to be refreshed by the user pressing button to view the new setup. Here the user may change the names of the event sources for the provider steps, if necessary. After submitting these settings again from the configuration GUI, the mesh setup is ready. Note that once the mesh is configured in this way, the configuration can be stored completely in the analysis preferences and restored on the next startup.

One could also think of a user defined GUI that handles both the setup of the TMeshParameter, and the rest of the analysis configuration in one window. This would offer the additional advantage that it could show the structure of the analysis mesh in a graphical way. However, such a user GUI is not delivered here, but can be created according to the hints given in package Go4UserGUI (see chapter 5.16, page 74).

4.9.5 Usage of the example:

One way to test the example could look like this:

§ Enable the first unpack step, disable the rest of the mesh. Use TGo4MbsRandom as event source for the Unpack and fill the output event TMeshRawEvent into a ROOT tree (switch on TGo4FileStore of unpack step). Do this until a reasonable number of events are processed.

§ Disable the unpack step, enable one or more of the subsequent execution steps. The input for the first 3 provider steps should be the ROOT file that was produced before. Note that the first providers could also read their sub-events from different files. Eventually, produce further output trees from the execution steps.

§ Change the setup in a way that only one branch of the mesh is processed, e.g. only Exec3 and Final.

§ Change the setup in a way that only a certain generation of events is processed, e.g. only Exec1, Exec2, and Exec3, writing output files of their results. Alternatively, let only Exec12 and Final work, reading their provider inputs from these output files.

§ Change the example code and recompile to add another execution branch, e.g. with new steps for InputProvider4, Exec4, OutputProvider4, and collect the results in the existing final step. New classes TMeshB4InputEvent, TMeshB4AnlProc, and TMeshB4OutputEvent should be defined for this (these can be derived from the corresponding classes as existing for the Exec3 branch).

§ Create a new mesh analysis from this template that matches your analysis structure.

5 How to Use the Go4 GUI

The GUI ist started from shell by command

go4

The following picture shows the GUI with all elements. On the right side you see the Go4 browser. The left side will be the display panel. Below is the Tree viewer, and under this the message window, the mbs monitor, and the analysis status display. With Show/Hide in the Settings one can configure the layout and save/restore it. All buttons in the top row are also available as pull down menus commands.

gui300

This would be the minimal look of a running analysis (the date is updated from the analysis):

gui301

There are many keyboard shortcuts to handle windows and actions. See chapter 11, page 90.

5.1 GUI menus

The icons in the top line are grouped into three segments corresponding to the first three pull down menus File, Tools, and Analysis.

5.1.1 File, Tools, Analysis menus

Pull down	Icon	Function
File		Open: opens local ROOT file
		Open Remote: open TNetFile, TWebFile or TRFIOFile to access remote data
		Connect DABC: open connection to DABC data socket (optional)
		Open HServer: open connection to gsi histogram server
		Save memory: save content of the memory browser into a ROOT file
		Close all files: close all ROOT files opened in file browser
		Exit: closes window and exit from GUI
Tools		View Panel: creates window (canvas) to display histogram(s)
		Fit Panel: opens fit panel