User's Guide (incomplete)

1. Introduction

The calice reconstruction and analysis software package is based on LCIO and Marlin. The package can be used to convert raw calice data files to LCIO, to create LCIO files with reconstructed hits, etc. . The conversion is achieved via the lcioconverter package. It can be performed on-the-fly without intermediate files.

The individual tasks are encapsulated in marlin processors. Thus, tasks can be executed consecutively by running one marlin job for each processor or in one go by stacking the processors together. A complete processor list is given in the section Processor references. Somce of the processors are rolled out to the separate package calice-analysis. It can be downloaded from the download page.

The processing is steered by Marlin steering files, which define the list of input files, the processors to be used and the output file. The creation of steering files is described in Steering Files.

You can easily add your own processors by building Your own marlin executable and which is linked against the libraries of this package (see Adding Processors).

If You are searching for How-to-use git You are wrong go away.

2. Steering Files

The processing is steered by marlin steering files which are either simple structured text files or full fledged XML files. To facilitate the creation of steering files, you can either run the marlin executable with -l:

caliceMarlin -l

which will produce a simple, structured text file including all processors or with -x:

caliceMarlin -x

which will produce a XML file. Another possibility is to use the script createSteer.sh. The script is located in the directory scripts/ of the calice source package, or can be downloaded. The script expects a list of processor names and some additional arguments like input files. For each given processor name, a small snippet is search for in the directory scripts/processors.d. The snippets contain the parameter section of the processor i.e. it is a snippet of the complete marlin steering file. Here an excerpt for the SimpleHitSearch processor processors.d/MySimpleHitSearch.steer:

.begin MySimpleHitSearch
ProcessorType SimpleHitSearch
#--- description not set by author 

#       The name of the adc collection (input) to be used
#        type:  [string]
#        default: CALDAQ_ADCCol
        ADCCollectionName   CALDAQ_ADCCol

....


.end -------------------------------------------------

To reference snippets, the name of the parameter section has to be used e.g. MySimpleHitSearch. The snippets are plugged together and some place holders are replaced with values from the command line or the default values specified in the file scripts/processors.d/variables (see below). The place holders are named @name@, where name is any name which is defined the file variables.

The file scripts/processors.d/variables contains for each defined variable one line:

input_file    x 1 1 ;+         f --file            name             A file name with full path name
first_event   o 3 1 0          - --event-range     _
last_event    o 3 2 500000     - --event-range     _
event_step    o 3 3 100        - --event-range     first_last_step  Extend the history graphs every  step events from the first event till the last event.

. Each line describes the name of a variable, the default value and how the variable is filled by command line arguments. The format of each line is the following:

the variable name.
one of the flags which characterise the variable:<
- x : the variable is assigned to a general argument which exists always independent of the choice of processors.
- o : the variable is assigan to an optional argument which is only allowed if this variables is used in on of the selected processor snippets.
- d : the default value for a variable which is used it the variable is not addressed by a command line argument. This flag makes only sense together with command line arguments which do not require further paremeters.
the number of parameters following the argument (0 means that no parameters are following the argument).
the parameter index (starting from 1) which is assigned to this variable.
the default value which is assigned to the variable if the variable is not addressed by the command line.
the name of a single character argument e.g. c will assign the variable to the argument -c
the name of the long argument e.g. --help
A one word description for each parameter following the argument or - (separated by commata; spaces are not allowed)
A short description of the argument and its parameters, which will be shown when the script is run with the option --help.

3. Example Tasks

In the following it is assumed, that the software is installed in $CALICE, that the environment variable LD_LIBRARY_PATH contains all path names where the required libraries are: lcio, Marlin, lccd, MySQL, CondDBMySQL, CLHEP, (ROOT), and the calice reconstruction libs e.g:

LD_LIBRARY_PATH=$CALICE/lib:$ILC_HOME/lib:$ILC_HOME/extern/lib:$ROOTSYS/lib

To test whether all libraries will be found, do:

$CALICE/bin/caliceMarlin -l | less

This should result in a long list of Marlin processors and their parameters.

Further, it is assumed that the scripts, which can be found either in the directory scripts of the source directory or can be downloaded from the download page, are located in the directory scripts of the current working directory, the LCIO conditions data base files are located in the sub directory conddb, data files are contained in the directory data/test-beam or data/simulation. The directory data/test-beam contains files named; Run100214.bin. The directory conddb, should contain files named e.g. condDB_CalibrationConstants_HEAD_20060228_164024.slcio. The names, in particular the date and time part of the name, should coincide with those given in scripts/processors.d/FileConditionsProcessor.steer.

3.2 Listing the LCIO collections

The following command should create a marlin steering file which will run a simple processor which will search for all collections in the events.The steering file is handed to the Marlin executable, which is executed directly:

> sh scripts/listCollections.sh --exe $CALICE/bin/caliceMarlin \
        --file data/simulation/Mokka.slcio \
	--max-records 1000

3.2 On-the-fly conversion and reconstruction

The following command should create a marlin steering file which will run the LCIO conversion processor, the drift chamber and ECAL reconstruction. The steering file is handed to the Marlin executable, which is automatically executed:

> sh scripts/tbAnalyse.sh --exe $CALICE/bin/caliceMarlin \
        --data-dir data/test-beam \
        --run 100214 \
        --max-records 10000 \
        --output-dir /tmp \
        --output-ext _firstTest

You can set or change the default values of all the possible command line arguments by editing the values in the 5th column of the file scripts/processors.d/variables e.g. you could change in the line which starts with exe the name of the executable from bin/caliceMarlin to the preferred one.

If you want to see the steering file rather then executing Marlin directly, you could add the argument --show-steer. You can get a full list of possible options for the given script by adding the option --help.

The reconstructed hit and track collections can be stored in an LCIO file. This requires in addition the LCIO output processor. To add the processor, edit the script scripts/tbAnalyse.sh and add MyLCIOOutputProcessor to the list of Processors.

3.3 On-the-fly conversion, reconstruction, and writing a ROOT tree.

The following command should create a marlin steering file which will run the LCIO conversion processor, the drift chamber and ECAL reconstruction. The resulting hit and track collections will be written to a ROOT tree. The script will directly execute the Marlin executable.

> sh scripts/writeTree.sh --exe $CALICE/bin/caliceMarlin \
        --data-dir data/test-beam \
        --run 100214 \
        --max-records 10000 \
        --output-dir /tmp \
        --output-ext _firstTest

The output file should be /tmp/HitTree_100214_firstTest.root.

3.4 Writing an equivalent ROOT tree from a Mokka sumlation.

The following command should read in the Mokka output LCIO file, create CalorimeterHit collections from the SimulatedCalorimeterHit collection, it will calibrate the signal in mips, and smear it. Furter more, a track is created from the SimulatedTrackerHit collections. Finally, the a ROOT tree is created from the new collections.

> sh scripts/writeSimulationTree.sh --exe $CALICE/bin/caliceMarlin \
        --file data/simulation/mokka.slcio \
        --output-dir /tmp \
        --output-ext _firstTest

The output file should be /tmp/HitTree__mokka___firstTest.root.

3.4 Create your own script.

Copy one of the scripts and replace the list of processors. For example, starting from scripts/tbAnalyse.sh. The script should stay mostly untouched. You should change the description, Then, add or change processors in the last line between $0 and --. Any processor can be used for which there is a snippet in processors.d. To set default command line arguments, add arguments between -- and $*:

#!/bin/sh
# about:
#  reconstruct test-beam data and write hits and tracks to a LCIO file

# --- guess the directory where the create script is located
...
..
# --- create steering file using the given processors and run marlin or show the steering file

$create_script $0  MarkAllTransient \
  MyDriftChamberReconstruction \
  MySimpleHitSearch \
  MyCollectionHistogramer \
  MyLcioOutputProcessor \
  -- --data-dir data/test-beam $*

The MyLcioOutputProcessor processor was added, some histogramming processors were removed, and the default argument --data-dir data/test-beam was set. The argument can still be overriden by command line.

4. Marlin Processor Reference

To be done. For the time being refer to the API documentation of calice-reco and calice-analysis (see derivatives of marlin::Processor).

5. Adding Processors

(see Installation - Adding Your Own processors)

6. Debugging

(see Development - Debugging)