Home

nshmp-haz-ws is a Java library developed by the U.S. Geological Survey (USGS) earthquake hazards program (EHP) to support web services built on top of the nshmp-haz PSHA library.

This documentation describes components of the new USGS NSHMP Unified Hazard Tool (UHT), including descriptions or examples of:

• The different editions of the hazard models the NSHMP produces.
• Static vs. dynamic data.
• Common use cases.

This documentation is being actively updated and improved based on user feedback for the UHT. It will supercede or supplant the limited documentation currently available via the Documentation & Help on the application page.

Editions Explained

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 generally associated with a USGS Open-File report and supporting datasets. However, layered on top of any given model release are numerous bug-fixes and model improvements.

With the update to a new codebase, nshmp-haz, the NSHMP is adopting semantic versioning 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 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	v4.1.0		✅
Conterminous U.S.	2014	v4.0.0	✅		ASCE7-16
Conterminous U.S.	2008	v3.3.0		✅
Conterminous U.S.	2008	v3.2.0	✅
Conterminous U.S.	2008	v3.1.0	✅		ASCE7-10
Conterminous U.S.	2008	v3.0.0
Conterminous U.S.	2002	v2.0.0
Conterminous U.S.	1996	v1.0.0
Alaska	2007	v2.1.0		✅
Alaska	2007	v2.0.0	✅		ASCE7-10
Alaska	1999	v1.0.0
American Samoa	2012	v1.0.0
Guam	2012	v1.0.0
Hawaii	2018	v2.0.0		TBD
Hawaii	1998	v1.1.0		TBD
Hawaii	1998	v1.0.0	✅		ASCE7-10
Puerto Rico & U.S. Virgin Islands	2003	v1.0.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'. 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, probably one of the dynamic editions is better.

Use Cases

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 chape 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. 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 is not the 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.