Skip to content

Latest commit

 

History

History
291 lines (247 loc) · 19.4 KB

README.md

File metadata and controls

291 lines (247 loc) · 19.4 KB
Raw

QADB

CLAS12 Quality Assurance Database

Provides storage of and access to the QA monitoring results for the CLAS12 experiment at Jefferson Lab

Table of Contents

  1. QA Information
  2. Database Access
  3. Data storage
  4. Faraday Cup Charge Access
  5. Database Management
  6. Contributions

QA Information

Caution

The QADB for older data sets may have some issues. It is HIGHLY recommended to check the known important issues to see if any issues impact your analysis.

Available Data Sets

The following tables describe the available datasets in the QADB. The columns are:

  • Pass: the Pass number of the data set (higher is newer)
  • Data Set Name: a unique name for the data-taking period; click it to see the corresponding QA timelines
    • Typically [RUN_GROUP]_[RUN_PERIOD]
    • [RUN_PERIOD] follows the convention [SEASON(sp/su/fa/wi)]_[YEAR], and sometimes includes an additional keyword
  • Run range: the run numbers in this data set
  • Status:
    • Up-to-Date: this is the most recent Pass of these data, and the QADB has been updated for it
    • Deprecated: a newer Pass exists for these data, but the QADB for this version is still preserved
    • TO DO: the Pass for these data exist, but the QADB has not yet been updated for it
  • Data files: the input data files used for the QA

Run Group A

Pass Data Set Name and Timelines Link Run Range Status Data Files
2 rga_fa18_inbending 5032 - 5419 TO DO
2 rga_fa18_outbending 5422 - 5666 TO DO
2 rga_sp19 6616 - 6783 Up-to-Date /cache/clas12/rg-a/production/recon/spring2019/torus-1/pass2/dst/recon
1 rga_fa18_inbending 5032 - 5419 Up-to-Date /cache/clas12/rg-a/production/recon/fall2018/torus-1/pass1/v0/dst/recon
1 rga_fa18_outbending 5422 - 5666 Up-to-Date /cache/clas12/rg-a/production/recon/fall2018/torus+1/pass1/v0/dst/recon
1 rga_sp19 6616 - 6783 Deprecated /cache/clas12/rg-a/production/recon/spring2019/torus-1/pass1/v0/dst/recon

Run Group B

Pass Data Set Name and Timelines Link Run Range Status Data Files
2 rgb_sp19 6156 - 6603 TO DO /cache/clas12/rg-b/production/recon/spring2019/torus-1/pass2/v0/dst/recon/
2 rgb_fa19 11093 - 11300 TO DO
2 rgb_wi20 11323 - 11571 TO DO
1 rgb_sp19 6156 - 6603 Up-to-Date /cache/clas12/rg-b/production/recon/spring2019/torus-1/pass1/v0/dst/recon
1 rgb_fa19 11093 - 11300 Up-to-Date /cache/clas12/rg-b/production/recon/fall2019/torus+1/pass1/v1/dst/recon
1 rgb_wi20 11323 - 11571 Up-to-Date /cache/clas12/rg-b/production/recon/spring2020/torus-1/pass1/v1/dst/recon

Run Group C

Pass Data Set Name and Timelines Link Run Range Status Data Files
1 rgc_su22 16042 - 16771 Up-to-Date /cache/clas12/rg-c/production/summer22/pass1

Run Group F

Pass Data Set Name and Timelines Link Run Range Status Data Files
1 rgf_sp20_torusM1 12210 - 12329 TO DO /cache/clas12/rg-f/production/recon/spring2020/torus-1_solenoid-0.8/pass1v0/dst/recon
1 rgf_su20_torusPh 12389 - 12434 TO DO /cache/clas12/rg-f/production/recon/summer2020/torus+0.5_solenoid-0.745/pass1v0/dst/recon
1 rgf_su20_torusMh 12436 - 12443 TO DO /cache/clas12/rg-f/production/recon/summer2020/torus-0.5_solenoid-0.745/pass1v0/dst/recon
1 rgf_su20_torusM1 12447 - 12951 TO DO /cache/clas12/rg-f/production/recon/summer2020/torus-1_solenoid-0.745/pass1v0/dst/recon

Run Group K

Pass Data Set Name and Timelines Link Run Range Status Data Files
2 rgk_fa18_7.5GeV 5674 - 5870 TO DO
2 rgk_fa18_6.5GeV 5875 - 6000 TO DO
1 rgk_fa18_7.5GeV 5674 - 5870 Up-to-Date /cache/clas12/rg-k/production/recon/fall2018/torus+1/7546MeV/pass1/v0/dst/recon
1 rgk_fa18_6.5GeV 5875 - 6000 Up-to-Date /cache/clas12/rg-k/production/recon/fall2018/torus+1/6535MeV/pass1/v0/dst/recon

Run Group M

Pass Data Set Name and Timelines Link Run Range Status Data Files
1 rgm_fa21 15019 - 15884 Up-to-Date /cache/clas12/rg-m/production/pass1/allData_forTimelines/

Defect Bit Definitions

  • QA information is stored for each QA bin, in the form of defect bits
    • the user needs only the run number and event number to query the QADB
  • A QA bin is:
    • the set of events between a fixed number of scaler readouts (roughly a time bin, although there are fluctuations in a bin's duration)
    • for older QADBs, Run Groups A, B, K, and M of Pass 1 data, the QA bins were DST 5-files
  • A defect bit is:
    • a bit (of a binary number) that is 1 if the QA bin exhibits the corresponding defect or 0 if not
    • each defect bit corresponds to a different defect, as shown in the table below
    • many defects check the value of N/F, defined as the trigger electron yield N, normalized by the DAQ-gated Faraday Cup charge F

Table of Defect Bits

Bit Name Description Additional Notes
0 TotalOutlier Outlier FD electron N/F, but not TerminalOutlier or MarginalOutlier
1 TerminalOutlier Outlier FD electron N/F of first or last QA bin of run
2 MarginalOutlier Marginal FD electron outlier N/F, within one standard deviation of cut line
3 SectorLoss FD electron N/F diminished for several consecutive QA bins For older datasets (RG-A,B,K,M pass 1), this bit replaced the assignment of TotalOutlier, TerminalOutlier, and MarginalOutlier; newer datasets only add the SectorLoss bit and do not remove the outlier bits.
4 LowLiveTime Live time < 0.9 This assignment of this bit may be correlated with a low fraction of events with a defined (nonzero) helicity.
5 Misc Miscellaneous defect, documented as comment This bit is often assigned to all QA bins within a run, but in some cases, may only be assigned to the relevant QA bins. The analyzer must decide whether data assigned with the Misc bit should be excluded from their analysis; the comment is provided for this purpose. Analyzers are also encouraged to check the Hall B log book for further details.
6 TotalOutlierFT Outlier FT electron N/F, but not TerminalOutlierFT or MarginalOutlierFT cf. TotalOutlier.
7 TerminalOutlierFT Outlier FT electron N/F of first or last QA bin of run cf. TerminalOutlier.
8 MarginalOutlierFT Marginal FT electron outlier N/F, within one standard deviation of cut line cf. MarginalOutlier.
9 LossFT FT electron N/F diminished for several consecutive QA bins cf. SectorLoss.
10 BSAWrong Beam Spin Asymmetry is the wrong sign This bit is assigned per run. The asymmetry is significant, but the sign is opposite than expected; analyzers must therefore flip the helicity sign.
11 BSAUnknown Beam Spin Asymmetry is unknown, likely because of low statistics This bit is assigned per run. There are not enough data to determine if the helicity sign is correct for this run.
12 TSAWrong Target Spin Asymmetry is the wrong sign Not yet used.
13 TSAUnknown Target Spin Asymmetry is unknown, likely because of low statistics Not yet used.
14 DSAWrong Double Spin Asymmetry is the wrong sign Not yet used.
15 DSAUnknown Double Spin Asymmetry is unknown, likely because of low statistics Not yet used.
16 ChargeHigh FC Charge is abnormally high NOTE: the assignment criteria of this bit are still under study.
17 ChargeNegative FC Charge is negative The FC charge is calculated from the charge readout at QA bin boundaries. Normally the later charge readout is higher than the earlier; this bit is assigned when the opposite happens.
18 ChargeUnknown FC Charge is unknown; the first and last time bins always have this defect QA bin boundaries are at scaler charge readouts. The first QA bin, before any readout, has no initial charge; the last QA bin, after all scaler readouts, has no final charge. Therefore, the first and last QA bins have an unknown, but likely very small charge accumulation.
19 PossiblyNoBeam Both N and F are low, indicating the beam was possibly off NOTE: the assignment criteria of this bit are still under study.

Database Access

You may access the QADB in many ways:

Text Access

  • human-readable tables are stored in qadb/*/qaTree.json.table; see the section QA data storage, Table files below for details for how to read these files
  • QADB JSON files are stored in qadb/*/qaTree.json

Software Access

Classes in both C++ and Groovy are provided, for access to the QADB within analysis code. In either case, you need environment variables; if you are using an ifarm build, they have already been set for you, otherwise:

source environ.sh   # for bash, zsh
source environ.csh  # for csh, tcsh

Then:

Important

C++ access needs rapidjson, provided as a submodule of this repository in srcC/rapidjson. If this directory is empty, you can clone the submodule by running

git submodule update --init --recursive

Data Storage

Table files

Human-readable format of QA result, stored in qadb/*/*/qaTree.json.table

  • each run begins with the keyword RUN:; lines below are for each of that run's QA bins and their QA results, with the following syntax:
    • run_number bin_number defect_bits :: comment
      • defect bits have the following form: bit_number-defect_name[list_of_sectors], and [all] means that all 6 sectors have this defect
      • comments are usually associated with Misc defects, but not always

JSON files

qaTree.json

  • The QADB itself is stored as JSON files in qadb/*/*/qaTree.json
  • the format is a tree:
qaTree.json ─┬─ run number 1
             ├─ run number 2 ─┬─ bin number 1
             │                ├─ bin number 2
             │                ├─ bin number 3 ─┬─ evnumMin
             │                │                ├─ evnumMax
             │                │                ├─ sectorDefects
             │                │                ├─ defect
             │                │                └─ comment
             │                ├─ bin number 4
             │                └─ bin number 5
             ├─ run number 3
             └─ run number 4
  • for each bin, the following variables are defined:
    • evnumMin and evnumMax represent the range of event numbers associated with this bin; use this to map a particular event number to a bin number
    • sectorDefects is a map with sector number keys paired with lists of associated defect bits
    • defect is a decimal representation of the OR of each sector's defect bits, for example, 11=0b1011 means that the OR of the defect bit lists is [0,1,3]
    • comment stores an optional comment regarding the QA result

chargeTree.json

  • the charge is also stored in JSON files in qadb/*/*/chargeTree.json, with a similar format:
chargeTree.json ─┬─ run number 1
                 ├─ run number 2 ─┬─ bin number 1
                 │                ├─ bin number 2
                 │                ├─ bin number 3 ─┬─ fcChargeMin
                 │                │                ├─ fcChargeMax
                 │                │                ├─ ufcChargeMin
                 │                │                ├─ ufcChargeMax
                 │                │                └─ nElec ─┬─ sector 1
                 │                │                          ├─ sector 2
                 │                │                          ├─ sector 3
                 │                │                          ├─ sector 4
                 │                │                          ├─ sector 5
                 │                │                          └─ sector 6
                 │                ├─ bin number 4
                 │                └─ bin number 5
                 ├─ run number 3
                 └─ run number 4
  • for each bin, the following variables are defined:
    • fcChargeMin and fcChargeMax represent the minimum and maximum DAQ-gated Faraday cup charge, in nC
    • ufcChargeMin and ufcChargeMax represent the minimum and maximum FC charge, but not gated by the DAQ
    • the difference between the maximum and minimum charge is the accumulated charge in that bin
    • nElec lists the number of electrons from each sector

Faraday Cup Charge Access

  • the charge is stored in the QADB for each QA bin, so that it is possible to determine the amount of accumulated charge for data that satisfy your specified QA criteria.
  • see chargeSum.groovy or chargeSum.cpp for usage example in an analysis event loop; basically:
    • call QADB::AccumulateCharge() within your event loop, after your QA cuts are satisfied; the QADB instance will keep track of the accumulated charge you analyzed (accumulation performed per QA bin)
    • at the end of your event loop, the total accumulated charge you analyzed is given by QADB::GetAccumulatedCharge()

Caution

For Pass 1 QA results for Run Groups A, B, K, and M, we find some evidence that the charge from bin to bin may slightly overlap, or there may be gaps in the accumulated charge between each bin; the former leads to a slight over-counting and the latter leads to a slight under-counting

  • this issue is why we transitioned from using DST files as QA bins to using nth scaler readouts as bin boundaries
  • corrections of this issue to these older QADBs will not be applied

QADB Management

Documentation for QADB maintenance and revision

Adding to or revising the QADB

  • the QADB files are produced by clas12-timeline
  • if you have produced QA results for a new data set, and would like to add them to the QADB, or if you would like to update results for an existing dataset, follow the following procedure:
    • mkdir qadb/pass${pass}/${dataset}/, then copy the final qaTree.json and chargeTree.json to that directory
    • add/update a symlink to this dataset in qadb/latest, if this is a new Pass
    • run source environ.sh, then bin/makeTables.sh
    • update customized QA criteria sets, such as OkForAsymmetry this function is no longer maintained
    • update the above table of data sets
    • submit a pull request

Adding new defect bits

  • defect bits must be added in the following places:
    • Groovy:
      • src/clasqa/Tools.groovy (copy from clasqa repository version)
      • src/clasqa/QADB.groovy
      • src/examples/dumpQADB.groovy (optional)
    • C++:
      • srcC/include/QADB.h
      • srcC/examples/dumpQADB.cpp (optional)
    • Documentation:
      • qadb/defect_definitions.json, then use bin/makeDefectMarkdown.rb to generate Markdown table for README.md

Contributions

All contributions are welcome, whether to the code, examples, documentation, or the QADB itself. You are welcome to open an issue and/or a pull request. If the maintainer(s) do not respond in a reasonable time, send them an email.