feat!: handle cook version (pass1 vs. pass2) (#52)

src/clasqa/QADB.groovy

@@ -11,20 +11,29 @@ class QADB {
   // constructor
   //``````````````
   // arguments:
+  // - cook: which cook (pass) to use:
+  //   - 'latest': just use the latest available one
+  //   - 'pass1': use pass 1
+  //   - 'pass2': use pass 2
   // - runnumMin and runnumMax: if both are negative (default), then the
   //   entire QADB will be read; you can restrict to a specific range of
   //   runs to limit QADB, which may be more effecient
   // - verbose: if true, print (a lot) more information
-  public QADB(int runnumMin=-1, runnumMax=-1, boolean verbose_=false) {
+  public QADB(String cook, int runnumMin=-1, runnumMax=-1, boolean verbose_=false) {
 
     // setup
     verbose = verbose_
     util = new Tools()
     nbits = util.bitDefinitions.size()
-    dbDirN = System.getenv('QADB') + '/qadb/latest'
+    dbDirN = System.getenv('QADB')
     if(dbDirN==null) {
-      System.err << "ERROR: env var QADB not set; source environ.sh\n\n\n"
-      return
+      throw new Exception("env var QADB not set; source environ.sh")
+    }
+    dbDirN += '/qadb'
+    if(cook in ["latest", "pass1", "pass2"]) {
+      dbDirN += "/${cook}"
+    } else {
+      throw new Exception("cook '${cook}' is not available in the QADB")
     }
     if(verbose) println("QADB dir = ${dbDirN}")
 
@@ -112,6 +121,19 @@ class QADB {
     allowMiscBitList = []
   }
 
+  public QADB(int runnumMin=-1, runnumMax=-1, boolean verbose_=false) {
+    System.err.print('''| ERROR: the QADB constructor now requires you to specify the cook as the first argument
+|   - use "latest" to use the latest available cook's QADB
+|     - see the QADB documentation for the list of available QADBs,
+|       https://github.com/JeffersonLab/clas12-qadb/blob/main/README.md
+|     - the latest cook may not yet have a QADB
+|   - use "pass1" to restrict to Pass 1 cooks
+|     - older data may have less QA defect bits, or other issues
+|   - use "pass2" to restrict to Pass 2 data, etc.
+''')
+    throw new Exception("please specify the cook");
+  }
+
   //...............................
   // deprecation warnings
   //```````````````````````````````

src/examples/chargeSum.groovy

@@ -16,9 +16,9 @@ reader.open(inHipoFile)
 
 
 // instantiate QADB
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 // alternatively, specify run range to restrict QADB (may be more efficient)
-//QADB qa = new QADB(5000,5500);
+//QADB qa = new QADB("latest",5000,5500);
 
 
 // define variables

src/examples/cutAsymmetry.groovy

@@ -15,9 +15,9 @@ reader.open(inHipoFile)
 
 
 // instantiate QADB
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 // alternatively, specify run range to restrict QADB (may be more efficient)
-//QADB qa = new QADB(5000,5500);
+//QADB qa = new QADB("latest",5000,5500);
 
 
 // define variables

src/examples/cutCustom.groovy

@@ -16,9 +16,9 @@ reader.open(inHipoFile)
 
 
 // instantiate QADB
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 // alternatively, specify run range to restrict QADB (may be more efficient)
-//QADB qa = new QADB(5000,5500);
+//QADB qa = new QADB("latest",5000,5500);
 
 
 // custom QA cut definition

src/examples/cutGolden.groovy

@@ -16,9 +16,9 @@ reader.open(inHipoFile)
 
 
 // instantiate QADB
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 // alternatively, specify run range to restrict QADB (may be more efficient)
-//QADB qa = new QADB(5000,5500);
+//QADB qa = new QADB("latest",5000,5500);
 
 
 // define variables

src/examples/dumpQADB.groovy

@@ -18,9 +18,9 @@ println "dump QADB for RUN NUMBER $runnum"
 
 
 // instantiate QADB
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 // alternatively, specify run range to restrict QADB (may be more efficient)
-//QADB qa = new QADB(5000,5500);
+//QADB qa = new QADB("latest",5000,5500);
 
 
 // loop through QA bins

src/tests/testCharge.groovy

@@ -6,9 +6,9 @@ import clasqa.QADB // access QADB
 
 
 // instantiate QADB
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 // alternatively, specify run range to restrict QADB (may be more efficient)
-//QADB qa = new QADB(5000,5500);
+//QADB qa = new QADB("latest",5000,5500);
 int evnum
 def defname
 int chargeInt

src/tests/testDumpQADB.groovy

@@ -24,9 +24,9 @@ println "test QADB for RUN NUMBER $runnum"
 
 
 // instantiate QADB
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 // alternatively, specify run range to restrict QADB (may be more efficient)
-//QADB qa = new QADB(5000,5500);
+//QADB qa = new QADB("latest",5000,5500);
 
 
 // loop through files

src/tests/testOkForAsymmetry.groovy

@@ -9,7 +9,7 @@ System.out.println("WARNING: run with `-Xmx4096m`")
 // to avoid in their analysis, and a list of runs for which the `Misc` defect bit
 // should be ignored
 System.out.println('Loading QADBs...\n...1/3...')
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 qa.checkForDefect('TotalOutlier')     // these choices match the criteria of `OkForAsymmetry`
 qa.checkForDefect('TerminalOutlier')
 qa.checkForDefect('MarginalOutlier')
@@ -32,9 +32,9 @@ qa.checkForDefect('Misc')
 
 // instantiate more QADBs, for comparison (`qa` will use the general method)
 System.out.println('...2/3...')
-QADB qa_deprecated = new QADB()  // will use `OkForAsymmetry`, which is deprecated
+QADB qa_deprecated = new QADB("latest")  // will use `OkForAsymmetry`, which is deprecated
 System.out.println('...3/3...')
-QADB qa_third_party = new QADB() // a third party, only used for DB traversal
+QADB qa_third_party = new QADB("latest") // a third party, only used for DB traversal
 System.out.println('...done')
 
 // compare the QADBs' results: prove the above general method is equivalent to `OkForAsymmetry`

srcC/examples/chargeSum.cpp

@@ -27,9 +27,9 @@ int main(int argc, char** argv) {
 
 
   // instantiate QADB
-  QADB * qa = new QADB();
+  QADB * qa = new QADB("latest");
   // alternatively, specify run range to restrict QADB (may be more efficient)
-  //QADB * qa = new QADB(5000,5500);
+  //QADB * qa = new QADB("latest",5000,5500);
 
 
   // define variables

srcC/examples/cutAsymmetry.cpp

@@ -26,9 +26,9 @@ int main(int argc, char** argv) {
 
 
   // instantiate QADB
-  QADB * qa = new QADB();
+  QADB * qa = new QADB("latest");
   // alternatively, specify run range to restrict QADB (may be more efficient)
-  //QADB * qa = new QADB(5000,5500);
+  //QADB * qa = new QADB("latest",5000,5500);
 
 
   // define variables

srcC/examples/cutCustom.cpp

@@ -28,9 +28,9 @@ int main(int argc, char** argv) {
 
 
   // instantiate QADB
-  QADB * qa = new QADB();
+  QADB * qa = new QADB("latest");
   // alternatively, specify run range to restrict QADB (may be more efficient)
-  //QADB * qa = new QADB(5000,5500);
+  //QADB * qa = new QADB("latest",5000,5500);
 
   // custom QA cut definition
   // - decide which defects you want to check for; an event will not pass

srcC/examples/cutGolden.cpp

@@ -27,9 +27,9 @@ int main(int argc, char** argv) {
 
 
   // instantiate QADB
-  QADB * qa = new QADB();
+  QADB * qa = new QADB("latest");
   // alternatively, specify run range to restrict QADB (may be more efficient)
-  //QADB * qa = new QADB(5000,5500);
+  //QADB * qa = new QADB("latest",5000,5500);
 
 
   // define variables

srcC/examples/dumpQADB.cpp

@@ -26,9 +26,9 @@ int main(int argc, char ** argv) {
 
 
   // instantiate QADB
-  QADB * qa = new QADB();
+  QADB * qa = new QADB("latest");
   // alternatively, specify run range to restrict QADB (may be more efficient)
-  //QADB * qa = new QADB(5000,5500);
+  //QADB * qa = new QADB("latest",5000,5500);
 
 
   // loop through QA bins

srcC/include/QADB.h

@@ -42,12 +42,28 @@ namespace QA {
       // constructor
       //`````````````````
       //arguments:
+      // - cook: which cook (pass) to use:
+      //   - 'latest': just use the latest available one
+      //   - 'pass1': use pass 1
+      //   - 'pass2': use pass 2
       // - runnumMin and runnumMax: if both are negative (default), then the
       //   entire QADB will be read; you can restrict to a specific range of
       //   runs to limit QADB, which may be more effecient
       // - verbose: if true, print (a lot) more information
-      inline QADB(int runnumMin_=-1, int runnumMax=-1, bool verbose_=false);
-
+      inline QADB(std::string const& cook, int runnumMin_=-1, int runnumMax=-1, bool verbose_=false);
+
+      inline QADB(int runnumMin_=-1, int runnumMax=-1, bool verbose_=false) {
+        std::cerr << R"(| ERROR: the QADB constructor now requires you to specify the cook as the first argument
+|   - use "latest" to use the latest available cook's QADB
+|     - see the QADB documentation for the list of available QADBs,
+|       https://github.com/JeffersonLab/clas12-qadb/blob/main/README.md
+|     - the latest cook may not yet have a QADB
+|   - use "pass1" to restrict to Pass 1 cooks
+|     - older data may have less QA defect bits, or other issues
+|   - use "pass2" to restrict to Pass 2 data, etc.
+)";
+        throw std::runtime_error("please specify the cook");
+      }
 
       //...............................
       // golden QA cut
@@ -228,7 +244,7 @@ namespace QA {
   //...............
   // constructor
   //```````````````
-  QADB::QADB(int runnumMin_, int runnumMax_, bool verbose_) {
+  QADB::QADB(std::string const& cook, int runnumMin_, int runnumMax_, bool verbose_) {
 
     runnumMin = runnumMin_;
     runnumMax = runnumMax_;
@@ -238,10 +254,14 @@ namespace QA {
     if(verbose) std::cout << "\n[+] find json files" << std::endl;
     std::string dbDirN = getenv("QADB") ? getenv("QADB") : "";
     if(dbDirN.compare("")==0) {
-      std::cerr << "ERROR: QADB environment variable not set" << std::endl;
-      return;
+      throw std::runtime_error("QADB environment variable not set");
     };
-    dbDirN += "/qadb/latest";
+    dbDirN += "/qadb";
+    std::set<std::string> cooks_avail{"latest", "pass1", "pass2"};
+    if(cooks_avail.find(cook) != cooks_avail.end())
+      dbDirN += std::string("/") + cook;
+    else
+      throw std::runtime_error("cook '" + cook + "' is not available in the QADB");
     if(verbose) std::cout << "QADB at " << dbDirN << std::endl;
 
     // get list of json files

srcC/tests/testCharge.cpp

@@ -14,9 +14,9 @@ using namespace std;
 int main(int argc, char ** argv) {
 
   // instantiate QADB
-  QADB * qa = new QADB();
+  QADB * qa = new QADB("latest");
   // alternatively, specify run range to restrict QADB (may be more efficient)
-  //QADB * qa = new QADB(5000,5500);
+  //QADB * qa = new QADB("latest",5000,5500);
   int evnum;
   string defname;
   int chargeInt;

srcC/tests/testDumpQADB.cpp

@@ -32,9 +32,9 @@ int main(int argc, char ** argv) {
 
 
   // instantiate QADB
-  QADB * qa = new QADB();
+  QADB * qa = new QADB("latest");
   // alternatively, specify run range to restrict QADB (may be more efficient)
-  //QADB * qa = new QADB(5000,5500);
+  //QADB * qa = new QADB("latest",5000,5500);
 
 
 

srcC/tests/testOkForAsymmetry.cpp

@@ -14,7 +14,7 @@ int main(int argc, char ** argv) {
   // to avoid in their analysis, and a list of runs for which the `Misc` defect bit
   // should be ignored
   std::cout << "Loading QADBs..." << std::endl;
-  auto qa = new QA::QADB();
+  auto qa = new QA::QADB("latest");
   qa->CheckForDefect("TotalOutlier");     // these choices match the criteria of `OkForAsymmetry`
   qa->CheckForDefect("TerminalOutlier");
   qa->CheckForDefect("MarginalOutlier");
@@ -36,8 +36,8 @@ int main(int argc, char ** argv) {
 
 
   // instantiate more QADBs, for comparison (`qa` will use the general method)
-  auto qa_deprecated = new QA::QADB();  // will use `OkForAsymmetry`, which is deprecated
-  auto qa_third_party = new QA::QADB(); // a third party, only used for DB traversal
+  auto qa_deprecated = new QA::QADB("latest");  // will use `OkForAsymmetry`, which is deprecated
+  auto qa_third_party = new QA::QADB("latest"); // a third party, only used for DB traversal
   std::cout << "...done" << std::endl;
 
   // compare the QADBs' results: prove the above general method is equivalent to `OkForAsymmetry`

util/access.groovy

@@ -9,7 +9,7 @@ import clasqa.QADB
 import clasqa.Tools
 
 Tools T = new Tools()
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 
 /*
 println "=========== raw"

util/chargeSumRuns.groovy

@@ -15,7 +15,7 @@ if(args.length==2) {
 }
 else { System.err << "ARGUMENTS: [runLB] [runUB]\n"; return; }
 println "run range: $runLB to $runUB"
-QADB qa = new QADB(runLB,runUB)
+QADB qa = new QADB("latest",runLB,runUB)
 
 
 // loop over runs and files

util/gap_charge_systematic/calculateGapCharge.groovy

@@ -16,7 +16,7 @@ if(args.length<1) {
   System.exit(101)
 }
 def arg_runnum = args[0].toInteger()
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 
 // define output file
 def datfileName   = "charge_gaps.dat"

util/makeLatexTable2.groovy

@@ -11,7 +11,7 @@ if(args.length==2) {
 }
 else { System.err << "ARGUMENTS: [runLB] [runUB]\n"; return; }
 println "run range: $runLB to $runUB"
-QADB qa = new QADB(runLB,runUB)
+QADB qa = new QADB("latest",runLB,runUB)
 
 def nPassQA, nTotal
 def exList = []

util/parseQaTree.groovy

@@ -6,7 +6,7 @@ import clasqa.Tools
 Tools T = new Tools()
 /*
 import clasqa.QADB
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 */
 
 infile="qa/qaTree.json"

util/printGoldenFiles.groovy

@@ -2,7 +2,7 @@
 // - "golden" means no defects
 
 import clasqa.QADB
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 
 // open output file writer
 def outFileObj = new File(System.getenv('QADB')+"/text/listOfGoldenFiles.txt")

util/printGoldenRuns.groovy

@@ -5,7 +5,7 @@
 
 import clasqa.QADB
 
-QADB qa = new QADB()
+QADB qa = new QADB("latest")
 def gold,silver
 def defect
 

util/printSummary.cpp

@@ -6,7 +6,7 @@ using namespace std;
 
 int main(int argc, char ** argv) {
 
-  QA::QADB * qa = new QA::QADB();
+  QA::QADB * qa = new QA::QADB("latest");
 
   /// get sorted list of runs
   auto qaTree = qa->GetQaTree();