add documentation for manual reduction

Signed-off-by: Jose Borreguero <[email protected]>
neutrons · Jul 9, 2024 · 7c5e08b · 7c5e08b
1 parent fc3b073
commit 7c5e08b
Show file tree

Hide file tree

Showing 9 changed files with 94 additions and 17 deletions.
diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml
@@ -35,6 +35,12 @@ jobs:
         run: |
           echo "running integration tests"
           git submodule update --init
+          echo "CONTENTS OF ./test/mr_reduction-data"
+          ls ./test/mr_reduction-data
+          echo "SHA in parent repo:"
+          git ls-tree $(git branch --show-current) ./tests/mr_reduction-data
+          echo "SHA in submodule:"
+          git submodule status ./tests/mr_reduction-data
           python -m pytest -vv -m "datarepo" --cov=src --cov-report=xml  --cov-report=term-missing tests/
           mv .coverage .coverage.integration
       - name: combine coverage reports

diff --git a/docs/index.rst b/docs/index.rst
@@ -16,17 +16,11 @@ User Guide
 
 Contacting the Team
 +++++++++++++++++++
-The best mechanism for a user to request a change or report a bug is to contact the SANS CIS.
+The best mechanism for a user to request a change or report a bug is to contact the Computer Instrument Scientist.
 Please email `Mathieu Doucet`_ with your request.
 
 .. _Mathieu Doucet: [email protected]
 
-A change needs to be in the form of a:
-
-- Story for any enhancement request
-- Defect for any bug fix request.
-
-
 Developer Guide
 ---------------
 

diff --git a/docs/user/conda_environments.rst b/docs/user/conda_environments.rst
@@ -3,8 +3,8 @@
 Conda Environments
 ==================
 
-Three conda environments are available in the analysis nodes, beamline machines, as well as the
-jupyter notebook severs. On a terminal:
+Three conda environments are available in the analysis nodes (analysis.sns.gov), beamline machines, as well as the
+jupyter notebook severs (jupyter.sns.gov). On a terminal:
 
 .. code-block:: bash
 
@@ -14,16 +14,16 @@ where `<environment>` is one of `mr_reduction`, `mr_reduction-qa`, and `mr_reduc
 
 mr_reduction Environment
 ------------------------
-Activates the latest stable release of `mr_reduction`. Typically users will reduce their data in this environment.
+Activates the latest production release of `mr_reduction`. Users will typically reduce their data in this environment.
 
 mr_reduction-qa Environment
 ---------------------------
-Activates a release-candidate environment.
+Activates the latest candidate release environment.
 Instrument scientists and computational instrument scientists will carry out testing on this environment
-to prevent bugs being introduce in the next stable release.
+to prevent bugs being introduce in the next production release.
 
 mr_reduction-dev Environment
 ----------------------------
 Activates the environment corresponding to the latest changes in the source code.
-Instrument scientists and computational instrument scientists will test the latest changes to `mr_reduction` in this
-environment.
+Instrument scientists and computational instrument scientists will test the latest features and bugfixes
+introduced in `mr_reduction`.
diff --git a/docs/user/media/manual_reduction.GIF b/docs/user/media/manual_reduction.GIF
diff --git a/docs/user/media/manual_reduction_report.GIF b/docs/user/media/manual_reduction_report.GIF
diff --git a/docs/user/media/manual_reduction_two_samples.GIF b/docs/user/media/manual_reduction_two_samples.GIF
diff --git a/docs/user/media/manual_reduction_two_samples_report.GIF b/docs/user/media/manual_reduction_two_samples_report.GIF
diff --git a/docs/user/reduce.rst b/docs/user/reduce.rst
@@ -1,6 +1,83 @@
 .. using_reduce_script
 
+Reduction
+=========
+
+
+Manual Reduction
+----------------
+Terminal command `reduce_REF_M` is available on the three conda environments. Running this command starts
+a simple web application to configure reduction of a single experiment.
+
+ .. code-block:: bash
+
+   > reduce_REF_M
+   **********************************************
+   * POINT YOUR BROWSER TO http://127.0.0.1:5000/
+   **********************************************
+   [2024-07-09 11:20:06 -0400] [278702] [INFO] Starting gunicorn 21.2.0
+   [2024-07-09 11:20:06 -0400] [278702] [INFO] Listening at: http://0.0.0.0:5000 (278702)
+   [2024-07-09 11:20:06 -0400] [278702] [INFO] Using worker: sync
+   [2024-07-09 11:20:06 -0400] [278707] [INFO] Booting worker with pid: 278707
+
+As the printout suggest, open a tab in your browser and enter address `http://127.0.0.1:5000/`.
+This webapp allows one to reduce a single run by entering the Nexus events file, entering the directory
+storing the reduced files, and selecting reduction options.
+Hovering over the bold-face text items will show explanatory tooltips.
+
+.. figure:: ./media/manual_reduction.GIF
+   :alt: Configuration for manual reduction.
+   :align: center
+   :width: 900
+
+   Configuration for manual reduction.
+
+Click on the **Submit** button to start reduction. The reduction typically takes one to two minutes during which
+time both **Submit** and **View Report** buttons became disabled. After reduction is finished,
+click on **View Report** for a summary of the results.
+
+.. figure:: ./media/manual_reduction_report.GIF
+   :alt: Report for the manual reduction.
+   :align: center
+   :width: 900
+
+   Report for the manual reduction.
+
+The report shown is HTML file `/tmp/test_webform/REF_M_REF_M_41445.html`, where `/tmp/test_webform/` is the
+output directory we selected.
+
+Notice how the report shows the superposition of reflectivity curves for runs 41445, 41446, and 41447. This
+will happen if reduced files for runs 41446 and 41447 are found either in the output directory `/tmp/test_webform`
+or the canonical output directory for autoreduction of runs corresponding to run 41445 which in this
+case is `/SNS/REF_M/IPTS-21391/shared/autoreduce/`. Runs 41445, 41446, and 41447 correspond to experiments
+taken on the same sample but with a different incidence angle.
+
+The webapp supports reduction of up to three samples for the scenarios when the run contains more than one sample.
+In the following screenshot we selected `Sample Count=2`, causing reduction taking into account options
+from `Sample #1` and `Sample #2`.
+
+.. figure:: ./media/manual_reduction_two_samples.GIF
+   :alt: Reduction of two samples.
+   :align: center
+   :width: 900
+
+   Reduction of two samples.
+
+The below excerpt from the corresponding report show the reflectivity curves for the two samples (41445_1 and 41445_2).
+
+.. figure:: ./media/manual_reduction_two_samples_report.GIF
+   :alt: Report for two samples.
+   :align: center
+   :width: 700
+
+   Report for two samples.
+
+
 Automated Reduction
-===================
+-------------------
 
-TBA
+The set of reduction options available in the manual reduction is also available in
+`https://monitor.sns.gov/reduction/ref_m/`. Updating these options ensure that auto-reduction
+of future experiment will employ the new options.
+Auto-reduced files are saved under directory `/SNS/REF_M/IPTS-XYZ/shared/autoreduce/`, where `XYZ` corresponds
+to the IPTS number associated to whatever run number is to be auto-reduced.
diff --git a/src/mr_autoreduce/reduce_REF_M_run.sh b/src/mr_autoreduce/reduce_REF_M_run.sh
@@ -3,4 +3,4 @@ echo "* POINT YOUR BROWSER TO http://127.0.0.1:5000/"
 echo "**********************************************"
 
 export PYTHONPATH="${PYTHONPATH}:$(dirname "$0")"
-exec gunicorn --timeout 60 --bind :5000 mr_reduction.reduce_REF_M_run:app
+exec gunicorn --timeout 60 --bind :5000 mr_autoreduce.reduce_REF_M_run:app