CMS HGCal Testbeam Analysis Framework

=============================================

• This new branch is to be used for analysing data from 2017 test beam.
• The code runs with the one layer data, and will need (major) updates when we will have more layers.
• This readme assumes one layer data.
• The README.md in other branches contain useful information about 2016 test beam analysis which might be still useful.

Content

• Download the code
• Location of data files
• Content of the code
• New data types
• DWC related plugins
• Possibly helpful plugins
• Exemplary analyzers
• Running the code
• More information

Download the code

• CMSSW Version 8.0.1

scram project ${RELEASE}
cd ${RELEASE}/src/
cmsenv
git cms-init
git clone git@github.com:CMS-HGCAL/TestBeam.git HGCal/
git checkout CERN_TestBeam_2017
git pull
scram b -j16

Location of data files

Raw data files

• The RAW files can be found in /afs/cern.ch/work/b/barneyd/public/data_May_2017/disk2_2TB/eudaq_data.

Electronics map

• The EMAP for this run map_CERN_Hexaboard_OneLayers_May2017.txt can be found in CondObjects/data

Content of the code

• The data are read using the EDProducer in RawToDigi/plugins/HGCalTBRawDataSource.cc(.h). The data are rearranged to recreate the Skiroc2CMS raw data map (Skiroc2CMS information: https://cms-docdb.cern.ch/cgi-bin/DocDB/ShowDocument?docid=13121). The object storing those data is defined in DataFormats/interface/HGCalTBSkiroc2CMS.h. This producer is creating a collection of these objects. With the one layer data, the size of the collection should be 4 (4 Skiroc2CMS chips per layer).
• An example of EDAnalyzer, reading the collection of HGCalTBSkirocCMS is available in RawToDigi/plugins/RawDataPlotter.cc. It creates 2 .txt files, containing high (resp. low) gain pedestal mean and standard deviation for each channel, for each SCA. It also produces a root file output with basic histograms:
  • high/low gain ADC distribution for all channels for all SCA
  • high/low gain as a function of the time for all channels
  • plots of mean and standard deviation of ADC counts using hexagonal geometry.
  • there is also an option to set to True to create event displays (One display per time sample). When the event display option is set, the code is slown down quite a lot, so my advice is to run only on few events.
• Another EDProducer RawToDigi/plugins/HGCalTBRawHitProducer.cc(.h) transforms the data format (HGCalTBSkiroc2CMS) into a digi format defined in DataFormats/interface/HGCalTBRawHit.h and stores collection these raw hits (the size of the collection should correspond to the number of channels = 4*64 ). An option is also available to perform the pedestal subtraction before the raw hit creation. It is mandatory to have the pedestal subtraction here, since it is done for each SCA.
• The EDAnalyzer RawToDigi/plugins/RawHitPlotter.cc analyzes the collection of HGCalTBRawHit. It creates the same kind of plots as in RawDataPlotter (high/low gain ADC distribution for each time sample, versus time sample, event display). An option is available to run with common mode evaluation and subtraction.
• The EDAnalyzer RawToDigi/plugins/PulseShapePlotter reads the collection of HGCalTBRawHit, perform the common mode subtraction. It creates for each event, for each channel two histograms (high/low gain) of ADC counts as a function of the time. When signals are high enough, one should be able to see pulse shapes.
• To run the 2 previous analyzers (RawHitPlotter and PulseShapePlotter) with the common mode option, the pedestal subtraction option in the raw hit producer should be set.
• The rechit producer in Reco/plugins/HGCalTBRecHitProducer.cc(.h) transforms the raw hit into the HGCalTBRecHit format and save collection of rechits. It assumes the pedestal subtraction is already done and it performs the common mode subtraction (one common mode per chip). A first version of this producer use only the time sample 3 for the energy.
• The EDAnalyzer Reco/plugins/RecHitPlotter.cc reads the rechit collection and again produces basic plots.

Running the code

• run2017_cfg.py is the script to run to start the analysis. This script is less complex (and less convenient) than the test_cfg.py in other branches. The chain sequence tool is absent, and will be re-implemented later.
• All the EDProducer and EDAnalyzer (described above) are loaded with default parameters. Some paths might need modification depending on the user.
• 3 different cms.Path are pre-filled (2 are actually commented). One of them allows to run the RawDataPlotter plugin analysis, the 2nd runs the HGCalTBRawHitProducer and the RawHitPlotter analyzer and the last one runs the PulseShapePlotter analyzer. These 3 cms.Path creates 2 root files:
  • cmsswEvents.root which contains the cmssw objects (HGCalTBSkiroc2CMS,HGCalTBRawHit). Running the following command should return the list of cmssw collections in the events:edmDumpEventContent cmsswEvents.root
  • HexaOutput_${runnumber}.root contains the analysis output histograms

New data types

RunData

• Defined in DataFormats/interface/HGCalTBRunData.h.
• An object that characterises a given event in terms of event numbers, trigger counters - independent of any event cuts if these variables are set at the unpacking stage -, run numbers, setup configurations ("1"=July 2017 TB - "4"=October 2017 with 20 layers), energy plus particle ID of the incident particles, and run types (pedestal, beam, sim.).

    int run; //run number to which the event belongs. The edm's run object is always set to 1
    int trigger; //could be assigned to the trigger counter that is stored in the HGCal timing files
    int event; //is assigned to the actual event number starting at 1 for each new run
    int configuration; //1: July TB with 6 layers, 2: September TB with 17 layers, 4: October TB with 20 layers
    double energy; //beam energy
    int pdgID;	//particle ID of the beam particle
    RUNTYPES runType; //possible choices: HGCAL_TB_PEDESTAL, HGCAL_TB_BEAM, HGCAL_TB_SIM

• Arbitrary double and boolean values are assigned as so-called UserRecords. As an example, the time difference [ms] between a synchronised event to the matched event from the HGCal data stream could be stored as such a userrecord.

• The updated HGCalTBRawDataSource plugin is equipped with necessary configurable options to correctly set these quantities at the ORM file unpacking stage and to add them to the edm format.

WireChamberData

• Defined in DataFormats/interface/HGCalTBWireChamberData.h.
• A simple structure that contains reconstructed DWC impact positions (x,y,z).
• Furthermore, lower level TDC data such as the number of received time stamps per DWC (<=4) as well as the averaged time stamp per DWC is stored.
• WireChamberData are instantiated in the HGCalTBWireChamberSource and HGCalTBBeamWireChamberProducer plugins.

HGCalTBDWCTrack

• Defined in DataFormats/interface/HGCalTBDWCTrack.h.

• An object that contains parameters from a straight-line fit using as many DWC measurements as possible in an event.

• Besides the four track parameters (slope and offset for each coordinate) and the quality information in terms of chi2's, the int referenceType indicates which DWCs have contributed to the track:

• referenceType += 1 for DWC E (CERN H2 TB area), or for the only DWC in H6A

• referenceType += 2 for DWC D (CERN H2 TB area)

• referenceType += 4 for DWC A (CERN H2 TB area)

• referenceType += 8 for DWC ext. (CERN H2 TB area)

• Under the provision of layer-distance files (see CondObjects/data/layer_distances_CERN_September_7EELayers_10FHLayers_V0.txt, values are given in mm, beginning EE part is at z=0mm.), the straight line trajectories are evaluated at each layer of the HGCal in the DWCTrackProducer plugin. Its extrapolations can be retrieved through std::pair<double, double> DWCExtrapolation_XY(int layerIndex) afterwards. Note that the layerIndex starts at "1".

DWC related plugins

HGCalTBTimingFileWriter

• Defined in RawToDigi/plugins/HGCalTBTimingFileWriter.cc.
• A plugin that produces timing files similar to the ones created directly in the July 2017 beam test. These files are necessary to synchronise the HGCal data streams offline with e.g. the TDC and AHCal data streams.
• It runs on unpacked ORM files and prints the timing information of the skiroc indexed "0".

HGCalTBWireChamberSource

• Defined in RawToDigi/plugins/HGCalTBWireChamberSource.*. This plugin runs on an arbitrary number of raw TDC files in which the hits from 4x4 TDC channels are stored in TTrees. The mapping to the DWCs is hard-coded. Similarly, the positions of the DWCs along the beam line (z-coordinate) are implemented with hard numbers both for H2 and H6.

• The position reconstruction is based on the time stamp difference and the multiplication by 0.2mm/ns. The TDC time stamp interval to ms is configurable in TDCTriggerTimeStampConversionToMs.

• For the second half of the July2017 TB, all hits are stored. Consequently, more complex reconstruction algorithms making use of the entire collection of received hits (instead of just the first one) could be designed and implemented in a next iteration of this source plugin.

• Furthermore, running this plugin yields one printout per event to ensure the successful synchronisation with the HGCal data stream. Here, the timing file from the HGCalTBTimingFileWriter plugin must be provided for each run. Both event offsets in the HGCal and/or the TDC da