seaturtles 1.1.0
Scenario Earthquakes and the Uncertainty in Regional-Level Estimates of Shaking intensities
License: MIT License

<p align="center"> <img src="https://raw.githubusercontent.com/annehulsey/seaturtles/main/doc_src/figures/seaturtles_title.PNG" align="middle" height=75 /></p>

<p align="center"> <b>S</b>cenario</b> <b>E</b>arthquakes</b> <b>a</b>nd</b> <b>t</b>he <b>U</b>ncertainty in <b>R</b>egional-<b>L</b>evel <b>E</b>stimates of <b>S</b>haking Intensities</p>



## What is it?

`seaturtles` is a Python package that provides tools for simulating a set of regional ground motion maps that represent the uncertainty in shaking intensities that could be generated by during earthquake scenario.

## What can I use it for?

`seaturtles` generates a set of simulated ground motion maps that represent the potential range of ground shaking intensities due to an earthquake scenario. For example, the spectral accelerations, Sa(T), generated at sites located across downtown San Francisco during a magnitude 7.2 event on a nearby segment of the San Andreas Fault.

These sets of ground motion maps are typically utilized in regional performance assessments that consider the range of potential performance, as opposed to the expected performance. These assessments include uncertainty in both the ground shaking intensity and the built environment's response to the shaking.

## How does it work?

`seaturtles` first uses SimCenter's [EQHazard tool](https://github.com/NHERI-SimCenter/GroundMotionUtilities/tree/master/EQHazard) to input a selected earthquake scenario (a rupture magnitude and location) and extract ground motion predictions (medians and standard deviations) for spatially distributed site locations. See the [EQHazard documentation](https://github.com/NHERI-SimCenter/GroundMotionUtilities/tree/master/EQHazard) for details on the available earthquake forecast rupture (ERF) models and ground motion models (GMMs). The EQHazard version included in the package was built on May 7, 2021.

`seaturtles` then uses a computationally efficient model ([Markhvida et al. 2018](https://doi.org/10.1002/eqe.3007)) for simulating spatially correlated residuals across multiple periods. These simulated residuals are combined with the medians and standard deviations at each site location to produce a set of ground motion maps. See [Markhvida et al. 2018](https://doi.org/10.1002/eqe.3007) for more details. (Note that this correlation model only considers periods up to 5 seconds. In order to include periods greater than 5 seconds, `seaturtles` assumes perfect correlation among the residuals for periods between 5 and 10 seconds.)

## How can I get started?

You can get oriented with the [example](https://github.com/annehulsey/seaturtles/tree/main/example/example.zip) provided on the `seaturtles` GitHub repository. This example includes three Jupyter Notebooks and two supporting data files:
- ***Selecting Indices for an Earthquake Scenario***: uses the EQHazard tool to filter an ERF's ruptures to identify relevant source and rupture indices for the desired magnitude(s) and location(s). 
- ***Simulate Ground Motion Maps for an Earthquake Scenario***: generates a set of simulated ground motion maps for a M<sub>w</sub>7.2 rupture on the San Andreas Fault, based on the site locations and the selected GMM (Chiou and Youngs, 2014).
- ***Simulate Ground Motion Maps for Multiple Earthquake Scenarios***: generates a set of simulated ground motion maps for each of four earthquake scenarios.
- ***SF_Downtown_Sites.csv***: contains attributes for the site locations.
- ***CA_polygon.geojson***: contains an outline of California, for mapping the ERF ruptures.

## Installation

`seaturtles` is available at the Python Package Index (PyPI). You can simply install it using `pip` as follows:

```
pip install seaturtles
```

The embedded [EQHazard tool](https://github.com/NHERI-SimCenter/GroundMotionUtilities/tree/master/EQHazard) requires Java. It can be downloaded [here](https://www.java.com/en/download/).

## License

`seaturtles` is distributed under the MIT license, see [LICENSE](https://github.com/annehulsey/seaturtles/blob/main/LICENSE).

## Contact

Anne Hulsey, University of Auckland, anne.hulsey@auckland.ac.nz