anss-formats 0.1.1__tar.gz → 0.1.2__tar.gz

anss_formats-0.1.2/PKG-INFO

@@ -0,0 +1,698 @@
+Metadata-Version: 2.4
+Name: anss-formats
+Version: 0.1.2
+Summary: Python implementation of the library used to communicate seismic event detection information between systems
+License: CC0-1.0
+Keywords: anss,earthquakes,formats,detection
+Author: John Patton
+Author-email: jpatton@usgs.gov
+Requires-Python: >3.9.1,<3.12
+Classifier: License :: CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Provides-Extra: pycurl
+Requires-Dist: certifi (>=2024.07.04,<2025.0.0)
+Requires-Dist: cryptography (>=42.0.5)
+Requires-Dist: docutils (!=0.21.post1)
+Requires-Dist: dparse (>=0.6.2,<0.7.0)
+Requires-Dist: pydantic (>=2.6.0,<3.0.0)
+Requires-Dist: requests (>=2.32.2,<3.0.0)
+Requires-Dist: twine (>=5.1.1,<6.0.0)
+Requires-Dist: urllib3 (>=2.6.0,<3.0.0)
+Project-URL: Homepage, https://gitlab.com/anss-netops/anss-data-formats
+Project-URL: Repository, https://gitlab.com/anss-netops/anss-data-formats
+Description-Content-Type: text/markdown
+
+# Python 3 ANSS Formats Library
+
+This is the Python implementation of the library used to generate and parse the 
+ANSS Formats.
+
+Dependencies
+------
+* ANSS Formats utilizes [JSON](www.json.org) for formatting.
+* ANSS Formats was written in Python 3.6
+* ANSS Formats uses [poetry](https://python-poetry.org/) for
+Package, dependency and environment management.
+
+Building
+------
+The steps to get and use the python ANSS-formats are as follows:
+
+1. Clone ANSS-formats.
+2. Open a command window and change directories to /python/
+3. To run unit tests, run the command `poetry run pytest --cov=anssformats --junitxml junit.xml`
+
+Using
+-----S
+Once you have the python distribution, simply import anssformats
+
+# ANSS Data Formats
+The US Geological Survey (USGS) Advanced National Seismic System (ANSS) defines a number of data exchange formats to communicate seismic event detection information between processing systems. These formats are defined using objects as defined in the [JSON standard](http://www.json.org).
+
+The purpose of this project is to:
+
+1. Define formats to hold data representing the estimates of various types of
+seismic event detections.
+2. Store the format definitions in a source controlled manner.
+3. Host libraries used to generate, parse, and validate the formats
+
+## Defined formats:
+
+* [Pick](format-docs/Pick.md) Format - A format for unassociated picks from a waveform arrival time picking algorithm.
+* [Detection](format-docs/Detection.md) Format - A format for an earthquake detection picks from a seismic detection algorithm.
+
+
+## Supporting format objects:
+
+* [Amplitude](format-docs/Amplitude.md) Object - An object that contains information about an amplitude as part of a pick.
+* [Analytics](format-docs/Analytics.md) Object - An object that holds extensible information from model outputs or other processing tags. 
+* [Association](format-docs/Association.md) Object - An object that contains associated information if a pick is included in a detection.
+* [Channel](format-docs/Channel.md) Object - A geoJSON object that contains channel/location information as part of a pick.
+* [EventType](format-docs/EventType.md) Object - An object that defines the event type for a detection.
+* [Filter](format-docs/Filter.md) Object - An object that contains filter information as part of a pick.
+* [Hypocenter](format-docs/Hypocenter.md) Object - A geoJSON object that contains the hypocentral location, arrival time, and error information as part of a detection.
+* [Magnitude](format-docs/Magnitude.md) Object - An object that defines an earthquake magnitude estimation for a detection.
+* [Source](format-docs/Source.md) Object - An object that defines the creator/source of a pick.
+
+
+# Amplitude Object Specification
+
+## Description
+
+The Amplitude object is an object designed to encode the amplitude information
+that may or may not be part of the [Pick](Pick.md) Format.  Amplitude uses the
+[JSON standard](http://www.json.org).
+
+## Usage
+
+The Amplitude object is intended for use as part of the [Pick](Pick.md) Format
+in seismic data messaging between seismic applications and organizations.
+
+## Output
+
+```json
+    {
+       "amplitude" : Number,
+       "period"    : Number,
+       "snr"       : Number
+    }
+```
+
+## Glossary
+
+**Optional Values:**
+
+The following are values that **may or may not** be provided as part of an
+amplitude.
+
+* amplitude - A decimal number containing the amplitude.
+* period - A decimal number containing the amplitude period.
+* snr - A decimal number containing the signal to noise ratio, capped at 1E9.
+
+
+# Analytics Object Specification
+
+## Description
+
+The Analytics object is an extensible format to encode model outputs for a [Pick](Pick.md).
+Model outputs are stored as a list of [Predictions](#Prediction-Object).
+Suitable for retaining output of pickers, analytical models, AI/ML predictors, etc.
+Analytics uses the [JSON standard](http://www.json.org).
+
+## Usage
+
+Analytics is intended for use as part of the [Pick](Pick.md) format in
+seismic data messaging between seismic applications and organizations.
+
+## Output
+
+```json
+{
+    "predictions": [
+        {
+            "label": String,
+            "value": String | Number | Array | Object,
+            "probability": Number,
+            "metrics": {
+                // Flexible structure for uncertainty quantification
+            },
+            "modelID": String,
+            "modelVersion": String,
+            "source": {
+                "agencyID": String,
+                "author": String
+            }
+        }
+    ],
+    "extensions": {
+        // Custom key-value pairs for experimental data
+    }
+}
+```
+
+## Glossary
+
+**Optional Values:**
+
+* `predictions` - An optional array of Prediction objects. Each prediction represents output from an analytical model.
+* `extensions` - An optional object containing custom key-value pairs for experimental or debug data.
+
+## Prediction Object
+
+* `label` (required) - A string identifying what is being predicted.
+  * Standard seismological labels: "phase", "magnitude", "eventType", "distance", "depth", "backAzimuth"
+  * Custom labels: any string (e.g., "pick_quality", "noise_level", "voorwerp_level")
+
+* `value` (required) - The predicted value. Can be:
+  * String (e.g., "P", "Earthquake")
+  * Number (e.g., 2.5, 0.94)
+  * Array (e.g., `[0.1, 0.3, 0.8]`)
+  * Object (e.g., `{"type": "Mb", "value": 2.5}`)
+
+* `probability` - A decimal number [0.0-1.0] containing the probability of this prediction
+
+* `metrics` - An object containing other model/pick information. Structure is flexible and can include things like:
+  * `std` - Standard deviation
+  * `range` - Array of [min, max] values
+  * `halfWidth` - Half-width of uncertainty range
+  * `sigma` - Sigma value for probability distribution
+  * Any other model-specific quantification metrics
+
+* `modelID` - A string identifying which model made this prediction
+* `modelVersion` - A string containing the version of the model
+* `source` - An object containing the source/author of the model, see [Source](Source.md)
+
+
+# Association Object Specification
+
+## Description
+
+The Association object is an object designed to encode information provided when a group of [Pick](Pick.md) are associated for an event.
+Association uses the [JSON standard](http://www.json.org).
+
+## Usage
+
+Association is intended for use as part of the [Pick](Pick.md) Format in seismic data messaging between seismic applications and organizations.
+
+## Output
+
+```json
+    {
+       "phase"    : String,
+       "distance" : Number,
+       "azimuth"  : Number,
+       "residual" : Number,
+       "sigma"    : Number
+    }
+```
+
+## Glossary
+
+**Optional Values:**
+
+The following are values that **may or may not** be provided as part of
+association.
+
+* phase - A string that identifies the seismic phase for this data if Association.
+* distance - A decimal number containing the distance in degrees between the detection's and data's locations if Association.
+* azimuth - A decimal number containing the azimuth in degrees between the detection's and data's locations if Association.
+* residual - A decimal number containing residual in seconds of the data if Association.
+* sigma - A decimal number reflecting the number of standard deviations of the data from the calculated value if Association.
+
+# Channel Object Specification
+
+## Description
+
+The Channel object is an object designed to define the seismic station used to produce a [Pick](Pick.md) message.
+Channel uses the [JSON](https://www.json.org) and [GeoJSON](https://geojson.org/) standards.
+
+## Usage
+
+Channel is intended for use as part of the [Pick](Pick.md) Format in seismic data messaging between seismic applications and organizations.
+
+## Output
+
+```json
+{
+  "type": "Feature",
+  "geometry": {
+    "type": "Point",
+    "coordinates": [125.6, 10.1]
+  },
+  "properties": {
+    "station"   : String,
+    "channel"   : String,
+    "network"   : String,
+    "location"  : String
+  }
+}
+```
+
+## Glossary
+
+**Required Values:**
+
+These are the properties **required** to define a Site.
+
+* type - A string indicating the geojson feature type
+* geometry - A geojson point containing the station coordinates in the form [Latitude, Longitude, Elevation (in meters)]
+* properties - The associated properties for this geojson feature
+
+**Required Properties:**
+
+These geojson feature properties are **required** to define a Site.
+* station - A string the station code.
+* network - A string containing network code.
+
+**Optional Properties:**
+
+The following are supplementary geojson feature properties that **may or may not** be provided by
+various algorithms.
+
+* channel - A string containing the channel code.
+* location - A string containing the location code.
+
+# Detection Format Specification
+
+## Description
+
+Detection is a format designed to encode the basic information of an earthquake
+event Detection.  Detection uses the [JSON standard](http://www.json.org).
+
+## Usage
+
+Detection is intended for use in seismic data messaging between seismic
+applications.
+
+## Output
+
+```json
+    {
+      "type"        : "Detection",
+      "id"          : String,
+      "source"      :
+      {
+         "agencyID" : String,
+         "author"   : String
+      },
+      "hypocenter"  :
+        {
+          "type": "Feature",
+          "geometry": {
+            "type": "Point",
+            "coordinates": [125.6, 10.1, 1589.0]
+        },
+          "properties": {
+            "originTime"      : ISO8601,
+            "latitudeError"   : Number,
+            "longitudeError"  : Number,
+            "depthError"      : Number,
+            "originTimeError" : Number
+        }      
+      },
+      "detectionType"   : String,
+      "detectionTime"   : ISO8601,
+      "eventType" :
+      {
+          "type"      : String,
+          "certainty" : String
+      },
+      "minimumDistance" : Number,
+      "rms"             : Number,
+      "maximumGap"      : Number,
+      "detector"        : String,
+      "pickData"  : [Pick Objects],
+      "magnitudeData" :
+      [
+        {
+          "type" : String,
+          "id" : String,
+          "value" : Number,
+          "source" :
+          {
+            "agencyID" : String,
+            "author"   : String
+          },
+          "error" : Number,
+          "probability" : Number
+        }, ...
+      ],
+      "analyticsInfo" :
+      {
+        "predictions" : [ {
+          "label" : String,
+          "value" : String | Number | Object | Array,
+          "probability" : Number,
+          "metrics" : Object,
+          "modelID" : String,
+          "modelVersion" : String,
+          "source" : {
+            "agencyID" : String,
+            "author"   : String
+          }
+        }, ...],
+        "extensions" : Object
+      }
+    }
+```
+
+## Glossary
+
+**Required Values:**
+
+These are the values **required** to define a detection.
+
+* type - A string that identifies this message as a detection.
+* id - A string containing an unique identifier for this Detection.
+* source - An object containing the source of the Detection, see [Source](Source.md).
+* hypocenter - An object containing the hypocenter of the Detection, see [Hypocenter](Hypocenter.md).
+
+**Optional Values:**
+
+The following are supplementary values that **may or may not** be provided as part of a detection.
+
+* detectionType - A string that identifies whether the Detection is `New`, `Update`, or `Final`.
+* detectionTime - A string containing the UTC time this detection was made, i.e. how quickly after origin time was this detection created, in the ISO8601 format `YYYY-MM-DDTHH:MM:SS.SSSZ`.
+* eventType - An object containing the event type of the correlation, see [EventType](EventType.md).
+* rms - A decimal number containing the rms estimate for the detction
+* minimumDistance - A decimal number representing the minimum distance to the closest supporting station.
+* maximumGap - A decimal number representing the maximum gap in degrees between supporting stations.
+* detector - A string identifying the detection grid, algorithm, or other information.
+* pickData - An array of [Pick](Pick.md) objects used to generate this Detection.
+* magnitudeData - An array of [Magnitude](Magnitude.md) objects for this Detection.
+* analyticsInfo - An object containing analytical information from one or more models/algorithms, see [Analytics](Analytics.md).
+
+# EventType Object Specification
+
+## Description
+
+The EventType object is an object designed to define the phenomena causing a seismic detection.
+EventType uses the [JSON standard](http://www.json.org).
+
+## Usage
+
+EventType is intended for use as part of the [Detection](Detection.md) object in seismic data
+messaging between seismic applications and organizations.
+
+## Output
+
+```json
+    {
+      "type"  : String,
+      "certainty"    : String
+    }
+```
+
+## Glossary
+
+**Required Values:**
+
+These are the values **required** to define a EventType
+
+* type - A string containing the event type, allowed type strings are: "Earthquake", "MineCollapse", "NuclearExplosion", "QuarryBlast", "InducedOrTriggered", "RockBurst", "FluidInjection", "IceQuake", and "VolcanicEruption"
+
+**Optional Values:**
+
+The following are values that **may or may not** be provided as part of EventType.
+
+* certainty - A string containing the certainty of the event type; allowed strings are "Suspected" and "Confirmed"
+
+# Filter Object Specification
+
+## Description
+
+The Filter object is an object designed to encode a single set of filter
+frequencies that may or may not be part of the filter list in the [Pick](Pick.md)
+Format. Filter uses the [JSON standard](http://www.json.org) .
+
+## Usage
+
+The Filter object is intended for use as part of the [Pick](Pick.md) Format
+in seismic data messaging between seismic applications and organizations.
+
+## Output
+
+```json
+   {
+      "type"     : String,
+      "highPass" : Number,
+      "lowPass"  : Number,
+      "units"    : String
+   }
+```
+
+## Glossary
+
+**Optional Values:**
+
+The following are values that **may or may not** be provided as part of a filter.
+
+* type - A string containing the type of filter
+* highPass - A decimal number containing the high pass frequency in Hz.
+* lowPass - A decimal number containing the low pass frequency in Hz.
+* units - A string containing the filter frequency units.
+
+Note: The Type of filter is assumed to be "BandPass", and the Units are assumed
+to be "Hertz"
+
+# Hypocenter Object Specification
+
+## Description
+
+The Hypocenter object is an object designed to define a Hypocenter as part of a [Detection](Detection.md) message.  Hypocenter uses the [JSON standard](http://www.json.org) and [GeoJSON](https://geojson.org/) standards.
+
+
+## Usage
+
+Hypocenter is intended for use as part of the [Detection](Detection.md) Format in seismic data messaging between seismic applications and organizations.
+
+## Output
+
+```json
+    {
+      "type": "Feature",
+      "geometry": {
+        "type": "Point",
+        "coordinates": [125.6, 10.1, 1589.0]
+      },
+      "properties": {
+        "originTime"      : ISO8601,
+        "latitudeError"   : Number,
+        "longitudeError"  : Number,
+        "depthError"      : Number,
+        "originTimeError" : Number
+      }      
+    }
+```
+
+## Glossary
+
+**Required Values:**
+
+These are the values **required** to define a hypocenter.
+* type - A string indicating the geojson feature type, always a point
+* geometry - A geojson point containing the station coordinates in the form [Latitude, Longitude, Depth (in meters)]
+* properties - The associated properties for this geojson feature
+
+**Required Properties:**
+
+These geojson feature properties are **required** to define a hypocenter.
+* originTime - A string containing the UTC origin time of this hypocenter, in the ISO8601 format `YYYY-MM-DDTHH:MM:SS.SSSZ`.
+
+**Optional Properties:**
+
+The following are supplementary geojson feature properties that **may or may not** be provided by
+various algorithms.
+
+* latitudeError - A decimal number that identifies the error of the latitude of this hypocenter in kilometers.
+* longitudeError - A decimal number that identifies the error of the longitude of this hypocenter in kilometers.
+* depthError - A decimal number that identifies the depth error of this hypocenter in kilometers.
+* originTimeError - A decimal number that identifies the error of the origin time in seconds.
+
+# Magnitude Object Specification
+
+## Description
+
+The Magnitude object is an object designed to hold information about a magnitude assigned to a [Detection](Detection.md).
+Magnitude uses the [JSON standard](http://www.json.org).
+
+## Usage
+
+Magnitude is intended for use as part of the [Detection](Detection.md) Format in seismic data
+messaging between seismic applications and organizations.
+
+## Output
+
+```json
+    {
+      "type" : String,
+      "id" : String,
+      "value" : Number,
+      "source" :
+      {
+         "agencyID" : String,
+         "author"   : String
+      },  
+      "error" : Number,
+      "probability" : Number
+    }
+```
+
+## Glossary
+
+**Required Values:**
+
+These are the values **required** to define a Magnitude
+
+* type - A string containing the name of the magnitude type.
+* value - A decimal number containing numarical value of the magnitude.
+
+**Optional Values:**
+
+The following are supplementary values that **may or may not** be provided as part of a Magnitude.
+
+* id - A string containing an unique identifier for this Magnitude.
+* source - An object containing the source of the Magnitude, see [Source](Source.md).
+* error - A decimal number containing numarical error estimate of the magnitude.
+* probability - A decimal number containing the probability of the magnitude
+
+# Pick Format Specification
+
+## Description
+
+Pick is a format designed to encode the basic information of an unassociated
+waveform arrival time pick.  Pick uses the
+[JSON standard](http://www.json.org).
+
+## Usage
+Pick is intended for use in seismic data messaging between seismic
+applications and organizations.
+
+## Output
+
+```json
+    {
+      "type"      : "Pick",
+      "id"        : String,
+      "channel"      :
+      {
+        "type": "Feature",
+        "geometry": {
+          "type": "Point",
+          "coordinates": [125.6, 10.1, 1589.0]
+        },
+        "properties": {
+          "station"   : String,
+          "channel"   : String,
+          "network"   : String,
+          "location"  : String
+        }
+      },
+      "time"      : ISO8601,
+      "source"    :
+      {
+         "agencyID"  : String,
+         "author"    : String
+      },
+      "phase"     : String,
+      "polarity"  : ("up" | "down"),
+      "onset"     : ("impulsive" | "emergent" | "questionable"),
+      "pickerType"    : ("manual" | "raypicker" | "filterpicker" | "earthworm" | "other"),
+      "filterInfo"    : [ {
+        "type"     : String,
+        "highPass" : Number,
+        "lowPass"  : Number,
+        "units"    : String
+        }, ...],
+      "amplitudeInfo" :
+      {
+         "value" : Number,
+         "period"    : Number,
+         "snr"       : Number
+      },
+      "associationInfo" :
+      {
+         "phase"    : String,
+         "distance" : Number,
+         "azimuth"  : Number,
+         "residual" : Number,
+         "sigma"    : Number
+      },
+      "analyticsInfo" :
+      {
+        "predictions" : [ {
+          "label" : String,
+          "value" : String | Number | Object | Array,
+          "probability" : Number,
+          "metrics" : Object,
+          "modelID" : String,
+          "modelVersion" : String,
+          "source" : {
+            "agencyID" : String,
+            "author"   : String
+          }
+        }, ...],
+        "extensions" : Object,
+      }
+    }
+```
+
+## Glossary
+
+**Required Values:**
+
+These are the values **required** to define a pick.
+
+* type - A string that identifies this message as a pick.
+* id - A string containing an unique identifier for this pick.
+* channel - A GeoJSON object containing the channel the pick was made at, see [Channel](Channel.md).
+* source - An object containing the source of the pick, see [Source](Source.md).
+* time - A string containing the UTC arrival time of the phase that was picked, in the ISO8601 format `YYYY-MM-DDTHH:MM:SS.SSSZ`.
+
+**Optional Values:**
+
+The following are supplementary values that **may or may not** be provided by
+various picking algorithms.
+
+* phase - A string that identifies the seismic phase that was picked.
+* polarity - A string containing the phase polarity; "up" or "down".
+* onset - A string containing the phase onset; "impulsive", "emergent", or "questionable" .
+* pickerType - A string describing the type of picker; "manual", "raypicker", "filterpicker", "earthworm", or "other".
+* filter - An array of objects containing the filter frequencies when the pick was made, see [Filter](Filter.md).
+* amplitude - An object containing the amplitude associated with the pick, see [Amplitude](Amplitude.md).
+* associationInfo - An object containing the association information if this pick is used as data in a Detection, see [Association](Association.md).
+* analyticsInfo - An object containing analytical information from one or more models/algorithms, see [Analytics](Analytics.md).
+
+# Source Object Specification
+
+## Description
+
+The Source object is an object designed to define the originating seismic
+organization that produced a [Pick](Pick.md) message.
+Source uses the [JSON standard](http://www.json.org).
+
+## Usage
+
+Source is intended for use as part of the [Pick](Pick.md) Format in seismic data
+messaging between seismic applications and organizations.
+
+## Output
+
+```json
+    {
+      "agencyID"  : String,
+      "author"    : String
+    }
+```
+
+## Glossary
+
+**Required Values:**
+
+These are the values **required** to define a Source
+
+* agencyID - A string containing the originating agency FDSN ID.
+* author - A string containing the source author.
+