From 3c9877a186ef88446dc09569190c1f42a5d14d9d Mon Sep 17 00:00:00 2001
From: Jason Altekruse <jaltekruse@usgs.gov>
Date: Tue, 29 Jun 2021 18:37:36 -0600
Subject: [PATCH] updating content, fixing links

---
 docs/pages/Building-&-Running.md   | 21 +++++-----
 docs/pages/Ground-Motion-Models.md | 67 ++++++++++++++++++------------
 docs/pages/Site-Specification.md   |  6 +--
 3 files changed, 52 insertions(+), 42 deletions(-)

diff --git a/docs/pages/Building-&-Running.md b/docs/pages/Building-&-Running.md
index 3a1bd0cc0..1e09b5ac5 100644
--- a/docs/pages/Building-&-Running.md
+++ b/docs/pages/Building-&-Running.md
@@ -84,9 +84,12 @@ By default, Docker Desktop for Mac is set to use 2 GB runtime memory. To run *ns
 memory available to Docker must be [increased](https://docs.docker.com/docker-for-mac/#advanced)
 to a minimum of 4 GB.
 
-### Running
+### Run in Docker
 
-TODO: is there a Docker image for nshmp-haz-v2?
+TODO: Docker scripts currently only get models from github (XML models), so nshmp-haz-v2 run fails
+to parse the models (CONUS_2018 or HAWAII_2021), need to at least update `nshmp-haz-v2/scripts/docker-functions.inc.sh`.
+
+TODO: Model identifiers need to be synced between here and the docker scripts (e.g. `HI-2020` vs `HAWAII_2021`).
 
 The *nshmp-haz-v2* application may be run as a Docker container which mitigates the need to install
 Git, Java, or other dependencies besides Docker. A public image is available on
@@ -106,14 +109,14 @@ docker run \
 # Example
 docker run \
     -e PROGRAM=hazard \
-    -e MODEL=CONUS-2018 \
+    -e MODEL=CONUS_2018 \
     -v $(pwd)/sites.geojson:/app/sites.geojson \
     -v $(pwd)/config.json:/app/config.json \
     -v $(pwd)/hazout:/app/output \
     usgs/nshmp-haz
 ```
 
-Where: (TODO links below need checking)
+Where:
 
 * `PROGRAM` is the nshmp-haz program to run:
   * disagg = `DisaggCalc`
@@ -121,16 +124,14 @@ Where: (TODO links below need checking)
   * rate = `RateCalc`
 
 * `MODEL` is the [USGS model (NSHM)](./USGS-Models.md) to run:
-  * CONUS-2018: [Conterminous U.S. 2018](https://code.usgs.gov/ghsc/nshmp/nshm-conus)
-  * HAWAII-2021: [Hawaii 2021](https://code.usgs.gov/ghsc/nshmp/nshm-hawaii)
+  * `CONUS_2018`: [Conterminous U.S. 2018](https://code.usgs.gov/ghsc/nshmp/nshm-conus)
+  * `HAWAII_2021`: [Hawaii 2021](https://code.usgs.gov/ghsc/nshmp/nshm-hawaii)
 
 * `RETURN_PERIOD`, in years, is only required when running a disaggregation
 
-TODO: what should these examples point to? links to example files? or where to look for the samples?
-
-* Other arguments:
+* Other arguments (local files mapped to files within the Docker container with `:/app/...`):
   * (required) The absolute path to a GeoJSON or CSV [site(s)](./Site-Specification.md) file
-    * CSV example: `$(pwd)/my-csv-sites.csv:/app/sites.csv` [`sites.csv`](../../etc/examples/3-sites-file/sites.csv)
+    * CSV example: `$(pwd)/my-csv-sites.csv:/app/sites.csv`
     * GeoJSON example: `$(pwd)/my-geojson-sites.geojson:/app/sites.geojson`
   * (optional) The absolute path to a [configuration](./Calculation-Configuration.md) file
     * Example: `$(pwd)/my-custom-config.json:/app/config.json`
diff --git a/docs/pages/Ground-Motion-Models.md b/docs/pages/Ground-Motion-Models.md
index fc7f55a0f..284ac2f6e 100644
--- a/docs/pages/Ground-Motion-Models.md
+++ b/docs/pages/Ground-Motion-Models.md
@@ -7,18 +7,24 @@ GMMs, as published, support both interface and intraslab events.
 
 [[_TOC_]]
 
-* How to add links to javadocs? ...not possible in wiki (separate repo)? except with external
-  http gitlab urls?
-* include NSHM that used each model?
-* save horizontal space in table by moving notes to table footnotes. this has to be done manually
-  (see NGA-East model IDs), since markdown footnotes always appear at the bottom of the page
-
-**gmm-config.json** Required adjacent to any `gmm-tree.json`. This file specifies the applicability
-distance of the associated GMM's and any additional epistemic uncertainty model and properties to
-apply to median ground motions derived from the GMM's. This uncertainty is distinct from the
-built-in aleatory variability (standard deviation or sigma) of the GMM's themselves. Use `null`
-values to indicate that no additional uncertainty model should be applied. Supported uncertainty
-models are detailed in the [ground motion models](ground-motion-models) section. For example:
+TODO: add links to GMM javadocs?
+
+TODO: list NSHMs that used each model?
+
+TODO: save horizontal space in table by moving notes to table footnotes (must be done manually because
+markdown footnotes are always at the bottom of the page)
+
+## GMM Configuration
+
+A **gmm-config.json** file governs how GMMs are applied in a NSHM and is required adjacent to any
+`gmm-tree.json` file. It specifies a maximum distance at which associated GMMs are applicable. It
+may also specify a model of additional epistemic uncertainty and the logic tree used to apply it to
+median ground motions derived from the GMMs. If no such model is required, the `epistemic-model` and
+`epistemic-tree` members must be `null`. This uncertainty is disctinct from the built-in aleatory
+variability (standard deviation or sigma) of the GMMs themselves. See [GMM Uncertainty Models](#gmm-uncertainty-models)
+for details on additional epistemic uncertainty in GMMs.
+
+A sample `gmm-config.json` file that specifies no additional epistemic uncertainty model:
 
 ```json
 {
@@ -28,13 +34,7 @@ models are detailed in the [ground motion models](ground-motion-models) section.
 }
 ```
 
-## GMM Configuration
-
-A `gmm-config.json` file governs how GMMs are applied in a NSHM. It specifies a maximum distance
-at which a GMM is applicable. It may also specify a model of additional epistemic uncertainty and
-the logic tree used to apply it. If no such model is required, the `epistemic-model` and
-`epistemic-tree` members must be `null`. See [Uncertainties in NSHMs](uncertainties-in-nshms) for
-details on additional epistemic uncertainty in GMMs.
+The following sample `gmm-config.json` file applies the NGA-West 2 epistemic uncertainty model:
 
 ```json
 {
@@ -50,13 +50,26 @@ details on additional epistemic uncertainty in GMMs.
 
 ## GMM Uncertainty Models
 
-TODO
+TODO: GMM uncertainty models (tables of values not necessary?)
+
+*nshmp-haz-v2* supports two models of additional epistemic uncertainty, derived from the PEER
+NGA-West 1 and NGA-West 2 projects.
+
+NGA-West 1  | Rrup < 10 | 10 <= Rrup < 30 | 30 <= Rrup
+:---:|:---|:---|:---
+**5 <= M < 6** | 0.375 | 0.21  | 0.245
+**6 <= M < 7** | 0.23  | 0.225 | 0.23
+**7 <= M**     | 0.40  | 0.36  | 0.31
 
 ## GMM Post Processors
 
-TODO
+TODO: GMM post processors (currently tabulated in "Auxiliary GMMs" section below)
+
+## GMMs By Tectonic Setting
+
+GMMs available in *nshmp-haz-v2* are tabulated by tectonic setting below.
 
-## Active Crust GMMs
+### Active Crust GMMs
 
 | Reference | ID | Component | Notes |
 |:---------:|:--:|:---------:|:------|
@@ -79,7 +92,7 @@ TODO
 | [Sadigh et al., 1997](http://dx.doi.org/10.1785/gssrl.68.1.180) | SADIGH_97 | Geometric mean of two horizontal components | Also used for interface sources in 2007 Alaska NSHM |
 | [Zhao et al., 2016](http://dx.doi.org/10.1785/0120150063) | ZHAO_16_SHALLOW_CRUST<br>ZHAO_16_UPPER_MANTLE | Geometric mean of two randomly oriented horizontal components |  |
 
-## Stable Crust GMMs
+### Stable Crust GMMs
 
 | Reference | ID | Component | Notes |
 |:---------:|:--:|:---------:|:------|
@@ -108,7 +121,7 @@ TODO
    NGA_EAST_SEED_PEER_EX, NGA_EAST_SEED_PEER_GP, NGA_EAST_SEED_PZCT15_M1SS,
    NGA_EAST_SEED_PZCT15_M2ES, NGA_EAST_SEED_SP15, NGA_EAST_SEED_SP16, NGA_EAST_SEED_YA15
 
-## Subduction GMMs  
+### Subduction GMMs  
 
 | Reference | ID | Component | Notes |
 |:---------:|:--:|:---------:|:------|
@@ -121,7 +134,7 @@ TODO
 | [Zhao et al., 2006](http://dx.doi.org/10.1785/0120050122) | ZHAO_06_INTERFACE<br>ZHAO_06_INTERFACE_BASIN<br>ZHAO_06_SLAB<br>ZHAO_06_SLAB_BASIN | Geometric mean of two horizontal components |  |
 | [Zhao et al., 2016](http://dx.doi.org/10.1785/0120150034)<br>[Zhao et al., 2016](http://dx.doi.org/10.1785/0120150056) | ZHAO_16_INTERFACE<br>ZHAO_16_SLAB<br>*ZHAO_16_UPPER_MANTLE* | Geometric mean of two randomly oriented horizontal components | Subduction Slab and Interface |
 
-## Regional and Specialized GMMs
+### Regional and Specialized GMMs
 
 | Reference | ID | Component | Notes |
 |:---------:|:--:|:---------:|:------|
@@ -149,9 +162,9 @@ TODO
 | [Atkinson, 2015](http://dx.doi.org/10.1785/0120140142) | ATKINSON_15 | orientation-independent horizontal |  |
 -->
 
-## Auxilliary Models
+### Auxiliary Models
 
-Auxilliary models are not used directly, they can be used by concrete implementations of GMMs to
+Auxiliary models are not used directly, they can be used by concrete implementations of GMMs to
 modify model output.
 
 | Reference | Purpose | Component | Notes |
diff --git a/docs/pages/Site-Specification.md b/docs/pages/Site-Specification.md
index 40808da9f..f7ad71b9c 100644
--- a/docs/pages/Site-Specification.md
+++ b/docs/pages/Site-Specification.md
@@ -2,10 +2,6 @@
 
 (TODO update etc and/or javadoc links)
 
-~~TODO: add README for `etc/nshm` directory so it can be linked here~~
-
-TODO: where is `etc/peer`? is it needed?
-
 The sites at which to perform hazard and related calculations may be defined in a variety of
 ways. Examples of the file formats described below are available in the resource directory:
 [`etc/nshm`](../../etc/nshm/README.md).
@@ -112,7 +108,7 @@ parallel to lines of latitude and longitude. Any points in the 'calculation' pol
 outside the 'calculation' polygon are set to zero. For an example, see the
 [NSHMP Western US](../../etc/nshm/map-wus.geojson) map site file.
 
-(TODO This needs updating; link to conus-2018 active crust map-region.geojson).
+TODO This needs updating; link to conus-2018 active crust map-region.geojson.
 
 ---
 
-- 
GitLab