Root event structure from H2 event reconstruction 
-------------------------------------------------------
  (Initial version:  S.Kunori/J.Damgov   01-08-2002)

   S.Kunori (kunori@fnal.gov), J.Damgov (jdamgov@fnal.gov)  
   V.Ladygin (ladygin@sunhe.jinr.ru)

Last update:  S.Kunori     16-Sep-2002     12:40pm (CERN)

This verstin (11a) was used by shifters for monitoring data
quality on 13th-18th of September.

The gain factor (i.e. QIE code to GeV conversion) is only valid
for runs after RM4-RM8 swap in September.

(This file is  ~ana/kunori/releases/v11a/RecoH2TB.doc)

Useful Web paes:
----------------
http://cms-testbeamh2.web.cern.ch/cms-testbeamh2/
         - 2002 HCAL H2 Test Beam Home page

http://flywheel.princeton.edu/~jmmans/HTBDAQ_data/
         - description of DAQ ROOT file and access mthods.

http://www-pat.fnal.gov/root/
         - See slides from FNAL ROOT tutorial, day 1,2,3.
           "C++ Basic for ROOT users" is a good starting point
           for C++ beginers.

http://root.cern.ch/
         - ROOT home page.  "Tutorial" and "How to" are helpful
           for beginers. "Reference Guide" has Class definition
           in html format.  "User's Guide"- you may want to have
           a printed version.

http://home.fnal.gov/~kunori/cms/tb2002
         - Kunori's page on tb2002.

Index:
   [1] ROOT Tree description:
   [2] Installation.
   [3] Creation of Reco-ROOT file.
   [4] Analysis of Reco-ROOT file.
   [5] Some Information
      5.1 conversion of QIE code to Charge used in "reco"
   [6] Examples of scripts.
   [7] History


///////////////////////////////////////////////////////////////////////////

[1] ROOT Tree description:

*******************
* Tree name: RECO *   Top level tree.
*******************

   (i) reco_vers -- reconstruction program version number   (not filled yet)

   (i) run      -- run number    
   (i) spill    -- spill number 
   (i) event    -- event number  

   (i) ninfo    -- number of information objects (=1,  if exists)

   (i) ntrig    -- number of Trigger objects (=1, if exist)
   (i) nwc      -- number of Wire Chamber objects (=1, if exist)
   (i) nphase   -- number of Phase objects

   (i) nhc       -- number of HCAL objects (=145, if exist)                   
   (i) nec       -- number of ECAL objects (=50, if exist)
   (i) ntiming   -- number of Timing objects (=1, if exist)

   (i) ne1x1     -- number of ECAL 1x1 cluster objects. (=1, if exist)
   (i) ne3x3     -- number of ECAL 3x3 cluster objects. (=1, if exist)
   (i) ne5x5     -- number of ECAL 5x5 cluster objects. (=1, if exist)

   (i) nh1x1     -- number of HCAL 1x1 cluster objects. (=1, if exist)
   (i) nh3x3     -- number of HCAL 3x3 cluster objects. (=1, if exist)
   (i) nh5x5     -- number of HCAL 5x5 cluster objects. (=1, if exist)
   (i) nh1x2     -- number of HCAL 1x2 cluster objects. (=1, if exist)
                        //for crack effects studies
   (i) nhl0      -- number of HCAL l0 objects.  (=1, if exist) 
                        //for L0 layer studies.

   (i) nho1x1    -- number of HO 1x1 cluster formed around h1x1.
   (i) nho3x3    -- number of HO 3x3 cluster formed around h1x1.
   (i) hhomax    -- number of HO 1x1 cluster which has the largest signal within HO.


********************
* Reco information *
********************

   (i) info[0].reco_vers  - Version number of this reconstruction program.
   (i) info[0].l0         - 0= no layer0,   1=layer0 (August)
   (i) inho[0].ho         - 0= no HO,  1=HO.
   (i) info[0].ecped      - EC pedestal subtraction method.  (to be defined)
   (i) info[0].hcped      - HC pedstal subtraction method.
                              0=no dubtraction,  -1=pedestal file
                              1=calculated in same event (dynamical subtraction)
                              2=calculated in the same run.
   (i) info[0].ped_nts   - the number of time slices used for pedestal calculation.
   (i) info[0].ped_nevt  - the number of events used for pedestal calculation. 
   (i) info[0].ts_low    - hc time slice number (low end) for energy extraction
   (i) info[0].ts_high   - hc time slice number (high end) for energy extraction
   (f) info[0].hcpedall  - sum of all hc pedstals / 144
   (f) info[0].hcpedphi[1:8]   - sum of hc pedestals in phi slice /18

   
***********************
* Trigger data object *
***********************

   This has unpacked trigger bits.

   (i) trig[0].beam
   (i) trig[0].fake
   (i) trig[0].s2req
   (i) trig[0].s3req
   (i) trig[0].muveto
   (i) trig[0].psveto
   (i) trig[0].calib
   (i) trig[0].pshit
   (i) trig[0].s2hit
   (i) trig[0].s3hit
   (i) trig[0].muhit
   (i) trig[0].calib1
   (i) trig[0].calib2
   (i) trig[0].calib3
   (i) trig[0].calib4
   (i) trig[0].ped

   (i) trig[0].ec_post       // QDC value from ECAL commission
   (i) trig[0].ec_muon      // QDC value from ECAL commission

    Note (a):  Index "[0]" may be omitted in most of use in interactive
               analysis.

*****************************
* Wire Chamber data objects *
*****************************

   (i) wc.nx1       -- number of hits in wc1-x 
   (i) wc.ny1       -- number of hits in wc1-y
   (i) wc.nx2       -- number of hits in wc2-x
   (i) wc.ny2       -- number of hits in wc2-y
   (f) wc.x1[50]    -- X position for chamber 1.
   (f) wc.y1[50]    -- Y position for chamber 1.
   (f) wc.x2[50]    -- X position for chamber 2.
   (f) wc.y2[50]    -- Y position for chamber 2.

*********************
* Phase data object *
*********************

   (i) phase[0].phase   -- raw TDC word from the phase measurement channel.
   (i) phase[0].t0      -- raw TDC word from the T0 measurement channel.
   (i) phase[0].clock   -- raw TDC word from the Clock measurement channel.
   (i) phase[0].scint   -- raw TDC word from a Scintillator measurement channel

********************
* HCAL data object *
********************

   (i) hc[i].id     -- sequential ID number. (i=1-144 is valid. 0 for dummy)
                       i=1 for (eta,phi)=(1,1), i=18 for (16b,1)
                       i=127 for (1,8), and     i=144 for (16b,8).
   (f) hc[i].eta    -- eta index.  Valid range is 1.0-16.0.
   (f) hc[i].phi    -- phi index   Valid range is 1.0-8.0.
   (f) hc[i].htr    -- HTR card slot number.
   (f) hc[i].chan   -- HTR card channel number.  
   (f) hc[i].adc[j] -- Linearlized ADC counts for j-th time slice. (j=0-19).
                       Pedestal is subtracted.
   (f) hc[i].ped    -- padestal value used for the subtraction (in adc count).
   (f) hc[i].pedrms -- rms of pedestals.                                     
   (f) hc[i].gain   -- gain factor for adc-to-GeV conversion.
   (i) hc[i].raw[j] -- raw data from DAQ. (originally 16bits word)
   (i) hc[i].tsmax  -- Time slice number which has the largest ADC value
                       in this channel. Note that the largest one in
                       event is reported in "Timing object".
   (f) hc[i].adcmax -- largest ADC count in this channel.

   -- methods --
   (i) hc[i].getCapid(j)   -- capid        for j-th time slice.
   (i) hc[i].getER(j)      -- error flag
   (i) hc[i].getDV(j)      -- data validity
   (f) hc[i].getEsum(-j,k) -- sum of ADC counts from -j time slice
                              to +k time slice around max time slice.

********************
* ECAL data object *
********************

   (i) ec[i].id     -- sequential ID number. (i=1-49 is valid. 0 for dummy)
                       i=1 for (eta,phi)=(-3,-3), i=7 for (3,-3)
                       i=43 for (-3,+3), and     i=49 for (3,3).

   (f) ec[i].eta    -- eta index.   Valid range is -3 to +3.
   (f) ec[i].phi    -- phi index.   Valid range is -3 to +3.
   (f) ec[i].adc    -- ADC count. (pedestal subtracted)
   (f) ec[i].ped    -- pedestal value used for subtraction.
   (f) ec[i].pedrms -- rms of pedestal
   (f) ec[i].gain   -- gain factor for adc-to-GeV conversion.


*****************
* Timing object *    
*****************

   (i) timing[0].hcid   -- id of HCAL channel which has the largest
                           energy in event.  Valid velue is 1-144.
   (f) timing[0].eta    --
   (f) timing[0].phi    --
   (f) timing[0].ts0    -- time slice number with the largest signal
   (f) timing[0].ts0t0  -- tmax-t0  in 30ns unit
   (f) timing[0].adcmax -- largest ADC counts in event. (linearlized)


******************************
* ECAL energy cluster object *
******************************
   
   *** 1x1 cluster ***
   (f) e1x1[0].eta   - eta of crystal with the largest ADC count.
   (f) e1x1[0].phi   - phi of crystal with the largest ADC count.
   (f) e1x1[0].e     - energy in GeV in crystal with the largest ADC count.
   (i) e1x1[0].ecseq - sequential id number of crystal with the largest ADC count.
   (f) e1x1[0].ectot - total energy in GeV for 7x7 crystals.

   *** 3x3 cluster ***
   (f) e3x3[0].eta   - eta of crystal with the largest ADC count.
   (f) e3x3[0].phi   - phi of crystal with the largest ADC count.
   (f) e3x3[0].e     - energy in GeV in 3x3 crystals.

   *** 5x5 cluster ***
   (f) e5x5[0].eta   - eta of crystal with the largest ADC count.
   (f) e5x5[0].phi   - phi of crystal with the largest ADC count.
   (f) e5x5[0].e     - energy in GeV in 5x5 crystals.

******************************
* HCAL energy cluster object *
******************************
   
   *** 1x1 cluster ***
   (f) h1x1[0].eta   - eta of tower with the largest ADC count.
   (f) h1x1[0].phi   - phi of tower with the largest ADC count.
   (f) h1x1[0].e     - energy in GeV in tower with the largest ADC count.
   (f) h1x1[0].adc   - linearized ADC counts  (pedestal subtracted)
   (f) h1x1[0].ped   - pedestal
   (f) h1x1[0].gain  - gain factor
   (i) h1x1[0].hcid  - sequential id number of hc object with the largest ADC count.

   *** 3x3 cluster ***
   (f) h3x3[0].eta   - eta of tower with the largest ADC count.
   (f) h3x3[0].phi   - phi of tower with the largest ADC count.
   (f) h3x3[0].e     - energy in GeV in 3x3 HB tower.

   *** 5x5 cluster ***
   (f) h5x5[0].eta   - eta of tower with the largest ADC count.
   (f) h5x5[0].phi   - phi of tower with the largest ADC count.
   (f) h5x5[0].e     - energy in GeV in 5x5 crystals.

   *** 1x2 cluster = tower with max ADC+ 
   *** tower with the highest ADC  trough 8 nearest  towers ***
   *** FOR CRACK EFFECTS STUDIES ***
   (f) h1x2[0].eta   - averaged eta for 2 towers.
   (f) h1x2[0].phi   - averaged phi for 2 towers.
   (f) h1x2[0].e     - energy in GeV in 1x2 towers.

   *** L0 layer ***
   *** FOR L0 studies  ***
   (f) hl0[0].eta   - eta for l0 (=h1x1[0].eta).   
   (f) hl0[0].phi   - phi for l0 (=h1x1[0].phi).
   (f) hl0[0].e     - energy in GeV in L0 layer.

******************************
* HO energy cluster object *
******************************

   *** 1x1 cluster ***    formed around HB1x1 cluster
   (f) ho1x1[0].eta   - eta of 1x1 cluster
   (f) ho1x1[0].phi   - phi of 1x1 cluster
   (f) ho1x1[0].e     - energy in GeV in 1x1 cluster.
   (f) ho1x1[0].adc   - linearized ADC counts.  (pedestal subtracted)
   (f) ho1x1[0].ped   - pedestal
   (f) ho1x1[0].gain  - gain factor
   (i) ho1x1[0].hcid  - sequential id number number of hc object.

   *** 3x3 cluster ***    formed around HB 1x1 cluster
   (f) ho3x3[0].eta   - eta of 3x3 cluster.
   (f) ho3x3[0].phi   - phi of 3x3 cluster.
   (f) ho3x3[0].e     - energy in GeV in 3x3 crystals.

   *** 1x1 cluster ***    max within HO
   (f) homax[0].eta   - eta of HO tile with the largest ADC count.
   (f) homax[0].phi   - phi of HO tile with the largest ADC count.
   (f) homax[0].e     - energy in GeV in crystal with the largest ADC count.
   (f) homax[0].adc   - linearized ADC counts.  (pedestal subtracted)
   (f) homax[0].ped   - pedstal
   (i) homax[0].hcid  - sequntial id number of hc object.


  
*************************************************
*         End of ROOT tree description          *
*************************************************

///////////////////////////////////////////////////////////////////////
[2] Installation

All required files are in /home/h2hcal/ana/kunori/releases/v11a.
Do the following.
   i) crate a work directory for you, i.e.
        mkdir  myworkarea
        cd myworkarea

  ii) copy all files from kunori's release area, i.e.
        cp /home/h2hcal/ana/kunori/releases/v11a .

That's all, if you use this on cmsru1.cern.ch.

If you are running on other node, you have to modify path
to input data file and some parameter files. (See [3.2])


[3] Creation of Reco-ROOT file.


[3.1] Example to run a job to create a root output file.

//      > root       -- to start a root session. 
//
//      root [0] .L /home/h2hcal/lib/libHTBDAQ_Data.so
//                                      (load ROOT definition for H2TB data)
//      root [1] .L libh2reco.so        (load ROOT definition for reco data)
//      root [2] .L RecoH2TB.C          (load this program)
//      root [3] RecoH2TB reco          (construct this program class)
//      root [4] reco.do(524,20)        (process /data/HTB_524.root, 20 evnets)
//      root [5] .q                     (quit)
//
//    This creates output file, reco_524.root
//
//    Instead of using "reco.do(524,20),
//         reco.doForcedEtaPhi(524,20,8,5)
//    creates h1x1, h3x3, h5x5 and timing around eta-8 and phi-5.
// 


[3.2] Changing parameters in RecoH2TB.C.

Many parameters are hard coded in RecoH2TB.C. Most common parameters
may be changed relatively easily. Those are:

  - directory of input ROOT files from DAQ. (Default: /data/HTB_XXX.root)
  - directory of output ROOT file.     (Default: your current directory.)
  - HCAL channel map file. (Default: /home/h2hcal/ana/kunori/hcalmap.txt)
  - ECAL pedestal file     (Default: /data/pedDB.xml)

  - The number of time slices to calculate ADC counts in HCAL 1x1
    3x3 and 5x5 cluster.      (Default:  -1 to +2).

Most of parameters are set in void RecoH2TB::init(int run_num).

Read the begining of RecoH2TB.C for more information.

[4] Analysis of Reco-ROOT file.

[4.1] Example to analyze

//        > root     -- to start a root session for data analysis.
//
//        root [0] .L libh2reco.so                 (load ROOT definition)
//        root [1] TFile f("reco_524.root")        (open input file)
//        root [2] .ls
//           TFile**         reco_524.root
//           TFile*         reco_524.root
//           KEY: TTree    RECO;1  h2reco Tree
//        root [3] RECO->StartViewer()             (to start Tree Viewer)
//        root [4] RECO->Draw("hc.adcmax")
//        root [5] RECO->Draw("hc.adcmax","hc.adcmax<2000.")
//        root [6] RECO->Draw("hc.tsmax","hc.adcmax>100.&hc.adcmax<2000.") 
//        root [7] RECO->Draw("h3x3[0].e-h5x5[0].e")
//        root [8] .q
//
//        [4] plots a histogram of largest adc signal in fC unit in 20 time
//        slices/channel for all readout channels.
//
//        [5] plots same as [4] with a cut on the adc to exclude
//        bad channel which has all ADC bits on.
//
//        [6] plots time slice number which has the largest adc
//        with a cut 100<adc<2000.
//       
//        [7] plots difference between h5x5 cluster and h3x3 cluster.

[4.2] Creation of macro file.

    root [14] RECO->MakeClass("myEcalSum");

    (to be described more.)

[5] Some information

[5.1] Conversion table form QIE code to Charge.

QIE code to Charge   (updated for RecoH2TB.C v10,  05-Sep-2002, S.Kunori)
   This is based on 
   http://home.fnal.gov/~kunori/cms/tb2002/info/020904-qie_scales.pdf

   0  -0.5   32  59.5   64  359.5   96  1859.5
   1  0.5   33  64.5   65  384.5   97  1984.5
   2  1.5   34  69.5   66  409.5   98  2109.5
   3  2.5   35  74.5   67  434.5   99  2234.5
   4  3.5   36  79.5   68  459.5   100  2359.5
   5  4.5   37  84.5   69  484.5   101  2484.5
   6  5.5   38  89.5   70  509.5   102  2609.5
   7  6.5   39  94.5   71  534.5   103  2734.5
   8  7.5   40  99.5   72  559.5   104  2859.5
   9  8.5   41  104.5   73  584.5   105  2984.5
   10  9.5   42  109.5   74  609.5   106  3109.5
   11  10.5   43  114.5   75  634.5   107  3234.5
   12  11.5   44  119.5   76  659.5   108  3359.5
   13  12.5   45  124.5   77  684.5   109  3484.5
   14  13.5   46  129.5   78  709.5   110  3609.5
   15  15   47  137   79  747   111  3797
   16  17   48  147   80  797   112  4047
   17  19   49  157   81  847   113  4297
   18  21   50  167   82  897   114  4547
   19  23   51  177   83  947   115  4797
   20  25   52  187   84  997   116  5047
   21  27   53  197   85  1047   117  5297
   22  29.5   54  209.5   86  1109.5   118  5609.5
   23  32.5   55  224.5   87  1184.5   119  5984.5
   24  35.5   56  239.5   88  1259.5   120  6359.5
   25  38.5   57  254.5   89  1334.5   121  6734.5
   26  42   58  272   90  1422   122  7172
   27  46   59  292   91  1522   123  7672
   28  50   60  312   92  1622   124  8172
   29  54.5   61  334.5   93  1734.5   125  8734.5
   30  59.5   62  359.5   94  1859.5   126  9359.5
   31  64.5   63  384.5   95  1984.5   127  9984.5

[6] Examples of Scripts/Macro.

Those scripts were mainly used on cmsru1.cern.ch during
data taking on 13th-19th September, 2002, i.e. close to the
end of the 2002 TB period.

[6.1] root macros for quasi-online monitoring.

These read a raw data root file in /data area and crate a
ourput reco_xxxx.root file. Then display plots of reconstructed
phi, eta, energy, average pedestals etc.

electon.C(runum) - displays phi, eta, h1x1.e, h1x1.adc, pedestals.
pion.C(runnum) - diplayse phi, eta,h3x3.3, h5x5.e, pedestals.
muon.C(runnum,eta,phi) - displays phi,eta,h1x1e,h1x1.adc,pedestals.

Those macros use "plotHCped.C", "plotHCped.h" which were created
by using a template generated by RECO->MakeClass("plotHCped").

input: raw root file

usage:  (inside root)
 > root
 .x electron(3200)

[6.2] root macro to display wire chamber hits.

wctest.C(run_number,no_of_event) - processes a raw data file and 
crates an ooutput reco root file. Then display wire chamber hits.

input: raw root file

usage:  (inside root)
 >root
 .x wctest.C(3200,1000)     - to analyze 1000 events in Run3200.

[6.3a] shell script to have gaussian fit to electron peak in
all electron scan runs (Run2946-3212) and print fitted value
in a log file (ascii file)

input: reco-root files (many)

usage:  (at shell )
  adc_gain.csh

[6.3b] root script to plot HCAL gain (GeV/fC) and resolution 
(sigma/mean). All values were taken from output log file
crated by [6.3a] and typed in by hand. (Of course, I did
screen-to-screen copy.)

input: (none- stand alone)

usage: (inside root)
 > root
 .x plotHCpeds.C()

 
[7] Release History

14-Sep-2002  S.Kunori
  (1) Update WC code (provided by R. Vidal)
  (2) Use gain factor calculated by ALvis in September source
      calibration run. The factor has been calculated only
      for mean response within each phi slice. So this code
      is valid for only September data, especially after
      swapping of RM4 and RM8.

09-Sep-2002  S.Kunori
  - Modification to ~/ana/vladygin/v09 (copied 9:45am,05.09.2002)
  (1) Change a conversion table for FADC code to Charge. The new table
      is based on the specification dated 03-Sep-2002, given by 
      Terri Shaw.
      (http://home.fnal.gov/~kunori/cms/tb2002/info/020904-qie_scales.pdf)
  (2) Add Ho1x1, Ho3x3, Homax.
  (3) Add ec_post, ec_muon in Trigger for muon tag.
  (4) Add reco.doForcedEtaPhi(2254,20,8,5) to create h1x1, h3x3 etc.
      at (around) eta=8 and phi=5.

08-Aug-2002  S.Kunori
  - initial version released.