Documentation: CSCTF Mode and Basic Cut Track Analysis Package

Kristin Beck, Summer Student 2008

Zipped files for CSCTF MBC Track Analysis Pack

Contents

1. Introduction
2. Quick Start
1. Installation from the *.zip file
2. Compiling and Running the Code
3. Output Overview
3. Code Recipes
4. Pre-Compiling Options
5. Understanding the Output
6. Outstanding Issues
7. Code Notes
8. Conclusions

Introduction

The CSCTF Mode and Basic Cut Track Analysis Package (CSCTF MBCTAP) is an analysis package designed to check the contents of tracks made by the CSC Track Finder as found in CSC data. In particular, it compares the assigned track modes with their contents and examines cuts Δη and Δφ. The package automatically outputs a few basic statistics for these analyses. The package also comes with a root script, showMBCTPlots, that displays the histograms of the data.

CSCTF MBCTAP was written during summer 2008 by Summer Student Kristin Beck using CMSSW_2_0_7.

[top of page]

Quick Start

Instalation from the *.zip file

The CSCTF MBCTAP is provided here as a *.zip file: [Zipped files for CSCTF MBC Track Analysis Pack]. This zipped package contains the following files:

• CSCTFAnalyzer.cc
• CSCTFAnalyzer.h
• analyzer_dch.cfg
• MBCTAnalyzer.C
• MBCTAnalyzer.h
• compile.sh
• runAnalysis.cpp
• showMBCTPlots

• move into folder .../EventFilter/CSCTFRawToDigi/plugins/:
  • CSCTFAnalyzer.cc
• move into folder .../EventFilter/CSCTFRawToDigi/interface/:
  • CSCTFAnalyzer.h
• move into folder .../EventFilter/CSCTFRawToDigi/test/ (or the directory folder within the CSCTFRawToDigi directory where you will be running over your test files. Please note that within this document, this directory will be referred to as test) :
  • analyzer_dch.cfg
  • MBCTAnalyzer.C
  • MBCTAnalyzer.h
  • compile.sh
  • runAnalysis.cpp
  • showMBCTPlots

[top of page]

Compiling and Running the Code

To compile the code, first make sure you have the appropriate files (see section 2a: Instalation from the *.zip file) and have set up your operating environment within CMSSW. This may be done by running the command eval `scramv1 runtime -csh` in the directory .../EventFilter/CSCTFRawToDigi/. Then, follow the following steps to compile:

1. Compile CSCTFAnalyzer.cc and related files by running the command scramv1 b -r from within the directory .../EventFilter/CSCTFRawToDigi/.
2. Compile MBCTAnalyzer.C by running the command ./compile.sh within the directory .../EventFilter/CSCTFRawToDigi/test/

To run the code, you will first need to choose the files to run over. You can either run over a *.root file saved locally or use one stored on CASTOR. As of the writing of this document, the easiest way to obtain the proper path for data file(s) is to use the DBS data discovery page. These path(s) need to be put into the file analyzer_dch.cfg, which should be in the .../EventFilter/CSCTFRawToDigi/test/ directory. They should be inserted on line 12 within the brackets following untracked vstring fileNames = { as follows:

• For local files: 'file:/absolute file path/file.root'
• For remote (CASTOR) files: '/store/path/file.root' (this entire line is the path copied from DBS)

• For multiple files:
     '/path to file 1/file1.root',
   '/path to file 2/file2.root',
   '/path to file 3/file3.root'

Now that you have edited analyzer_dch.cfg, it's time to run the code.

1. From the directory .../EventFilter/CSCTFRawToDigi/test/ run the command cmsRun analyzer_dch.cfg.
1. There is a lot of output at this stage, which you may want to save for cross checks at a later stage by piping it to a file, for example, cmsRun analyzer_dch.cfg > ! myOutFile.txt.
2. Because it takes so long to run this bit of code, you may want to run this in the background by ending the line with an ampersand (&).
2. Once this code has finished executing, you will have two additional output files, mbctaCodeError.txt and mbcta.root. For information on the output files, see section 2c: Understanding the Output.
1. N.B. If you have broken a single run into multiple jobs, you should rename the output root files so that they have the same base name followed by an increming arabic number starting from 0 (i.e. mbcta.root, mbcta0.root, mbcta1.root, mbcta2.root, mbcta3.root, etc.). Multiple files are not yet supported in the *.C second stage analysis.
3. Run the command ./runAnalysis.exe
4. After this executes, you will have two additional output files, mbctaTextOut_#####.txt and mbctaPlots_#####.root where ##### is the run number for the input data.
5. To display the graphs, run the ROOT script showMBCTPlots by running the command root showMBCTPlots -l. You will be prompted for 3 numbers, which you should enter separated by spaces followed by a carridge return:
   • a choice of graphs to display (0 displays mode error graphs, 1 displays Δη and Δφ graphs, 42 displays both),
   • whether or not to output graphic files (1 is yes, 0 is no)
   • and the run number for the data you're interested in looking at. The run number is used to find the corresponding file mbctaPlots_#####.root.
   For example, to show (and not save) the mode error plots for run 51047, you would type 0 0 51047 after the prompt.

[top of page]

Output Overview

If you run the complete code, there will be several output files and command line outputs. These outputs include (1) information about the program's operation, including error messages pertaining to the program itself, (2) slimmed down data (*.root) files, (3) information about the data processed, including statistics, (4) *.root histograms and (5) graphs.

Of these, the files you will use for checking data are mbctaTextOut_#####.txt, which is output from the second stage of analysis (./runAnalysis.exe), and the graphics files that come out of the final root script (root showMBCTPlots -l).

mbctaTextOut_#####.txt is divided into 3 sections.

• The header includes the run number, information on modes masked and any additional notes you have added for specific mode error analysis (see 4: Pre-Compiling Options for information about how to set this).
• The error messages section includes mode errors and track errors. Mode errors are differences found between expected LCT content of tracks and the actual LCT content of tracks. Mode errors report as two lines, for example:
  ERROR: Mode 6 track with LCTs 1-3- filled. Global LCTs : 1-3- Expected from Mode : 12-- **** expected is not in the track ****
     Track # 0 in Event # 3742778 in Run # 51047
  If the global track contains the tracks that are expected, the output will not include the tag **** expected is not in the track ****, for example:
  ERROR: Mode 15 track with LCTs ---- filled. Global LCTs : 123- Expected from Mode : -23-
     Track # 1 in Event # 3706572 in Run # 51047
  Cut errors are differences found between expected cuts on Δη and Δφ and the quantities found in the data. Cut errors report as two lines, for example:
  ERROR: Delta Eta out of bounds. I have Delta Eta = 7 which is out of our allowed range for mode 8 of [-5, 5].
     Track # 0 in Event # 14579 in Run # 46794 with Global LCTs : -23-
  You may also find LCT error messages in this file, which are reported if/when an LCT is filled when a lower-indexed LCT is not filled. An error of this type generally indicates an error within the analysis code CSCTFAnalyzer.cc and not an error with the data.
• The statistics section includes the following statistics:
  • Mode errors scaled to total in mode is the fraction of a given mode xthat is in error, e.g. (total mode errors in mode x)/(total tracks of mode x).
  • Total mode error fraction is the fraction of all tracks that are in error, e.g. (total errors)/(total tracks).
  • Relative mode occupations is the fraction of all tracks that are in a given mode x, e.g. (total tracks of mode x)/(total tracks).
  • Delta Eta (Delta Phi) Error Counts are the fraction of tracks that are in a given mode with Δη (or Δφ) out of range for that mode. So, for a given mode x, this fraction is (total tracks of mode x with Δη (or Δφ) out of bounds for mode x)/(total tracks of mode x).
  • Number of Delta Eta (Delta Phi) out of bounds is the total number of tracks of any mode that are reporting Δη (or Δφ) out of bounds (based on the maximum and minimum set for their track mode).
  • Total Fraction of (Delta Phi) out of bounds is (Number of trakcs with Δη (or Δφ) out of bounds)/(total number of tracks).
  • Δη and Δφ by mode maximum and minimums are the maximum and minimum values of Δη and Δφ in each mode.
  The first two statistics are reported with and without the mode error mask if a mode mask is set.

There are three graphs that showMBCTPlots automatically outputs (all of these graphs are output when you use option 42 for the choice of graphs):

• MBCTA_Mode_##### displays the total mode occupation, all mode errors, and unsuppressed mode errors. These three histograms are displayed individually with their own scales on the left of the plot and in the same graph with a logarithmic scale to the right. In addition, a histogram of tracks that do not have appropriate mode content in the global tracks is overlayed in the large plot with a hashed fill pattern.
  
• MBCTA_DPhi_##### displays Δφ by mode, calculated by φ2-φ1 (where φ1 and φ2 correspond to the φ values from LCTs in the first and second stations in the track). This canvas contains 16 individual histograms, arranged in order by mode number from left to right, top to bottom. The individual histograms can be accessed within the file mbctaPlots_#####.root.
  
• MBCTA_DEta_##### is the same as MBCTA_DPhi_#####, but with η instead of φ.
  

[*.ppt overview of the graphs]

[top of page]

Code Recipes

The following is what I type into my command line window to run the code. I assume you already have the unzipped files in a directory named csctf-MBCTAP located in .../EventFilter/CSCTFRawToDigi/ and are operating within the directory .../EventFilter/CSCTFRawToDigi/.

Installation
cp csctf-mbctap/CSCTFAnalyzer.cc plugins/.
cp csctf-mbctap/CSCTFAnalyzer.h interface/.
cp csctf-mbctap/analyzer_dch.cfg test/.
cp csctf-mbctap/MBCTAnalyzer.C test/.
cp csctf-mbctap/MBCTAnalyzer.h test/.
cp csctf-mbctap/compile.sh test/.
cp csctf-mbctap/runAnalysis.cpp test/.
cp csctf-mbctap/showMBCTPlots test/.


Compiling
eval `scramv1 runtime -csh`
scramv1 b -r
cd test
cmsRun analyzer_dch.cfg > ! myOutFile.txt &
...when that is done running...
./compile.sh
./runAnalysis.exe


Showing and Saving Graphs
root showMBCTPlots -l
42 1 ##### [return] (where ##### is the run number).

[top of page]

Pre-Compiling Options

This package has been written so that commonly changed parameters are easily accessible before compiling the package. The following options can be set:

• Comment String to start mbctaCodeError.txt output from cmsRun. Edit the string myStringForSaving on line 116 of CSCTFAnalyzer.cc
• Error Suppression from entire modes. Edit the mask modeErrorSuppressionMask on line 16 of MBCTAnalyzer.C. This mask is defined in binary as (0b)fedcba9876543210 where each character stands for the mode with the corresponding name. A zero masks a mode. For example, 0b0111111110111101 (which is 0x7fbd in hexidecimal) masks modes 1, 6 and 15.
• Additional Suppression Notes and Comment String to be included in mbctaTextOut_#####.txt. Edit the string supressionNotes on line 25 of MBCTAnalyzer.C.
• Choice of tracks to use to calculate Δη and Δφ can be chosen on line 28 of MBCTAnalyzer.C. Choices are:
  • 0 difference calculated from just the first two nonempty tracks
  • 1 difference calculated from any two consecutive tracks
  • 2 difference calculated from any combination of tracks
  For example, if we have a mode with LCTs 12-4, 0 would return the difference between the values read from stations 4 and 2, 1 would return 4-2, 2-1 and 2 would return 4-2, 4-1 and 2-1.
• Maximum and minimum values of Δη and Δφ to use to calculate errors with Δη and Δφ are coded on lines 39-42 of MBCTAnalyzer.C. They are in arrays have the values by mode where we have modes given by {0,1,2,3,4,5,6,7,8,9,a,b,c,d,e,f}.
• Masking (or showing) Δη and Δφ errors can be set on lines 44 and 45 of MBCTAnalyzer.C.
• Specific masks for errors should be added to the logic code in MBCTAnalyzer.C on the line that currently reads if (!((modeErrorSuppressionMask & (1 >>csctf_mode-track])) == 0) { //mask here. Refined mode definitions should be added in the if-statement that begins 6 lines before this.
• Scaling on Δη and Δφ graphs. These graphs are actually collections of 16 histograms that display Δη and Δφ by mode. The scale for the collection of graphs can either be the same (equalScalingByMode=kTRUE) or scaled automatically to fit the data in the histogram (equalScalingByMode=kFALSE). This option is set on line 6 of showMBCTPlots.
• Output graphics file type for the graphs produced by showMBCTPlots. The string graphicsType on line 8 of showMBCTPlots determines the file type for output. Options accepted by the command include jpg, eps, ps, pdf, jpg, cxx, xml, png, xpm, svg, tif & root.
• The text of the mode key, which is displayed when the mode error graphs are examined, can be edited by changing the cout statement that begins with cout<<"Mode key: \nMode || Sections Occupied\n... in showMBCTPlots (line 193-195). This should be changed to reflect any specialized mode placement, for example the assignment of low eta tracks to mode 6 with track content other than tracks 1 and 2.

[top of page]

Understanding the Output

For an overview of the analysis output files, see section 2c: Output Overview.

The complete code outputs several output files and command line outputs. These outputs include (1) information about the program's operation, including error messages pertaining to the program itself, (2) slimmed down data (*.root) files, (3) information about the data processed, including statistics, (4) *.root histograms and (5) graphs. We will go through the outputs file-by-file.

• out is the file that runtime data is piped to from the command cmsRun analyzer_dch.cfg > out. This file contains error logs from CMSSW and descriptions of the events that have been unpacked. If you have edited CSCTFAnalyzer.cc to include cout statements for debugging, you will find them in this file.
• mbctaCodeError.txt is a file that contains error messages related the size of the arrays used to store global LCTs and attempts to overwrite array elements that have already been written (usually due to an indexing error). These messages correspond to either the global LCTs (error message reads ...an LCT with an ID more than..., corresponds to gbl_station_lct) or track LCTs (error message reads ...a track LCT..., gbl_phi_t and gbl_eta_t)
• mbcta.root is the *.root tree that contains the data we need from the entire data file for analyzing the track content, mode and Δη and Δφ cuts.
• mbctaTextOut_#####.txt contains error messages from checking track content against track mode and statistics. For a complete description, see section 2c: Output Overview.
• mbctaPlots_#####.root is the *.root tree that contains histograms produced by analysis. If you want to view, for example, a single histogram from the Δη or Δφ by mode graphs, one way of accessing it would be to open this file using the TBrowser in root.
• Image files CSCTF_Mode_#####, DEtaByMode_##### and DPhiByMode_##### display the histograms of the data in a compact form that can be used for presentations. For a complete description, see section 2c: Output Overview.

[top of page]

Outstanding Issues

• Problems
• Multiple counting showing up in tracks with more than 2 LCTs
• Missing Functionality
• There is no functionality built in for using information from DT tracks (mode checking, η and φ).
• Support for multiple file documents after first stage of analysis in MBCTAnalyzer.C
• More sophisticated logic for selecting which LCTs to compare in the calculation of Δη and Δφ that more closely resembles the logic actually used in the track finder.
• Parameter Checks
• Check special cases for mode 6 tracks (namely, different filling with low η and/or low φ)
• Check scaling factor for η from LUTs in MBCTAnalyzer.C
• Potential unpacker (or earlier) errors
• Mode 15 tracks appear without any associated LCTs, although the related LCTs are in the event.
• Mode 6 track with LCTs 1-3-, not 12--, including in event data (event 3742778 in run 51047).
• Check to make sure that the new unpacker (on machines other than Khristian's computer) doesn't see empty tracks, tracks with partial filling, etc.
• 1% events over expected cut in Δη (run 46794)

[top of page]

Code Notes

CSCTFAnalyzer.cc and CSCTFAnalyzer.h

This code is the basic analyzer that interacts with CMSSW to extract data from the massive *.root data files. This code extracts data from both the global event LCTs and the track LCTs. The areas where this extraction takes place are clearly marked.

If any errors show up in mbctaCodeError.txt that say that an upper limit needs to be updated, this means that the corresponding arrays for variables in either the global LCTs ("...an LCT with an ID more than...", corresponds to gbl_station_lct) or track LCTs ("...a track LCT...", gbl_phi_t and gbl_eta_t)

analyzer_dch.cfg

This is the configuration file for CMSSW's cmsRun. The source path to the original *.root data file for analysis is entered here.

showMBCTPlots

This root script is responsible for the display of the histograms. It is responsible for the way the histograms are displayed and graphics output.

MBCTAnalyzer.C and MBCTAnalyzer.h

These *.C and *.h files are responsible for the majority of the analysis work that the analysis package does. They build histograms, calculate Δη and Δφ and compare track content to assigned mode.

compile.sh

Instructions for compiling runAnalysis.cpp and thus how to access the functionality of MBCTAnalyzer.C

runAnalysis.cpp

Instructions for how to use the codebits from MBCTAnalyzer.C; this is what is actually compiled and run.

[top of page]

Conclusions

Best of luck using this analysis package; if you have any questions, please do not hesitate to contact me [Kristin Beck's email].

[top of page]

Last updated: 15 August, 2008