This page is an introduction guide on how to install, setup and use software and tools for the analysis of test beam data.<<BR>>
Several software packages are used for this purpose:

1. ILCSoft ( mainly lcio and gear )
   
2. If ILCSoft version < v01-16-02 MarlinTPC ( !AdvancedAltroConverter and reconstruction processors )
  
3. !TestBeamAnalysisLibrary ( general analysis of different data levels and plotting tools )
   

== Software requirements: ==

1. ILCSoft:
   An installation of ilcsoft somewhere, either locally or from afs. <<BR>>
   To do so:
   {{{
   source /afs/desy.de/project/ilcsoft/sw/x86_64_gcc41_sl5/v01-16-02/init_ilcsoft.sh
   }}}
   Note: If you use an older version than v01-16-02  
         you need to install MarlinTPC trunk and modify init_ilcsoft.sh to take this local Marlin installation.
         Remove from the MARLIN_DLL in the Marlin section the MarlinTPC library.<<BR>>
         Change and extend the following environment in the MarlinTPC section:<<BR>>
         {{{
         export MARLINTPC="/mypathto/MarlinTPC_trunk"
         export PATH="$MARLINTPC/bin:$PATH"
         export MARLIN_DLL="$MARLINTPC/lib/libMarlinTPC.so:$MARLIN_DLL"
         export LD_LIBRARY_PATH="$MARLINTPC/lib:$LD_LIBRARY_PATH"
         source init_ilcsoft.sh
         }}}	
2. Install the !TestbeamLibrary:
   {{{
   svn co https://svnsrv.desy.de/desy/flctpcsw/public/TestBeamAnalysis/trunk
   }}}
   Cmake is now impelmented for this package.<<BR>>
   In the main directory call 
   {{{
   mkdir build
   cd build
   cmake -C <path-to-ilcsoft>/ILCSoft.cmake ..
   make install
   cd ..
   }}}
   Note: If you want to use your own installation of MarlinTPC, you need to copy and modify ILCSoft.cmake: replace
      {{{
      ${ILC_HOME}/MarlinTPC/v<...>
      }}}
      with
      {{{
      $ENV{MARLINTPC}
      }}}
   Set the environment:<<BR>>
   {{{
   export TBANALYSISLIB="$PWD" or "/mypathto/TestBeamAnalysis"
   source $TBANALYSISLIB/initTBAnalysis.sh   (for zsh-users: initTBAnalysis_zsh.sh)
   }}}
3. Scripts to run the applications from the !TestbeamLibrary 
   There is a folder containing python scripts to steer the testbeam analysis steps with a configuration file 
   containing e.g. parameters for marlin scripts.<<BR>>
   Go to $TBANALYSISLIB/pythonScripts
   {{{
   chmod +x TestBeamAnalysis.py GenerateConfigFile.py
   source python.sh     (or zsh: python_zsh.sh)
   }}}

4. Prepare the environment for the testbeam analysis:
   Make a folder for the analysis and go there.<<BR>>
   Create the following sub folders:<<BR>>
   {{{	
   mkdir raw	
   mkdir pedstore
   mkdir LCIOrawdata
   mkdir HitRecoData
   mkdir TrackRecoData
   mkdir RootRecoData
   mkdir Summaries
   }}}
   Copy  $TBANALYSISLIB/pythonScripts/TBAnalysisEnv.sh to current location and source it.<<BR>>
   Put the rawdata into the folder raw and the pedestal files in pedstore. <<BR>>
   When converting raw data to lcio the output will be written to LCIOrawdata. <<BR>>
   Reconstructed pulse and hit data will go into !HitRecoData and tracks into !TrackRecoData. <<BR>>
   When switching on the writing of a root tree these files will end up in !RootRecoData. <<BR>>
   All summary plots will end up in Summaries in corresponding subdirectories.
    
	
== Using the scripts: ==

The main program is called !TestBeamAnalysis.py reading in a 
config file and a run number.

=== Usage ===
1. Create a config file:
   !GenerateConfigFile.py runnumber or a name<<BR>>
   Example: 
     !GenerateConfigFile.py 1234 produces config-run1234.ini<<BR>>
     !GenerateConfigFile.py test produces config-runtest.ini 
2. Edit the config file if necessary. 
   One config file can be used for more than on run. <<BR>>
   Suggestion would be to rename it accordingly e.g. config_1moduleRuns.ini
3. Run the analysis
   !TestBeamAnalysis.py configFile_example.ini runnumber<<BR>>
   This will execute all steps switched on in config file


=== The Config File ===

The configuration is separated into different categories:

1. database
   Here we define the data base folders. !ConvertRun will fill these folders and during the pulse 
   and hit reconstructions they will be read out.
2. files
   Input files needed for the reconstruction like the gear file and the channel mapping. Either copy these
   files to the folder where you have set up the analysis environment or give a full path.
3. lcio
   Variables used during the creation of the lcio file by the !AdvancedAltroConverter.

Now we get to the actual steering of what is executed:

4. reco
   Switch for the reconstruction steps to be carried out. <<BR>>
   convert = calling the !AdvancedAltroConverter converting raw data to lcio <<BR>>
   hitreco = creates and executes a Marlin steering file running a set of processors including the !PulseFinder and the !RowBasedHitFinder<<BR>>
   trackreco = creates and executes a Marlin steering file running a set of processors including the !PathFinderInterfaceProcessor
5. parameters
   A collection of parameters that are needed to generate correct Marlin steering files for the reconstruction.
6. plots
   Define which summary plots are created. Summaries are available for the different processing steps of the data:
   rawdata, pedestal, pulse, hit and track level.
7. ROOToutput
   With output on or off this section can be enabled. One can then list the names of lcio input collection
   to be dumped into a root tree and give a name for the tree. Based on this configuration the Marlin processor
   !DumpAllDataToTree is called.