View source for Instructions for analysis shifts

== Instructions for analysis shifts / VCS E12-15-001 experiment ==

• Connect to cdaql1: ssh cdaql1 and go to /home/cdaq/vcs2019/hallc_replay_vcs

Warning: from this directory, please don't make any modifications on the source code. If you want to do tests or modify things, go to github and fork to your personnal directory. 

The source code is available from: https://github.com/JeffersonLab/hallc_replay_vcs

Before starting to run it, run:

> getstarted.sh

It will change path that are hardcoded in Ana/datainfo c-shell scripts. 

=== Kinematic setting ===

- For each new run, the file: DBASE/COIN/standard.kinematics is updated. Check regularly if it is the case.

- If needed to manually enter a new run, type new values for: beam energy (in principle it won't change), target mass (amu), HMS and SHMS central momentum and angle, particle mass detected in each arm (in principle, it won't change: proton in HMS, electron in SHMS). Note that the names of arm variable start with letter "h" for HMS and "p" for SHMS.

=== HMS and SHMS replay ===

This step should be done by the SL or TO, but the person on analysis shift can also perform additional monitoring.

- Run standard HMS and SHMS coincidence replay after 50000 events and once after the run is done. Run:

> ./run_coin_hms.sh		

> ./run_coin_shms.sh

It replays the most recent run and monitoring plots will automaticaly open. 
Provide "run number" and "N events" (or -1 for full replay) if you want to replay a previous run or limit the number of events.

=== Analyzer coincidence and physics replay script ===

- After 200,000 events and once when the run is finished, run the analysis replay. It can be done more often during the run, but at least 2 times.

For a partial run replay, do:

> ./run_partial_replay.csh (run number) (# events) (process = elastic, vcs...) (target = LH2 or dummy)

After the run, do:

> ./run_full_replay.csh (run number) (process = elastic, vcs...) (target = LH2 or dummy)

Don't forget later to run the full replay at least once! It can take a long time to convert the data. It will also allow to build a permanent database.

- Running these scripts command will convert data to coincidence root files, build a database, run analysis monitoring plots and provide a reduced root file for this run.

- If needed for a second monitoring or after changing analysis cuts, run only the analyzer, without replaying the full run. It takes only a few minutes for a complete run.

Change cuts in: Ana/ANA_CUTS.input amd histogram limits / binning in Ana/ANA_HIST.input if needed. 

Keep track of the cuts you set. Please don't change any source code in this directory, do it from your fork if needed.

> ./run_ana_only.csh (run number) (# events) (process = elastic, vcs...) (target = LH2 or dummy)

You can also run directly the analysis script by going to the Ana directory. To run it, do:

> ./HallCana "vcs" "ana" "LH2" "runnumber" -f "input file .root"    (look at the README.txt for details)

options for process are: 

vcs, pi0, pi+, K+, elastic = call these options if the electron is in SHMS

vcsLT, pi0LT, pi+LT, K+LT, elasticLT = call these options if the electron is in HMS

=== Things to check ===

All the monitoring information will be open automatically at the end of the replay. Check additionnal information if needed from text and pd files.

==== 1) Timing cuts ====

- This file is open automatically. If not, open: Ana/files/timing_(run).dat

→ the first line is information about the selected coincidence time peak in order:
peak position, charges – bkg, events in time peak, bkg (low), bkg (up), peak max

- check if the peak position is < 0.2. If not, this means the coincidence time is not set properly. Change it in Ana/ANA_CUTS.input and run again the analyzer

- check that the number of events in the peak is larget than the numbers for "bkg (low, up)"

- enter the value of "event – bkg" in the run database

- Look if there is a secondary or third peak: line 2 and 3 correspond to potential physics peaks. If the value of charges - background is significant, compare values of charges in peak and average background (up, low). If the number of charges in this peak is significantly higher, enter it in the run database and enter the peak position

- If no peak is found, try to figure out why:

Possibilities: look at the figures with coincidence time minus the time delay to be set, look at the absolute coincidence time, check the quality of the fit and of the peak finder (monitoring figures, see below), change cuts and replay the analyzer... It may also be that there are not enough events in this run: check the luminosity, the running time. Look if there is any obvious reason for the number of events to be low. First check histograms, and make a log entry and/or write it is database and/or the run sheet if anything is wrong and/or write it in the database and the run sheet. Call the expert if needed to avoid loosing good data.

==== 2) Luminosity ====

- This file is open automatically. If not, open: Ana/files/lumi_(run).dat
The one line contains: run number, luminosity (HMS), luminosity (SHMS), actual running time (HMS), actual running time (SHMS), current (HMS), current (SHMS)

- check if the luminosity are the same in HMS and SHMS, and write them in the run database. If there are different, try to figure out why and call expert if needed.

==== 3) Missing mass peaks position ====

- This file is open automatically. If not, open: Ana/files/missmass2_(run).dat

3 lines correspond to possible 3 found peaks in the squared missing mass, with entries: M², integral 

- record the position of the 2 main peaks: VCS M² ~ 0 GeV² and π° M² ~ 0.02 GeV² and the integrals int(VCS) / int (π°)

- if the ratio doesn't make sense and is far from ~ 1/10, check the quality of the fit and/or try to understand. If something is wrong, write it in the database and/or run sheet.

- if less than one peak is found, or the 2 peaks (VCS and π°) are merged into one, it may be a problem with the calibration, resolution... Try to understand why. If the problem is very bad, write in database and run sheet.

==== 4) Monitoring plots, to compare with reference plots ====

All the figures to look at will pop-up in a condensed replay "ana_monitor_(run).pdf. If additionnal check need to be done, open the extra pdf files as indicated.


• Timing

Extra monitoring: Ana/Results/cointime_(run).pdf

→ Look at the coincidence time distribution for ROC2: if no peak is found there is a problem. If no peak is found near 0 and/or no peak for the red curve, change the time shift in ANA_CUTS.input and replay the analyzer.

→ Check the quality of the peak finder and the fitting 

→ Compare β and missing mass distributions to reference


• Kinematic distributions

Extra monitoring: Ana/Results/kinematics_(run).pdf and Ana/Results/kinematics2D_(run).pdf

→ Compare the figures with reference plots for each kinematic setting.

→ Check also  Ana/Results/positions_(run).pdf if something strange. If the HMS and SHMS positions don't match expectation from run plan, figure out why and/or call an expert.

• Exclusivity distributions 

Extra monitoring: Ana/Results/exclusivity_(run).pdf (multipage)

→ Compare selected data exclusivity distributions to the reference

→ Check if there are 2 missing mass peaks on the missing mass and squared missing mass distributions corresponding to 0 mass and π° mass, compare to the reference


• Analysis root data

A root file has been created and contains filtered data. If histograms are empty and/or the tree is empty or don't contain a significant number of events after a full replay, it can come from cuts badly set, from not the good option being called, from database information not properly filled or from a problem with the data.

> root -l Ana/files/HallCdata_(run).root

> (root) > HallCTree->GetEntries();

> (root) > HallCTree->Show(0);