Difference between revisions of "TAGM TW Calibration"

From GlueXWiki
Jump to: navigation, search
(→‎Verifying the corrections)
(→‎Calibration Procedure)
 
(9 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== Overview ==
 
== Overview ==
−
The plugin TAGM_TW is used to determine the time-walk of the tagger microscope TDCs. Instead of using the fADC for a time reference, the RF signal is used. In the spring 2015 run the TAGM has a large time-walk effect and requires looking for coincidences with the pair spectrometer in order to find the best RF time. This plugin will generate a ROOT file from an EVIO or HDDM file that contains 100 histograms, the time difference versus pedestal-subtracted pulse peak amplitude for all 100 readout channels. A separate ROOT macro will analyze and fit these histograms and provide a table for the CCDB as well as an output ROOT file containing the results for verification.
+
<b> The official README can be found on [https://github.com/JeffersonLab/sim-recon/tree/master/src/plugins/Calibration/TAGM_TW Github]</b>.
 +
 
 +
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.
  
 
Files:
 
Files:
 
*JEventProcessor_TAGM_TW.cc
 
*JEventProcessor_TAGM_TW.cc
 
*JEventProcessor_TAGM_TW.h
 
*JEventProcessor_TAGM_TW.h
−
*tw_corr.C
+
*tw.py
−
*defaults.C
+
*timing.py
−
*tagm_tw_parms_defaults.out
+
*display.C
−
*tagm_tw_parms.out
+
*push-to-ccdb.sh
−
*sigmas.out
+
−
*results.root
+
  
−
== Generating a ROOT file ==
+
<b>Note: You must have your CCDB environment variables set as timing.py pulls the constants before generating new ones.</b>
−
To run the plugin, use the following command:
+
 
 +
== 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.
 +
 
 +
<b>CCDB version 1.06 or greater is needed for timing.py to work.</b>
 +
 
 +
=== Running TAGM_TW ===
 +
 
 +
All calibrations scripts assume a ROOT file structure as generated by TAGM_TW.
  
 
<pre>
 
<pre>
−
hd_root -PPLUGINS=TAGM_TW /path/to/datafile
+
hd_root -PPLUGINS=TAGM_TW -PTAGMHit:DELTA_T_ADC_TDC_MAX=200 /path/to/files/hd_rawdata_XXXXXX_00*
 
</pre>
 
</pre>
  
−
If a different output filename must be used, change the output file name by adding the following to the hd_root command
+
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.
 +
 
 +
<b>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.</b>
  
 
<pre>
 
<pre>
−
-o new_filename.root
+
python timing.py -b <rootfile> <run number> rf <CCDB variation>
 
</pre>
 
</pre>
  
−
*Note: If a file other than hd_root.root is used as the input file for the fitting macro, the macro will need it's input file changed.
+
This script produces the file adc_offsets-######.txt and tdc_offsets-######.txt where ###### is the full run number.
  
−
== Using the ROOT macro ==
+
These can be pushed to the CCDB using a script
−
Once the file ROOT file has been generated use the macro tw_corr.C in the following way
+
<pre>
 +
./push-to-ccdb.sh <run number> <variation> adc tdc
 +
</pre>
 +
or manually
 +
<pre>
 +
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
 +
</pre>
 +
 
 +
=== 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.
 +
 
 +
<b>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.</b>
  
 
<pre>
 
<pre>
−
$ root -l -b -q 'tw_corr.C("hd_root.root")'
+
python tw.py -b <rootfile> <run number>
 
</pre>
 
</pre>
  
−
This will load the macro tw_corr.C and then call the method tw_corr(). Once it finishes it will exit ROOT. No display will be set.
+
This creates the files results.root and tw-corr.txt
  
−
*Screen output has been turned off by default. If you would like to see the results as they are computed, change the flag OUTPUT to true at the top of the macro.
+
To check the fits:
−
*There is also a flag for debugging, DEBUG, that can be set to true for additional screen output.
+
<pre>
 +
root -l -b 'display.C("results.root")'
 +
</pre>
  
−
*If the input file is not hd_root.root, edit the command so that it matches the correct filename.
+
Add to the CCDB
 +
<pre>
 +
./push-to-ccdb.sh <run number> <variation> tw
 +
</pre>
 +
or manually
 +
<pre>
 +
ccdb add /PHOTON_BEAM/microscope/tdc_timewalk_corrections -v <variation> -r #-# tw-corr.txt
 +
</pre>
  
−
== Verifying the corrections ==
+
=== Corrected TDC-RF calibration ===
−
The ROOT macro tw_corr.C will create an output ROOT file called results.root which will contain the time-walk histograms before and after the corrections as well as the TProfile used for fitting. It will also create a text file sigmas.out that contains the final sigmas of the timing distributions.
+
  
−
results.root contains three main directories: dt_vs_pp, dt_vs_pp_0, dt_vs_pp_corr, and dt_vs_pp_profile.
+
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.
−
*dt_vs_pp
+
−
**These directories contain the initial time-walk curves for the 100 readout channels
+
−
*dt_vs_pp_corr
+
−
**These directories contain the corrected time-walk curves for the 100 readout channels
+
−
*dt_vs_pp_profile
+
−
**These directories contain the TProfile plots used during the fitting process.
+
  
−
The histograms in dt_vs_pp_corr should be roughly horizontal for good channels. Low amplitude channels may not be horizontal.
+
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.
  
−
In the main directory there are two summary plots, sigmas_before and sigmas_after, which show the timing resolution for each channel before and after the corrections.
+
<b>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.</b>
  
−
== Adding the time-walk parameters to CCDB ==
+
<pre>
−
To add files to the CCDB, type the following
+
python timing.py -b <rootfile> <run number> self <CCDB variation>
 +
</pre>
 +
 
 +
The script overwrites the previous tdc_offsets-#####.txt file
  
 
<pre>
 
<pre>
−
ccdb add /PHOTON_BEAM/microscope/tdc_timewalk_corrections -v default -r $RunNo-$RunNo tagm_tw_parms.out
+
./push-to-ccdb.sh <run number> <variation> tdc
 
</pre>
 
</pre>
 +
or manually
 +
<pre>
 +
ccdb add PHOTON_BEAM/microscope/tdc_time_offsets -v <variation> -r #-# tdc_offsets-######.txt
 +
</pre>
 +
 +
=== Calibration validation ===
 +
 +
After all steps are complete, a calibration validation can be performed. Run the plugin TAGM_TW again with the new constants.
 +
 +
<pre>
 +
python timing.py -b <rootfile> <run number> validate <CCDB variation>
 +
</pre>
 +
 +
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.
 +
 +
<pre>
 +
python timing.py -b <rootfile> <run number> res <CCDB variation>
 +
</pre>
 +
 +
== OLD/DEPRECATED Calibration Procedure ==
 +
(Note: The most up to date procedure will be kept in [https://github.com/JeffersonLab/sim-recon/tree/master/src/plugins/Calibration/TAGM_TW 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:
 +
 +
# hd_root -PPLUGINS=TAGM_TW /path/to/PS-skim.evio
 +
# Get updated calibration constants for the ADC using the (ADC - RF) histogram
 +
## python timing.py -b <root file> <run number> rf <CCDB variation>
 +
## This produces the file adc_offsets-####.txt
 +
# ccdb add PHOTON_BEAM/microscope/fadc_time_offsets -v default -r ####-#### adc_offsets-####.txt
 +
# hd_root -PPLUGINS=TAGM_TW /path/to/PS-skim.evio
 +
# Now measure the timewalk
 +
## python tw.py -b <root file> <run number>
 +
## This produces the file tw-corr.txt
 +
# ccdb add PHOTON_BEAM/microscope/tdc_timewalk_corrections -v default -r ####-#### tw-corr.txt
 +
# hd_root -PPLUGINS=TAGM_TW /path/to/PS-skim.evio
 +
# With the adc aligned with the RF and the timewalk calibrated, align the TDC to the ADC
 +
## python timing.py -b <root file> <run> self <CCDB variation>
 +
## This generates the file tdc_offsets-####.txt
 +
# ccdb add PHOTON_BEAM/microscope/tdc_time_offsets -v default -r ####-#### tdc_offsets-####.txt
 +
# hd_root -PPLUGINS=TAGM_TW /path/to/PS-skim.evio
 +
# Check TDC - ADC timing distributions
 +
## 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.
  
−
To start with initial default parameters, add tagm_tw_parms_defaults.out.
+
<pre> root -l 'display.C("/path/to/rootfile.root")'</pre>

Latest revision as of 10:20, 27 May 2017

Overview

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.

Files:

  • 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")'
Retrieved from "https://halldweb1.jlab.org/wiki/index.php?title=TAGM_TW_Calibration&oldid=82487"