TAGM TW Calibration

From GlueXWiki
Jump to: navigation, search


The official README can be found on Github.

The plugin TAGM_TW is used to determine the time-walk of the tagger microscope TDCs. For a time reference, the RF is used by finding the RF time nearest to the ADC time, as the ADC has its timewalk corrected through firmware. This RF time provides an excellent reference for measuring the TAGM timewalk.

In addition, the plugin is used to calibrate the microscope timing. It aligns the ADC to the RF and then matches the TDC to the ADC time. It does not align the microscope with the halls in the detector as another plugin does that already (HLDetectorTiming).

For efficient calibrations, this plugin should be used on PS skims with about 500k events, though less may suffice. This is roughly the first 10 skim files for a run.

The plugin produces timewalk curves (dt vs pulse peak) using both the "corrected" and uncorrected TDC times. The corrected TDC curves can be used to see the quality of the calibration. The plugin also produces plots of ADC - RF for all columns, including individual fibers, as well as corrected TDC - ADC.


  • JEventProcessor_TAGM_TW.cc
  • JEventProcessor_TAGM_TW.h
  • tw.py
  • timing.py
  • display.C
  • push-to-ccdb.sh

Note: You must have your CCDB environment variables set as timing.py pulls the constants before generating new ones.

Calibration Procedure

This plugin and scripts are designed to provide basic, initial timing and timewalk calibrations for the tagger microscope. Once all steps are complete, each TAGM channel should be aligned with the RF in both the TDC and ADC with timewalk corrected TDC times.

To fully align the TAGM with the rest of the detectors, use HLDetectorTiming.

CCDB version 1.06 or greater is needed for timing.py to work.

Running TAGM_TW

All calibrations scripts assume a ROOT file structure as generated by TAGM_TW.

hd_root -PPLUGINS=TAGM_TW -PTAGMHit:DELTA_T_ADC_TDC_MAX=200 /path/to/files/hd_rawdata_XXXXXX_00*

Follow these steps after running hd_root with the TAGM_TW plugin. Be aware that the CCDB table /PHOTON_BEAM/microscope/integral_cuts can interfere with the pulse height distributions. To set these values to 0 on the fly, run with the option -PTAGMHit:CUT_FACTOR=0.

Also, be aware that the reference RF source for this plugin is the TAGH. Make sure that the TAGH RF signal is calibrated before proceeding.

Initial ADC-RF and raw TDC-ADC calibration

This is the first step to calibrate the TAGM. Because the ADC is already timewalk corrected, this can be immediately aligned with an RF bucket. At the same time, the uncorrected TDC time can be adjusted to be aligned with the new ADC time. This is a rough calibration of the raw TDC time which will avoid the timewalk from absorbing large offsets.

For this step, it is important to include -PTAGMHit:DELTA_T_ADC_TDC_MAX=200 when running TAGM_TW. Occasionally, the initial time difference is very large.

python timing.py -b <rootfile> <run number> rf <CCDB variation>

This script produces the file adc_offsets-######.txt and tdc_offsets-######.txt where ###### is the full run number.

These can be pushed to the CCDB using a script

./push-to-ccdb.sh <run number> <variation> adc tdc

or manually

ccdb add PHOTON_BEAM/microscope/fadc_time_offsets -v <variation> -r #-# adc_offsets-######.txt
ccdb add PHOTON_BEAM/microscope/tdc_time_offsets -v <variation> -r #-# tdc_offsets-######.txt

Timewalk corrections

The timewalk corrections are to be performed after the initial ADC-RF and raw TDC-ADC calibrations have been performed.

The timewalk plugin uses the TAGH RF as a reference. For a given hit, the RF time closest to the ADC time is selected and set as the RF time. The time difference between the TDC time and the RF time is taken. By doing it this way, there are not multiple timewalk distributions every beam period. This allows for large timewalks to be included in the fit.

The constants from the first step need to be pushed to CCDB and a new root file needs to be created using TAGM_TW before performing this step.

python tw.py -b <rootfile> <run number>

This creates the files results.root and tw-corr.txt

To check the fits:

root -l -b 'display.C("results.root")'

Add to the CCDB

./push-to-ccdb.sh <run number> <variation> tw

or manually

ccdb add /PHOTON_BEAM/microscope/tdc_timewalk_corrections -v <variation> -r #-# tw-corr.txt

Corrected TDC-RF calibration

At this point, the previous steps should be completed and verified. The ADC-RF distribution should be centered at 0 as well as the raw TDC-ADC.

This step takes the timewalk corrected TDC time and compares it with the ADC. Since the ADC is already aligned with the RF, this will align the TDC with both.

The constants from the previous steps need to be pushed to CCDB and a new root file needs to be created using TAGM_TW before performing the next step.

python timing.py -b <rootfile> <run number> self <CCDB variation>

The script overwrites the previous tdc_offsets-#####.txt file

./push-to-ccdb.sh <run number> <variation> tdc

or manually

ccdb add PHOTON_BEAM/microscope/tdc_time_offsets -v <variation> -r #-# tdc_offsets-######.txt

Calibration validation

After all steps are complete, a calibration validation can be performed. Run the plugin TAGM_TW again with the new constants.

python timing.py -b <rootfile> <run number> validate <CCDB variation>

This produces a file problem-channels.txt containing any errors or fits that are exceeding a default value. These channels should be investigated.

Timing resolutions

Once all of the calibrations are done, the timing resolutions can be measured. The timing.py script will look at the corrected TDC-RF (t-rf) plots and fit the distributions with a Gaussian. The results are provided as 1 sigma as well as FWHM and can be seen in the ROOT file resolutions.root.

python timing.py -b <rootfile> <run number> res <CCDB variation>

OLD/DEPRECATED Calibration Procedure

(Note: The most up to date procedure will be kept in sim-recon in the README file.)

Please have CCDB 1.06 or greater. 1.05b does not work with timing.py.

To calibrate the microscope, follow this procedure:

  1. hd_root -PPLUGINS=TAGM_TW /path/to/PS-skim.evio
  2. Get updated calibration constants for the ADC using the (ADC - RF) histogram
    1. python timing.py -b <root file> <run number> rf <CCDB variation>
    2. This produces the file adc_offsets-####.txt
  3. ccdb add PHOTON_BEAM/microscope/fadc_time_offsets -v default -r ####-#### adc_offsets-####.txt
  4. hd_root -PPLUGINS=TAGM_TW /path/to/PS-skim.evio
  5. Now measure the timewalk
    1. python tw.py -b <root file> <run number>
    2. This produces the file tw-corr.txt
  6. ccdb add PHOTON_BEAM/microscope/tdc_timewalk_corrections -v default -r ####-#### tw-corr.txt
  7. hd_root -PPLUGINS=TAGM_TW /path/to/PS-skim.evio
  8. With the adc aligned with the RF and the timewalk calibrated, align the TDC to the ADC
    1. python timing.py -b <root file> <run> self <CCDB variation>
    2. This generates the file tdc_offsets-####.txt
  9. ccdb add PHOTON_BEAM/microscope/tdc_time_offsets -v default -r ####-#### tdc_offsets-####.txt
  10. hd_root -PPLUGINS=TAGM_TW /path/to/PS-skim.evio
  11. Check TDC - ADC timing distributions
    1. python timing.py -b <root file> <run> validate <CCDB variation>

Verifying the timewalk corrections

The ROOT macro display.C will show the timewalk distributions for all channels.

 root -l 'display.C("/path/to/rootfile.root")'