Start Counter Calibration Procedures

From GlueXWiki
Jump to: navigation, search


Some of the procedures described here will commit calibration constants to a database that is used by the entire collaboration. Extreme care must be taken to not inadvertently write to the database. When writing to the database, this should be discussed and coordinated with experts.

No calibrations should be uploaded to the database until after the final third step of the calibration procedures, i.e., until after having checked the impact on the timing resolution. In order to check this impact you should work with a local copy of the database. Do the following:

Working with a private SQLite file

This follows recommendations from a presentation by Rupesh Dotel and Sean Dobbs[1]

  • Copy the latest sqlite file (eg : /group/halld/Software/calib/ccdb_sqlite/latest_version.sqlite) to your work directory (in this example the latest version is called ccdb_2022-11-10.sqlite.
  • Configure your environment to use the private copy of ccdb (not the master) with
 setenv CCDB_CONNECTION sqlite:///{$PWD}/ccdb_2022-11-10.sqlite
 setenv JANA_CALIB_URL sqlite:///{$PWD}/ccdb_2022-11-10.sqlite

This needs to get done after having set up your GlueX environment; otherwise, setting up the environment will overwrite this. You should check that CCDB uses your local copy by starting an interactive session:

 ccdb -i

This should show you that CCDB is connecting to your local file and not the master file.


This page describes the calibration procedures for the Start Counter. If you are not familiar with the concepts of time-walk effect and propagation time in scintillators, you should read Chapter 4: Start Counter Calibration in Eric Pooser's dissertation[2].

The procedure employs three plugins, which are used to analyze raw data files (evio):

  • 1) Start Counter Time Walk Corrections Plugin (st_tw_corr_auto)
  • 2) Start Counter Propagation Time Corrections Plugin (ST_Propagation_Time)
  • 3) Start Counter Time Resolution Plugin (ST_Tresolution)

These plugins provide histogram files, which subsequently are analyzed with root macros. You can find and inspect these plugins and their associated root macros on GitHub or in your local installation at $HALLD_RECON_HOME/src/plugins/Calibration. A summary of how to run each code and the expected outcomes of the macros will be shown in details below

ST Time Walk Plugin "st_tw_corr_auto"

The signals from the start counter's silicone photomultipliers (SciPMs) are split into two branches. One is processed by leading edge discriminators; the discriminator output, which is subject to the pulse height dependent time-walk is fed into F1TDCs. The second branch is fed into the FADC250, which record pulse height as well as timing. The FADC time can serve as a reference time to extract the time-walk corrections for the F1TDCs.

The plugin, which creates the histograms, and the root macros, which analyze the histograms can be inspected at GitHub and on your local installation at $HALLD_RECON_HOME/src/plugins/Calibration/st_tw_corr_auto. There you will find the following plugin and macro files:

  • Plugin Files:
  • Macros Files:

This plugin must run in two passes. The first pass generates uncorrected timing distributions; a macro extract parameters for the time walk corrections. In the second pass, the time walk corrections are applied and verified. This is controlled from the command line by the parameter SC:USE_TIMEWALK_CORRECTION (see for details.)

The following shows an example of how to run the plugin on ifarm at Jefferson Lab for a raw data file from the PrimeX fall 2022 run:

 hd_root /cache/halld/RunPeriod-2022-08/rawdata/Run110896/hd_rawdata_110896_000.evio -PPLUGINS=st_tw_corr_auto -PNTHREADS=8 -PSC:USE_TIMEWALK_CORRECTION=0

If this worked, you will have a newly created file hd_root.root, which contains five histograms for each of the 30 scintillator paddles of the start counter. For each counter the first three will be filled,

Paddle10 before correction 2D.pngPulse peak paddle10.pngPaddle10 ST Time beforeTWcorr 111155.png

- The plots above are an example of the filled histograms when running st_tw_corr_auto with timewalk correction = 0 (Run111155). -

The other two will be empty. The first histogram, stt_vs_pp_chan_*, shows ... . This histogram exhibits the pulse height dependent time walk for the FTDC signals. The macro st_tw_resols.C will fit the time walk correction coefficients. If you have not done yet, you should copy the root macros to your working directory

 cp $HALLD_RECON_HOME/src/plugins/Calibration/st_tw_corr_auto/macros/* .

Now start a root session and then run the first pass macro

 .x st_tw_fits.C("hd_root.root")

The file st_timewalks.txt will be created with the needed constants for the walk corrections. After verifying that you use a local copy you can upload these constants into the local CCDB use the command:

 ccdb add START_COUNTER/timewalk_parms_v2 st_timewalks.txt

Now run the second pass of the plugin:

 hd_root /cache/halld/RunPeriod-2022-08/rawdata/Run110896/hd_rawdata_110896_000.evio -PPLUGINS=st_tw_corr_auto -PNTHREADS=8 -PSC:USE_TIMEWALK_CORRECTION=1

Then start a root session and run the second pass macro

.x st_tw_resols.C("hd_root.root")

Examples of the excpected plots can be found here ST_tw_corr


For this plugin you will need the following:

  • Plugins:
  • Macros:

The paths are included in the instructions below.

Needs updating. See GitHub readme-s .

This plugin must run after we have the walk corrected times from the ST and TOF. (How do we know that TOF has been calibrated???)

Following the example above, you run the plugin:

 hd_root /cache/halld/RunPeriod-2022-08/rawdata/Run110896/hd_rawdata_110896_000.evio -PPLUGINS=ST_Propagation_Time -PNTHREADS=8 

Note that on farm with 8 threads, this plugin runs at ~90 Hz. For a first check, you might want to limit the number of events by running with parameter -PEVENTS_TO_KEEP=100000, for example. The author (J.R.) has not yet established how much statistics is necessary for a good calibration. For this plugin, you would like to submit a job to the farm to run the plugin over various evio files.

The first pass of this plugin will generate a ROOT file from an EVIO data file that contains histograms of the ST propagation time versus Z coordinate of the ST hit location for all 30 start counter sectors. This ROOT file needs to be analyzed by SC_PTC.C macro, which calculates the mean value of time versus Z. The results are saved in a text file called: " SC_PTC.txt ". The next step is to run the macro SC_PTC_Plot.C, which takes the values from the SC_PTC.txt text file, and plot them vs Z. This macro will create fits according to the section (nose, bent or straight) and will write the constants in the file PTC_1DFits.txt.

After verifying that you are working with a local copy of the CCDB, you can add these constants with the command :

 ccdb add  START_COUNTER/propagation_time_corr PTC_1DFits.txt

To check the time resolution after uploading the constants can be done by running the plugin again, and obtaining a new ROOT file. This ROOT file can be analyzed using the macro: Resolution.C, which will give you the time resolution per paddle. You can also use the macro SC_PTC_RvsZ.C to get the time resolution versus Z and then plot it using SC_PTC_ResolvsZPlot.C. All the macros needed can be extracted as before:

cp $HALLD_RECON_HOME/src/plugins/Calibration/ST_Propagation_time/macros/* .

You can also check the instructions in Github: [1].


This plugin must run after the ST propagation time constants are uploaded in the CCDB. This plugin will generate a ROOT file from an EVIO data file that contains histograms of the ST corrected time for each paddle versus Z coordinate of the ST hit location. To run the plugin use the hd_root command mentioned in section 1 of this page. To run the macro use the command :

.x st_time_resolution.C("hd_root.root")

The output of this macro will be 30 canvas of the two dimensional histograms mentioned above in addition to Y projection of these histograms. The time resolution will be ploted in another canvas. Examples of these histograms can be found in the following link ST Propagation Time Correction and Time resolution


  1. Rupesh Dotel and Sean Dobbs, Start Counter Recalibration, March 5, 2020, GlueX DocDB #4371
  2. Pooser, Eric J., "The GlueX Start Counter & Beam Asymmetry \Sigma in Single \pi ^{{0}} Photoproduction" (2016). FIU Electronic Theses and Dissertations. 2450.