doc: update all documentation in preparation for v1.0 (#114)

README.md

@@ -1,6 +1,6 @@
 # clas12-timeline
 
-Timeline production for CLAS12. Timelines are deployed to [clas12mon](https://clas12mon.jlab.org).
+Timeline production for CLAS12. Timelines are deployed to [`clas12mon`](https://clas12mon.jlab.org).
 
 ## Setup
 
@@ -15,26 +15,25 @@ mvn package
 ```
 #### Additional Build Notes:
 - Use `mvn clean` if you want to clean build targets. 
-- The [top-level POM](pom.xml) includes the following submodules, which you may build individually with the `-f` option of `mvn`:
-  1. [`monitoring`](monitoring): generate histograms for detectors
+- Use the `-f` option of `mvn` to build individual submodules:
+  1. [`monitoring`](monitoring): generates histograms for detectors
   1. [`detectors`](detectors): uses detector histograms to generate timelines
 
 ## Procedure
 
 Two types of timelines are produced:
-1. Detector timelines, to monitor detector parameters, histograms, and calibration
-2. Physics timelines, to monitor higher-level quantities to perform Quality Assurance (QA) for physics analysis
+1. **Detector timelines**: monitor detector parameters, histograms, and calibration
+1. **Physics timelines**: monitor higher-level quantities to perform Quality Assurance (QA) for physics analysis
 
-NOTE: physics timeline production and QA are typically only valuable on high-statistics datasets; you may not want
-to produce them if you are only interested in detector timelines.
+NOTE: physics timeline production and QA are typically only valuable on high-statistics datasets, whereas detector timelines need files produced with `mon` schema, which are typically only produced with low statistics; therefore, for a given dataset, typically one set of timelines is produced but not the other.
 
-Both of these timeline types are produced in two stages:
+Both of these timeline types are produced in the following steps:
 
-### Stage 1: Data Monitoring
+### Step 1: Data Monitoring
 
-This stage reads DST files and produces histograms and auxiliary files, which are then consumed by Stage 2 to produce the timelines. Since DST files are read, it is recommended to use a computing cluster.
+This step reads input HIPO files (_e.g._, DST or `mon` files) and produces histograms and auxiliary files, which are then consumed by Step 2 to produce the timelines. Since many input files are read, it is recommended to use a computing cluster.
 
-To run this stage, execute:
+To run this step, execute:
 ```bash
 bin/run-monitoring.sh
 ```
@@ -46,9 +45,9 @@ which will print the usage guide, along with some examples (since it was called
 - data monitoring for physics timelines is handled by the [`qa-physics/` subdirectory](qa-physics);
   see [its documentation](qa-physics/README.md)
 
-### Stage 2: Timeline Production and QA
+### Step 2: Timeline Production and QA
 
-After Stage 1 is complete, run the following Stage 2 scripts to produce the timeline `HIPO` files and to run the automatic QA procedures. Run them with no arguments to print the usage guides.
+After Step 1 is complete, run the following Step 2 scripts to produce the timeline HIPO files and to run the automatic QA procedures. There is one script for each timeline type: run them with no arguments to print the usage guides:
 
 ```bash
 bin/run-detectors-timelines.sh
@@ -63,9 +62,9 @@ bin/run-physics-timelines.sh
 - physics timeline production and QA are handled by the [`qa-physics/` subdirectory](qa-physics);
   see [their documentation](qa-physics/README.md)
 
-### Stage 3: Deployment
+### Step 3: Deployment
 
-To view the timelines on the web, you must deploy them by copying the timeline HIPO files to a directory served to the web. Note that you must have write-permission for that directory. To deploy, run (with no arguments, for the usage guide):
+To view the timelines on the web, you must deploy them by copying the timeline HIPO files to a directory with a running web server. Note that you must have write-permission for that directory. To deploy, run (with no arguments, for the usage guide):
 
 ```bash
 bin/deploy-timelines.sh
@@ -74,15 +73,8 @@ bin/deploy-timelines.sh
 If all went well, a URL for the new timelines will be printed; open it in a browser to view them.
 
 
-## QA Database (QADB) Production
-
-The [QADB](https://github.com/JeffersonLab/clas12-qadb) is produced by the physics timeline QA, typically only for a fully cooked dataset. It is automatically produced from the physics QA, but it is highly recommended to perform a "manual QA" afterward, by looking at the automatic QA results, cross checking with the experimental log book, and modifying the QADB accordingly.
-
-See [its documentation here](qa-physics) for more details.
-
-
 # Flowchart
-Here is a flowchart illustrating the data and steps for timeline production:
+Here is a flowchart illustrating the data and steps for timeline production. See the next section for details on output file organization.
 
 ```mermaid
 flowchart TB
@@ -222,8 +214,15 @@ top_level_target_directory
   │
   └── ...
 ```
-For compatibility with the file tree expected by downstream `bin/run-*-timelines.sh` scripts (see above), symbolic links may be made to these `timeline_{detectors,physics}` directories.
+For compatibility with the file tree expected by downstream `bin/run-*-timelines.sh` scripts (see above), symbolic links may be made to these `timeline_{detectors,physics}` directories, but this is not required since these scripts also allow for the specification of an input directory.
 
 Separate `--focus-detectors` and `--focus-physics` options are preferred, since:
 - offers better organization of the contract data between `swif` jobs and downstream scripts
 - often we will run one and not the other: `--focus-detectors` needs `mon` schema, whereas `--focus-physics` prefers high statistics
+
+
+## QA Database (QADB) Production
+
+The [QADB](https://github.com/JeffersonLab/clas12-qadb) is produced by the physics timeline QA, typically only for a fully cooked dataset. It is automatically produced from the physics QA, but it is highly recommended to perform a "manual QA" afterward, by looking at the automatic QA results, cross checking with the experimental log book, and modifying the QADB accordingly.
+
+See [its documentation here](qa-physics) for more details.

detectors/README.md

@@ -1,2 +1,5 @@
-# Timeline code
-This the the directory with code for producing timelines. To run it, [look one directory above](/../../)
+# Detector Timeline Production
+
+This is the submodule for producing detector timelines. The primary executable is `run.groovy`, found within its source code. 
+
+To run it, it is better to follow the [main documentation](../README.md).

monitoring/README.md

@@ -1,34 +1,41 @@
-# clas12_monitoring
-An independent set of classes for clas12 monitoring
+# `clas12_monitoring`
+An independent set of classes for clas12 monitoring of detectors
 
-Current active branches in the repo only supports hipo4 and coatjava6.
+Follow the [main documentation](../README.md) for guidance, otherwise continue reading this file for details on detector monitoring code and execution.
 
+## How to run the detector monitoring code
 
-## How to run the monitoring codes
+For example, the run 11127 of Run Group B can be monitored in following steps.
 
-For example, the run 11127 of rg-b can be monitored in following steps.
+The first step is to create the list of files to be monitored:
+```bash
+ls /cache/clas12/rg-b/production/decoded/6.5.6/011127/*.hipo > list11127.txt
+mkdir plots11127
+```
 
-- ```ls /cache/clas12/rg-b/production/decoded/6.5.6/011127/* > list11127.txt```
-- ```mkdir plots11127```
-- ```java -DCLAS12DIR="$COATJAVA" -cp "$COATJAVA/lib/clas/*:$COATJAVA/lib/utils/*:target/*" org.jlab.clas12.monitoring.ana_2p2 11127 plots list11127.txt 100000000 10.4```
+Next run the compiled code, after setting some environment variables from [`environ.sh`](../bin/environ.sh):
+```bash
+source ../bin/environ.sh
+java $TIMELINE_JAVA_OPTS org.jlab.clas12.monitoring.ana_2p2 11127 plots11127 list11127.txt 100000000 10.4
+```
+ Change 11127 to the wanted run number. The last two arguments are the maximum number of events to monitor, and the beam energy (10.4 GeV for example).
 
-The first step is to create the list of files to be monitored, and the second one is to run the compiled codes for monitoring. Change 11127 to the wanted run number. The last two arguments are the maximum event numbers to monitor, and the beam energy (10.4 GeV for example).
-
-The class ana_2p2 runs [all source codes](src/main/java/org/jlab/clas12/monitoring). If it is enough to create updates in a specific detector monitoring, one can run the relevant code only. For example, for DC and TOF monitoring, please use org.jlab.clas12.monitoring.tof_monitoring.
+The class `ana_2p2` runs [all detectors' monitoring](src/main/java/org/jlab/clas12/monitoring). If it is enough to create updates in a specific detector monitoring, one can run the relevant code only. For example, for DC and TOF monitoring, please use `org.jlab.clas12.monitoring.tof_monitor`.
 
 Currently, each detector is related to the following class names.
 
-- All detectors: ana_2p2
-- BAND: BAND
-- CVT, CTOF: central
-- CND: cndCheckPlots
-- general DST monitoring: monitor2p2GeV
-- rgb LD2 target: deutrontarget
-- rgb specific DST monitoring: dst_mon
-- FT: FT
-- HTCC: HTCC
-- LTCC: LTCC
-- CVT occupancies: occupancies
-- RICH: RICH
-- DC, FTOF: tof_monitor
-
+| Detector(s)                 | Class           |
+| ---                         | ---             |
+| All detectors               | `ana_2p2`       |
+| BAND                        | `BAND`          |
+| CVT, CTOF                   | `central`       |
+| CND                         | `cndCheckPlots` |
+| general DST monitoring      | `monitor2p2GeV` |
+| rgb LD2 target              | `deutrontarget` |
+| rgb specific DST monitoring | `dst_mon`       |
+| FT                          | `FT`            |
+| HTCC                        | `HTCC`          |
+| LTCC                        | `LTCC`          |
+| CVT occupancies             | `occupancies`   |
+| RICH                        | `RICH`          |
+| DC, FTOF                    | `tof_monitor`   |

qa-detectors/README.md

@@ -1,23 +1,22 @@
-# qa-detectors
+# `qa-detectors`
 
-This procedure reads `clas12mon` detector timelines, and checks if certain parameters are within
+This procedure reads detector timelines and checks if certain parameters are within
 QA specifications.
 
 ## Defining the Specifications
 The specifications are specified by text files in [the `cuts` directory](cuts). The default file is `cuts/cuts.txt`
 - cuts file syntax:
   - each line should have the following columns, delimited by spaces:
     - detector name
-    - hipo file name
-    - lower bound
-    - upper bound
+    - HIPO file name (_i.e._, the timeline name, with spaces changed to underscores)
+    - lower bound of QA cut
+    - upper bound of QA cut
     - units
-    - (optional) additional specifier(s)
-  - comments can be added using the symbol `#`
-    - this is useful for commenting out timelines, especially when debugging a particular timeline
+    - (optional) additional specifier(s), _e.g._, specific sectors
+  - comments can be added using the symbol `#`, which is useful for commenting out timelines, especially when debugging a particular timeline
 - other files in `cuts/` may override the default file
-  - overrides are applied by comparing the `clas12mon` input timeline path to a regular expression
-  - see `util/applyBounds.groovy` for the mapping of regular expressions to overriding cuts file
+  - overrides are applied by comparing the input timeline path to a regular expression
+  - see [`util/applyBounds.groovy`](util/applyBounds.groovy) for the mapping of regular expressions to overriding cuts file
   - for example, paths which match the regular expression `/rga.*fa18/` could use the file `cuts/cuts_rga_fa18.txt`
 
 ## Procedure
@@ -26,10 +25,6 @@ The specifications are specified by text files in [the `cuts` directory](cuts).
   ../bin/run-detectors-timelines.sh               # print usage guide
   ../bin/run-detectors-timelines.sh  --focus-qa   # run detector QA only (for debugging this QA code; you may need to set other options)
   ```
+- see [main documentation](../README.md) for more details
 - note to developers: if you want to run local scripts, call `source ../bin/environ.sh` (this is
   automatically done when running the wrapper `../bin/run-detectors-timelines.sh`)
-- The URLs for the timelines will be printed upon success
-- The new timeline files will appear in `/path/to/timelines_qa` (or in the
-  custom directory, if you specified one), where any timeline hipo file to
-  which QA cuts were applied has replaced the original hipo file, with the name
-  "QA" appended to the file name

qa-physics/QA/meld/README.md

@@ -6,5 +6,5 @@ want to "meld" the new results with old results
 * this script is "one-time-use", so you need to read it carefully before
   running it
 * it assumes the file names are `qaTree.json.old` and `qaTree.json.new`
-* the ouptut will be `qaTree.json.melded`
+* the output will be `qaTree.json.melded`
 * be sure to backup any `qaTree.json` files in case something goes wrong