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 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 ------------|----------|----------|----------|----------------  | 00000032 | 00000000 | 0 | sensorID:0,sparsePixelType:1chargeADC : 529,324,1,529,325,1,530,325,1,  | 00000033 | 00000000 | 0 | sensorID:1,sparsePixelType:1chargeADC : 536,315,1,  | 00000034 | 00000000 | 0 | sensorID:2,sparsePixelType:1chargeADC : 542,324,1,543,324,1,159,434,1,  | 00000035 | 00000000 | 0 | sensorID:3,sparsePixelType:1chargeADC : 482,329,1,482,330,1,483,330,1,  | 00000036 | 00000000 | 0 | sensorID:4,sparsePixelType:1chargeADC : 195,0,1,206,0,1,214,0,1,270,0,1,276,0,1,  | 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 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.
[install: not yet finished description]
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.
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
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.
In order to build the CED server you need to install yet another external dependency. Run either
sudo apt-get install freeglut3 freeglut3-dev
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
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
A tool for selecting and assembling histogram plots and comparision plots from multiple ROOT files at once
Due to its dependency on the rootpy module (see below), pyroplot requires a Python interpreter version 2.6 or later.
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 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: 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.
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.