Feature #101 lulc metplus

.github/workflows/documentation.yml

@@ -17,21 +17,21 @@ jobs:
     name: Documentation
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.8'
       - name: Install dependencies
         run: |
           python -m pip install --upgrade -r docs/requirements.txt
       - name: Build Documentation
         run: ./.github/jobs/build_documentation.sh
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         if: always()
         with:
           name: i-wrf_documentation
           path: artifact/documentation
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         if: failure()
         with:
           name: documentation_warnings.log

docs/Users_Guide/use-cases/lulc/common/metplus.rst

@@ -0,0 +1,66 @@
+
+.. dropdown:: Run METplus
+
+  .. dropdown:: Define Environment Variables for METplus
+
+     Set environment variables to define paths and Docker image names::
+
+         METPLUS_IMAGE=ncar/iwrf-metplus:latest
+         OBS_DATA_VOL=lulc-input-obs-d03
+         OBS_DATA_IMAGE=ncar/iwrf-data:${OBS_DATA_VOL}.docker
+         METPLUS_OUTPUT=~/metplus_out
+         METPLUS_CONFIG_DIR=~/i-wrf/use_cases/Land_Use_Land_Cover/METplus
+         PLOT_SCRIPT_DIR=~/i-wrf/use_cases/Land_Use_Land_Cover/Visualization
+
+     The path to the WRF data to be read into METplus depends on how WRF was
+     run in the previous steps.
+     Set the **WRF_TOP_DIR** environment variable using one of the following approaches:
+
+     If the Control simulation was run, set::
+
+        WRF_TOP_DIR=${WRF_OUTPUT}/ctl
+
+     If the DFW 4x simulation was run, set::
+
+        WRF_TOP_DIR=${WRF_OUTPUT}/dfw4x
+
+     If the WRF simulation was not run and the output was obtained via Ceph, set::
+
+        WRF_TOP_DIR=~/lulc_full_output
+
+
+  .. dropdown:: Get METplus Docker Images
+
+     The METplus software and observation data are both available on DockerHub.
+     Run commands to pull the images and create the Docker data volume::
+
+         sudo docker pull ${METPLUS_IMAGE}
+         sudo docker pull ${OBS_DATA_IMAGE}
+         sudo docker create --name ${OBS_DATA_VOL} ${OBS_DATA_IMAGE}
+
+  .. dropdown:: Run METplus Verification
+
+    The LULC use case includes verification for two meteorological variables:
+    accumulated precipitation and radar reflectivity.
+    Each verification is run separately using its own METplus configuration file.
+    Run the accumulated precipitation verification::
+
+        docker run --rm -it \
+          --volumes-from ${OBS_DATA_VOL} \
+          -v ${METPLUS_CONFIG_DIR}:/config \
+          -v ${PLOT_SCRIPT_DIR}:/plot_scripts \
+          -v ${WRF_TOP_DIR}:/data/input/wrf \
+          -v ${METPLUS_OUTPUT}:/data/output ${METPLUS_IMAGE} \
+          /metplus/METplus/ush/run_metplus.py /config/GridStat_apcp_lulc.conf \
+          config.FCST_PCP_COMBINE_INPUT_TEMPLATE="wrfout_d03_{valid?fmt=%Y-%m-%d_%H:%M}:*"
+
+    Run the reflectivity verification::
+
+        docker run --rm -it \
+          --volumes-from ${OBS_DATA_VOL} \
+          -v ${METPLUS_CONFIG_DIR}:/config \
+          -v ${PLOT_SCRIPT_DIR}:/plot_scripts \
+          -v ${WRF_TOP_DIR}:/data/input/wrf \
+          -v ${METPLUS_OUTPUT}:/data/output ${METPLUS_IMAGE} \
+          /metplus/METplus/ush/run_metplus.py /config/GridStat_refc_lulc.conf \
+          config.FCST_GRID_STAT_INPUT_TEMPLATE="wrfout_d03_{valid?fmt=%Y-%m-%d_%H:%M}:*"

docs/Users_Guide/use-cases/lulc/jetstream2.rst

@@ -134,3 +134,20 @@ to secure access to and log in to Jetstream2.
         df -h ${mountPoint}
 
     The full output should be in ``/home/exouser/lulc_full_output``.
+
+  .. include:: lulc/common/metplus.rst
+
+  .. dropdown:: View the Plotted Simulation Results
+
+    The METplus container also plots the results of the simulation, outputting them as PNG images.
+    To view these images:
+
+    * Find the desktop shortcut "Files" on the left side of the desktop and click it to open a file browser.
+    * Double-click on the following folders in order: metplus_out, met_plot, and either apcp or refc.
+    * Double-click on the image files in the folder, which opens an image viewing application.
+    * Click the Maximize button in the upper right to increase the viewer to full size.
+    * Click the button in the middle of the right side of the image to advance to the next image.
+
+  When you are finished running simulations and viewing their results,
+  you can close the web browser tab containing your Web Desktop.
+  Then, return to the Exosphere dashboard to manage your instance so it does not incur further charges.

docs/Users_Guide/use-cases/lulc/red-cloud.rst

@@ -138,3 +138,20 @@ to secure access to and log in to Red Cloud.
         df -h ${mountPoint}
 
     The full output should be in ``/home/ubuntu/lulc_full_output``.
+
+  .. include:: lulc/common/metplus.rst
+
+  .. dropdown:: View the Plotted Simulation Results
+
+    The METplus container also plots the results of the simulation, outputting them as PNG images.
+    To view these images:
+
+    * Disconnect from the instance and reconnect using SSH with X11 forwarding enabled by running ``ssh -X ubuntu@<instance-ip>``. The ``-X`` option enables X11 forwarding, which allows images to be displayed on your local screen. Note that you must also have an X server running on your local machine (XQuartz on macOS or Xming on Windows).
+    * Install the ``feh`` image viewer on the instance by running ``sudo apt update`` followed by ``sudo apt install feh``. This installation only needs to be done once.
+    * Navigate to the plots folder: ``cd ~/metplus_out/met_plot/apcp`` or ``cd ~/metplus_out/met_plot/refc``.
+    * Open all the images in the folder by running ``feh .``.
+    * Press the right arrow key to advance to the next image or the left arrow key to go back.
+    * Press ``q`` to quit the viewer.
+
+Refer back to the **Managing a Red Cloud Instance** section of the :ref:`compute-platform-red-cloud`
+instructions to avoid unneccessary computing costs.

docs/Users_Guide/use-cases/matthew/red-cloud.rst

@@ -144,7 +144,18 @@ and then pasted into your web shell by right-clicking.
     These files contain tabular output that can be viewed in a text editor. Turn off word wrapping for better viewing.
     Refer to the MET User's Guide for more information about the
     `Point-Stat output <https://met.readthedocs.io/en/latest/Users_Guide/point-stat.html#point-stat-output>`_.
-    In the near future, this exercise will be extended to include instructions to visualize the results.
+
+  .. dropdown:: View the Plotted Simulation Results
+
+    The METplus container also plots the results of the simulation, outputting them as PNG images.
+    To view these images:
+
+    * Disconnect from the instance and reconnect using SSH with X11 forwarding enabled by running ``ssh -X ubuntu@<instance-ip>``. The ``-X`` option enables X11 forwarding, which allows images to be displayed on your local screen. Note that you must also have an X server running on your local machine (XQuartz on macOS or Xming on Windows).
+    * Install the ``feh`` image viewer on the instance by running ``sudo apt update`` followed by ``sudo apt install feh``. This installation only needs to be done once.
+    * Navigate to the plots folder: ``cd ~/metplus_out/wrf/20161006_00/plots``.
+    * Open all the images in the folder by running ``feh .``.
+    * Press the right arrow key to advance to the next image or the left arrow key to go back.
+    * Press ``q`` to quit the viewer.
 
 Refer back to the **Managing a Red Cloud Instance** section of the :ref:`compute-platform-red-cloud`
 instructions to avoid unneccessary computing costs.

use_cases/Land_Use_Land_Cover/METplus/GridStat_apcp_lulc.conf

@@ -169,7 +169,7 @@ OBS_PCP_COMBINE_METHOD = ADD
 
 OBS_PCP_COMBINE_INPUT_DATATYPE = NETCDF
 OBS_PCP_COMBINE_INPUT_ACCUMS = 10M
-OBS_PCP_COMBINE_INPUT_NAMES = i-wrf/use_cases/Land_Use_Land_Cover/METplus/read_lulc_radar_obs.py {OBS_PCP_COMBINE_INPUT_DIR}/RADAR_DFW22_N1P_20170703_d03_2017Jul03_2017Jul05.nc accum {valid?fmt=%Y%m%d_%H%M}
+OBS_PCP_COMBINE_INPUT_NAMES = /config/read_lulc_radar_obs.py {OBS_PCP_COMBINE_INPUT_DIR}/RADAR_DFW22_N1P_20170703_d03_2017Jul03_2017Jul05.nc accum {valid?fmt=%Y%m%d_%H%M}
 
 OBS_PCP_COMBINE_OUTPUT_ACCUM = 1H
 OBS_PCP_COMBINE_OUTPUT_NAME = APCP

use_cases/Land_Use_Land_Cover/METplus/GridStat_refc_lulc.conf

@@ -62,7 +62,7 @@ FCST_VAR1_NAME = REFD_MAX
 FCST_VAR1_LEVELS = (0,*,*)
 FCST_VAR1_THRESH = ge20, ge30, ge40, ge50
 
-OBS_VAR1_NAME = i-wrf/use_cases/Land_Use_Land_Cover/METplus/read_lulc_radar_obs.py {OBS_GRID_STAT_INPUT_DIR}/RADAR_DFW22_NCR_20170703_d03_2017Jul03_2017Jul05.nc refl {valid?fmt=%Y%m%d_%H%M}
+OBS_VAR1_NAME = /config/read_lulc_radar_obs.py {OBS_GRID_STAT_INPUT_DIR}/RADAR_DFW22_NCR_20170703_d03_2017Jul03_2017Jul05.nc refl {valid?fmt=%Y%m%d_%H%M}
 OBS_VAR1_THRESH = ge20, ge30, ge40, ge50