...

The centerpiece of the framework is a regular Python application (pyana) which can load one or more PSDM:user analysis modules which are also written in Python. The core application is responsible for the following tasks:

...

The core application have a number of configuration options which can be set or changed from PSDM:configuration file or from a command line. If the same option appears both in configuration file and command line the n the command line value overrides value in the configuration file.

...

• "AmoETof-0|Acqiris-0" – selects data produced by detector AmoETof, detId 0, device Acqiris, devId 0
• "AmoETof|Acqiris" – selects data produced by detector AmoETof, any detId, device Acqiris, any devId
• "AmoETof-*|Acqiris-*" – same as above
• "AmoETof-0" – selects data produced by detector AmoETof, detId 0, any device, any devId
• "|Acqiris-0" – selects data produced by any detector, any detId, device Acqiris, devId 0
• "*-*|Acqiris-0" – same as above

Configuration

Analysis job can read the configuration options from the command line and/or the configuration file. Command line can be used to set options only for the pyana application itself but not user analysis modules. Options for user modules can be set in configuration file only.

...

Configuration File

The default name for the configuration file is "pyana.cfg" in the current directory. The name can be changed with the --config or -c command line option. The format of the configuration file follows the widely accepted syntax for INI files. File consists of series of sections, beginning of each section is marked by the section name in square brackets. Each section contains arbitrary number of options in the form option = value. Both section header and option name must start on first column, white space at the beginning of the line means that line is a continuation of the previous option line. Empty lines and lines beginning with word # (hash sign) or ; (semicolon) are considered comments. Semicolon anywhere on the line as considered a beginning of the comment if it follows space character. The word REM (case insensitive) at the beginning of the line starts a comment if it is followed by space, TAB or new-line.

Here is an example of the configuration file syntax:

...

# Comment line
; Another comment
[section1]
name = Default    ; In-line comment

# next line shows line continuation
modules = module.A module.B
          module.C

REM REM-style comment
[section2]
limit = 1000

Methods

As mentioned above the class in the user module defines number of methods. These methods are called by the Pyana framework at the appropriate moments during data analysis. Here is the explanation when these methods are called and what arguments they accept.

• beginjob(evt, env) – this method is called for at a Configure transition. Typically this is the place to initialize various things that may depend on the data being processed. Configuration objects which are part of the Configure transition are accessed through the env object. evt object provides interface to the datagram data and can be used to extract all contained data too, but preferred way to access configuration data objects is through the environment object. This method is usually called once per job, but in case when pyana is instructed to process multiple runs it can be called several times if there is more than one Configure transition happened during those runs.

• endjob(env) – this method is called at Unconfigure transition. Typically used to process collected statistics, close output files, etc. Like beginjob() it can be called multiple times if there is more that one Configure transition happes during the run range being processed.

• beginrun(evt, env) – this method is called for at a BeginRun transition. There is usually no data associated with this transition so evt object would be empty, but env object contains all configuration objects. This method is called once for every run and is a good place to prepare for the processing of the next run.

• endrun(env) – this method is called for at a EndRun transition. Typically used to process statistics collected during the run.

• begincalibcycle(evt, env) – this method is called for at a BeginCalibCycle transition. This method is called once for every calibration cycle.

• endcalibcycle(env) – this method is called for at a EndCalibCycle transition. Typically used to process statistics collected during the calibration cycle.

Methods beginrun(), endrun(), begincalibcycle(), and endcalibcycle() are optional, analysis module does not have to define them and they are called only if defined.

Configuration

Analysis job can read the configuration options from the command line and/or the configuration file. Command line can be used to set options only for the pyana application itself but not user analysis modules. Options for user modules can be set in configuration file only.

Configuration File

The default name for the configuration file is "pyana.cfg" in the current directory. The name can be changed with the --config or -c command line option. The format of the configuration file follows the widely accepted syntax for INI files. File consists of series of sections, beginning of each section is marked by the section name in square brackets. Each section contains arbitrary number of options in the form option = value. Both section header and option name must start on first column, white space at the beginning of the line means that line is a continuation of the previous option line. Empty lines and lines beginning with word # (hash sign) or ; (semicolon) are considered comments. Semicolon anywhere on the line as considered a beginning of the comment if it follows space character. The word REM (case insensitive) at the beginning of the line starts a comment if it is followed by space, TAB or new-line.

Here is an example of the configuration file syntax:

# Comment line
; Another comment
[section1]
name = Default    ; In-line comment

# next line shows line continuation
modules = module.A module.B
          module.C

REM REM-style comment
[section2]
limit = 1000

Core Options

By default the core application options are read from {{\[PSDM:pyana\]}} section of the configuration file. If the option {{\-C _name_}} or {{\-\-config-name=_name_}} is given on the command line then additional section {{\[PSDM:pyana._name_]\}} is read and values in that section override values from {{\[PSDM:pyana\]}} section.

Here is the list of all command line and configuration file options availabale currently:

User Module Options

For every user module the configuration file may contain one or more configuration sections. The section header for the user module has format {{\[PSDM:module\]}} or {{\[module:_name_\]}}. When defining the user modules either with {{--module}} command line option or {{modules}} configuration file option one can optionally qualify the module name with a colon followed by arbitrary single-word string. Without this optional qualification the framework will load the user module and will use the options from {{\[PSDM:module\]}} section to initialize the instance of the analysis class (as explained in [PSDM:Initialization|#Initialization] section). If, on the other hand, the qualified name is used then the framework will initialize the instance with the options combined from the sections {{\[PSDM:module\]}} and {{\[module:_name_\]}} with the latter section overriding the values from the former section. One could use several qualified forms of the same module name to produce several instances of the analysis class in the same job with different options. 

Here

...

Core Options

By default the core application options are read from {{\[pyana\]}} section of the configuration file. If the option {{\-C _name_}} or {{\-\-config-name=_name_}} is given on the command line then additional section {{\[pyana._name_]\}} is read and values in that section override values from {{\[pyana\]}} section.

Here is the list of all command line and configuration file options availabale currently:

...

User Module Options

For every user module the configuration file may contain one or more configuration sections. The section header for the user module has format {{\[module\]}} or {{\[module:_name_\]}}. When defining the user modules either with {{--module}} command line option or {{modules}} configuration file option one can optionally qualify the module name with a colon followed by arbitrary single-word string. Without this optional qualification the framework will load the user module and will use the options from {{\[module\]}} section to initialize the instance of the analysis class (as explained in [Initialization|#Initialization] section). If, on the other hand, the qualified name is used then the framework will initialize the instance with the options combined from the sections {{\[module\]}} and {{\[module:_name_\]}} with the latter section overriding the values from the former section. One could use several qualified forms of the same module name to produce several instances of the analysis class in the same job with different options. 

Here is an almost identical example from Initialization section above which illustrates the inheritance and overriding of the user options:

[pyana]
modules = mypackage.myana mypackage.myana:wide

[mypackage.myana]
lower = 0
upper = 100
name = default

[mypackage.myana:wide]
; 'lower' option will be reused from [mypackage.myana] section
bins = 1000   ; this overrides default module value
; two options below will override [mypackage.myana] values
upper = 1000
name = wide

...

Methods

As mentioned above the class in the user module defines number of methods. These methods are called by the Pyana framework at the appropriate moments during data analysis. Here is the explanation when these methods are called and what arguments they accept.

• beginjob(evt, env) – this method is called for at a Configure transition. Typically this is the place to initialize various things that may depend on the data being processed. Configuration objects which are part of the Configure transition are accessed through the env object. evt object provides interface to the datagram data and can be used to extract all contained data too, but preferred way to access configuration data objects is through the environment object. This method is usually called once per job, but in case when pyana is instructed to process multiple runs it can be called several times if there is more than one Configure transition happened during those runs.

• endjob(env) – this method is called at Unconfigure transition. Typically used to process collected statistics, close output files, etc. Like beginjob() it can be called multiple times if there is more that one Configure transition happes during the run range being processed.

• beginrun(evt, env) – this method is called for at a BeginRun transition. There is usually no data associated with this transition so evt object would be empty, but env object contains all configuration objects. This method is called once for every run and is a good place to prepare for the processing of the next run.

• endrun(env) – this method is called for at a EndRun transition. Typically used to process statistics collected during the run.

• begincalibcycle(evt, env) – this method is called for at a BeginCalibCycle transition. This method is called once for every calibration cycle.

• endcalibcycle(env) – this method is called for at a EndCalibCycle transition. Typically used to process statistics collected during the calibration cycle.

...

...