CRT & ESA Setups Analysis1

CRT & ESA setups analysis1

Cosmic Ray Telescope

Endstation A setup

Analysis

Software

Manual

Josef Uher

Content

1Introduction

1.1Changes

1.2Conventions of this manual

2Installation

2.1Requirements

2.2Compilation and installation

3Usage

3.1General Usage

4Analysis tutorial

4.1Viewing raw data – analysis quick start

4.2AnalyzeCRT Control window

4.3Ignoring devices/modules

4.4Defining cuts

4.5Advanced histogram plotting control

4.6Cherenkov ring plotting

4.7Creating ADC/TDC table correction file

4.8Using ADC/TDC correction function

4.9Optimizing correction parameters using sigma minimization

4.10Creating dependency of resolution as a function of amount of photons

4.11Time and charge dependencies

4.12Treating of cross talk

4.12.1Aligning peaks

4.12.2Creating dependency of resolution vs. cross talk window

4.13Online monitoring

4.14Data connection files

4.14.1Module connections to ROOT branches

4.14.2Channel order file for the online monitoring

5Code description

5.1Introduction into the code structure

5.2Setup definition and the main event loop

5.3Analysis initialization

5.4Dataflow and analysis run

5.4.1Data source classes

5.5Event rejection dependencies

5.6Canvases, histograms and graphs

5.6.1Canvas factory

5.6.2Cherenkov ring canvas

5.6.3CRT graphs

5.6.4Graph collector

5.6.5Cherenkov ring

5.6.6Fits

5.7Minimization

5.8Exceptions

5.9XML file

5.10Log file class

5.11Output file

5.12Adding new module

5.12.1Creating class

5.12.2Linking values for corrections

5.12.3Adding new object to Makefile

5.13Generating fake data for debugging

5.14Version control class

5.15Remote analysis run control

5.15.1System V IPC brief description

5.15.2Messenger class

5.15.3Control console class

5.15.4Graphical User Interface

5.16Overview of auxiliary scripts

6XML settings file description

6.1Classes and their variables in XML input file

7Questions and Answers

8Appendix – XML file examples

8.1XML Settings file for cosmic ray telescope

8.2XML Settings file for Endstation A setup

8.3Settings file example

9List of online resources

1Introduction

CRTAnalysis is the software for Cosmic Ray Telescope and Endstation A setup data analysis. It provides the ability to view histograms of measured data. It also provides a wide range of corrections of timing resolution parameters. The corrections can be based on particle tracking, signal amplitude etc.

All information (coefficients) for corrections and other parameters are stored in a separate XML file. This file can be used for configuration of any object involved in the analysis.

1.1Changes

The software (including this manual) is still under development. Most of details described in this manual may be changed.

1.2Conventions of this manual

To improve orientation in this text and for better legibility, following types and colors are used for different types of text:

example of XML code
example of source code
Linux console command

2Installation

2.1Requirements

It is necessary to have properly installed and configured CERN's ROOT libraries of version 4.00 or higher. Also the XML configuration file requires Gnome libxml2 libraries.

2.2Compilation and installation

The CRTAnalysis package can be copied from the following location on AFS

It requires that your UNIX environment is configured to the extend that you can run ROOT. An example of such a configuration is given on the DIRC R&D web pages:

Once you copied the software and configured your environment you compile and link the CRTAnalysis package using the Makefile by typing

make dep

make

and the software should be compiled. If it does not compile, check libraries and include paths in the Makefile. A convenient way to display the code is to use the kdevelop tool. Go to your directory where you copied the CRTAnalysis package and type kdevelop crtanalysis.kdevprj &

3Usage

3.1General Usage

Providing that you have properly configured XML setting file (described in the next chapter), the usage is simple. To run CRT analysis type for instance:

./analyzeCRT -s settings.xml -p histograms.ps -l crt.log -runapp

Description of switches:

-s [file name]

It defines the XML file name which contains the analysis parameters. If not specified, then program searches for file "settings.xml" in the current directory.

-p [file name]

A name of postscript output file. If not specified, postscript files with names of appropriate canvases are generated in the current directory.

-pson

Switch on the postscript.(JS does pson always have to be specified when –p is used? Or is that automatic?)

-gifon

Switch on gif pictures.

-l [file name]

It is a name of log file with description of analysis and analyzed events. If not specified, log is switched off.

-runapp

Runs ROOT application after the analysis is finished.

-detail

Switch on creating of detailed gif files during fitting slices or creating time dependency histograms.

-fitoff

Switch of all fits.

-normmax

Normalize all histograms to their peak height

-v

Print version.

-r

ROOT file (if not defined in XML).

-o [file name]

Output file name.

-monitor [refresh]

Starts the application in the online monitoring mode. Parameter refresh is optional and defines number of events after which all plotted histograms will be redrawn.

-control [pid]

Connects via System V messages to analysis running with PID. See chapter 4.2 of this manual for detail.

4Analysis tutorial

We will analyze step by step the measured data from Endstation A setupin this chapter. The result of our work will be an XML settings input file and some results and their description. At the beginning few words about the structure of a XML file.

XML stands for Extensible Markup Language. All data in a XML file are structured by tags. A tag is something like: <myTag> and defines beginning of data. Data ends with end tag which is: </myTag>. I.e. it differs from the previous one by slash. Start tag and end tag defines an "area" where other information related to this tag can be found. This area can contain other tags - this creates a tree or folder like structure.

Each tag can contain a property, which defines details about the tag. Example is
<myTag myProp="black">.

The input data is aROOT data file created from the ASCII file that is written by the data acquisition in Endstation A. Theconversion from *.dat file into *.root file is done using the tools from the CRT software package. The general idea of the conversion is that you start root and run a macro that converts the ASCII file into a ROOT file. Currently this is done automatically for you by the run.pl script we use to run the DAQ.

For the purpose of this manual we will assume that a run was taken und a ROOT file was created with the name testrun_for_tutorial.root.

4.1Viewing raw data – analysis quick start

This supposes to be a quick start into the analysis and thus many steps there are not described into details. The details will be explained later in the following chapters. The first of all, we want to see what's inside the data file, i.e. we just want to see raw data and we will focus on start counter 1 (quartz bar) and particularly on pad 0 0. To reach that goal we need to prepare an XML input file, which defines the problem for analysisCRT code. We can call this file tutorial.xml.

The first line which must be included in all files is:

<?xml version="1.0"?>

This is only a definition of the XML language and does not affect the analysis. The next lines are only about the definition of the analysis. The first tag defines that we will analyze the setup from EndstationA. This tag must enclose the whole data area for this analysis, so the end tag will be at the end of file.

<includeDirectory>/u2/juhe/endstationA/Data_Connections_Repository</includeDirectory>

<include>2005-05-06_64_channels_across_all_slots.xml</include>

Include tags contains description of connections between analysis modules and branches (channels) in the root file. Then we define the directory which contains the ROOT data file(s) and datafiles (divided by comma, without extender .root).

<rootDirectory>/u2/juhe/endstationA</rootDirectory>

<rootFiles>testrun_for_tutorial</rootFiles>

Now we define from which to which event we want to run the analysis. We want to start at the beginning (event 0) and stop after event 35000.

Information about events are followed by global definitions that affect all histograms unless specifically changed–for instance the default number of bins in histogram, the default range and number of events which are taken into average value for "value vs. time" and "value vs. charge" plots.

The next part defines parameters for the setup endstationA. Inside, we must define all modules/devices which are present in the setup. If we want to avoid modules to affect the analysis (by global rejection of events or so), we can define property ignoreDev="1" and such device is "out of game". Nothing or ignoreDev="0" means "use this device". Here we basically ignore everything except "delta" and "startCnt1". "delta" device is harmless from point of view of events rejection – it is used only for temperature corrections and startCnt1 is the device we want to look at.

<delta>

</delta>

</russMcp>

</quantacom>

</startCnt2>

</leadGlass>

</startCnt1>

</slot2>

</slot3>

</slot4>

</slot5>

</slot6>

</endstationA>

And we must not forget the end tag of the whole analysis!

</AnalyzeEndstationA>

Let's focus on what will be inside the <startCnt1> tag. In the first approach we just want to see raw data of the first pad.So we will define:

<mcpPad_row_0_column_0>

</ADC>

</TDC>

</mcpPad_row_0_column_0>

</startCnt1>

These lines will draw TDC and ADC spectra of raw and corrected data. Because we didn't define any correction, the "corrected" histogram will be the same as the "raw" one. If you want to see more histograms, you can define histLevel="4" (simply, a higher number) and more histograms will be shown.To see ADC vs. TDC 2D histograms, we must define histLevel property also for tag <mcpPad_row_0_column_0>:

<mcpPad_row_0_column_0 histLevel="2">

We defined not only histLevel property, but also some parameters of the 2D histogram. Especially the first two lines are very important. The tag <xTdcAdcHistBins> defines number of bins in x axis and similar is <yTdcAdcHistBins>, but for y axis. If these two variables are not defined, 2D histogram will have default values which are 4096 x 4096 bins! It can be too large especially if more that one 2D histogram will be created. Because the histLevel is "2" also a histogram of fitted slices will be created. We defined that it will draw slices from 0 to 350 (tags <slicesYBinFrom> and <slicesYBinTo>), all bins will be fitted, even empty (<slicesYCuts>0</slicesYCuts>) and two adjacent bins will be grouped before fitting (<slicesYconsecBins>2</slicesYconsecBins>). In y axis the fit will be done on the whole range (variables <slicesYFitFrom> and <slicesYFitTo>).

The whole file is then:

<?xml version="1.0"?>

<includeDirectory>/u2/juhe/endstationA/Data_Connections_Repository</includeDirectory>

<include>2005-05-06_64_channels_across_all_slots.xml</include>

<rootDirectory>/u2/juhe/endstationA</rootDirectory>

<rootFiles>testrun_for_tutorial</rootFiles>

<delta>

</delta>

</russMcp>

</quantacom>

</startCnt2>

</leadGlass>

</slot2>

</slot3>

</slot4>

</slot5>

</slot6>

<mcpPad_row_0_column_0 histLevel="2">

</ADC>

</TDC>

</mcpPad_row_0_column_0>

</startCnt1>

</endstationA>

</AnalyzeEndstationA>

When the file is created, we can run the analysis. The command will be:

./analyseCRT -s tutorial.xml -runapp -fitoff

Switch -runapp will cause that the analysis will stay in Root application mode when finished and during the run the analysis can be controlled through window which will appear (see 4.2). User can then zoom histograms, save pictures into files and so on. (see Root documentation for details). Switch
-fitoff turns off fitting of resulting histograms. Step of the simple viewing data is done.

4.2AnalyzeCRT Control window

If switch -runapp is applied the analyze control GUI window will be opened (Fig. 1). It possesses histograms plotting and the analysis run.

Fig. 1Analysis run control window

Fig. 2ROOT application exit button

When the “Run ROOT application” button is pressed all histograms canvases go into the user interactive mode. User can change ranges of histograms, make manual fits etc. If the “Exit ROOT application mode” button is pressed (Fig. 2) then the code continues analysis of further events. Note: always use this button to exit the application mode. The only exception is if the whole analysis is over and it goes to the application mode without showing the “Exit ROOT application mode” button. In this case the analysis can be closed by selecting menu “File” -> ”Quit ROOT”. Try to avoid killing the application by pressing ctrl-c or sending “kill” signal. The application has opened system messaging queues which will not be deleted from the system automatically (see 5.16 and Linux manual page for ipcs command).

4.3Ignoring devices/modules

When some module is disconnected or when is giving "wrong" data which can cause event rejection, it is possible to ignore such device. It is as simple as defining property ignoreDev="1" in the appropriate module tag. i.e.:

</russMcp>

Parameter ignoreDev also helps to speed up analysis by switching off unnecessary modules. Note: the ignoreDev parameter of superior object is decisive. I.e. it is not possible to set ignoreDev=”1” for the whole MCP and then set ignoreDev=”0” only for one pad. The pad will be still ignored. This logic is used due to the increase of analysis speed. If the only one pad has to be chosen then ignoreDev=”1” must be set for all pads except the one in the MCP.

4.4Defining cuts

Sometimes it is necessary to "get rid" of events which has some parameter out of given range. It is possible to define ranges using tag dcLoLimit and dcUpLimit for appropriate ADC or TDC module. We can show it again on example of start counter 1 and it is pad 00.

<mcpPad_row_0_column_0>

</ADC>

</TDC>

</mcpPad_row_0_column_0>

</startCnt1>

Now will be in this module rejected all events with ADC value smaller than 100 and bigger than 300.

4.5Advanced histogram plotting control

Parameter histLevel is not the only way how to control which histograms will be plotted. There is also another possibility to choose particular types of histograms to be plotted. This can be done using tag <histTypeID_X> where X is from 0 to 9. Types of histograms which can be set are in the table below (this list was extracted from BaseTH.h C++ header file).

DC_SPECTRUM_RAW_HIST_TYPE 100

DC_SPECTRUM_CORR_HIST_TYPE 200

DC_SPECTRUM_LOCALCORR_HIST_TYPE 300

DC_SPECTRUM_REJECT_HIST_TYPE 400

TIME_GRAPH_RAW_HIST_TYPE 500

TIME_GRAPH_CORR_HIST_TYPE 600

TIME_GRAPH_LOCALCORR_HIST_TYPE 700

TIME_GRAPH_REJECT_HIST_TYPE 800

TIME_GRAPH_SIGMA_HIST_TYPE 900

CHARGE_GRAPH_RAW_HIST_TYPE 1000

CHARGE_GRAPH_CORR_HIST_TYPE 1100

CHARGE_GRAPH_LOCALCORR_HIST_TYPE 1200

CHARGE_GRAPH_REJECT_HIST_TYPE 1300

ADCTDC_SPECTRUM_RAW_HIST_TYPE 1400

ADCTDC_SPECTRUM_CORR_HIST_TYPE 1500

CROSSTALK_SPECTRUM_HIST_TYPE 1600

CROSSTALK_DELTA_CORR_HIST_TYPE 1700

CROSSTALK_MAP_HIST_TYPE 1800

CROSSTALK_AFFMAP_HIST_TYPE 1900

MCP_RAW_HIT_MAP_HIST_TYPE 2000

MCP_CORR_HIT_MAP_HIST_TYPE 2100

MCP_MEAN_TDC_RAW_SPCT_HIST_TYPE2200

MCP_MEAN_TDC_CORR_SPCT_HIST_TYPE2300

MCP_MEAN_TDC_REJCT_SPCT_HIST_TYPE2400

MCP_MEDIAN_CORR_SPCT_HIST_TYPE2500

MCP_MULTIHIT_RAW_SPCT_HIST_TYPE2600

MCP_MULTIHIT_CORR_SPCT_HIST_TYPE2700

MCP_CROSSFREQUENCY_SPCT_HIST_TYPE2800

MCP_MEAN_ADC_RAW_SPCT_HIST_TYPE2900

MCP_MEAN_ADC_CORR_SPCT_HIST_TYPE3000

MCP_MEAN_ADC_REJCT_SPCT_HIST_TYPE3100

MCP_ADC_SUM_SPCT_HIST_TYPE3200

HODO_PROFILE_RAW_HIST_TYPE3300

HODO_PROFILE_CORR_HIST_TYPE3400

HODO_MAP_RAW_HIST_TYPE3500

HODO_MAP_CORR_HIST_TYPE3600

CHERENKOV_RAW_HIST_TYPE3700

CHERENKOV_CORR_HIST_TYPE3800

CHERENKOV_REJECT_HIST_TYPE3900

Parameter <histTypeID_X> is always used in combination with histLevel. Parameter histLevel must be always high enough to cover histogram types chosen by tags <histTypeID_X>. For instance, if we want to plot corrected spectrum we have to define <histTypeID_0200/histTypeID_0 and at leasthistLevel=”2”. Histograms types can be defined for each module (<histTypeID_X>) or globally using gHistTypeID_X>. This global tag must be placed “above” all modules, i.e. immediately between tags <AnalyzeEndstationA>...</AnalyzeEndstationA>. Next tags which control histograms or layout are:

How windows will be divided into canvases for histograms:

Global settings for number of histogram bins and histogram ranges:

Global settings for histogram zoom ranges (x axes):

Global settings for histogram zoom ranges (y or z axes):

Histogram ranges can be defined also for particular module using:

Modules based on MCP and PMT[1] can have defined property crossOff which switch off the mean blue dash cross on 2D histograms (ADC/TDC dependencies).

4.6Cherenkov ring plotting

Note: to be able to draw the Cherenkov ring appropriate 2D hit maps (raw/corrected/rejected) for each slot must be switched on!

4.7Creating ADC/TDC table correction file

We will create the basic ADC/TDC correction in this chapter. The easiest (and in many cases most efficient) correction of TDC data by pulse height is based on table, which contains correction factor (offset) for each bin in ADC spectrum. We will show this algorithm again on startCnt1.

It is necessary to add a line defining a file where the correction factors will be stored. This is done by adding tag: <tableAdcCorrFileName create="1"> for each pad and TDC which we want to correct on ADC. The XML file for start counter 1 will be then:

<?xml version="1.0"?>

<includeDirectory>/u2/juhe/endstationA/Data_Connections_Repository</includeDirectory>

<include>2005-05-06_64_channels_across_all_slots.xml</include>

<rootDirectory>/u2/juhe/endstationA</rootDirectory>

<rootFiles>testrun_20050401_1648_1000000</rootFiles>

<endstationA>Data for analyzes

<delta<tempCoef>1.0</tempCoef</delta>

<mcpPad_row_0_column_0 histLevel="3" whichSliceFit="0">

</ADC>

correction.adcCorr</tableAdcCorrFileName>

</TDC>

</mcpPad_row_0_column_0>

<mcpPad_row_0_column_1 histLevel="0">

</mcpPad_row_0_column_1>

<mcpPad_row_1_column_0 histLevel="0">

</mcpPad_row_1_column_0>

<mcpPad_row_1_column_1 histLevel="0">

</mcpPad_row_1_column_1>

</startCnt1>

</quantacom>

</startCnt2>

</slot3>

</slot4>

</slot5>

</slot6>

</russMcp>

</leadGlass>

</endstationA>

</AnalyzeEndstationA>

In this example we have defined the correction only for pad 0 0, i.e. first pad. The same line must be added for all pads which have to be corrected. We have also already defined ranges, where the table will be created - tags from xTdcAdcHistBins to slicesYFitTo. Notice, that there are also two new properties defined in the tag <startCnt1>. The first property is histLevel="2" - it defines that 2D scatter histogram will be created as well as histogram of slices will be plotted. The property whichSliceFit="0" defines that slices will not be fitted, but mean value and RMS will be used instead. Other possible options for whichSliceFit are fits using single Gaussian (="1") and double Gaussian (="2"). Gif pictures of each slice and fit in each slice are also created for control if fits in each slice are correct (parameter –detail on command line).

Now run the analysis as it was mentioned in the previous chapter:

./analyseCRT -s tutorial.xml -runapp -detail

Parameter -detail will switch on gif files for each slice. It is necessary to determine ranges in which the slices are created - both on ADC a then also TDC side. This is even more important if data are noisy. Check results when the analysis finish. Especially check the gif files created for each slice of ADC/TDC 2D histogram. This step is necessary to be sure that the correction table was created properly. To use the correction table just change property create="1" of tag tableAdcCorrFileName to create="0". Since this moment the table will not be created, but used. The same procedure can be done for any PMT, which has connected both ADC and TDC. Creating of correction table is done.