readme updates

etc/examples/1-simple-hazard/README.md → etc/examples/1-hazard-curve/README.md

 Example 1: A simple hazard calculation
 --------------------------------------
 
+Working directory: `/path/to/repo/nshmp-haz/etc/examples/1-hazard-curve`
+
 On the command line, navigate to this directory and execute the following:
 
 ```Shell

etc/examples/2-custom-config/README.md

 Example 2: Custom configuration
 -------------------------------
 
-Navigate up to the `examples/` directory and execute the following:
+Working directory: `/path/to/repo/nshmp-haz/etc/examples`
+
+Navigate up one level to the `examples/` directory and execute the following:
 
 ```Shell
 hazard ../peer/models/Set1-Case1 2-custom-config/config.json

etc/examples/3-sites-file/README.md

 Example 3: Using a custom sites file
 ------------------------------------
 
+Working directory: `/path/to/repo/nshmp-haz/etc/examples`
+
 One can also supply a comma-delimited site data file, which may be easier to work with in some applications.
 
 ```Shell
@@ -9,4 +11,4 @@ hazard ../peer/models/Set1-Case1 3-sites-file/config.json 3-sites-file/sites.csv
 
 See the [site file](3-sites-file/sites.csv) itself for details on the expected file structure. Under all use cases, if the name of a site is supplied, it will be included in the first column of any result files.
 
-#### Next: [Example 4](../4-complex-model)
+#### Next: [Example 4](../4-hazard-map)

etc/examples/4-hazard-map/README.md

+Example 4: A simple hazard map
+------------------------------
+
+Working directory: `/path/to/repo/nshmp-haz/etc/examples`
+
+A hazard map is just a lot of hazard curves. To compute curves at reqularly spaced intervals in latitude and longitude, the sites configuration can instead be specified as a polygon.
+
+```Shell
+hazard ../peer/models/Set1-Case1 3-sites-file/config.json
+```
+
+See the [site file](3-sites-file/sites.csv) itself for details on the expected file structure. Under all use cases, if the name of a site is supplied, it will be included in the first column of any result files.
+
+#### Next: [Example 5](../5-complex-model)

etc/examples/4-hazard-map/config-region-sf.json

+{
+  "exceedanceModel": "TRUNCATION_UPPER_ONLY",
+  "truncationLevel": 3.0,
+  "imts": ["PGA", "SA0P2", "SA1P0"],
+  "customImls": {
+    "PGA":   [0.0050, 0.0070, 0.0098, 0.0137, 0.0192, 0.0269, 0.0376, 0.0527, 0.0738, 0.103, 0.145, 0.203, 0.284, 0.397, 0.556, 0.778, 1.09, 1.52, 2.2, 3.3],
+    "SA0P2": [0.0050, 0.0075, 0.0113, 0.0169, 0.0253, 0.0380, 0.0570, 0.0854, 0.128, 0.192, 0.288, 0.432, 0.649, 0.973, 1.46, 2.19, 3.28, 4.92, 7.38],
+    "SA1P0": [0.0025, 0.00375, 0.00563, 0.00844, 0.0127, 0.0190, 0.0285, 0.0427, 0.0641, 0.0961, 0.144, 0.216, 0.324, 0.487, 0.730, 1.09, 1.64, 2.46, 3.69, 5.54]
+  },
+  "sites": {  
+    "region": {
+      "name": "Downtown San Francisco",
+      "spacing": 0.1,
+      "border": [  
+        [-122.7, 37.5],
+        [-122.2, 38.0]
+      ],
+      "vs30": 760,
+      "vsInf": true
+    }
+  }
+}
\ No newline at end of file

etc/examples/4-hazard-map/config.json

+{
+  "exceedanceModel": "TRUNCATION_UPPER_ONLY",
+  "truncationLevel": 3.0,
+  "imts": ["PGA", "SA0P2", "SA1P0"],
+  "customImls": {
+    "PGA":   [0.0050, 0.0070, 0.0098, 0.0137, 0.0192, 0.0269, 0.0376, 0.0527, 0.0738, 0.103, 0.145, 0.203, 0.284, 0.397, 0.556, 0.778, 1.09, 1.52, 2.2, 3.3],
+    "SA0P2": [0.0050, 0.0075, 0.0113, 0.0169, 0.0253, 0.0380, 0.0570, 0.0854, 0.128, 0.192, 0.288, 0.432, 0.649, 0.973, 1.46, 2.19, 3.28, 4.92, 7.38],
+    "SA1P0": [0.0025, 0.00375, 0.00563, 0.00844, 0.0127, 0.0190, 0.0285, 0.0427, 0.0641, 0.0961, 0.144, 0.216, 0.324, 0.487, 0.730, 1.09, 1.64, 2.46, 3.69, 5.54]
+  },
+  "sites": {  
+    "region": {
+      "name": "Downtown San Francisco",
+      "spacing": 0.1,
+      "border": [  
+        [-122.7, 37.5],
+        [-122.2, 38.0]
+      ],
+      "vs30": 760,
+      "vsInf": true
+    }
+  }
+}
\ No newline at end of file

etc/examples/5-complex-model/README.md

+Example 5: A more complex model
+-------------------------------
+
+Working directory: `/path/to/repo/nshmp-haz/etc/examples`
+
+Most PSHAs involve the use of more complex source models, the components of which might use different ground motion models. For this and ensuing examples, we'll use the 2008 USGS National Seismic Hazard Model (NSHM) for the western U.S.
+
+First, clone the 2008 USGS NSHM. Assuming `examples/` is the currnet working directory, the following will create a copy of the model adjacent to nshmp-haz:
+
+```Shell
+git clone https://github.com/usgs/nshmp-model-cous-2008.git ../../..
+```
+
+THe 2008 NSHM repository contains two source models one for the western U.S. and a one for the central and eastern U.S. More complex models make for longer, per-site calculations. The default configurations for the NSHM are set to output very large maps, which are time-consuming and inappropriate as examples. To compute hazard for a few sites in the Western U.S., execute:
+
+```Shell
+hazard ../../../nshmp-model-cous-2008/Western\ US 5-complex-model/config.json
+```
+
+#### Next: [Example 6](../4-enhanced-output)

etc/examples/6-enhanced-output/README.md

+Example 6: Enhanced output
+--------------------------
+
+Working directory: `/path/to/repo/nshmp-haz/etc/examples`
+
+By default, `HazardCalc` outputs only total mean hazard curves, however, curves by ground motion model and source type can also be written. Execute
+
+```Shell
+hazard ../../../nshmp-model-cous-2008/Western\ US 6-enhanced-output/config.json
+```
+
+#### Next: [Example ????](../)

etc/examples/README.md

 Examples
 --------
 
-1. **Note:** All examples avoid a lengthy call to Java and the HazardCalc program by using the following system alias:
-   
-        ```Shell
-        alias hazard='java -cp /path/to/repo/nshmp-haz/dist/nshmp-haz.jar org.opensha2.programs.HazardCalc'
-        ```
-   
-Because each example builds on prior concepts, it is best step through all the examples, however quickly.
+These examples are designed to be executed locally while following the READMEs on GitHub. All examples avoid a lengthy call to Java and the `HazardCalc` program by using the following system alias:
 
-#### Calculating hazard maps
-Hazard maps are generated from numerous uniformely spaced hazard curves. To compute such a curve set, the same program is used, but sites are instead specified as a region.
-```
-java -cp ../dist/nshmp-haz.jar org.opensha2.programs.HazardCalc peer/models/Set1-Case1 examples/config-region-sf.json
+```Shell
+alias hazard='java -cp /path/to/repo/nshmp-haz/dist/nshmp-haz.jar org.opensha2.programs.HazardCalc'
 ```
 
+Because each example builds on prior concepts, it is best step through all the examples, however quickly.
+
+#### Start: [Example 1](1-hazard-curve)
+