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

{anss_formats-0.1.0 → anss_formats-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anss-formats
-Version: 0.1.0
+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
@@ -13,17 +13,18 @@ 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 (>=44.0.1,<45.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
 
-# ANSS Data Formats
+# Python 3 ANSS Formats Library
 
 This is the Python implementation of the library used to generate and parse the 
 ANSS Formats.
@@ -35,6 +36,19 @@ Dependencies
 * 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:
@@ -49,19 +63,20 @@ seismic event detections.
 * [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.
-* [Associated](format-docs/Associated.md) Object - An object that contains associated information if a pick is included in a detection.
+* [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 MachineLearning info.
+* [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.
-* [MachineLearning](format-docs/MachineLearning.md) Object - An object that defines the machine learning information for a pick.
-* [Magnitude](format-docs/Magnitude.md) Object - An object that defines an earthquake magnitude estimation, as part of a Machine Learning classification or earthquake detection.
-* [Quality](format-docs/Quality.md) Object - An object that defines the data quality of a pick.
+* [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
@@ -96,12 +111,86 @@ 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 [Pick](Pick.md).  Association uses the [JSON standard](http://www.json.org).
+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
 
@@ -132,16 +221,16 @@ 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.
 
-# Site Object Specification
+# Channel Object Specification
 
 ## Description
 
-The Site object is an object designed to define the seismic station used to
-produce a [Pick](Pick.md) message.  Site uses the [JSON](https://www.json.org) and [GeoJSON](https://geojson.org/) standards.
+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
 
-Site is intended for use as part of the [Pick](Pick.md) Format in seismic data messaging between seismic applications and organizations.
+Channel is intended for use as part of the [Pick](Pick.md) Format in seismic data messaging between seismic applications and organizations.
 
 ## Output
 
@@ -236,7 +325,7 @@ applications.
       "detector"        : String,
       "pickData"  : [Pick Objects],
       "magnitudeData" :
-      [ 
+      [
         {
           "type" : String,
           "id" : String,
@@ -245,11 +334,27 @@ applications.
           {
             "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
+      }
     }
 ```
 
@@ -277,18 +382,18 @@ The following are supplementary values that **may or may not** be provided as pa
 * 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 originating seismic
-organization that produced a [MachineLearning](MachineLearning.md) object.
-Site uses the [JSON standard](http://www.json.org).
+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 [PicMachineLearningk](MachineLearning.md) Oject in seismic data
+EventType is intended for use as part of the [Detection](Detection.md) object in seismic data
 messaging between seismic applications and organizations.
 
 ## Output
@@ -406,96 +511,12 @@ various algorithms.
 * 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.
 
-# MachineLearning Object Specification
-
-## Description
-
-The MachineLearning object is an object designed to encode value added
-information available for a [Pick](Pick.md) from advanced algorithms such as
-machine learning. MachineLearning uses the [JSON standard](http://www.json.org).
-
-## Usage
-
-MachineLearning 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,
-        "phaseProbability"     : Number,
-        "distance"             : Number,
-        "distanceProbability"  : Number,
-        "distanceRangeHalfWidth"   : Number,
-        "distanceRangeSigma"       : Number,
-        "backAzimuth"              : Number,
-        "backAzimuthProbability"   : Number,
-        "magnitude" :
-        {
-            "type" : String,
-            "id" : String,
-            "value" : Number,
-            "source" :
-            {
-                "agencyID" : String,
-                "author"   : String
-            },  
-            "error" : Number,
-            "probability" : Number
-        }, 
-        "depth"                : Number,
-        "depthProbability"     : Number,
-        "eventType" :
-        {
-            "type"      : String,
-            "certainty" : String
-        },
-        "eventTypeProbability" : Number,
-        "repickShift" : Number,
-        "repickSTD" : Number,
-        "repickCredibleIntervalLower" : Number,
-        "repickCredibleIntervalUpper" : Number,
-        "source" :
-        {
-            "agencyID" : String,
-            "author"   : String
-        }
-    }
-```
-
-## Glossary
-
-**Optional Values:**
-
-The following are values that **may or may not** be provided as part of MachineLearning.
-
-* phase - A string that identifies the seismic phase for this data
-* phaseProbability - A decimal number containing the probability of the phase identification
-* distance - A decimal number containing a distance estimation in degrees
-* distanceProbability - A decimal number containing the probability of the distance estimation
-* distanceRangeHalfWidth - A decimal number containing the half-width of a distance range centered at Distance  (e.g. Distance is 15 deg +/- 10 deg)
-* distanceRangeSigma - A decimal number containing the standard deviation for a probability PDF curve for Distance (e.g. Distance is 15 deg +/- 3 * DistanceRangeSigma where DistanceProbability is modified by the PDF probability, lowering as it gets further from Distance ).  DistanceRangeSigma is mutually exclusive of DistanceRangeHalfWidth, and if both are provided DistanceRangeSigma should be used. 
-* backAzimuth - A decimal number containing a backazimuth estimation in degrees
-* backAzimuthProbability - A decimal number containing the probability of the backazimuth estimation
-* magnitude - A [Magnitude](Magnitude.md) object containing the machine learning magnitude estimation
-* depth - A decimal number containing a depth estimation in kilometers
-* depthProbability - A decimal number containing the probability of the depth estimation
-* eventType - An object containing the event type, see [EventType](EventType.md).
-* eventTypeProbability - A decimal number containing the probability of the event type estimation
-* repickShift - A decimal number containing the repick shift in seconds (to regenerate the initial Pick.Time, subtract this value from the current Pick.Time)
-* repickSTD - A decimal number containing the repick shift standard deviation
-* repickCredibleIntervalLower - A decimal number containing the repick shift credible interval lower
-* repickCredibleIntervalUpper - A decimal number containing the repick shift credible interval upper
-* source - An object containing the source of the MachineLearning, see [Source](Source.md).
-
 # Magnitude Object Specification
 
 ## Description
 
-The Magnitude object is an object designed to hold data quality for a [Detection](Detection.md) message.
-Site uses the [JSON standard](http://www.json.org).
+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
 
@@ -599,48 +620,21 @@ applications and organizations.
          "residual" : Number,
          "sigma"    : Number
       },
-      "qualityInfo" : [ {
-        "standard": String,
-        "value": Number
-        }, ...],
-      "machineLearningInfo" :
+      "analyticsInfo" :
       {
-        "phase"                : String,
-        "phaseProbability"     : Number,
-        "distance"             : Number,
-        "distanceProbability"  : Number,
-        "distanceRangeHalfWidth"   : Number,
-        "distanceRangeSigma"       : Number,
-        "backAzimuth"              : Number,
-        "backAzimuthProbability"   : Number,
-        "magnitude" :
-        {
-          "type" : String,
-          "id" : String,
-          "value" : Number,
-          "source" :
-          {
-            "agencyID" : String,
-            "author"   : String
-          },  
-          "error" : Number,
-          "probability" : Number
-        },
-        "depth"                : Number,
-        "depthProbability"     : Number,
-        "eventType" : {
-          "type"      : String,
-          "certainty" : String
-        },
-        "eventTypeProbability" : Number,
-        "repickShift" : Number,
-        "repickSTD" : Number,
-        "repickCredibleIntervalLower" : Number,
-        "repickCredibleIntervalUpper" : Number,
-        "source" : {
+        "predictions" : [ {
+          "label" : String,
+          "value" : String | Number | Object | Array,
+          "probability" : Number,
+          "metrics" : Object,
+          "modelID" : String,
+          "modelVersion" : String,
+          "source" : {
             "agencyID" : String,
             "author"   : String
-        }
+          }
+        }, ...],
+        "extensions" : Object,
       }
     }
 ```
@@ -668,39 +662,8 @@ various picking algorithms.
 * 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 [Associated](Associated.md).
-* machineLearningInfo - An object containing the machine learning  information of this pick, see [MachineLearning](MachineLearning.md).
-* qualityInfo - An array of objects containing the containing the quality metric information for this pick, see [Quality](Quality.md).
-
-# Quality Object Specification
-
-## Description
-
-The Quality object is an object designed to hold data quality for a [Pick](Pick.md) message.
-Site uses the [JSON standard](http://www.json.org).
-
-## Usage
-
-Quality is intended for use as part of the [Pick](Pick.md) Format in seismic data
-messaging between seismic applications and organizations.
-
-## Output
-
-```json
-    {
-        "standard": String,
-        "value": Number
-    }
-```
-
-## Glossary
-
-**Required Values:**
-
-These are the values **required** to define a Quality
-
-* standard - A string containing the name of the quality standard.
-* value - A string containing numarical value of the quality standard.
+* 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
 
@@ -708,7 +671,7 @@ These are the values **required** to define a Quality
 
 The Source object is an object designed to define the originating seismic
 organization that produced a [Pick](Pick.md) message.
-Site uses the [JSON standard](http://www.json.org).
+Source uses the [JSON standard](http://www.json.org).
 
 ## Usage