shakemap-sampling-tool 1.0.1

USGS Earthquake Basic Geographic Utilities

ShakeMap Sampling Tool

This page describes tools that can be used to extract station data and sample modeled values from ShakeMaps either online or on a user's local system.

NOTE: All tools described here only sample binary HDF files, not grid.xml, and only sample from NEIC (source=us) ShakeMaps when sampling online!

• Install
• Update
• Usage
  • Getting Help
  • Sampling
    • Sample Locally
    • Sample at Station Locations
    • Sample at a Single Coordinate
    • Sample at All Stations
  • Get All Values for Point ShakeMaps
  • Sample From Input Spreadsheet

Reference

If you wish to cite this software, please use this reference:

• Hearne, M., and D. J. Wald (2021). ShakeMap Sampling Tool, USGS Software Release, doi: 10.5066/P94RJYCS.

Install

• pip install git+https://code.usgs.gov/ghsc/esi/shakemap-sampling-tool.git
• Run sst --help to see an how the command works.

Update

• pip install --upgrade git+https://code.usgs.gov/ghsc/esi/shakemap-sampling-tool.git

Usage:

Getting Help

First type sst -h

and you will see help for the main program, along with a list of sub-commands:

usage: sst [-h] {get-stations,sample} ...

Sample ShakeMap data, online or on local ShakeMap installation.

This program offers a number of sub-commands, listed below. To see the help
for any of these commands, type:

sst [SUB-COMMAND] --help

optional arguments:
  -h, --help            show this help message and exit

Sub-commands:
  {get-stations,sample}
                        sub-command help
    get-stations        Get list of stations included in ShakeMap
    sample              Sample online ShakeMap.

To see the help for the first sub-command, get-stations, type sst get-stations -h:

usage: sst get-stations [-h] [-l] [-o OUTFILE] [-m] eventid

Return a list of stations contained in the processed files.

positional arguments:
  eventid               ComCat event ID.

optional arguments:
  -h, --help            show this help message and exit
  -l, --local           Search for ShakeMap information on local system. (default: False)
  -o OUTFILE, --outfile OUTFILE
                        Output station information to Excel/CSV file. (default: None)
  -m, --max-horizontal  Only return rows with maximum horizontal value. (default: False)

To see the help for the second sub-command, type sst sample -h:

usage: sst sample [-h] (-c ID LAT LON | -s STATIONS [STATIONS ...] | -a | -f FILE) [-o OUTFILE] [-l LOCAL] eventid

Sample local data sets using one of a number of methods.

Mutually exclusive sampling options include:
 - By a single set of coordinates: (-c, --coordinates)
 - By supplying station IDs found in ShakeMap: (-s, --stations)
 - Sample locations of every station found in ShakeMap: (-a, --all-stations
 - By supplying an input file with IDs and coordinates: (-f, --file)

positional arguments:
  eventid               ComCat event ID.

optional arguments:
  -h, --help            show this help message and exit
  -c ID LAT LON, --coordinates ID LAT LON
                        Use an ID string and single set of coordinates to sample ShakeMap. (default: None)
  -s STATIONS [STATIONS ...], --stations STATIONS [STATIONS ...]
                        Use station codes (NET.STA format) (found in ShakeMap) to sample ShakeMap. (default: None)
  -a, --all-stations    Output values at nearest point of all stations found in ShakeMap. (default: False)
  -f FILE, --file FILE  Use CSV/Excel file to sample ShakeMap. File must at least contain columns that start with
                        "lat" or "lon" (case does not matter. Optionally, it may contain a column called "id" (again,
                        case insensitive) which will be used to identify each point. In the absence of this column,
                        each point will be assigned an oridinal ID number "Point1", "Point2", and so on. (default:
                        None)
  -o OUTFILE, --outfile OUTFILE
                        Output station information to Excel/CSV file. (default: None)
  -l LOCAL, --local LOCAL
                        Sample local HDF file. (default: None)

Sampling

Cut and paste the "event id" from a ComCat event page:

For this URL:

https://earthquake.usgs.gov/earthquakes/eventpage/ci38695658/executive

The event ID is "ci38695658".

---

Sample Locally

If you have ShakeMap installed locally, you can run any event found in ComCat with its input data. See the ShakeMap Wiki which describes basic installation and running.

Any command described below can be used to sample the local copy of an event simply by adding the "-l" or "--local" options:

sst sample ci38695658 -c "Mobil Refinery" 33.853 -118.336

will work assuming that you have

1. Installed ShakeMap locally and
2. Run the event ci38695658 on your system.

---

Get List of Stations

You can get a list of all stations contained in that ShakeMap by running:

sst get-stations ci38695658 -o ~/tmp/ci38695658_stations.xlsx

This command will take several seconds to run, as it must download a binary data file from the ANSS ComCat system and then extract information from that file.

---

Sample at Station Locations

Opening that file you will see a list of all station data that was provided to ShakeMap. Note that not all of the stations listed here will be inside the bounds of the ShakeMap. If you want to be assured that the stations at which you sample the ShakeMap are inside the map, you can use the interactive ShakeMap on the page above by clicking on "ShakeMap" on the left hand side, and then clicking anywhere in the map shown in the center. You can click on any of the triangle symbols on this map and bring up the name and code of a station:

To sample the data at this station:

sst sample ci38695658 -s CI.RHC2

You will see output that looks like this:

     id      lat        lon sample_lat sample_lon sample_distance_m       vs30  MMI_mean  MMI_std  PGA_mean  PGA_std  PGV_mean  PGV_std  SA(0.3)_mean  SA(0.3)_std  SA(1.0)_mean  SA(1.0)_std  SA(3.0)_mean  SA(3.0)_std
CI.RHC2 34.00100 -118.01330   34.00000 -118.01667          329.6720 408.831879  4.353083 0.512055 -2.877283 0.521441  0.654555 0.448521     -2.217618     0.548467     -4.778402     0.427761     -6.815022     0.356534

You can sample multiple stations at the same time, and output the results to a CSV or Excel file:

sst sample ci38695658 -s CI.RHC2 CI.RUS CE.23077 -o ~/tmp/ci38695658_samples.xlsx

---

Sample at a Single Coordinate

You can also sample one station by providing an ID and lat/lon coordinates at the command line:

sst sample ci38695658 -c "Mobil Refinery" 33.853 -118.336

            id      lat        lon sample_lat sample_lon sample_distance_m       vs30  MMI_mean  MMI_std  PGA_mean  PGA_std  PGV_mean  PGV_std  SA(0.3)_mean  SA(0.3)_std  SA(1.0)_mean  SA(1.0)_std  SA(3.0)_mean  SA(3.0)_std
Mobil Refinery 33.85300 -118.33600   33.85000 -118.33333          414.6328 283.185089  3.149629 0.497229 -4.092396 0.537725 -0.605861 0.464171     -3.528294     0.562528     -5.650388     0.444138     -7.813053     0.377669

---

Sample at All Stations

To sample the ShakeMap at all of the stations provided to ShakeMap that are also inside the boundaries of the map:

sst sample ci38695658 -a -o ~/tmp/ci38695658_sample_all_stations.xlsx

Note that stations not inside the map bounds have blank values for intensities.

Get All Values for Point ShakeMaps

ShakeMap allows for creation of "point-based" maps that only calculate the model at specific input locations. (see https://cbworden.github.io/shakemap/manual4_0/tg_processing.html#output-points-vs-grids)

This command only works for local files, as there are no Global ShakeMaps online that are constructed in this way.

To extract all the values for the input points:

sst locations nc216859 -o ~/tmp/loma_prieta_buildings.xlsx

---

Sample From Input Spreadsheet

Finally, you can sample stations at locations you have predefined from a spreadsheet or CSV file:

sst sample ci38695658 -f ~/tmp/socal_sampling_sites.xlsx -o ~/tmp/ci38695658_sample_socal.xlsx