Testbeam Data Analysis Procedures

This page contains the documentation, the notes and the how-to perform the analysis of the test beam data, using MarlinTPC and the Testbeam Analysis Library. These two packages depend on other ILCSoft packages like LCCD, GEAR and LCIO and is assumed that the user is able to correctly install and initialize the ILCSoft environment. The information on these pages can be directly applied to the data taken with the ALTRO electronics but most of them can be applied to any type of TPC testbeam data taken in the framework of the LCTPC collaboration.

An updated webpage with instructions on how to install the necessary software and run the tesbeam analysis can be found here: https://znwiki3.ifh.de/MarlinTPC/HowToRunTestBeamAnalysisSoftware.

The scripts and Marlin Templates used for the analysis of the testbeam data are stored in the FLC-TPC group SVN repository.

Where to start from

The minimal requirements for the analysis of the testbeam data are the raw data file, possibly converted to the LCIO format, an xml file containing the initialization parameters for GEAR and the channel mapping and pedestal data that could be retrieved from file or database. For data taken with the ALTRO electronic the initial set of file, for each run will be:

Let's assign the name TBLPDATA to environment variable pointing to the base folder of the area where you are going to store and execute the analysis Let's also assign the name TBANALYSISLIB to the base folder of the testbeam Analysis Library that also contain some useful script for the analysis of the testbeam data. In the TBLPDATA folder there should be a shell script to set the environment variables, functions and aliases named TBAnalysisEnv.sh which should start more or less as follows

export ALTROPED="$TBLPDATA/pedstore"
export LCIORAW="$TBLPDATA/LCIOrawdata"
export HITRECO="$TBLPDATA/HitRecoData"
export TRACKRECO="$TBLPDATA/TrackRecoData"
export ROOTRECO="$TBLPDATA/RootRecoData"
export SUMMARIES="$TBLPDATA/Summaries"
source "$TBANALYSISLIB/initTBAnalysis.sh"

Finally the last line executes the initialization script of the testbeam Analysis Library to make available in the path the applications and scripts defined there and to add the library to the list of those loaded by Marlin

Data Conversion and database fill

The first operation to perform to execute an analysis of the testbeam data from the very beginning (i.e. just after the data have been acquired during a testbeam campaign) is to convert the raw data to the LCIO format and to store the pedestal and channel mapping information in the database. To this goal there is an application in the MarlinTPC toolbox called AdvancedAltroConverter which performs the conversion and, using the timestamps for the run start and end retrieved from the raw data feeds to the database the pedestal and channel mapping information and also includes the electronic information. To steer the program with the default arguments for a given testbeam run a script, called ConvertRun.sh is included in the scripts folder. It is similar to the following:

if [ -f $ALTROPED/pedestals-0-$1.ldat ]

if [ -f $LCIORAW/readout-$1.000.slcio ]
rm $LCIORAW/readout-$1.*.slcio

local Infilename="readout-$1_0.dat"
for Pedestal in $PedFileList
ExecCommand="$ExecCommand -P $Pedestal"


Analysis of the raw data

The next step in the testbeam procedure is to evaluate the quality of the data prior to any reconstruction. There are several programs that allow to perform this operation. Each program uses the objects defined in the testbeamAnalysis library and is compiled together with that, residing in the bin folder of that package. For each program there is also a standard script that applies the standard steering parameters to the program and execute it on a single run of the testbeam dataset. These program are listed in the following table

Program Name

Standard script




This program perform an analysis of the pedestal used in a given run and stores the results in a ROOT file and/or in a PDF file. The program requires the pedestal, channel mapping information and gear file for the run to analyze and it can retrieve them from the condition database or from files. For the database retrieval the program needs a timestamp that can be given explicitly by the user or retrieved from the LCIO file containing the run.



This program dumps the raw data information from an LCIO file containing the raw data of the testbeam to a ROOT tree using the default data converters.



This program performs the standard summary on the raw data.


This script performs all the operations described thus far for a single run, in a single go. That is converts the raw data to lcio, dumps the data to a ROOT tree and performs the pedestal and raw data summary

Standard Reconstruction (Hit Level)

The analysis of the raw data creates a set of summaries that are useful to evaluate the parameters for the pulse reconstruction, in particular the thresholds to optimize the finding. The next step is to perform a standard reconstruction using Marlin. It's often useful to stop at the hit reconstruction level and do the track finding and fitting separately because this step usually takes a relevant amount of time.

The Marlin process need an xml steering file and is usually useful to store the steering file used for the data processing together with the file obtained, for further, future reference, even if, in most of the cases, the parameters used in the reconstruction are stored in the LCIO file itself. It would be possible to manually create the steering files and run them but this is a boring and error prone procedure and not necessary in most of the cases. In fact most of the runs should be reconstructed with the same parameters with the simple modification of the input and output file names. For this reason there are is a script that creates the steering files necessary for this step from a template, assuming the template has been prepared correctly.

This script is called CreateHitRecoSteeringFile and requires the run number and, optionally the template to use as a source. The basic code looks like this :

        local template="$MARLINTBTEMPLATES/HitReco_Default_Template.xml"        
        if [[ $# == 1 ]]
                echo "Creating the MARLIN hit reconstruction steering file for run $1 using the default file $template"
        if [[ $# == 2 ]]
                echo "Creating the MARLIN steering file for run $1 using the template $2"
        local outsteeringfile="$HITRECO/HitReco-run$1.xml"
        local lcioinputfile="$LCIORAW/readout-$1.000.slcio"
        local lciooutputfile="$HITRECO/HitReco-run$1.slcio"
        local gearfile="$TBLPDATA/gearfile.xml"
        local rootfilename="$ROOTRECO/RootReco-run$1.root"
        sed -e "s,__RUNNUMBER__,$1,g" \
        -e "s,__INPUTRUN__,$lcioinputfile,g" \
        -e "s,__GEARFILE__,$gearfile,g" \
        -e "s,__OUTPUTFILE__,$lciooutputfile,g" \
        -e "s,__ROOTOUT__,$rootfilename,g" \
        < $template > $outsteeringfile

If the run number only is provided a default template, located at $MARLINTBTEMPLATES is used, otherwise the one provided by the user will be used. The template must provide the following placeholders for the different elements to substitute:




The run number


Full path to the lcio file containing the input data


Full path to the gear initialization file


Full path to the lcio file where to store the output data


Full path to the root file where to store the output data

This script creates the paths automatically from the run number and the standard path of the folders where this files should be stored reducing the error possibilities and enforcing a well defined file system structure. This lack of flexibility is a design choice.

To simplify the procedure even more a second script called PerformHitRecoRun.sh that creates a steering file if necessary or required and executes the Marlin process. The script requires the run number to process and, optionally, a template with which to create a new steering file. If a template is provided any steering file already present will be overwritten, otherwise a new steering file will be created from the default template only if a steering file is not already present. The relevant code looks like:

local Template="$MARLINTBTEMPLATES/HitReco_Default_Template.xml"
if [[ $# == 2 ]]
echo "Creating new steering file from template $Template"
source $TBANALYSISSCRIPTS/CreateHitRecoSteeringFileRun.sh $1 $Template
if [ -f "$HITRECO/HitReco-run$1.xml" ]
Marlin $HITRECO/HitReco-run$1.xml       
echo "Creating new steering file from template $Template"
source $TBANALYSISSCRIPTS/CreateHitRecoSteeringFileRun.sh $1 $Template
Marlin $HITRECO/HitReco-run$1.xml

LC note on "Analysis Tools in MarlinTPC for pad-based readout systems": LC-TOOL-2014-010


TestbeamAnalysisProcedures (last edited 2015-03-26 09:23:51 by AnnikaVauth)