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, the following types and colors are used for different types of text:

example of XML code
example of source code
Linux console command

2Installation (plus advice on using CVS)

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

To install the DIRC R&D analysis software package you need a UNIX directory with at least 40MB of available disk space. Then type:

setenv CVSROOT /afs/slac.stanford.edu/u/eb/jochen/Babar

cvs co CRTanalysis

This will create a subdirectory called CRTanalysis with several subdirectories. You can view the code with kdeveloper by typing

cd CRTanalysis

kdevelop crtanalysis.kdevprj

Okay, that's it, now we can try to run some CRT analysis code.

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 compile. 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 &

2.3Modifying an Existing File

If you make changes to the code in this package and wish to commit those changes back, be sure to test all changes before committing anything to CVS!. Once you are satisfied that the changes do not break the system, you must first make certain all files in your directory are concurrent with the HEAD of CVS. Enter the directory you wish to update and issue the following command:

cvs update –A

This will reset any sticky tags. Next do the following:

Once you are satisfied with your changes, you must bring the CVS repository up-to-date with your changes. This is accomplished by committing changes as follows:

cvs commit

which commits the entire package, or

cvs commit filename

where filename is the file which you wish to commit.

2.4Adding a New File

To add a new file to the existing repository, simply create the file and issue the following

command:

cvs add filename

where filename is the file which you have created. This will make an entry in CVS for your file. You must still commit this file to the repository in order to make its addition permanent. Commitment of a file is done using the following command:

cvs commit

which commits the entire package, or

cvs commit filename

where filename is the file which you wish to commit.

The cvs commitwill commit all changes to the HEAD of the CRTAnalysis CVS archive. Next, you will want to tag the changes so that they can be retrieved after a later revision of the HEAD, to do so simply issue:

cvs tag <tag string>

where <tag string> is an identifier (no spaces!) that uniquely tags this set of changes to the code. For instance, if your initials are abc:

cvs tag abc-20July2005

This is particularly useful if you need to revert back to an earlier version of the code, as there is always a snapshot of a frozen version available.

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 (GUI controlled).

-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 setup in 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 a ROOT data file created from the ASCII file that is written by the data acquisition in Endstation A. The conversion 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 in detail. The details will be explained later in the following chapters. 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 Endstation A. 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>

The <include> tags contains description of connections between the analysis modules and the branches (channels) in the root file. Then we define the directory which contains the ROOT data file(s) and data files (divided by a “,” without the extender “.root”).

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

<rootFiles>testrun_for_tutorial</rootFiles>

Now we define the events on which 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 of the 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. The first two lines are very important, the tag <xTdcAdcHistBins> defines the number of bins in x axis and similarly <yTdcAdcHistBins> for the 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", a histogram of fitted slices will also be created. We have defined that it will draw slices from 0 to 350 (using the tags <slicesYBinFrom> and <slicesYBinTo>), all bins will be fitted, even empty ones (defined by <slicesYCuts>0</slicesYCuts>), also two adjacent bins will be grouped before fitting (this is defined by the tags <slicesYconsecBins>2</slicesYconsecBins>). In the y axis, the fit will be done on the whole range (variables <slicesYFitFrom> and <slicesYFitTo>).

The entire file then becomes:

<?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 the analysis to stay in Root application mode when finished, and during the run the analysis can be controlled through the GUI which will appear (see 4.2). The user can then zoom into histograms, save pictures into files and so on. (see Root documentation for details). The switch
-fitoff turns off the fitting of the resulting histograms. The step of the simple viewing data is now done.

4.2AnalyzeCRT Control window

If the 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. The user can change the 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>

The parameter ignoreDev also helps to speed up the 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 to increase the 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 have some parameter out of a given range. It is possible to define ranges using the tags dcLoLimit and dcUpLimit, for the appropriate ADC or TDC module. An example is shown of start counter 1 and its pad 00.

<mcpPad_row_0_column_0>

</ADC>

</TDC>

</mcpPad_row_0_column_0>

</startCnt1>

Now this module rejects all events with ADC value smaller than 100 and bigger than 300.

4.5Advanced histogram plotting control

The parameter histLevel is not the only 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 the tag <histTypeID_X> where X is from 0 to 9. The 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_TYPE1000

CHARGE_GRAPH_CORR_HIST_TYPE1100

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_TYPE1600

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_RAW_ADC_HIT_MAP_HIST_TYPE 2010

MCP_CORR_ADC_HIT_MAP_HIST_TYPE 2110

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

CHERENKOV_ADC_RAW_HIST_TYPE3750

CHERENKOV_ADC_CORR_HIST_TYPE3850

CHERENKOV_ADC_REJECT_HIST_TYPE3950

HODO_MULTIHIT_RAW_SPCT_HIST_TYPE4000

HODO_MULTIHIT_CORR_SPCT_HIST_TYPE4100

DIRC_MEAN_TDC_RAW_SPCT_HIST_TYPE 4200

DIRC_MEAN_TDC_CORR_SPCT_HIST_TYPE4300

DIRC_MEAN_TDC_REJCT_SPCT_HIST_TYPE 4400//not used

DIRC_MEAN_ADC_RAW_SPCT_HIST_TYPE4200

DIRC_MEAN_ADC_CORR_SPCT_HIST_TYPE4600

DIRC_MEAN_ADC_REJCT_SPCT_HIST_TYPE 4700//not used

DIRC_MEDIAN_CORR_SPCT_HIST_TYPE4800

DIRC_MEAN_TDC_TIME_GRAPH_RAW_HIST_TYPE 4900

DIRC_MEAN_TDC_TIME_GRAPH_CORR_HIST_TYPE 5000

DIRC_MEAN_TDC_TIME_GRAPH_REJECT_HIST_TYPE 5100

The parameter <histTypeID_X> is always used in combination with histLevel. The parameter histLevel must be always high enough to cover histogram types chosen by the tags <histTypeID_X>. For instance, if we want to plot the corrected spectrum we have to define <histTypeID_0>200</histTypeID_0> and at least histLevel=”2”. Histogram 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 the tags <AnalyzeEndstationA>...</AnalyzeEndstationA>. The next tags which control histograms or the layout are:

How windows will be divided into canvases for histograms: