Additional Tools

 

Here are some additional tools that either do not come with the standard EUTelescope installation since they require additional dependencies or are just worth being mentioned. Since they might be handy from time to time this page provides some usage and installation directions.

  • dumpevent - a tiny tool to inspect the content of a LCIO file
  • MarlinGUI - build Marlin steering files with a GUI
  • EUTelEventViewer - freely movable and rotatable 3D representation of your detector and events (tracks, hits)
  • pyroplot - A tool for selecting and generating histogram plots and comparision plots from multiple ROOT files at once

 

dumpevent

 

dumpevent is a tiny tool which provides a convenient way to inspect the content of a LCIO file. It is already provided by the LCIO installation within your ILCsoft framework and can be invoked by simply running

dumpevent my_file.slcio X

where "X" is the event number to display, e.g. "1" for the first event contained in the file. dumpevent will display information from the run header, the event header and every single collection contained in the event (slightly shortened here):

 

============================================================================
        Event  : 1 - run:  6692 - timestamp 90823001025 - weight 1
============================================================================
 detector : unknown
 event parameters: 
 parameter EventType [int]: 2, 

 collection name : zsdata_m26
--------------- print out of TrackerData collection --------------- 
 parameter CellIDEncoding [string]: sensorID:5,sparsePixelType:5, 

 [   id   ] |  cellid0 |  cellid1 |   time   | cellid-fields  
------------|----------|----------|----------|----------------
 [00000022] | 00000032 | 00000000 |        0 | sensorID:0,sparsePixelType:1chargeADC : 
                                               529,324,1,529,325,1,530,325,1,
 [00000023] | 00000033 | 00000000 |        0 | sensorID:1,sparsePixelType:1chargeADC : 
                                               536,315,1,
 [00000024] | 00000034 | 00000000 |        0 | sensorID:2,sparsePixelType:1chargeADC : 
                                               542,324,1,543,324,1,159,434,1,
 [00000025] | 00000035 | 00000000 |        0 | sensorID:3,sparsePixelType:1chargeADC : 
                                               482,329,1,482,330,1,483,330,1,
 [00000026] | 00000036 | 00000000 |        0 | sensorID:4,sparsePixelType:1chargeADC : 
                                               195,0,1,206,0,1,214,0,1,270,0,1,276,0,1,
 [00000027] | 00000037 | 00000000 |        0 | sensorID:5,sparsePixelType:1chargeADC : 
                                               410,331,1,410,332,1,395,393,1,396,393,1,403,393,1,
------------|----------|----------|----------|----------------

 

which is in this case the zero-suppressed raw data from the DATURA telescope. The collection name is shown before printing the actual event data. The [id] field is the unique id which is assigned to every LCIO object, the telescope plane is denominated by the sensorID and the pixel hits are stored in the chargeADC field as x coordinate, y coordinate and ADC value (For the MIMOSA26 only binary readout, so only "1").

 

MarlinGUI

 

MarlinGUI is a graphical user interface to Marlin which allows to build up XML steering files for Marlin just by selecting available processors from a list and directly editing their parameters and inputs. Since it depends on the rather large framework QT it is not part of the main installation of EUTelescope but can easily be installed additionally by following the steps below.

 

MarlinGUI Installation

[install: not yet finished description]

Install QT:

sudo apt-get install qt4-dev-tools

sudo yum install qt4-devel

Add Marlin GUI and QT to ilcsoft installation scripts (/path/to/ilcsoft-install/examples/eutelescope/release-standalone.cfg)

ilcsoft.module("Marlin").envcmake["MARLIN_GUI"] = 'ON'

ilcsoft.use( QT( "/path/to/QT"))

where /path/to/QT is likely something like "/usr"

Re-run the installation.

[/install]

 

MarlinGUI Usage

MarlinGUI can update your existing steering file. Just open and save it. Furthermore it helps you to create new steering files. Click on "Add" to select additional processors from a list containing all currently available Marlin (and EUTelescope) processors, another window will be opened allowing you to modify the processor's parameters.

MarlinGUI with a steering file for clustering

 

EUTelEventViewer

 

The C Event Display (CED) is a client - server based graphical user interface which can be used to display single events and cross-check e.g. the track fit. It uses the OpenGL graphics system to provide 3D perspective views with fast rendering, free rotating, and zooming of the display. EUTelescope features an interface to CED via the CEDViewer and the respective EUTelEventViewer processor within the framework. This makes it easy for users to set up a pretty advanced event display just with some lines of steering file. Further information on CED can be found here.

 

CED Installation

In order to build the CED server you need to install yet another external dependency. Run either

sudo apt-get install freeglut3 freeglut3-dev

or

sudo yum install freeglut freeglut-devel

in order to install the needed packages on your system. After that we need to tell the ILCsoft installer to additionally build the CED server (called glced) as wel as the CEDViewer component. This is done by uncommenting the following two lines in your respective configuration file (release-eutel-XXXX.cfg):

ilcsoft.module("CED").envcmake['CED_SERVER']='ON'
ilcsoft.install( CEDViewer( CEDViewer_version ))

You probably need to remove CED folder of your ILCsoft installation to have ILCsoft Installer rebuilding it. After compilation succeeded check in the folder ilcsoft/vXX-XX/CED/vXX-XX/bin if the file "glced" has been created. If so you should be ready to use the C Event Display with EUTelescope.

 

Using CED to display events

Especially with a newly prepared analysis chain it can be very useful to review the outcome of the tracking process by eye. Event displays such as CED provide the possibility of a fast and easy inspection of event data. The implementation into the ILCsoft framework with the CEDViewer which directly reads LCIO data simplifies this even further. By rotating and zooming the detector view the accordance of the single hits with the corresponding track can be checked.

To display events from a LCIO file a CED server instance has to be provided which is invoked using the

glced

command. The EUTelescope Marlin processor EUTelEventViewer can then be executed in a second terminal providing the LCIO file to display. The processor will automatically detect the running CED server and connect to it. The next event is displayed by hitting the return key. An example steering file containing only the event viewer processor is provided here event-viewer-tmpl.xml

wget http://eutelescope.web.cern.ch/sites/eutelescope.web.cern.ch/files/additional_tools/\
     event-viewer-tmpl.xml

An elaborate description of CED and its options can be found in the user manual.

Perspective view: CED showing three tracks in the DATURA telescope

Detail: In this example both the aligned hit position and the fitted hit position are marked in the sensor plane

 

pyroplot - Python ROOT plotter

 

A tool for selecting and assembling histogram plots and comparision plots from multiple ROOT files at once

 

Requirements

Python

Due to its dependency on the rootpy module (see below), pyroplot requires a Python interpreter version 2.6 or later.

PyROOT

PyROOT is part of the ROOT package and is usually installed automatically as long as the python developer libraries are found during configure time. Install python-dev through your distribution's package manager, e.g. on Ubuntu:

sudo apt-get install python-dev

rootpy

rootpy makes the ROOT Python interface more "pythonic" and easier to use. EUTelescope ships with a development snapshot (in ./external/pymodules/rootpy-dev). Alternatively, install a more up-to-date one from http://rootpy.org/install.html

 

Usage

usage: pyroplot.py [-h] [--version] [-l LEVEL] [--compare] [-log]
                   [--select SELECT] [--selection-from-file FILE]
                   [--one-file-per-histogram] [-o FILE/PATH] [--with-2D]
                   [--with-3D] [--list-only] [--strict]
                   files [files ...]

Python ROOT plotter - A tool for selecting and assembling histogram plots and
comparision plots from multiple ROOT files at once

positional arguments:
  files                 The files to be processed; additional info STRING to
                        be included in the plot legend can be added by
                        specifiying FILE:STRING

optional arguments:
  -h, --help            show this help message and exit
  --version             show program's version number and exit
  -l LEVEL, --log-level LEVEL
                        Sets the verbosity of log messages where LEVEL is
                        either debug, info, warning or error
  --compare             Compare the selected histograms between files (ratio
                        plots, chi2) where the first file provides the
                        reference.
  -log, --log-scale     Uses a logarithmic scale for the y axis; only relevant
                        when not using '--compare'.
  --select SELECT, -s SELECT
                        Specify regular expression(s) for histogram selection.
  --selection-from-file FILE
                        Load list of regular expressions for histogram
                        selection from file (plain text file, one reg ex per
                        line).
  --one-file-per-histogram
                        Writes one file per histogram instead of storing all
                        plots in one single file.
  -o FILE/PATH, --output FILE/PATH
                        Output path and file name. If the file does not end in
                        '.pdf' it will be assumed to be a path and created if
                        needed. If --one-file-per-histogram is set, this will
                        be the output directory for the plots.
  --with-2D, -2D        Also loads TH2-type histograms.
  --with-3D, -3D        Also loads TH3-type and Profile2D-type histograms,
                        implies --with-2D.
  --list-only           Do not generate plots but only list objects in ROOT
                        file(s) and indicate which ones would be selected.
  --strict              Require the selection to match the full histogram path
                        and name (with implied '^' and '$') instead of only a
                        partial match.

 

Examples

Plot all histograms from multiple files into one pdf

python pyroplot.py run000123*.root

This will generate plots for every root file matching "run000123*" and will store it into the file "overview.pdf" in the local directory.

Plot only a selection of histograms

python pyroplot.py --select 'detector_4/.*' run000123_clustering.root

Multiple regular expressions can be specified by repeating the "–select" switch. The regular expressions can alternatively also be saved into a text file (one per line) and loaded using the "–selection-from-file" switch.

A global default selection will be used if no selection criteria were given; this is then loaded from the file 'default.sel' in the pyroplot directory.

Compare histograms from two (or more) files

python pyroplot.py --compare --select 'detector_4/.*' run000123_clustering.root run00987_clustering.root

To make the output easier to interpret, additional information on the files can be specified using the "FILE:INFOSTRING" syntax, e.g.

python pyroplot.py --compare run000123_clustering.root:"6GeV @ DESY" run00987_clustering.root:"120GeV at SPS"

This information will be displayed in the plots' legend.