# Table of Contents
- [Table of Contents](#table-of-contents)
- [Introduction](#introduction)
- [Installation](#installation)
- [Upgrade](#upgrade)
- [Configuration](#configuration)
- [Usage](#usage)
- [Probabilities] (#probabilities)
- [Glossary](#glossary)
# Introduction
This library and set of tools was created to provide functionality to
automatically determine the tectonic region of an earthquake
(Subduction, Active, Volcanic, Stable), and the distance to the tectonic
regions to which it does *not* belong.
In addition, SeismoTectonic Regime Earthquake Calculator (STREC) provides a tool that,
in subduction zones, returns information about the subduction zone, using the
USGS Slab2 models.
(https://www.sciencebase.gov/catalog/item/5aa1b00ee4b0b1c392e86467/).
This code was based on the [paper](https://doi.org/10.1785/0120110124):
```
A Global Earthquake Discrimination Scheme to Optimize Ground‐Motion Prediction Equation Selection
D. García; D. J. Wald; M. G. Hearne
Bulletin of the Seismological Society of America (2012) 102 (1): 185–203.
```
# Installation
`pip install usgs-strec`
# Upgrade
`pip install --upgrade usgs-strec`
# Configuration
In order to use STREC you will need to:
- download USGS Slab 2.0 models, described at the Science Base
link above.
- create a database of moment tensors, either manually from a
spreadsheet/CSV file (described below), or by downloading
a default database of moment tensors from the
[Global Centroid Moment Tensor (GCMT) catalog](https://www.globalcmt.org/)
- Create a configuration file describing the locations of these files.
To make this easier, a configuration progran called `strec_cfg` is provided which automates
all of these processes. This program comes with two *sub-commands* called `info` and `update`.
To initialize the system with the Slab 2.0 grids and GCMT moment tensor database:
`strec_cfg update --datafolder <path/to/data/folder> --slab --gcmt`
For example, if you set the STREC data folder to be */data/strec*:
`strec_cfg update --datafolder /data/strec --slab --gcmt`
and then use the following command to see the resulting configuration:
`strec_cfg info`
The output should look something like the following:
```
Config file /home/user/.strec/config.ini:
------------------------
[DATA]
folder = /data/strec
slabfolder = /data/strec/slabs
dbfile = /data/strec/moment_tensors.db
[CONSTANTS]
minradial_disthist = 0.01
maxradial_disthist = 1.0
minradial_distcomp = 0.5
maxradial_distcomp = 1.0
step_distcomp = 0.1
depth_rangecomp = 10
minno_comp = 3
default_szdip = 17
dstrike_interf = 30
ddip_interf = 30
dlambda = 60
ddepth_interf = 20
ddepth_intra = 10
------------------------
Moment Tensor Database (/data/strec/moment_tensors.db) contains 60535 events from 1 sources.
There are 135 slab grids from 27 unique slab models located in /data/strec/slabs.
```
# Usage
`regcalc` is the program used to calculate region parameters.
The details of the options are visible by running `regcalc --help`.
The three most basic use cases are:
- Getting information about an event by ComCat ID: `regcalc -d us6000id0t`
- Getting information about a (possibly theoretical) event by providing hypocenter information: `regcalc -e -5.0735 103.0826 50.5`
- Getting information about more than one event, with input like below as Excel or CSV:
<table>
<tr>
<th>Latitude</th>
<th>Longitude</th>
<th>Depth</th>
</tr>
<tr>
<td>-5.074</td>
<td>103.083</td>
<td>50.5</td>
</tr>
<tr>
<td>-1.008</td>
<td>98.642</td>
<td>17.6</td>
</tr>
</table>
`regcalc -i input_file.xlsx`
You can add a ComCat ID column to this - the name which will be automatically detected is *EventID* (case does not matter). If the file has another name for the same column you can supply that with the --id-column command line option:
`regcalc -i input_file.xlsx --id-column id`
If the file contains column names for latitude, longitude and depth that do not match the regular expression patterns "^lat", "^lon", "^dep" (ignoring case) then you can supply those column names as well using the --hypo-columns command line option:
`regcalc -i input_file.xlsx --hypo-columns EventLatitude EventLongitude EventDepth`
If an input spreadsheet has moment tensor columns named Mrr, Mtt, Mpp, etc. (case does not matter) then those values will be used to calculate the Kagan angle and determine the focal mechanism.
You can also optionally specify moment tensor information for a single event in the form of strike/dip/rake angles and a magnitude, using the --moment-info command line option:
`regcalc -e -0.950 -21.725 10.0 -m 260 84 169 6.9`
*Note: Users may notice that distances to tectonic regions the earthquake is NOT in may be unreasonably large values. The reason
for returning the distances to other regions is to help inform the user when the earthquake is close to another region.
When STREC outputs these large numbers it indicates that the distance to that other region is not close enough to affect
the properties of the earthquake.*
# Probabilities
STREC now calculates the probabilities of an earthquake being in any of the tectonic regions, and also in
any of the various defined depth categories. For subduction regions these are hardcoded as
crustal, interface, and intraslab. For other regions, the *default* configuration includes the following:
- acr_shallow : active earthquakes occurring above 30 km
- acr_deep - active earthquakes occurring below 30 km
- scr_shallow - stable earthquakes at any depth
- volcanic_shallow - volcanic earthquakes at any depth
## Probability configuration
Users can configure the probability settings to include more finely grained depth zones for active,
stable, and volcanic regions. The default config file is located in the [repository]
(https://code.usgs.gov/ghsc/esi/strec/-/blob/main/src/strec/data/select.conf) and
installed with the software. To customize the probability depth zones, download a copy of the file from
the repository and save it in the [DATA]->folder in the config.ini file described above.
```
[DATA]
folder = /data/strec
```
The relevant section of the select.conf file to modify looks like the following:
```
[tectonic_regions]
[[acr]]
horizontal_buffer = 100
vertical_buffer = 5
depth_labels = shallow, deep
min_depth = -Inf, 30
max_depth = 30, Inf
[[scr]]
horizontal_buffer = 100
vertical_buffer = 5
depth_labels = shallow
min_depth = -Inf
max_depth = Inf
[[subduction]]
horizontal_buffer = 100
vertical_buffer = 5
depth_labels = crustal, interface, intraslab
min_depth = -Inf, 15, 70
max_depth = 15, 70, Inf
use_slab = True
[[volcanic]]
horizontal_buffer = 10
vertical_buffer = 5
depth_labels = shallow
min_depth = -Inf
max_depth = Inf
```
To add a "deep" (10 km or deeper) category to the scr section, you would modify that
section to look like the following:
```
[[scr]]
horizontal_buffer = 100
vertical_buffer = 5
depth_labels = shallow, deep
min_depth = -Inf, 10
max_depth = 10, Inf
```
# Glossary
STREC defines a number of terms that may not be commonly
understood, so they are explained here. These terms may be different
from the Garcia paper upon which this software is originally based.
- *Tectonic Region*: One of Subduction, Active, Volcanic, or Stable.
We have split up the globe into these four regions, such that any
point on the globe should fall into one and only one of these
regions.
* *Subduction*: A tectonic region defined by one plate descending below
another (e.g., the western portion of the United States), more specifically
by those locations above the Slab2.0 grids.
* *Active*: A tectonic region which experiences crustal deformation due
to plate tectonics.
* *Volcanic*: A tectonic region which is sitting above mantle plumes,
where magma pushes through cracks in the crust.
* *Stable*: Tectonic regions which unlike Active regions, do not
experience crustal deformation (e.g., the interior of the
Australian continent.)
*Fig 1 - Map showing tectonic regions. ACR=Active Crustal Region, SUB=Subduction Zone, VOL=Volcanic Region, SCR=Stable Continental Region*
- *Oceanic*: Another region, not exclusive with the four Tectonic
Regions, that indicates whether the point supplied is in the ocean
(i.e., not continental).
- *Continental*: The opposite of Oceanic.
- *Backarc*: The area of a subduction region that is behind the volcanic arc.
- *Focal Mechanism*: A set of parameters that define the deformation in
the source region that generates the seismic waves of an earthquake.
- *Tensor Type*: The short name for the algorithm used to generate
the moment tensor used to determine focal mechanism, Kagan angle,
etc. This is usually a short code like *Mww* (W-phase), *Mwr*
(regional), *Mwb* (body wave), or *composite*, which indicates that
there is no computed moment tensor, so a composite of historical
moment tensors around the input coordinates is used instead.
- *Tensor Source*: When available, this is usually the network that
contributed the moment tensor, followed by the ID used by that
network (e.g., us_2000bmcg).
- *Kagan Angle*: An single angle between any two moment tensors or in
our case, between a moment tensor and a subducting slab.
- *Composite Moment Tensor*: When moment tensors are not available
for a given event, a composite moment tensor is calculated by
essentially taking the mean of at least three moment tensors in a 0.1
degree box surrounding the earthquake hypocenter.
- *Composite Variability*: When the moment tensor solution is of type
*composite*, a scalar value describing the variability of the moment
tensors used to determine the composite.
- *Distance to [Region]*: The great circle distance from the input
coordinates to the nearest vertex of [Region] polygon.
- *Slab Model Region*: We currently use Slab 2.0 subduction models
(Hayes 2012), which are currently provided for 27 regions around
the globe. These regions are described in detail here:
https://www.sciencebase.gov/catalog/item/5aa1b00ee4b0b1c392e86467/
- *Slab Model Depth*: The best estimate of depth to subduction
interface.
- *Slab Model Depth Uncertainty*: The best estimate of the uncertainty
of the depth to subduction interface.
- *Slab Model Dip*: The best estimate of the dip angle of the
subducting plate.
- *Slab Model Strike*: The best estimate of the strike angle of the
subducting plate.
Raw data
{
"_id": null,
"home_page": "",
"name": "usgs-strec",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "comcat,earthquake",
"author": "",
"author_email": "Mike Hearne <mhearne@usgs.gov>, Eric Thompson <ethompson@usgs.gov>",
"download_url": "https://files.pythonhosted.org/packages/35/10/61bc51d6d36958f59726750fed5eab646ad222823d51977a7599ae4cc937/usgs-strec-2.3.3.tar.gz",
"platform": null,
"description": "# Table of Contents\n- [Table of Contents](#table-of-contents)\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Upgrade](#upgrade)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Probabilities] (#probabilities)\n- [Glossary](#glossary)\n\n# Introduction\n\nThis library and set of tools was created to provide functionality to\nautomatically determine the tectonic region of an earthquake\n(Subduction, Active, Volcanic, Stable), and the distance to the tectonic\nregions to which it does *not* belong.\n\nIn addition, SeismoTectonic Regime Earthquake Calculator (STREC) provides a tool that, \nin subduction zones, returns information about the subduction zone, using the \nUSGS Slab2 models.\n\n(https://www.sciencebase.gov/catalog/item/5aa1b00ee4b0b1c392e86467/).\n\n\nThis code was based on the [paper](https://doi.org/10.1785/0120110124):\n\n```\nA Global Earthquake Discrimination Scheme to Optimize Ground\u2010Motion Prediction Equation Selection\nD. Garc\u00eda; D. J. Wald; M. G. Hearne\nBulletin of the Seismological Society of America (2012) 102 (1): 185\u2013203.\n```\n\n\n# Installation\n\n`pip install usgs-strec`\n\n# Upgrade\n\n`pip install --upgrade usgs-strec`\n\n# Configuration\n\nIn order to use STREC you will need to:\n\n - download USGS Slab 2.0 models, described at the Science Base \n link above. \n - create a database of moment tensors, either manually from a \n spreadsheet/CSV file (described below), or by downloading \n a default database of moment tensors from the \n [Global Centroid Moment Tensor (GCMT) catalog](https://www.globalcmt.org/)\n - Create a configuration file describing the locations of these files.\n\nTo make this easier, a configuration progran called `strec_cfg` is provided which automates \nall of these processes. This program comes with two *sub-commands* called `info` and `update`. \nTo initialize the system with the Slab 2.0 grids and GCMT moment tensor database:\n\n`strec_cfg update --datafolder <path/to/data/folder> --slab --gcmt`\n\nFor example, if you set the STREC data folder to be */data/strec*:\n\n`strec_cfg update --datafolder /data/strec --slab --gcmt`\n\nand then use the following command to see the resulting configuration:\n\n`strec_cfg info`\n\nThe output should look something like the following:\n\n```\nConfig file /home/user/.strec/config.ini:\n------------------------\n[DATA]\nfolder = /data/strec\nslabfolder = /data/strec/slabs\ndbfile = /data/strec/moment_tensors.db\n\n[CONSTANTS]\nminradial_disthist = 0.01\nmaxradial_disthist = 1.0\nminradial_distcomp = 0.5\nmaxradial_distcomp = 1.0\nstep_distcomp = 0.1\ndepth_rangecomp = 10\nminno_comp = 3\ndefault_szdip = 17\ndstrike_interf = 30\nddip_interf = 30\ndlambda = 60\nddepth_interf = 20\nddepth_intra = 10\n------------------------\n\nMoment Tensor Database (/data/strec/moment_tensors.db) contains 60535 events from 1 sources.\n\nThere are 135 slab grids from 27 unique slab models located in /data/strec/slabs.\n```\n\n# Usage\n\n`regcalc` is the program used to calculate region parameters.\n\nThe details of the options are visible by running `regcalc --help`.\n\nThe three most basic use cases are:\n\n - Getting information about an event by ComCat ID: `regcalc -d us6000id0t`\n - Getting information about a (possibly theoretical) event by providing hypocenter information: `regcalc -e -5.0735 103.0826 50.5`\n - Getting information about more than one event, with input like below as Excel or CSV:\n\n<table>\n<tr> \n <th>Latitude</th>\n <th>Longitude</th>\n <th>Depth</th>\n</tr>\n<tr>\n <td>-5.074</td>\n <td>103.083</td>\n <td>50.5</td>\n</tr>\n<tr>\n <td>-1.008</td>\n <td>98.642</td>\n <td>17.6</td>\n</tr>\n</table>\n\n`regcalc -i input_file.xlsx`\n\nYou can add a ComCat ID column to this - the name which will be automatically detected is *EventID* (case does not matter). If the file has another name for the same column you can supply that with the --id-column command line option:\n\n`regcalc -i input_file.xlsx --id-column id`\n\nIf the file contains column names for latitude, longitude and depth that do not match the regular expression patterns \"^lat\", \"^lon\", \"^dep\" (ignoring case) then you can supply those column names as well using the --hypo-columns command line option:\n\n`regcalc -i input_file.xlsx --hypo-columns EventLatitude EventLongitude EventDepth`\n\nIf an input spreadsheet has moment tensor columns named Mrr, Mtt, Mpp, etc. (case does not matter) then those values will be used to calculate the Kagan angle and determine the focal mechanism.\n\nYou can also optionally specify moment tensor information for a single event in the form of strike/dip/rake angles and a magnitude, using the --moment-info command line option:\n\n`regcalc -e -0.950 -21.725 10.0 -m 260 84 169 6.9`\n\n*Note: Users may notice that distances to tectonic regions the earthquake is NOT in may be unreasonably large values. The reason \nfor returning the distances to other regions is to help inform the user when the earthquake is close to another region.\nWhen STREC outputs these large numbers it indicates that the distance to that other region is not close enough to affect\nthe properties of the earthquake.*\n\n# Probabilities\n\nSTREC now calculates the probabilities of an earthquake being in any of the tectonic regions, and also in\nany of the various defined depth categories. For subduction regions these are hardcoded as \ncrustal, interface, and intraslab. For other regions, the *default* configuration includes the following:\n\n - acr_shallow : active earthquakes occurring above 30 km\n - acr_deep - active earthquakes occurring below 30 km\n - scr_shallow - stable earthquakes at any depth\n - volcanic_shallow - volcanic earthquakes at any depth\n\n## Probability configuration\n\nUsers can configure the probability settings to include more finely grained depth zones for active, \nstable, and volcanic regions. The default config file is located in the [repository] \n(https://code.usgs.gov/ghsc/esi/strec/-/blob/main/src/strec/data/select.conf) and \ninstalled with the software. To customize the probability depth zones, download a copy of the file from \nthe repository and save it in the [DATA]->folder in the config.ini file described above.\n\n```\n[DATA]\nfolder = /data/strec\n```\n\nThe relevant section of the select.conf file to modify looks like the following:\n\n```\n[tectonic_regions]\n [[acr]]\n horizontal_buffer = 100\n vertical_buffer = 5\n depth_labels = shallow, deep\n min_depth = -Inf, 30\n max_depth = 30, Inf\n [[scr]]\n horizontal_buffer = 100\n vertical_buffer = 5\n depth_labels = shallow\n min_depth = -Inf\n max_depth = Inf\n [[subduction]]\n horizontal_buffer = 100\n vertical_buffer = 5\n depth_labels = crustal, interface, intraslab\n min_depth = -Inf, 15, 70\n max_depth = 15, 70, Inf\n use_slab = True\n [[volcanic]]\n horizontal_buffer = 10\n vertical_buffer = 5\n depth_labels = shallow\n min_depth = -Inf\n max_depth = Inf\n```\n\nTo add a \"deep\" (10 km or deeper) category to the scr section, you would modify that \nsection to look like the following:\n\n```\n [[scr]]\n horizontal_buffer = 100\n vertical_buffer = 5\n depth_labels = shallow, deep\n min_depth = -Inf, 10\n max_depth = 10, Inf\n```\n\n\n# Glossary\n\nSTREC defines a number of terms that may not be commonly\nunderstood, so they are explained here. These terms may be different\nfrom the Garcia paper upon which this software is originally based.\n\n - *Tectonic Region*: One of Subduction, Active, Volcanic, or Stable.\n We have split up the globe into these four regions, such that any\n point on the globe should fall into one and only one of these\n regions.\n \n * *Subduction*: A tectonic region defined by one plate descending below\n another (e.g., the western portion of the United States), more specifically\n by those locations above the Slab2.0 grids.\n\n * *Active*: A tectonic region which experiences crustal deformation due\n to plate tectonics.\n\n * *Volcanic*: A tectonic region which is sitting above mantle plumes, \n where magma pushes through cracks in the crust.\n\n * *Stable*: Tectonic regions which unlike Active regions, do not\n experience crustal deformation (e.g., the interior of the\n Australian continent.)\n\n![Map showing tectonic regions](select_regions.png \"Map Showing Tectonic Regions\")\n*Fig 1 - Map showing tectonic regions. ACR=Active Crustal Region, SUB=Subduction Zone, VOL=Volcanic Region, SCR=Stable Continental Region* \n\n - *Oceanic*: Another region, not exclusive with the four Tectonic\n Regions, that indicates whether the point supplied is in the ocean\n (i.e., not continental).\n\n - *Continental*: The opposite of Oceanic.\n\n - *Backarc*: The area of a subduction region that is behind the volcanic arc.\n\n - *Focal Mechanism*: A set of parameters that define the deformation in\n the source region that generates the seismic waves of an earthquake.\n\n - *Tensor Type*: The short name for the algorithm used to generate\n the moment tensor used to determine focal mechanism, Kagan angle,\n etc. This is usually a short code like *Mww* (W-phase), *Mwr*\n (regional), *Mwb* (body wave), or *composite*, which indicates that\n there is no computed moment tensor, so a composite of historical\n moment tensors around the input coordinates is used instead.\n\n - *Tensor Source*: When available, this is usually the network that\n contributed the moment tensor, followed by the ID used by that\n network (e.g., us_2000bmcg).\n\n - *Kagan Angle*: An single angle between any two moment tensors or in\n our case, between a moment tensor and a subducting slab.\n\n - *Composite Moment Tensor*: When moment tensors are not available \n for a given event, a composite moment tensor is calculated by \n essentially taking the mean of at least three moment tensors in a 0.1 \n degree box surrounding the earthquake hypocenter.\n\n - *Composite Variability*: When the moment tensor solution is of type\n *composite*, a scalar value describing the variability of the moment\n tensors used to determine the composite.\n\n - *Distance to [Region]*: The great circle distance from the input\n coordinates to the nearest vertex of [Region] polygon.\n\n - *Slab Model Region*: We currently use Slab 2.0 subduction models\n (Hayes 2012), which are currently provided for 27 regions around\n the globe. These regions are described in detail here:\n https://www.sciencebase.gov/catalog/item/5aa1b00ee4b0b1c392e86467/\n\n - *Slab Model Depth*: The best estimate of depth to subduction\n interface.\n\n - *Slab Model Depth Uncertainty*: The best estimate of the uncertainty\n of the depth to subduction interface.\n\n - *Slab Model Dip*: The best estimate of the dip angle of the\n subducting plate.\n\n - *Slab Model Strike*: The best estimate of the strike angle of the\n subducting plate.\n\n",
"bugtrack_url": null,
"license": "License ======= Unless otherwise noted, This project is in the public domain in the United States because it contains materials that originally came from the United States Geological Survey, an agency of the United States Department of Interior. For more information, see the official USGS copyright policy at https://www2.usgs.gov/visual-id/credit_usgs.html#copyright This information is preliminary or provisional and is subject to revision. It is being provided to meet the need for timely best science. The information has not received final approval by the USGS and is provided on the condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the information. ",
"summary": "USGS SeismoTectonic Regime Earthquake Calculator (STREC)",
"version": "2.3.3",
"project_urls": null,
"split_keywords": [
"comcat",
"earthquake"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e4fa98ee9cb9dbeafcc5c598185e8202e902f4eddd220b556b55df5c3deaada6",
"md5": "9daf02e3f5ffa4740319174bd6913f29",
"sha256": "603e364fe958c2fc8cc9abb53d18773b08cb90c13b9f243c72c9dba229cf8a34"
},
"downloads": -1,
"filename": "usgs_strec-2.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9daf02e3f5ffa4740319174bd6913f29",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 3381071,
"upload_time": "2024-02-05T17:52:03",
"upload_time_iso_8601": "2024-02-05T17:52:03.795484Z",
"url": "https://files.pythonhosted.org/packages/e4/fa/98ee9cb9dbeafcc5c598185e8202e902f4eddd220b556b55df5c3deaada6/usgs_strec-2.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "351061bc51d6d36958f59726750fed5eab646ad222823d51977a7599ae4cc937",
"md5": "e52f648af8f82c94bbd43ccef9c0aeb2",
"sha256": "358229773839fc04f3e6cb6b3895c8ef76d7dd4ab490cec5775d1db7ab4fea2a"
},
"downloads": -1,
"filename": "usgs-strec-2.3.3.tar.gz",
"has_sig": false,
"md5_digest": "e52f648af8f82c94bbd43ccef9c0aeb2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3353423,
"upload_time": "2024-02-05T17:52:05",
"upload_time_iso_8601": "2024-02-05T17:52:05.654782Z",
"url": "https://files.pythonhosted.org/packages/35/10/61bc51d6d36958f59726750fed5eab646ad222823d51977a7599ae4cc937/usgs-strec-2.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-05 17:52:05",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "usgs-strec"
}
