feat: calculate gap and overlapping charge from Pass 1 QADB (#47)

README.md

@@ -1,4 +1,4 @@
-![QADB](/util/logo.png)
+![QADB](/doc/logo.png)
 
 # CLAS12 Quality Assurance Database
 Provides storage of and access to the QA monitoring results for the 
@@ -15,6 +15,9 @@ CLAS12 experiment at Jefferson Lab
 <a name="info"></a>
 # QA Information
 
+> [!CAUTION]
+> The QADB for older data sets may have some issues. It is **HIGHLY recommended** to [check the known important issues](/doc/issues.md) 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)

doc/issues.md

@@ -0,0 +1,9 @@
+# Issues Relevant for Physics Analysis
+
+This page lists known issues which have potential impact on physics data analysis; such issues are a subset of the [GitHub issues](https://github.com/JeffersonLab/clas12-qadb/issues), focusing on only the issues that are relevant to user analysis.
+
+| Dataset | Impact | Issue and Details |
+| --- | --- | --- |
+| Pass-1 Run Groups A, B, K, M | QA cut boundaries and charge may be ill-defined for some runs | https://github.com/JeffersonLab/clas12-qadb/issues/9 |
+| Pass-1 Run Group A | FC charge is incorrect for a set of runs | https://github.com/JeffersonLab/clas12-qadb/issues/12 |
+| Pass-1 Run Groups A, B, K, M | Accumulated FC charge is inaccurate | https://github.com/JeffersonLab/clas12-qadb/issues/48 |

src/clasqa/QADB.groovy

@@ -189,7 +189,10 @@ class QADB {
   public String getComment() { return found ? comment : "" }
   public int getEvnumMin() { return found ? evnumMin : -1 }
   public int getEvnumMax() { return found ? evnumMax : -1 }
-  public double getCharge() { return found ? charge : -1 }
+  public double getCharge() {
+    System.err.println "WARNING: the charge stored in the Pass 1 QADB for Run Groups A, B, K, and M is NOT quite correct, and may be off by ~1%, depending on the particular runs! This will be fixed for their Pass 2 data sets."
+    return found ? charge : -1
+  }
   // --- access QA info
   // check if the file has a particular defect
   // - if sector==0, checks the OR of all the sectors
@@ -350,7 +353,10 @@ class QADB {
   }
   // -- accessor
   // call this method at the end of your event loop
-  public double getAccumulatedCharge() { return chargeTotal }
+  public double getAccumulatedCharge() {
+    System.err.println "WARNING: the charge stored in the Pass 1 QADB for Run Groups A, B, K, and M is NOT quite correct, and may be off by ~1%, depending on the particular runs! This will be fixed for their Pass 2 data sets."
+    return chargeTotal
+  }
   // reset accumulated charge, if you ever need to
   public void resetAccumulatedCharge() { chargeTotal = 0 }
 

srcC/include/QADB.h

@@ -67,7 +67,10 @@ namespace QA {
       inline std::string GetComment() { return found ? comment : ""; };
       inline int GetEvnumMin() { return found ? evnumMin : -1; };
       inline int GetEvnumMax() { return found ? evnumMax : -1; };
-      inline double GetCharge() { return found ? charge : -1; };
+      inline double GetCharge() {
+        std::cerr << "WARNING: the charge stored in the Pass 1 QADB for Run Groups A, B, K, and M is NOT quite correct, and may be off by ~1%, depending on the particular runs! This will be fixed for their Pass 2 data sets." << std::endl;
+        return found ? charge : -1;
+      }
       // --- access QA info
       // check if the file has a particular defect
       // - if sector==0, checks the OR of all the sectors
@@ -119,7 +122,10 @@ namespace QA {
       // -- accessor
       // returns total accumlated charge that passed your QA cuts; call this
       // method after your event loop
-      inline double GetAccumulatedCharge() { return chargeTotal; };
+      inline double GetAccumulatedCharge() {
+        std::cerr << "WARNING: the charge stored in the Pass 1 QADB for Run Groups A, B, K, and M is NOT quite correct, and may be off by ~1%, depending on the particular runs! This will be fixed for their Pass 2 data sets." << std::endl;
+        return chargeTotal;
+      }
       // reset accumulated charge, if you ever need to
       inline void ResetAccumulatedCharge() { chargeTotal = 0; };
 

util/gap_charge_systematic/.gitignore

@@ -0,0 +1 @@
+*.dat

util/gap_charge_systematic/README.md

@@ -0,0 +1,8 @@
+The code in this directory is used for estimating a systematic uncertainty on the accumulated FC charge, based on <https://github.com/JeffersonLab/clas12-qadb/issues/48>.
+
+### Procedure
+
+- edit the scripts such that the specific list of runs is used
+- `run-groovy calculateGapCharge.groovy`
+- `root analyzeGapCharge.C`
+- the mean of the resulting fractional charge-difference distribution is the systematic uncertainty