diff --git a/README.md b/README.md index aa89e7c117402f75652d001879e9a61a66041fb8..4c0ade7846c6b35f2d41305d9f4c04906b36aacb 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,6 @@ -# nshmp-haz-ws +# Legacy nshmp-haz-ws U.S. Geological Survey ([USGS](https://www.usgs.gov)) National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards/)) web service code. -Please see the [wiki](https://github.com/usgs/nshmp-haz-ws/wiki) for more information. - -> This repository has been moved to GitLab: -> [https://code.usgs.gov/ghsc/nshmp/nshmp-haz](https://code.usgs.gov/ghsc/nshmp/nshmp-haz). +Please see the [docs](./docs/README.md) for more information. diff --git a/docs/Building-&-Running.md b/docs/Building-&-Running.md new file mode 100644 index 0000000000000000000000000000000000000000..42da4b1cd8a2e38832ef0ae9b5fd739d90d9d90e --- /dev/null +++ b/docs/Building-&-Running.md @@ -0,0 +1,168 @@ + +<!-- Overview --> +### Overview +* [Build and Run Locally](#build-and-run-locally) +* [Run with Docker](#run-with-docker) + +<!-- Build and run locally --> +## Build and Run Locally + +### Build requirements: + +* Java 8 JDK: [Oracle](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) or [OpenJDK](http://openjdk.java.net/install/) +* Projects needed in adjacent directories: + * [nshmp-haz](https://github.com/usgs/nshmp-haz) + * nshmp-haz-ws (this project) + * [2014 NSHM for the Conterminous U.S.](https://github.com/usgs/nshm-cous-2014) + * [2008 NSHM for the Conterminous U.S.](https://github.com/usgs/nshm-cous-2008) + * [2007 NSHM for Alaska](https://github.com/usgs/nshm-ak-2007) +* Dependencies (managed by [Gradle](https://gradle.org)): + * Java servlet support (e.g. [Apache Tomcat 8](https://tomcat.apache.org)) + * [Guava](http://code.google.com/p/guava-libraries/) + * [Gson](https://code.google.com/p/google-gson/) + +### Running: + +Running *nshmp-haz-ws* services locally requires installation of a Java Servlet 3.1 container (e.g. [Apache Tomcat 8](https://tomcat.apache.org)). Once configured, executing: + +```bash +cd /path/to/nshmp-haz-ws +./gradlew war +``` + +... creates a deployable [WAR](https://en.wikipedia.org/wiki/WAR_(file_format)) file in `nshmp-haz-ws/build/libs`. + +#### To build, run, and test web applications using Eclipse, install: +* [Eclipse IDE for Java EE Developers](https://www.eclipse.org/downloads/eclipse-packages/) +* [Apache Tomcat 8.0](https://tomcat.apache.org) + +Please see [`build.gradle`](https://github.com/usgs/nshmp-haz-ws/blob/master/build.gradle) for additional details on configuring paths to model directories. + +#### Eclipse configuration and execution: +* Set the Java 8 JDK installation as the default: `Preferences > Java > Installed JREs` +* Set up a Tomcat server: `Preferences > Server > Runtime Environments > Add...` +* Import *nshmp-haz*: `File > Import > Gradle > Existing Gradle Project` +* Import *nshmp-haz-ws*, also as a Gradle project. +* `Window > Perspective > Open Perspective > Java Browsing` +* Select *nshmp-haz-ws* in the `Package Explorer` tab. +* `Run > Run As > Run on Server` + +<!-- Run with Docker --> +## Run with Docker + +### Build requirements: +- [Docker](https://docs.docker.com/install/) + +### Getting Latest Docker Image +To ensure you are on the latest nshmp-haz-ws update, pull the image from Docker: + +```bash +docker pull usgs/nshmp-haz-ws-legacy +``` + +### Docker Memory on Mac +By default, Docker Desktop for Mac is set to use 2 GB runtime memory. To run nshmp-haz-ws, 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-ws application may be run as a Docker container. +A public image is available on Docker Hub at +<https://hub.docker.com/r/usgs/nshmp-haz-ws-legacy> which can be run with: + +```bash +docker run -p <PORT>:8080 -d usgs/nshmp-haz-ws-legacy + +# Example +docker run -p 8080:8080 -d usgs/nshmp-haz-ws-legacy +``` + +`<PORT>` should be replaced with an available port that is not in use. The application +can then be accessed from: + +```bash +http://localhost:<PORT>/nshmp-haz-ws + +# Example +http://localhost:8080/nshmp-haz-ws +``` + +The `<PORT>` should be replaced with the same value to start the container. + +#### Running Customization + +##### Java Memory +When running nshmp-haz-ws with Docker the initial (Xms) and maximum (Xmx) JVM memory sizes can +be set with the environment flag (-e, -env): +```bash +docker run -p <PORT>:8080 -e JAVA_OPTS="-Xms<INITIAL> -Xmx<MAX>" -d usgs/nshmp-haz-ws-legacy + +# Example +docker run -p 8080:8080 -e JAVA_OPTS="-Xms1g -Xmx8g" -d usgs/nshmp-haz-ws-legacy +``` + +Where `<INITIAL>` and `<MAX >`should be set to the desired initial and maximum memory sizes, +respectively. + +##### Repository Versions +When running the Docker image the version, branch, or commit may be supplied as arguments +for nshmp-haz and the models: + +```bash +docker run -p <PORT>:8080 \ + -e NSHMP_HAZ_VERSION=some-version-or-branch-or-commit \ + -e NSHM_AK_2007_VERSION=some-version-or-branch-or-commit \ + -e NSHM_COUS_2008_VERSION=some-version-or-branch-or-commit \ + -e NSHM_COUS_2014_VERSION=some-version-or-branch-or-commit \ + -e NSHM_COUS_2018_VERSION=some-version-or-branch-or-commit \ + usgs/nshmp-haz-ws-legacy + +# Example +docker run -p 8080:8080 \ + -e NSHMP_HAZ_VERSION=v1.2.0 \ + -e NSHM_AK_2007_VERSION=master \ + -e NSHM_COUS_2008_VERSION=master \ + -e NSHM_COUS_2014_VERSION=v4.1.4 \ + -e NSHM_COUS_2018_VERSION=master \ + usgs/nshmp-haz-ws-legacy +``` + +To exclude a model from deploying set the version to `null`. + +##### Default Repository Versions +* nshmp-haz: master +* nshm-ak-2007: master +* nshm-cous-2008: master +* nshm-cous-2014: v4.1.4 +* nshm-cous-2014b: master +* nshm-cous-2018: master + +### Building +A Docker image may additionaly be built from the source using the accompanying Dockerfile: +```bash +docker build -t <IMAGE_NAME>:<IAMGE_TAG> . + +# Example +docker build -t nshmp-haz-ws-legacy:latest . +``` + +### Development +Docker Compose can be used for development: + +```bash +# Look for changes and rebuild WAR file +./gradlew assemble --continuous + +# Run docker-compose.yaml file +docker-compose up -d +``` + +`./gradlew assemble --continuous` looks for any changes in the source +code and rebuilds the WAR file. Docker Compose looks for any changes to the +WAR file and redeploys. + +### Models +Models load as requested. While all supported models are available, requesting +them all will eventually result in an `OutOfMemoryError`. +Increase `-Xmx` to `-Xmx16g` or `-Xmx24g`, if available +(See [running customization](#running-customization)). \ No newline at end of file diff --git a/docs/Editions Explained.md b/docs/Editions Explained.md new file mode 100644 index 0000000000000000000000000000000000000000..9b5f43f8b0ed1ec3132e512b39fb9bad37a091f4 --- /dev/null +++ b/docs/Editions Explained.md @@ -0,0 +1,50 @@ + +USGS hazard models are created and updated in response to user needs. In some cases a model is updated in response to cyclic updates to the U.S. Building Code. In other cases, enough time has passed that there have been significant advancements in the science, availability of relevant data, or modeling procedures that warrant a model update. Every model the USGS produces is associated with a USGS Open-File report or refereed journal article and supporting datasets. However, layered on top of any given model release are bug-fixes and model improvements. + +With the update to a new codebase, [nshmp-haz](https://github.com/usgs/nshmp-haz), the NSHMP has adopted [semantic versioning](http://semver.org) to keep track of different hazard models. For any given model region, the first number (or major version) corresponds to a particular release or update year. For example, we consider the initial [1996 conterminous U.S. NSHM](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#1996) to be v1.0.0. The second number (or minor version) reflects updates to a particular release that likely causes small changes to hazard values. The third number reflects non-hazard altering changes; for instance, a change to the model file format that has no consequence on computed hazard. + +The USGS NSHMP is committed to supporting current and prior model releases in any given region via web services. The table below provides a summary of all NSHM releases and their corresponding version numbers. + +Region | Year | Version | Static | Dynamic | Notes | +-------|:----:|:-------:|:------:|:-------:|-------| +Conterminous U.S. | [2014](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2014) | [v4.2.0](https://github.com/usgs/nshmp-model-cous-2014/releases/tag/v4.2.0)<sup>†</sup> | |:small_blue_diamond:| | +Conterminous U.S. | [2014](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2014) | [v4.1.4](https://github.com/usgs/nshmp-model-cous-2014/releases/tag/v4.1.4)<sup>†</sup> | |:small_blue_diamond:| | +Conterminous U.S. | [2014](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2014) | [v4.0.0](https://github.com/usgs/nshmp-haz-fortran/releases/tag/nshm2014r1) |:small_blue_diamond:| | ASCE7-16 | +Conterminous U.S. | [2008](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2008) | v3.3.3 | |:small_blue_diamond:| | +Conterminous U.S. | [2008](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2008) | [v3.2.0](https://github.com/usgs/nshmp-haz-fortran/releases/tag/nshm2008r3) |:small_blue_diamond:| | | +Conterminous U.S. | [2008](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2008) | v3.1.0 |:small_blue_diamond:| | ASCE7-10 | +Conterminous U.S. | [2008](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2008) | v3.0.0 | | | | +Conterminous U.S. | [2002](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2002) | v2.0.0 | | | | +Conterminous U.S. | [1996](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#1996) | v1.0.0 | | | | +Alaska | [2007](https://earthquake.usgs.gov/hazards/hazmaps/ak/index.php#2007) | v2.1.0 | |:small_blue_diamond:| | +Alaska | [2007](https://earthquake.usgs.gov/hazards/hazmaps/ak/index.php#2007) | v2.0.0 |:small_blue_diamond:| | ASCE7-10 | +Alaska | [1999](https://earthquake.usgs.gov/hazards/hazmaps/ak/index.php#1999) | v1.0.0 | | | | +American Samoa | [2012](https://earthquake.usgs.gov/hazards/hazmaps/islands.php#samoapacific) | v1.0.0 | | | | +Guam | [2012](https://pubs.usgs.gov/of/2012/1015/) | v1.0.0 | | | | +Hawaii | [2018](https://earthquake.usgs.gov/hazards/hazmaps/islands.php#hi) | v2.0.0 | | TBD | | +Hawaii | [1998](https://earthquake.usgs.gov/hazards/hazmaps/islands.php#hi) | v1.1.0 | | TBD | | +Hawaii | [1998](https://earthquake.usgs.gov/hazards/hazmaps/islands.php#hi) | v1.0.0 |:small_blue_diamond:| | ASCE7-10 | +Puerto Rico & <br/> U.S. Virgin Islands | [2003](https://earthquake.usgs.gov/hazards/hazmaps/islands.php#prvi) | v1.0.0 | | | | + +<sup>†</sup> __Note on the 2014 Conterminous U.S. NSHM:__ Initial publication of the [2014 model](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2014) included data to support updates to the U.S. Building Code, specifically hazard curves for peak ground acceleration (PGA), and 0.2 and 1.0 second spectral accelerations, all at a BC boundary site class with Vs30 = 760 m/s. Some time later, the model was deployed to the Unified Hazard Tool (UHT) and included support in the Wester U.S. for calculations at sites other than Vs30 = 760 m/s, consistent with dynamic calculations using the 2008 model. Subsequently, we updated the 2014 model with [addional periods and site classes](https://pubs.er.usgs.gov/publication/ofr20181111). Doing so required dropping several ground motion models (GMMs) and a redistribution of logic-tree weights. Specifically, the Idriss (2014) model is inappropriate for use at soft soil sites and the Atkinson & Boore (2003) model does not support long periods (see the [open-file report](https://pubs.er.usgs.gov/publication/ofr20181111) for more information). Moving forward, we will continue to include the original dynamic version of the 2014 model (v4.1.4) in the UHT. However, we recommend that users consider the updated model (4.2.0). + +### Static vs. Dynamic + +Historically, the USGS NSHMP has produced static datasets of hazard curves that accompany the 'official' release or update to a model. In the context of providing interactive web services, such static datasets can be quickly retreived and provide most users with the data they seek. More complex analyses, such as deaggregations, require that a complete hazard calculation be performed on demand. Historically, USGS deaggregation services were provided for particular model years and regions, each located at a unique web address and supported by a unique codebase. However, it has proven too difficult to maintain numerous isolated services, and we therefore developed a single codebase that supports all current and prior models. + +Moreover, as time goes by, there may be more customization options we want to expose to users. However, with each additional level of customization, it quickly becomes too difficult to produce and version corresponding static datasets. We therefore identify model versions that support deaggregations and other calculations as 'dynamic'. At present, only the most current versions of a particular model region and year are supported via 'dynamic' calculations. + +In practice, this leads to results produced by 'dynamic' caluculations being somewhat different than those stored in static datasets of prior model minor versions, although usually not by much. The release notes for each model version detail the changes that give rise to changes in hazard between between versions. There are also differences that arise from different modeling assumptions between past and current codebases that are detailed below. + +It is important for users to know which edition they should be using. For instance if one is bound to use those values adopted by the U.S. building code, one of the editions marked `ASCE7-*` is probably most appropriate. However, if one is bound to use the most up to date source model, one of the dynamic editions is likely better. + +Dynamic editions are supported through web-services provided by the `nshmp-haz-ws` library (this repository). Static editions are supported via a separate set of services. Both are documented on the [web services](web-services) page. + +### Region specific changes + +Changes between editions in model regions are documented in the release notes of the individual model repositories. + +* [Conterminous US (2014)](/usgs/nshmp-model-cous-2014/wiki) +* [Conterminous US (2008)](/usgs/nshmp-model-cous-2008/wiki) +* [Alaska (2007)](/usgs/nshmp-model-ak-2007/wiki) + diff --git a/docs/Frequently Asked Questions.md b/docs/Frequently Asked Questions.md new file mode 100644 index 0000000000000000000000000000000000000000..815bde0fdf25ab4d3468ccc1f119150f5f45b112 --- /dev/null +++ b/docs/Frequently Asked Questions.md @@ -0,0 +1,92 @@ + +### General +* [What is the Unified Hazard Tool (UHT)?](#what-is-the-unified-hazard-tool-uht) +* [How long will the UHT be supported?](#how-long-will-the-uht-be-supported) +* [Will the URL of the tool change?](#will-the-url-of-the-tool-change) +* [What are the strengths and limitations of the UHT?](#what-are-the-strengths-and-limitations-of-the-uht) +* [Where are the earthquake rate, deaggregation, and other tools now?](#where-are-the-earthquake-rate-deaggregation-and-other-tools-now) +* [Why were the existing tools retired?](#why-were-the-existing-tools-retired) +* [Are the web-services underlying the UHT documented and available for use?](#are-the-web-services-underlying-the-uht-documented-and-available-for-use) +* [I have a question or suggestion; how can I provide feedback?](#i-have-a-question-or-suggestion-how-can-i-provide-feedback) + +### Models & Editions +* [What models are supported?](#what-models-are-supported) +* [Is the 2002 Conterminous U.S. model supported?](#is-the-2002-conterminous-us-model-supported) +* [Are time dependent models supported?](#are-time-dependent-models-supported) +* [Why are some site classes and spectral periods disabled?](#why-are-some-site-classes-and-spectral-periods-disabled) +* [How do I enter a custom site class or Vs30?](#how-do-i-enter-a-custom-site-class-or-vs30) + +### Deaggregation +* [How do I generate a PDF deaggregation report?](#how-do-i-generate-a-pdf-deaggregation-report) +* [Where is the geographic deaggregation option?](#where-is-the-geographic-deaggregation-option) +* [Where is the conditional spectrum option?](#where-is-the-conditional-spectrum-option) +* [How are UCERF3 deaggregations handled?](#how-are-ucerf3-deaggregations-handled) +* [What are 'Recovered targets'?](#what-are-recovered-targets) + + +## General + +#### What is the Unified Hazard Tool (UHT)? +The Unified Hazard Tool provides a single, streamlined interface for accessing various USGS National Seismic Hazard Models (NSHMs) and data derived therefrom. One may use the UHT to obtain probabilistic hazard curves, perform deaggregations of seismic hazard, as well as obtain earthquake rate and probability data. The UHT replaces a suite of independent tools formerly available on the USGS website. + +#### How long will the UHT be supported? +Indefinitely. + +#### Will the URL of the tool change? +Not anytime soon. If and when it does, a redirect will be used. We apologize that this was not done when retiring our legacy tool set. + +#### What are the strengths and limitations of the UHT? +TODO + +#### Where are the earthquake rate, deaggregation, and other tools now? +These data and services are now provided exclusively through the UHT and its underlying web services. Please see the [legacy tools](legacy-tools) page for a summary of those tools that were retired and how they are being replaced. + +#### Why were the existing tools retired? +TODO + +#### Are the web-services underlying the UHT documented and available for use? +Yes, please see the [web-service](home#web-services) documentation. + +#### I have a question or suggestion; how can I provide feedback? +Developers of the UHT can be reached via the ["Question or comments?"](mailto:pmpowers+uht@usgs.gov?subject=EHP%20Website%20Email%20) link at the bottom of the UHT page. For technical problems relating to the UHT, consider submitting an [issue](https://github.com/usgs/earthquake-hazard-tool/issues). For problems relating to any underlying web-services and results generated by the UHT, one may alternatively submit an issue [here](https://github.com/usgs/nshmp-haz-ws/issues). + + +## Models & Editions + +#### What models are supported? +Our goal is to support static datasets and dynamic calculations in the UHT using the current and prior model in any given region. For the Conterminous U.S., we therefore provide access to the 2008 and 2014 models and related data. In other regions, for example Hawaii where the last model update was in 1998, we've decided to delay support for dynamic calculations (e.g. deaggregation) until we've updated the model itself, an effort that is currently underway. + +#### Is the 2002 Conterminous U.S. model supported? +Unfortunately, no. [See above](#what-models-are-supported). The 2002 raw data and publications are still available [here](https://earthquake.usgs.gov/hazards/hazmaps/conterminous/index.php#2002). We recommend users try to use the much improved 2008 model if possible. + +#### Are time-dependent models supported? +All USGS models and data provided by the UHT are time-independent. This may change in the future. + +#### Why are some site classes and spectral periods disabled? +The UHT provides both [static and dynamic](home#static-vs-dynamic) data. Static data only exists at those site classes and spectral periods for which we have precomputed hazard curves. Some site classes are region specific. For example hazard for hard-rock sites (Vs30 = 2000 m/s) is only available for sites on the stable craton of the central and eastern U.S. For the 2014 Conterminous U.S. editions, we are currently reviewing datasets for additional site classes and spectral periods and will add them to the tool soon. For dynamic editions, we plan to add the ability for users to specify a site class (Vs30 value) in the near future. + +#### How do I enter a custom site class or Vs30? +The UHT provides both [static and dynamic](home#static-vs-dynamic) data. Static data is precomputed and retrieved from a database and only exists for those sites + +## Deaggregation + +#### How do I generate a PDF deaggregation report? + + +#### Where is the geographic deaggregation option? +Geographic deaggregation was an option in the legacy deaggregation tools. The UHT does not currently generate an aerial perspective plot as was available previously, however the *Deaggregation Contributors* list reports location data for those sources that significantly contribute to hazard at a site. We are considering adding a downloadable Google Earth KML to the deaggregation results, or may spend time developing a new perspective plot. We welcome any [feedback](mailto:pmpowers+uht@usgs.gov?subject=EHP%20Website%20Email%20) on what users would prefer. + +#### Where is the conditional spectrum option? +Conditional spectrum was an option in the legacy deaggregation tools. We are actively developing a replacement for this, however it will intitally only be available via the web-service results. At some later date, we'll likely add a plot to accompany the total and per-ground-motion-model deaggregations. + +#### How are UCERF3 deaggregations handled? +[UCERF3](http://www.wgcep.org/UCERF3) is the California component of the 2014 USGS National Seismic hazard Model (NSHM). It relaxes fault segmentation, allowing for "multi-fault ruptures", and therefore provides rates for hundreds-of-thousands of possible rupture geometries within the California fault network, where all named, mapped, 'parent' faults have been discretized into ~7 km long sections. When deaggregating, the list of contributing sources to hazard at a site is very long with no individual rupture or ruptures contributing significantly to the total hazard. To address this, the deaggregation service behind the UHT aggregates contributions on a per-fault-section basis, with rupture contributions only ever counted once. The UHT deaggregation contributor list shows those sections, identified by a 'parent' fault name and section index, which contribute most to hazard at a site. Under the hood, the total contribution of a section is also decomposed by magnitude, however we do not report these value at this time, just the mean magnitude for the section. + +#### What are 'Recovered targets'? +__TODO: move to tool documentation__When deaggregating hazard, the target ground motion at which to deaggregate is selected via interpolation using the specified time horizon in the UHT. This target ground motion is rarely the same as one of the original hazard ordinates, so in performing the deaggregation, the contribution to hazard at the specified ground motion is computed for all sources, with the sum of the contributions generally coming in a few percent lower than that computed via interpolation of the total hazard curve. UHT deaggregations also do not consider the additional epistemic uncertainty applied to ground motion models used in the Western U.S. + + + + + + diff --git a/docs/Legacy Tools.md b/docs/Legacy Tools.md new file mode 100644 index 0000000000000000000000000000000000000000..5a2cbf8ef710160e456fbb79e17b8bc5dfa03dd5 --- /dev/null +++ b/docs/Legacy Tools.md @@ -0,0 +1,38 @@ +The following table lists the National Seismic Hazard Mapping Project (NSHMP) online tools that were recently retired. Many of the tools were model edition sepcific. Most have been replaced by, or will soon be added to, the new [Unified Hazard Tool (UHT)](https://earthquake.usgs.gov/hazards/interactive/) or the [web services](home#web-services) that underlie it. + +Application | Year | Status | +------------|:----:|:------:| +Custom Hazard Maps<sup>†</sup> | multiple | :large_orange_diamond: +Earthquake Probabiltiy Maps<sup>†</sup> | multiple | :large_orange_diamond: +Hazard Curve Tool<sup>††</sup> | multiple | :white_check_mark: +Deaggregation (a.k.a Interactive Deaggregation) | | + – Conterminous U.S. | 2014 | :white_check_mark: + – Conterminous U.S. | 2008 | :white_check_mark: + – Conterminous U.S. | 2002 | :x: + – Conterminous U.S. | 1996 | :x: + – Alaska | 2007 | :white_check_mark: + – Alaska | 1999 | :x: + – American Samoa | 2012 | :large_orange_diamond: + – Guam & Northern Mariana Islands | 2012 | :large_orange_diamond: + – Hawaii | 1998 | :large_orange_diamond: + – Puerto Rico & U.S. Virgin Islands | 2003 | :large_orange_diamond: +Banded Deaggregation<sup>†††</sup> | | :x: +Conditional Spectrum (deaggregation add-on)<sup>†††</sup> | | :large_orange_diamond: +Fault Source Map<sup>‡</sup> | multiple | :eight_spoked_asterisk: +Fault Source Database Search<sup>‡</sup> | multiple | :eight_spoked_asterisk: +Vs30 Global Map Server<sup>‡‡</sup> | | :x: + +:white_check_mark: = implemented in UHT +:eight_spoked_asterisk: = updated tool with new URL +:large_orange_diamond: = partial implementation or under development for inclusion in UHT +:x: = retired + +<sup>†</sup> Custom hazard and earthquake probability maps are now included in the _Earthquake Hazard and Probability Maps_ module of the UHT. The current set of layers is limited but will be expanded in the future. Earthquake probabilities for a site of interest are available via a [web service](home#web-services). + +<sup>††</sup> The legacy _Hazard Curve Tool_ reported precomputed, static hazard curves for multiple site classes and spectral periods, and for the 2008 Conterminous U.S. model exclusively. This functionality has been transferred to the UHT, along with support for numerous outher models. See also the explanation of [Editions](home#editions-explained). + +<sup>†††</sup> Banded deaggregation will likely be replaced by the ability to deaggregate on the probability of _occurrence_, as opposed to _exceedance_. Conditional spectra data will initially be included in [deaggregation service](home#web-services) responses; in the future the UHT will render these data in plot form. + +<sup>‡</sup> The fault source map and database search tools that accompanied many model releases are now available in updated locations. For example, for the 2014 Conterminous U.S. model see this [map](https://earthquake.usgs.gov/hazards/qfaults/map/#hazfaults2014) and [database](https://earthquake.usgs.gov/cfusion/hazfaults_2014_search) search. The fault source maps are slated for inclusion in the _Earthquake Hazard and Probability Maps_ module of the UHT. + +<sup>‡‡</sup> A web service replacement for the the global Vs30 map server is planned. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000000000000000000000000000000000..b27a12200cd7695a1073e529ba92aa022a059793 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,11 @@ + +> This repository has been moved to GitLab: +> [https://code.usgs.gov/ghsc/nshmp/nshmp-haz](https://code.usgs.gov/ghsc/nshmp/nshmp-haz). + +***nshmp-haz-ws*** is a web-service wrapper around the *[nshmp-haz](https://github.com/usgs/nshmp-haz)* probabilistic seismic hazard analysis (PSHA) platform. It is developed and maintained by the National Seismic Hazard Mapping Project ([NSHMP](https://earthquake.usgs.gov/hazards)) within the U.S. Geological Survey's ([USGS](https://www.usgs.gov)) earthquake hazards program ([EHP](http://earthquake.usgs.gov)). + +*nshmp-haz-ws* services supply data to the USGS NSHMP [Unified Hazard Tool (UHT)](https://earthquake.usgs.gov/hazards/interactive/). While basic documentation on the use of the tool is available [here](https://earthquake.usgs.gov/hazards/interactive/documentation.php), this documentation describes the details of the underlying data and calculations, including descriptions or examples of: +* How to [run hazard and deaggregation services](building-&-running) locally. +* The different [editions](editions-explained) of the hazard models the NSHMP produces and their distinguidhing features. +* [Static vs. dynamic](editions-explained#static-vs-dynamic) data. +* Common [use cases](use-cases). diff --git a/docs/UHT Release Notes.md b/docs/UHT Release Notes.md new file mode 100644 index 0000000000000000000000000000000000000000..a0a4619257675e980b20fd2eb25fa1810e7621c9 --- /dev/null +++ b/docs/UHT Release Notes.md @@ -0,0 +1,7 @@ + + +Date | nshmp-haz | nshmp-haz-ws | COUS 2008 | COUS 2014 | AK 2007 | +-----|:---------:|:------------:|:---------:|:---------:|---------| +03/01/17 | v1.0.0 | v1.0.0 | v3.3.0 | v4.1.0 | | +04/01/17 | v1.0.1 | v1.0.1 | v3.3.0 | v4.1.0 | | +05/05/17 | v1.1.1 | v1.1.1 | v3.3.1 | v4.1.1 | v2.1.0 | diff --git a/docs/Use Cases.md b/docs/Use Cases.md new file mode 100644 index 0000000000000000000000000000000000000000..91a1da976e07da53d0ce919fb6d62c50fb09843f --- /dev/null +++ b/docs/Use Cases.md @@ -0,0 +1,29 @@ + +This page explains in greater detail how to obtain different types of information from the Unified Hazard Tool (UHT). + +#### How do I get the PGA value for a specific return period (e.g. 2475 years)? + +> This information was formerly available via the Hazard Curve Application and various Interactive Deaggregation applications. + +1. __Input panel:__ select `Edition`, `Location`, and `Site Class`. You may also select `Spectral Period` and `Time Horizon` at this time but it is not necessary. +2. __Hazard Curve panel__: `Compute Hazard Curve`. + +__What's happening above?__ When `Compute Hazard Curve` is selected, either static hazard curves are retreived from a database or curves are computed on demand depending on the `Edition` selected. In either case, the curves for _all_ supported spectral periods are retrieved. When the _Hazard Curve_ plot is drawn, whichever `Spectral Period` is selected in the __Input__ panel is now highlighted in black. You can change the selected `Spectral Period` by either changing the input control, or by selecting the curve or legend item in the plot. Note that when you change the spectral period, the black dot on the _Reponse Spectrum_ plot also moves. + +__What is a response spectrum?__ The _Reponse Spectrum_ plot shows the ground motion values of each spectral period for the currently selected `Time Horizon`. These values are the intercepts, computed via log-log interpolation, of the red, horizontal line in the _Hazard Curve_ plot (__KNOWN ISSUE:__ RED TIME HORIZON LINE IS NOT BEING DRAWN ON PLOT). If you change the `Time Horizon` in the `Input` panel, you will see the shape of the response spectrum change. + +3. __Hazard Curve panel__: _Response Spectrum_ plot; hover over the points to get the ground motion value for the `Spectral Period` and `Time Horizon` of interest. The first point (at x = 0.0) is always PGA. In the near future, we will be adding a label to the response spectrum plot that shows the selected spectral period and corresponding ground motion level, the information currently displayed in the pop-up. + +#### How do I perform a deaggregation? + +> This information was formerly available via various Interactive Deaggregation applications. + +It is important to note that many users had been using the interactive deaggregations applications to get a single value off a hazard curve. While a deaggregation does compute and report this data point as part of a result, it can also be found following the steps in the first use case [above](#use-cases). In point of fact, a deaggregation uses that single value as a starting point to analyze the relative contributions to hazard from different sources. The value itself is not the primary result of performing the deaggregation. + +1. __Input panel:__ select a 'dynamic' `Edition`. +2. __Input panel:__ select a `Location`, and `Site Class`, `Spectral Period` and `Time Horizon`. +3. __Deaggregation panel__: `Compute Deaggregation`. + +KNOWN ISSUES: +* Deaggregation bars overrun plot boundaries +* `Download Deaggregation Report` link does not work. This is a known issue with recent versions of Internet Explorer; please use Chrome until this can be fixed. diff --git a/docs/_Footer.md b/docs/_Footer.md new file mode 100644 index 0000000000000000000000000000000000000000..2d4ca388b4d8b8d0490a96eb062ef8754f06bb29 --- /dev/null +++ b/docs/_Footer.md @@ -0,0 +1 @@ +[<img valign="middle" src="images/usgs-icon.png">](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/_Sidebar.md b/docs/_Sidebar.md new file mode 100644 index 0000000000000000000000000000000000000000..6bd372e8b445556ded97fabe1a9b387eefd35d94 --- /dev/null +++ b/docs/_Sidebar.md @@ -0,0 +1,7 @@ +[Home](home) +[Building & Running](building-&-running) +[Editions Explained](editions-explained) +[UHT Release Notes](uht-release-notes) +[Use Cases](use-cases) +[Legacy Tools](legacy-tools) +[FAQs](frequently-asked-questions) diff --git a/docs/images/usgs-icon.png b/docs/images/usgs-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..034fdba1d046f4da94dc04fb034f6f5b55a76c49 Binary files /dev/null and b/docs/images/usgs-icon.png differ