USGS ShakeMap Interface

This module provides functionality to load, manage, and export ground motion data from ShakeMap products generated by the USGS (or compatible implementations), especially in the context of emergency response, scientific exercises, or automated seismic impact evaluation.

ShakeMap products typically include: - Metadata describing the seismic event (info.json) - A regular grid of ground motion values (grid.xml) - Standard deviations for each grid point (uncertainty.xml) - (Optional) Observational data from stations (stationlist.json)

The main class, ShakeMapEvent, serves as a container that organizes these files and provides methods for: - loading from a ShakeMap directory or individual files, - querying ground motion parameters (PGA, MMI, etc.), - exporting results in CSV or GeoJSON format, - interpolating values onto custom site locations, - and summarizing available information.

Usage Examples

Example 1 – Quick loading from a ShakeMap folder

This is the most convenient method for loading a complete ShakeMap directory. All supported files (grid.xml, info.json, etc.) are automatically detected and parsed.

Python 
 1from shakelab.hazard.usgs import ShakeMapEvent
 2
 3# Load all ShakeMap files in one call
 4event = ShakeMapEvent(folder="shakemap/current/products")
 5
 6# Print metadata
 7print("Event ID:", event.event_id)
 8print("Magnitude:", event.magnitude)
 9print("Origin time:", event.origin_time)
10
11# Access PGA values
12pga = event.gm_data.get_param("PGA")
13print("First PGA:", pga[0])
14
15# Export the original grid to GeoJSON
16event.export("outputs/output_grid.geojson")

Example 2 – Create an empty object and load files incrementally

If needed, you can construct an event in steps, by loading each file manually. This is useful when working with incomplete data or during interactive debugging.

Python 
 1from shakelab.hazard.usgs import ShakeMapEvent
 2
 3event = ShakeMapEvent()
 4
 5# Load each file manually
 6event.load_info("shake/info.json")
 7event.load_grid("shake/grid.xml")
 8event.load_uncertainty("shake/uncertainty.xml")
 9event.load_stations("shake/stationlist.json")
10
11# Export to CSV using original grid points
12event.export("outputs/shaking.csv")

Example 3 – Export to a custom site grid (GeoJSON input, CSV output)

You can export ground motion values interpolated onto a custom list of sites, for instance centroids of exposure zones. This example shows input via GeoJSON and output as CSV.

Python 
 1from shakelab.hazard.usgs import ShakeMapEvent
 2
 3event = ShakeMapEvent(folder="shake/")
 4
 5event.export(
 6    path="outputs/custom_sites.csv",
 7    site_file="inputs/grid_ita_centroids.geojson",
 8    parameters=["PGA", "MMI"],
 9    nan_fill=0.0
10)

Example 4 – Export interpolated values to GeoJSON

This example performs the same interpolation as above but produces a GeoJSON output, including additional uncertainty parameters if available.

Python 
1event.export(
2    path="outputs/custom_sites.geojson",
3    site_file="inputs/grid_ita_centroids.geojson",
4    parameters=["PGA", "MMI", "STDPGA"],
5    nan_fill=-999.0
6)

Example 5 – Display a summary of the ShakeMap contents

The .summary() method provides a quick overview of the loaded files, number of grid points, available parameters, and geographic extent.

Python 
1event = ShakeMapEvent(folder="shakemap/current/products")
2event.summary()

Example 6 – Query ground motion values at custom locations

You can use the get_ground_motion() method to retrieve interpolated values of ground motion parameters (PGA, MMI, etc.) at one or more site coordinates. This can be useful for rapid checks or integration with other models (e.g. exposure, fragility).

Python 
 1from shakelab.hazard.usgs import ShakeMapEvent
 2
 3event = ShakeMapEvent(folder="shake/")
 4
 5# Single site: (longitude, latitude)
 6result = event.get_ground_motion((13.5, 46.0),
 7                                 parameters=["PGA", "MMI"])
 8print(result[0])  # e.g. {'PGA': 0.32, 'MMI': 6.9}
 9
10# Multiple sites
11sites = [(13.2, 45.8), (13.7, 46.2)]
12values = event.get_ground_motion(sites,
13                                 parameters=["MMI"],
14                                 nan_fill=0.0)
15
16for v in values:
17    print(v)  # e.g. {'MMI': 6.3}, {'MMI': 7.1}