From 17caf58c7671933489349de41fea39a0560f7f36 Mon Sep 17 00:00:00 2001
From: Jason Altekruse <jaltekruse@usgs.gov>
Date: Tue, 29 Jun 2021 11:06:13 -0600
Subject: [PATCH] updating links, building & running related docs, fixing URLs
---
docs/README.md | 4 +-
docs/pages/About-the-NSHMP.md | 4 +-
docs/pages/Building-&-Running.md | 51 +++++++------
docs/pages/Calculation-Configuration.md | 73 +++++++++++--------
docs/pages/Developer-Basics.md | 12 ++-
docs/pages/Ground-Motion-Models.md | 4 +-
docs/pages/Hazard-Model.md | 4 +-
docs/pages/Logic-Trees-&-Uncertainty.md | 6 +-
.../Magnitude-Frequency-Distributions.md | 4 +-
docs/pages/Model-Editions.md | 4 +-
docs/pages/Model-Files.md | 4 +-
docs/pages/Model-Structure.md | 4 +-
docs/pages/Rupture-Scaling-Relations.md | 4 +-
docs/pages/Site-Specification.md | 37 ++++++----
docs/pages/Source-Types.md | 10 +--
docs/pages/USGS-Models.md | 6 +-
etc/nshm/README.md | 3 +
17 files changed, 137 insertions(+), 97 deletions(-)
create mode 100644 etc/nshm/README.md
diff --git a/docs/README.md b/docs/README.md
index 02bfc5e74..3eba4574a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -17,8 +17,8 @@ to use *nshmp-haz-v2* as well as underlying model implementation details.
* [Developer Basics](./pages/Developer-Basics.md)
* [Calculation Configuration](./pages/Calculation-Configuration.md)
* [Site Specification](./pages/Site-Specification.md)
- * Examples [on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz-v2/-/tree/master/etc/examples)
- or [in a local copy](../etc/examples/README.md)
+ * [Examples](../../etc/examples/README.md) (or
+ [on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz-v2/-/tree/master/etc/examples))
* [Hazard Model](./pages/Hazard-Model.md)
* [Model Structure](./pages/Model-Structure.md)
* [Model Files](./pages/Model-Files.md)
diff --git a/docs/pages/About-the-NSHMP.md b/docs/pages/About-the-NSHMP.md
index 76f1ce136..2ee3a89ea 100644
--- a/docs/pages/About-the-NSHMP.md
+++ b/docs/pages/About-the-NSHMP.md
@@ -24,8 +24,8 @@ U.S. and its territories to consider the best available science.
---
-[**Documentation Index**](docs/README.md)
+[**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Building-&-Running.md b/docs/pages/Building-&-Running.md
index beda1c7e4..3a1bd0cc0 100644
--- a/docs/pages/Building-&-Running.md
+++ b/docs/pages/Building-&-Running.md
@@ -2,7 +2,12 @@
## Related Pages
-TODO
+* Building & Running
+ * [Developer Basics](./Developer-Basics.md)
+ * [Calculation Configuration](./Calculation-Configuration.md)
+ * [Site Specification](./Site-Specification.md)
+ * [Examples](../../etc/examples/README.md) (or
+ [on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz-v2/-/tree/master/etc/examples))
## Build & Run Options
@@ -11,12 +16,12 @@ TODO
## Build and Run Locally
-Building and running *nshmp-haz* requires prior installation of Git and Java. Please see the
-[developer basics](developer-basics) page for system configuration guidance.
+Building and running *nshmp-haz-v2* requires prior installation of Git and Java. Please see the
+[developer basics](./Developer-Basics.md) page for system configuration guidance.
### Building
-Navigate to a location on your system where you want *nshmp-haz* code to reside, clone the
+Navigate to a location on your system where you want *nshmp-haz-v2* code to reside, clone the
repository, and compile:
```bash
@@ -40,16 +45,16 @@ measures. For example:
java -cp path/to/nshmp-haz.jar gov.usgs.earthquake.nshmp.HazardCalc model sites [config]
```
-At a minimum, the hazard source [model](Hazard-Model.md) and the [site](Site-Specification.md)(s) at
-which to perform calculations must be specified. The source model should specified a path to a
+At a minimum, the hazard source [model](./Hazard-Model.md) and the [site](./Site-Specification.md)(s)
+at which to perform calculations must be specified. The source model should specified a path to a
directory. A single site may be specified with a string; multiple sites must be specified using
either a comma-delimited (CSV) or [GeoJSON](http://geojson.org) file. The path to a custom
-[configuration](Calculation-Configuration.md) file containing user-specific settings may optionally
+[configuration](./Calculation-Configuration.md) file containing user-specific settings may optionally
be supplied as a third argument. It can be used to override any calculation settings; if absent
-[default](Calculation-Configuration.md) values are used.
+[default](./Calculation-Configuration.md) values are used.
-See the [examples](https://code.usgs.gov/ghsc/nshmp/nshmp-haz-v2/-/tree/master/etc/examples)
-directory for more details.
+See the [examples](../../etc/examples/README.md) directory for more details (or
+[on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz-v2/-/tree/master/etc/examples))
### Computing Disaggregations
@@ -63,11 +68,11 @@ java -cp nshmp-haz.jar gov.usgs.earthquake.nshmp.DisaggCalc model sites returnPe
Disaggregations build on and output `HazardCalc` results along with other disaggregation specific
files. Disaggregations also have some independent
-[configuration](Calculation-Configuration.md#config-disagg) options.
+[configuration](./Calculation-Configuration.md#config-disagg) options.
## Run with [Docker](https://docs.docker.com/install/)
-To ensure you are have the latest *nshmp-haz* update, always first pull the image from Docker:
+To ensure you are have the latest *nshmp-haz-v2* update, always first pull the image from Docker:
```bash
docker pull usgs/nshmp-haz
@@ -75,13 +80,15 @@ docker pull usgs/nshmp-haz
### Docker Memory on Mac
-By default, Docker Desktop for Mac is set to use 2 GB runtime memory. To run *nshmp-haz*, the
+By default, Docker Desktop for Mac is set to use 2 GB runtime memory. To run *nshmp-haz-v2*, the
memory available to Docker must be [increased](https://docs.docker.com/docker-for-mac/#advanced)
to a minimum of 4 GB.
### Running
-The *nshmp-haz* application may be run as a Docker container which mitigates the need to install
+TODO: is there a Docker image for nshmp-haz-v2?
+
+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
Docker hub at [https://hub.docker.com/r/usgs/nshmp-haz](https://hub.docker.com/r/usgs/nshmp-haz)
which can be run with:
@@ -113,24 +120,26 @@ Where: (TODO links below need checking)
* hazard = `HazardCalc`
* rate = `RateCalc`
-* `MODEL` is the [USGS model (NSHM)](USGS-Models.md) to run:
+* `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)
* `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:
- * (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`
+ * (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)
* GeoJSON example: `$(pwd)/my-geojson-sites.geojson:/app/sites.geojson`
- * (optional) The absolute path to a [configuration](Calculation-Configuration.md) file
+ * (optional) The absolute path to a [configuration](./Calculation-Configuration.md) file
* Example: `$(pwd)/my-custom-config.json:/app/config.json`
* (required) The absolute path to an output directory
* Example: `$(pwd)/my-hazard-output:/app/output`
### Run Customization
-When running *nshmp-haz* with Docker the initial (Xms) and maximum (Xmx) JVM memory sizes can
+When running *nshmp-haz-v2* with Docker the initial (Xms) and maximum (Xmx) JVM memory sizes can
be set with the environment flag (-e, -env):
```bash
@@ -148,8 +157,8 @@ Where:
---
-[**Documentation Index**](docs/README.md)
+* [**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Calculation-Configuration.md b/docs/pages/Calculation-Configuration.md
index f76ae6386..78210b1dd 100644
--- a/docs/pages/Calculation-Configuration.md
+++ b/docs/pages/Calculation-Configuration.md
@@ -1,50 +1,55 @@
# Calculation Configuration
-A `calc-config.json` file _may_ reside at the root of every [hazard model](hazard-model). This
+A `calc-config.json` file _may_ reside at the root of every [hazard model](./Hazard-Model.md). This
file, if present, will override any built-in default calculation configuration parameters, as
-listed below. See the [examples](/usgs/nshmp-haz/tree/master/etc/examples) directory, or any
-[USGS model](usgs-models), for concrete examples (TODO decide if last sentence needed and check
-links).
+listed below. See the [examples](../../etc/examples/README.md) directory, or any
+[USGS model](./Usgs-Models.md), for concrete examples.
## Calculation Configuration Parameters
Calculation configuration parameters are optional (i.e. defaults are used for missing values) and
-may be overridden. See [building and running](building-&-running) and the
-[examples](/usgs/nshmp-haz/tree/master/etc/examples) for details.
-
-(TODO needs updated javadoc links)
+may be overridden. See [building and running](./Building-&-Running.md) and the
+[examples](../../etc/examples/README.md) for details.
Parameter | Type | Default | Notes |
--------- | ---- | ------- | ----- |
__`hazard`__
- `.exceedanceModel` |`String` | `TRUNCATION_3SIGMA_UPPER` | [`ExceedanceModel`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ExceedanceModel.html)
- `.truncationLevel` |`Double` | `3.0` | [1](notes)
- `.imts` |`String[]` | `[ PGV, PGA, SA0P01, SA0P02, SA0P03, SA0P05, SA0P075, SA0P1, SA0P15, SA0P2, SA0P25, SA0P3, SA0P4, SA0P5, SA0P75, SA1P0, SA1P5, SA2P0, SA3P0, SA4P0, SA5P0, SA7P5, SA10P0 ]` | [`Imt`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/gmm/Imt.html)
+ `.exceedanceModel` |`String` | `TRUNCATION_3SIGMA_UPPER` | [`ExceedanceModel`][url-exceedance]
+ `.truncationLevel` |`Double` | `3.0` | [1](#notes)
+ `.imts` |`String[]` | `[ PGV, PGA, SA0P01, SA0P02, SA0P03, SA0P05, SA0P075, SA0P1, SA0P15, SA0P2, SA0P25, SA0P3, SA0P4, SA0P5, SA0P75, SA1P0, SA1P5, SA2P0, SA3P0, SA4P0, SA5P0, SA7P5, SA10P0 ]` | [`Imt`][url-imt]
`.customImls` |`Map<String, Double[]>` | `{}` (empty object) | [2](#notes)
`.gmmUncertainty` |`Boolean` | `false` | [3](#notes)
- `.valueFormat` |`String` | `ANNUAL_RATE` | [`ValueFormat`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ValueFormat.html)
+ `.valueFormat` |`String` | `ANNUAL_RATE` | [`ValueFormat`][url-valueformat]
__`deagg`__
`.bins` |`Object` | | [4](#notes)
`.contributorLimit` |`Double` | `0.1` | [5](#notes)
__`rate`__
`.bins` |`Object` | | [6](#notes)
`.distance` |`Double` | `20` km
- `.distributionFormat` |`String` | `INCREMENTAL` | [`DistributionFormat`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/DistributionFormat.html)
+ `.distributionFormat` |`String` | `INCREMENTAL` | [`DistributionFormat`][url-distribution]
`.timespan` |`Double` | `30` years
- `.valueFormat` |`String` | `ANNUAL_RATE` | [`ValueFormat`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ValueFormat.html)
+ `.valueFormat` |`String` | `ANNUAL_RATE` | [`ValueFormat`][url-valueformat]
__`site`__
- `.vs30` |`Double` | `760.0` | [`Site`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/Site.html)
+ `.vs30` |`Double` | `760.0` | [`Site`][url-site]
`.vsInferred` |`Boolean` | `true`
`.z1p0` |`Double` | `null` | [7](#notes)
`.z2p5` |`Double` | `null` | [7](#notes)
__`output`__ |
`.directory` |`String` | `hazout`
- `.dataTypes` |`String[]` | `[ TOTAL ]` | [`DataType`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/DataType.html)
+ `.dataTypes` |`String[]` | `[ TOTAL ]` | [`DataType`][url-datatype]
__`performance`__
`.optimizeGrids` |`Boolean` | `true` | [8](#notes)
`.smoothGrids` |`Boolean` | `true` | [9](#notes)
`.systemPartition` |`Integer` | `1000` | [10](#notes)
- `.threadCount` |`String` | `ALL` | [`ThreadCount`](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/calc/ThreadCount.html)
+ `.threadCount` |`String` | `ALL` | [`ThreadCount`][url-sheets]
+
+[url-exceedance]: https://earthquake.usgs.gov/nshmp/docs/nshmp-lib/gov/usgs/earthquake/nshmp/calc/ExceedanceModel.html
+[url-imt]: https://earthquake.usgs.gov/nshmp/docs/nshmp-lib/gov/usgs/earthquake/nshmp/gmm/Imt.html
+[url-valueformat]: https://earthquake.usgs.gov/nshmp/docs/nshmp-lib/gov/usgs/earthquake/nshmp/calc/ValueFormat.html
+[url-distribution]: https://earthquake.usgs.gov/nshmp/docs/nshmp-lib/gov/usgs/earthquake/nshmp/calc/DistributionFormat.html
+[url-site]: https://earthquake.usgs.gov/nshmp/docs/nshmp-lib/gov/usgs/earthquake/nshmp/calc/Site.html
+[url-datatype]: https://earthquake.usgs.gov/nshmp/docs/nshmp-lib/gov/usgs/earthquake/nshmp/calc/DataType.html
+[url-sheets]: https://earthquake.usgs.gov/nshmp/docs/nshmp-lib/gov/usgs/earthquake/nshmp/calc/ThreadCount.html
## Notes
@@ -54,7 +59,7 @@ __`performance`__
been defined, this value en/disables this feature.
3. `hazard.customImls`: Hazard is computed at default intensity measure levels (IMLs) for every
supported intenisty measure type (IMT), but a user can specify different IMLs as needed (see
- this [example](/usgs/nshmp-haz/blob/master/etc/examples/2-custom-config/config.json) and the
+ this [example](../../etc/examples/2-custom-config/README.md) and the
table of default IMLs, below).
4. `disagg.bins`: This field maps to a data container that specifies the following default ranges
and intervals for distance, magnitude, and epsilon binning: `"bins": { "rMin": 0.0, "rMax":
@@ -82,22 +87,28 @@ not listed use the values of the next highest spectral period.
IMT | IMLs
-----------|-----
-PGV | 0.237, 0.355, 0.532, 0.798, 1.19, 1.80, 2.69, 4.04, 6.06, 9.09, 13.6, 20.5, 30.7, 46.0, 69.0, 103.0, 155.0, 233.0, 349.0, 525.0
-PGA | 0.00233, 0.00350, 0.00524, 0.00786, 0.0118, 0.0177, 0.0265, 0.0398, 0.0597, 0.0896, 0.134, 0.202, 0.302, 0.454, 0.680, 1.02, 1.53, 2.30, 3.44, 5.17
-T ≤ 0.01 s | 0.00233, 0.00350, 0.00524, 0.00786, 0.0118, 0.0177, 0.0265, 0.0398, 0.0597, 0.0896, 0.134, 0.202, 0.302, 0.454, 0.680, 1.02, 1.53, 2.30, 3.44, 5.17
-T ≤ 0.02 s | 0.00283, 0.00424, 0.00637, 0.00955, 0.0143, 0.0215, 0.0322, 0.0483, 0.0725, 0.109, 0.163, 0.245, 0.367, 0.551, 0.826, 1.24, 1.86, 2.79, 4.18, 6.27
-T ≤ 0.05 s | 0.00333, 0.00499, 0.00749, 0.0112, 0.0169, 0.0253, 0.0379, 0.0569, 0.0853, 0.128, 0.192, 0.288, 0.432, 0.648, 0.972, 1.46, 2.19, 3.28, 4.92, 7.38
-T ≤ 2 s | 0.00250, 0.00375, 0.00562, 0.00843, 0.0126, 0.0190, 0.0284, 0.0427, 0.0640, 0.0960, 0.144, 0.216, 0.324, 0.486, 0.729, 1.09, 1.64, 2.46, 3.69, 5.54
-T ≤ 3 s | 0.00200, 0.00300, 0.00449, 0.00674, 0.0101, 0.0152, 0.0228, 0.0341, 0.0512, 0.0768, 0.115, 0.173, 0.259, 0.389, 0.583, 0.875, 1.31, 1.97, 2.95, 4.43
-T ≤ 4 s | 0.00133, 0.00200, 0.00300, 0.00449, 0.00674, 0.0101, 0.0152, 0.0228, 0.0341, 0.0512, 0.0768, 0.115, 0.173, 0.259, 0.389, 0.583, 0.875, 1.31, 1.97, 2.95
-T ≤ 5 s | 0.000999, 0.00150, 0.00225, 0.00337, 0.00506, 0.00758, 0.0114, 0.0171, 0.0256, 0.0384, 0.0576, 0.0864, 0.130, 0.194, 0.292, 0.437, 0.656, 0.984, 1.48, 2.21
-T ≤ 7.5 s | 0.000499, 0.000749, 0.00112, 0.00169, 0.00253, 0.00379, 0.00569, 0.00853, 0.0128, 0.0192, 0.0288, 0.0432, 0.0648, 0.0972, 0.146, 0.219, 0.328, 0.492, 0.738, 1.11
-T ≤ 10 s | 0.000333, 0.000499, 0.000749, 0.00112, 0.00169, 0.00253, 0.00379, 0.00569, 0.00853, 0.0128, 0.0192, 0.0288, 0.0432, 0.0648, 0.0972, 0.146, 0.219, 0.328, 0.492, 0.738
+PGV | 0.237, 0.355, 0.532, 0.798, 1.19, 1.80, 2.69, 4.04, <br>6.06, 9.09, 13.6, 20.5, 30.7, 46.0, 69.0, 103.0, 155.0, <br>233.0, 349.0, 525.0
+PGA | 0.00233, 0.00350, 0.00524, 0.00786, 0.0118, 0.0177, <br>0.0265, 0.0398, 0.0597, 0.0896, 0.134, 0.202, 0.302, 0.454, <br>0.680, 1.02, 1.53, 2.30, 3.44, 5.17
+T ≤ 0.01 s | 0.00233, 0.00350, 0.00524, 0.00786, 0.0118, 0.0177, <br>0.0265, 0.0398, 0.0597, 0.0896, 0.134, 0.202, 0.302, 0.454, <br>0.680, 1.02, 1.53, 2.30, 3.44, 5.17
+T ≤ 0.02 s | 0.00283, 0.00424, 0.00637, 0.00955, 0.0143, 0.0215, <br>0.0322, 0.0483, 0.0725, 0.109, 0.163, 0.245, 0.367, 0.551, 0.826, <br>1.24, 1.86, 2.79, 4.18, 6.27
+T ≤ 0.05 s | 0.00333, 0.00499, 0.00749, 0.0112, 0.0169, 0.0253, <br>0.0379, 0.0569, 0.0853, 0.128, 0.192, 0.288, 0.432, 0.648, 0.972, <br>1.46, 2.19, 3.28, 4.92, 7.38
+T ≤ 2 s | 0.00250, 0.00375, 0.00562, 0.00843, 0.0126, 0.0190, <br>0.0284, 0.0427, 0.0640, 0.0960, 0.144, 0.216, 0.324, 0.486, <br>0.729, 1.09, 1.64, 2.46, 3.69, 5.54
+T ≤ 3 s | 0.00200, 0.00300, 0.00449, 0.00674, 0.0101, 0.0152, <br>0.0228, 0.0341, 0.0512, 0.0768, 0.115, 0.173, 0.259, 0.389, <br>0.583, 0.875, 1.31, 1.97, 2.95, 4.43
+T ≤ 4 s | 0.00133, 0.00200, 0.00300, 0.00449, 0.00674, 0.0101, <br>0.0152, 0.0228, 0.0341, 0.0512, 0.0768, 0.115, 0.173, 0.259, <br>0.389, 0.583, 0.875, 1.31, 1.97, 2.95
+T ≤ 5 s | 0.000999, 0.00150, 0.00225, 0.00337, 0.00506, 0.00758, <br>0.0114, 0.0171, 0.0256, 0.0384, 0.0576, 0.0864, 0.130, 0.194, <br>0.292, 0.437, 0.656, 0.984, 1.48, 2.21
+T ≤ 7.5 s | 0.000499, 0.000749, 0.00112, 0.00169, 0.00253, 0.00379, <br>0.00569, 0.00853, 0.0128, 0.0192, 0.0288, 0.0432, 0.0648, <br>0.0972, 0.146, 0.219, 0.328, 0.492, 0.738, 1.11
+T ≤ 10 s | 0.000333, 0.000499, 0.000749, 0.00112, 0.00169, 0.00253, <br>0.00379, 0.00569, 0.00853, 0.0128, 0.0192, 0.0288, 0.0432, <br>0.0648, 0.0972, 0.146, 0.219, 0.328, 0.492, 0.738
---
-[**Documentation Index**](docs/README.md)
+* [**Documentation Index**](../README.md)
+* [Building & Running](./Building-&-Running.md)
+ * [Developer Basics](./Developer-Basics.md)
+ * [Calculation Configuration](./Calculation-Configuration.md)
+ * [Site Specification](./Site-Specification.md)
+ * [Examples](../../etc/examples/README.md) (or
+ [on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz-v2/-/tree/master/etc/examples))
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Developer-Basics.md b/docs/pages/Developer-Basics.md
index 791ab835b..d2e8a181b 100644
--- a/docs/pages/Developer-Basics.md
+++ b/docs/pages/Developer-Basics.md
@@ -53,7 +53,7 @@ git clone https://code.usgs.gov/ghsc/nshmp/nshmp-haz.git
## Eclipse Integration (Optional)
Eclipse provides automatic compilation, syntax highlighting, and integration with Git, among
-other useful features. To build or modify *nshmp-haz* using [Eclipse](http://www.eclipse.org/),
+other useful features. To build or modify *nshmp-haz-v2* using [Eclipse](http://www.eclipse.org/),
install the [Eclipse IDE for Java Developers](https://www.eclipse.org/downloads/packages/) or
[Eclipse IDE for Enterprise Java and Web Developers](https://www.eclipse.org/downloads/packages/),
if you plan on developing web services. Import the project into Eclipse: `File > Import >
@@ -61,8 +61,14 @@ Gradle > Existing Gradle Project`
---
-[**Documentation Index**](docs/README.md)
+* [**Documentation Index**](../README.md)
+* [Building & Running](./Building-&-Running.md)
+ * [Developer Basics](./Developer-Basics.md)
+ * [Calculation Configuration](./Calculation-Configuration.md)
+ * [Site Specification](./Site-Specification.md)
+ * [Examples](../../etc/examples/README.md) (or
+ [on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz-v2/-/tree/master/etc/examples))
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Ground-Motion-Models.md b/docs/pages/Ground-Motion-Models.md
index 4527f365d..fc7f55a0f 100644
--- a/docs/pages/Ground-Motion-Models.md
+++ b/docs/pages/Ground-Motion-Models.md
@@ -161,8 +161,8 @@ modify model output.
---
-[**Documentation Index**](docs/README.md)
+[**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Hazard-Model.md b/docs/pages/Hazard-Model.md
index fa537064e..92171f527 100644
--- a/docs/pages/Hazard-Model.md
+++ b/docs/pages/Hazard-Model.md
@@ -34,8 +34,8 @@ support modeling of complex logic trees.
---
-[**Documentation Index**](docs/README.md)
+[**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Logic-Trees-&-Uncertainty.md b/docs/pages/Logic-Trees-&-Uncertainty.md
index b5db0a58a..57c05cda5 100644
--- a/docs/pages/Logic-Trees-&-Uncertainty.md
+++ b/docs/pages/Logic-Trees-&-Uncertainty.md
@@ -1,7 +1,7 @@
# USGS Models: Logic Trees & Uncertainty
The following page details the logic trees of epistemic uncertainty considered in NSHMs supported
-by *nshmp-haz*. Logic trees are represented in a NSHM using files ending in `-tree.json`.
+by *nshmp-haz-v2*. Logic trees are represented in a NSHM using files ending in `-tree.json`.
[[_TOC_]]
@@ -125,8 +125,8 @@ alternative models.
---
-[**Documentation Index**](docs/README.md)
+[**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Magnitude-Frequency-Distributions.md b/docs/pages/Magnitude-Frequency-Distributions.md
index 9fd7e7c06..0d041cc9c 100644
--- a/docs/pages/Magnitude-Frequency-Distributions.md
+++ b/docs/pages/Magnitude-Frequency-Distributions.md
@@ -286,8 +286,8 @@ TODO: convert example to JSON format (or see `mfd-config.json` section above)
---
-[**Documentation Index**](docs/README.md)
+[**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Model-Editions.md b/docs/pages/Model-Editions.md
index bdecc204a..c47e2f313 100644
--- a/docs/pages/Model-Editions.md
+++ b/docs/pages/Model-Editions.md
@@ -102,8 +102,8 @@ TODO: Update model links
---
-[**Documentation Index**](docs/README.md)
+[**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Model-Files.md b/docs/pages/Model-Files.md
index c1c485fad..ca478d5ee 100644
--- a/docs/pages/Model-Files.md
+++ b/docs/pages/Model-Files.md
@@ -186,8 +186,8 @@ is composed of an array of rupture-sets.
---
-[**Documentation Index**](docs/README.md)
+[**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Model-Structure.md b/docs/pages/Model-Structure.md
index df34c9fc4..e7230c6b1 100644
--- a/docs/pages/Model-Structure.md
+++ b/docs/pages/Model-Structure.md
@@ -196,8 +196,8 @@ See also: [Subduction Intraslab Source Type](source-types#subduction-intraslab-s
---
-[**Documentation Index**](docs/README.md)
+[**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Rupture-Scaling-Relations.md b/docs/pages/Rupture-Scaling-Relations.md
index 3e29c61b7..e78cd91a9 100644
--- a/docs/pages/Rupture-Scaling-Relations.md
+++ b/docs/pages/Rupture-Scaling-Relations.md
@@ -70,8 +70,8 @@ relationships for subduction zone earthquakes. Seismological Research Letters 68
---
-[**Documentation Index**](docs/README.md)
+[**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Site-Specification.md b/docs/pages/Site-Specification.md
index 3b3dfb497..40808da9f 100644
--- a/docs/pages/Site-Specification.md
+++ b/docs/pages/Site-Specification.md
@@ -2,18 +2,22 @@
(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`](/usgs/nshmp-haz/tree/master/etc/nshm).
+[`etc/nshm`](../../etc/nshm/README.md).
-__Note on Coordinates:__ *nshmp-haz* supports longitude and latitude values in the closed
+__Note on Coordinates:__ *nshmp-haz-v2* supports longitude and latitude values in the closed
ranges `[-360° ‥ 360°]` and `[-90° ‥ 90°]`. Note, however, that mixing site and/or source
coordinates across the antimeridian (the -180° to 180° transition) will yield unexpected results.
For Pacific models and calculations, always use positive or negative longitudes exclusively.
## Site String
-For the case of running a single site of interest, most *nshmp-haz* programs accept a
+For the case of running a single site of interest, most *nshmp-haz-v2* programs accept a
comma-delimited string of the form: `name,lon,lat[,vs30,vsInf[,z1p0,z2p5]]`, where `vs30`, `vsInf`,
`z1p0`, and `z2p5` are optional. Note that if `vs30` is supplied, so too must `vsInf`. Likewise if
`z1p0` is supplied, so too must `z2p5`. If the string contains any spaces, escape them or wrap the
@@ -21,7 +25,7 @@ entire string in double quotes.
For any site parameter values that are not supplied on the command line or in the file formats
below, the following defaults are used (see the `site` member of the
-[configuration](calculation-configuration) file):
+[configuration](./Calculation-Configuration.md) file):
```text
name: Unnamed
@@ -47,7 +51,7 @@ it's 'default' basin depth scale factor.
## GeoJSON Format (\*.geojson)
Although more verbose than the comma-delimited format, [GeoJSON](http://geojson.org) is a more
-versatile format for encoding geographic data. *nshmp-haz* uses GeoJSON for both lists of sites
+versatile format for encoding geographic data. *nshmp-haz-v2* uses GeoJSON for both lists of sites
and to define map regions. If you encounter problems when formatting JSON files, use
[JSONLint](http://jsonlint.com) or [GeoJSONLint](http://geojsonlint.com) for validation.
@@ -79,19 +83,19 @@ A site list is expected as a `FeatureCollection` of `Point` features. For exampl
As with the CSV format, the minimum required data is a `geometry` `coordinates` array. All
`properties` are optional. When using GeoJSON, the `title` property maps to the name of the site.
-Additional properties, if present, are ignored by *nshmp-haz* but permitted as they may be
+Additional properties, if present, are ignored by *nshmp-haz-v2* but permitted as they may be
relevant for other applications. For example, [styling
properties](https://help.github.com/articles/mapping-geojson-files-on-github/#styling-features)
may be used to improve rendering in mapping applications. For a fully fledged example, see the
-[NSHM test sites](/usgs/nshmp-haz/blob/master/etc/nshm/sites-nshmp.geojson) file.
+[NSHM test sites](../../etc/nshm/sites-nshmp.geojson) file.
### Map Regions
-GeoJSON is also used to define *nshmp-haz* map regions. For example, see the file that defines a
+GeoJSON is also used to define *nshmp-haz-v2* map regions. For example, see the file that defines a
region commonly used when creating hazard and other maps for the
-[Los Angeles basin](/usgs/nshmp-haz/blob/master/etc/nshm/map-la-basin.geojson).
+[Los Angeles basin](../../etc/nshm/map-la-basin.geojson).
-A map region is expected as a `Polygon` `FeatureCollection`. Currently, *nshmp-haz* only supports
+A map region is expected as a `Polygon` `FeatureCollection`. Currently, *nshmp-haz-v2* only supports
a `FeatureCollection` with 1 or 2 polygons. When a single polygon is defined, it must consist of a
single, simple closed loop. Additional arrays that define holes in the polygon (per the GeoJSON
spec) are not processed and results are undefined for self-intersecting coordinate arrays. This
@@ -106,13 +110,20 @@ have a feature `id` of `Extents`, and *must* be rectangular (in a mercator proje
parallel to lines of latitude and longitude. Any points in the 'calculation' polygon outside the
'extents' polygon are ignored; hazard values at any points within the 'extents' polygon but
outside the 'calculation' polygon are set to zero. For an example, see the
-[NSHMP Western US](/usgs/nshmp-haz/blob/master/etc/nshm/map-wus.geojson) map site file.
+[NSHMP Western US](../../etc/nshm/map-wus.geojson) map site file.
+
(TODO This needs updating; link to conus-2018 active crust map-region.geojson).
---
-[**Documentation Index**](docs/README.md)
+* [**Documentation Index**](../README.md)
+* [Building & Running](./Building-&-Running.md)
+ * [Developer Basics](./Developer-Basics.md)
+ * [Calculation Configuration](./Calculation-Configuration.md)
+ * [Site Specification](./Site-Specification.md)
+ * [Examples](../../etc/examples/README.md) (or
+ [on GitLab](https://code.usgs.gov/ghsc/nshmp/nshmp-haz-v2/-/tree/master/etc/examples))
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/Source-Types.md b/docs/pages/Source-Types.md
index baaf1f4f1..b6a0382a3 100644
--- a/docs/pages/Source-Types.md
+++ b/docs/pages/Source-Types.md
@@ -12,15 +12,15 @@ geometry itself is unknown or very poorly defined.
[[_TOC_]]
-Source models for use with *nshmp-haz* are defined using [JSON](https://www.json.org) and
-[GeoJSON](https://geojson.org). *nshmp-haz* makes determinations about how to represent a source
+Source models for use with *nshmp-haz-v2* are defined using [JSON](https://www.json.org) and
+[GeoJSON](https://geojson.org). *nshmp-haz-v2* makes determinations about how to represent a source
based on a GeoJSON geometry type in conjunction with supporting JSON configuration files. Example
source configuration files, `*-config.json`, are provided with each source type description.
Configuration files must be fully specified with `null` JSON member values used to specify 'do
nothing' where appropriate. Any configuration member value in ALL_CAPS indicates the value is one
of a fixed number of options commonly referred to as an enum.
-__Note on Coordinates:__ *nshmp-haz* supports longitude and latitude values in the closed ranges
+__Note on Coordinates:__ *nshmp-haz-v2* supports longitude and latitude values in the closed ranges
`[-360°‥360°]` and `[-90°‥90°]`. Note, however, that mixing site and/or source coordinates across
the antimeridian (the -180° to 180° transition) will yield unexpected results. For Pacific models
and calculations, always use positive or negative longitudes exclusively.
@@ -347,8 +347,8 @@ using an `slab-config.json` file.
---
-[**Documentation Index**](docs/README.md)
+[**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/docs/pages/USGS-Models.md b/docs/pages/USGS-Models.md
index 7d28b81b6..6a686b063 100644
--- a/docs/pages/USGS-Models.md
+++ b/docs/pages/USGS-Models.md
@@ -6,7 +6,7 @@ years. This window is narrowing, however, and updates are also being undertaken
models for states and territories outside the conterminous U.S. These pages describe the models
that are available and some of the history and versions of each. The models are intended for use
with the USGS probabilistic earthquake hazard codebase:
-[*nshmp-haz*](https://github.com/usgs/nshmp-haz).
+[*nshmp-haz-v2*](https://github.com/usgs/nshmp-haz).
As specified in this documentation, NSHM files are organized by tectonic setting and then further
by source type. For larger models, such as that of the conterminous U.S., sources are commonly
@@ -32,8 +32,8 @@ Each model region has a dedicated repository with version tags marking different
* [Model Editions](model-editions.md)
* [Logic Trees & Uncertainty](logic-trees-&-uncertainty.md)
-[**Documentation Index**](docs/README.md)
+[**Documentation Index**](../README.md)
---
- [U.S. Geological Survey](https://www.usgs.gov)
+ [U.S. Geological Survey](https://www.usgs.gov)
National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/))
diff --git a/etc/nshm/README.md b/etc/nshm/README.md
new file mode 100644
index 000000000..96c4ee61a
--- /dev/null
+++ b/etc/nshm/README.md
@@ -0,0 +1,3 @@
+# NSHM site and map files
+
+This directory contains the sites, map, and boundary files used in NSHM calculations.
--
GitLab