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

anss_formats-0.1.1/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: anss-formats
+Version: 0.1.1
+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

anss_formats-0.1.1/anssformats/__init__.py

@@ -0,0 +1,26 @@
+from anssformats.pick import Pick
+from anssformats.source import Source
+from anssformats.amplitude import Amplitude
+from anssformats.analytics import Analytics, Prediction
+from anssformats.association import Association
+from anssformats.detection import Detection
+from anssformats.hypocenter import Hypocenter
+from anssformats.magnitude import Magnitude
+from anssformats.channel import Channel
+from anssformats.filter import Filter
+from anssformats.eventType import EventType
+
+__all__ = [
+    "Pick",
+    "Source",
+    "Amplitude",
+    "Analytics",
+    "Prediction",
+    "Association",
+    "Detection",
+    "Hypocenter",
+    "Magnitude",
+    "Channel",
+    "Filter",
+    "EventType",
+]

anss_formats-0.1.1/anssformats/analytics.py

@@ -0,0 +1,82 @@
+from typing import Optional, Union, List
+
+from pydantic import Field
+
+from anssformats.formatbasemodel import FormatBaseModel
+from anssformats.source import Source as SourceFormat
+
+
+class Prediction(FormatBaseModel):
+    """A generic prediction from an analytical model (AI/ML, statistical, rule-based, etc.)
+
+    This class provides a flexible structure for representing any type of prediction
+    with associated metrics and model provenance.
+
+    Attributes
+    ----------
+    label: string identifying what is being predicted (e.g., "phase", "magnitude",
+        "eventType", "custom_attribute")
+
+    value: the predicted value - can be string, number, or structured object
+
+    probability: optional float [0.0-1.0] containing the probability of this prediction
+
+    metrics: optional dict containing additional prediction metrics such as confidence,
+        uncertainty quantification (std, ranges, credible intervals), entropy, etc.
+        Structure is flexible to support any model-specific metrics.
+
+    modelID: optional string identifying which model made this prediction
+
+    modelVersion: optional string containing the version of the model
+
+    source: optional Source object containing the source/author of the
+    """
+
+    label: str = Field(
+        ...,
+        description="What is being predicted (e.g., phase, magnitude, eventType, distance)",
+    )
+    value: Union[str, float, int, list, dict] = Field(
+        ..., description="The predicted value"
+    )
+    probability: Optional[float] = Field(
+        None, ge=0.0, le=1.0, description="Probability of this prediction [0.0-1.0]"
+    )
+    metrics: Optional[dict] = Field(
+        None,
+        description="Additional prediction metrics (confidence, uncertainty, entropy, etc.)",
+    )
+    modelID: Optional[str] = Field(
+        None, description="Identifier for the model that made this prediction"
+    )
+    modelVersion: Optional[str] = Field(None, description="Version of the model")
+    source: Optional[SourceFormat] = Field(
+        None, description="Source/author of the model"
+    )
+
+
+class Analytics(FormatBaseModel):
+    """A conversion class used to create, parse, and validate analytical information
+    from models such as pickers, analytical models, AI/ML, etc.
+
+    This class provides an extensible structure supporting multiple models, arbitrary
+    prediction labels, and custom extensions.
+
+    Attributes
+    ----------
+
+    predictions: optional list of Prediction objects containing predictions from one
+        or more models. Each prediction can represent any type of analytical output
+        with associated confidence metrics and model provenance.
+
+    extensions: optional dict containing custom key-value pairs for experimental code and debugging.
+
+    """
+
+    predictions: Optional[List[Prediction]] = Field(
+        None, description="Array of predictions from one or more analytical models"
+    )
+
+    extensions: Optional[dict] = Field(
+        None, description="Custom key-value pairs for experimental or debuging data"
+    )

anss_formats-0.1.1/anssformats/channel.py

@@ -0,0 +1,40 @@
+from typing import Optional, List, Literal
+
+from pydantic import Field, field_validator, ValidationInfo
+from anssformats.formatbasemodel import FormatBaseModel
+from anssformats.geojson import PointGeometry
+
+
+class ChannelProperties(FormatBaseModel):
+    """A class holding the channel specific custom properties for a geojson point feature
+
+    Station: string containing the station code
+
+    Channel: optional string containing the channel code
+
+    Network: string containing the network code
+
+    Location: optional string containing the location code
+    """
+
+    station: str
+    channel: Optional[str] = None
+    network: str
+    location: Optional[str] = None
+
+
+class Channel(FormatBaseModel):
+    """A conversion class used to create, parse, and validate geojson Channel data as part of
+    detection data.
+
+    type: string containing the type of this geojson
+
+    geometry: PointGeometry object containing the geojson geometry for this feature
+
+    properties: ChannelProperties object containing the channel properties
+    """
+
+    type: str = "Feature"
+
+    geometry: PointGeometry
+    properties: ChannelProperties

anss_formats-0.1.1/anssformats/detection.py

@@ -0,0 +1,69 @@
+from typing import List, Literal, Optional
+
+from pydantic import Field
+
+
+from anssformats.formatbasemodel import CustomDT, FormatBaseModel
+from anssformats.eventType import EventType
+from anssformats.hypocenter import Hypocenter, HypocenterProperties
+from anssformats.source import Source
+from anssformats.pick import Pick
+from anssformats.magnitude import Magnitude
+from anssformats.analytics import Analytics
+
+
+class Detection(FormatBaseModel):
+    """A conversion class used to create, parse, and validate detection data.
+
+    type: string identifying this message as a detection
+
+    id: string containing a unique identifier for this detection
+
+    source: Source object containing the source of the detection
+
+    hypocenter: Hypocenter object containing the hypocenter of the detection
+
+    detectionType: optional string containing the origin type of this detection; valid
+        values are "New", "Update", "Final", and "Retract"
+
+    detectionTime: optional datetime containing the time this detection was made
+
+    eventType: optional EventType object containing the event type of the detection
+
+    minimumDistance: optional float containing the distance to the closest station
+
+    rms: optional float containing the detection RMS
+
+    maximumGap: optional float containing the detection gap
+
+    detector: optional string containing the detection grid, algorithm, or other
+        information
+
+    pickData: optional list of either Pick objects used to generate
+        this detection
+
+    analyticsInfo: optional analytics object containing model output attached to this detection
+    """
+
+    type: Literal["Detection"]
+    id: str
+    source: Source
+
+    hypocenter: Hypocenter
+
+    detectionType: Optional[Literal["New", "Update", "Final", "Retract"]] = None
+    detectionTime: Optional[CustomDT] = None
+
+    eventType: Optional[EventType] = None
+
+    minimumDistance: Optional[float] = Field(None, ge=0.0)
+    rms: Optional[float] = None
+    maximumGap: Optional[float] = Field(None, ge=0.0, le=360.0)
+
+    detector: Optional[str] = None
+
+    pickData: Optional[List[Pick]] = None
+
+    magnitudeData: Optional[List[Magnitude]] = None
+
+    analyticsInfo: Optional[Analytics] = None

{anss_formats-0.0.4 → anss_formats-0.1.1}/anssformats/formatbasemodel.py

@@ -1,7 +1,7 @@
 from datetime import datetime
 from typing import Any
 
-from pydantic import BaseModel, GetCoreSchemaHandler
+from pydantic import BaseModel, GetCoreSchemaHandler, field_validator
 from pydantic_core import CoreSchema, core_schema
 
 
@@ -22,10 +22,6 @@ def convert_datetime_to_iso8601_with_z_suffix(dt: datetime) -> str:
 class FormatBaseModel(BaseModel):
     """A Pydantic BaseModel used for any required formatting of keys and values"""
 
-    class Config:
-        # conversion for datetime to datetime string
-        json_encoders = {datetime: convert_datetime_to_iso8601_with_z_suffix}
-
     def model_dump(self):
         """Override the default model_dump method to always exclude None values"""
         return super().model_dump(exclude_none=True)
@@ -41,17 +37,22 @@ class CustomDT(datetime):
     strings.
     """
 
+    @field_validator("*", mode="before")
     @classmethod
     def validate_no_tz(cls, v: Any, info: core_schema.ValidationInfo) -> Any:
         if isinstance(v, str):
             return datetime.strptime(v, "%Y-%m-%dT%H:%M:%S.%fZ").replace(tzinfo=None)
-        else:
-            return v.replace(tzinfo=None)
+        return v.replace(tzinfo=None)
 
     @classmethod
     def __get_pydantic_core_schema__(
         cls, source_type: Any, handler: GetCoreSchemaHandler
     ) -> CoreSchema:
-        return core_schema.with_info_plain_validator_function(
-            function=cls.validate_no_tz
+        return core_schema.with_info_before_validator_function(
+            cls.validate_no_tz,
+            handler(datetime),
+            serialization=core_schema.plain_serializer_function_ser_schema(
+                convert_datetime_to_iso8601_with_z_suffix,
+                when_used="json-unless-none",
+            ),
         )

anss_formats-0.1.1/anssformats/geojson.py

@@ -0,0 +1,41 @@
+from typing import Optional, List, Literal
+
+from pydantic import Field, field_validator, ValidationInfo
+from anssformats.formatbasemodel import FormatBaseModel
+
+
+class PointGeometry(FormatBaseModel):
+    """A class holding a geojson point geometry
+
+    type: string containing the type of this geometry
+
+    coordinates: List of floats containing the longitude in degrees, latitude in degrees, and elevation in meters or depth in kilometers, in that order
+    """
+
+    type: str = "Point"
+    coordinates: List[float]
+
+    # check that coordinates are valid
+    @field_validator("coordinates")
+    @classmethod
+    def validate_coordinates(
+        cls, value: List[float], info: ValidationInfo
+    ) -> List[float]:
+        if value is None:
+            raise ValueError("Missing coordinates")
+
+        if len(value) != 3:
+            raise ValueError("Incomplete coordinates")
+
+        # longitude
+        if value[0] < -180.0 or value[0] > 180.0:
+            raise ValueError("Longitude coordinate out of valid range")
+
+        # latitude
+        if value[1] < -90.0 or value[1] > 90.0:
+            raise ValueError("Latitude coordinate out of valid range")
+
+        # don't validate elevation/depth
+        # value[2]
+
+        return value

anss_formats-0.1.1/anssformats/hypocenter.py

@@ -0,0 +1,47 @@
+from typing import Optional, List, Literal
+
+from pydantic import Field, field_validator, ValidationInfo
+from anssformats.formatbasemodel import CustomDT, FormatBaseModel
+from anssformats.geojson import PointGeometry
+
+
+class HypocenterProperties(FormatBaseModel):
+    """A class holding the hypocenter specific custom properties for a geojson point feature
+
+    originTime: required datetime containing the origin time of the hypocenter
+
+    latitudeError: optional float containing the error of the latitude of this
+        hypocenter in kilometers
+
+    longitudeError: optional float containing the error of the longitude of this
+        hypocenter in kilometers
+
+    depthError: optional float containing the error of the depth of this hypocenter in
+        kilometers
+
+    timeError: optional float containing the error of the origin time of this hypocenter
+        in seconds
+    """
+
+    originTime: CustomDT
+    latitudeError: Optional[float] = None
+    longitudeError: Optional[float] = None
+    depthError: Optional[float] = None
+    timeError: Optional[float] = None
+
+
+class Hypocenter(FormatBaseModel):
+    """A conversion class used to create, parse, and validate geojson Hypocenter data as part of
+    detection data.
+
+    type: string containing the type of this geojson
+
+    geometry: PointGeometry object containing the geojson geometry for this feature
+
+    properties: HypocenterProperties object containing the hypocenter properties
+    """
+
+    type: str = "Feature"
+
+    geometry: PointGeometry
+    properties: HypocenterProperties

anss_formats-0.1.1/anssformats/magnitude.py

@@ -0,0 +1,35 @@
+from typing import Optional
+
+from pydantic import Field
+
+from anssformats.formatbasemodel import FormatBaseModel
+from anssformats.source import Source
+
+
+class Magnitude(FormatBaseModel):
+    """A conversion class used to create, parse, and validate Magnitude data as part
+    of detection data.
+
+    Attributes
+    ----------
+
+    value: float containing the magnitude value
+
+    type: string containing the magnitude type
+
+    error: optional float containing the associated magnitude error (if any)
+
+    probability: optional float containing the associated magnitude probability (if any)
+
+    id: optional string containing a unique identifier for this magnitude
+
+    source: optional Source object containing the source of the magnitude
+    """
+
+    value: float = Field(None, ge=-2.0, le=10.0)
+    type: str
+
+    error: Optional[float] = Field(None, ge=0.0)
+    probability: Optional[float] = Field(None, ge=0.0, le=100.0)
+    id: Optional[str] = None
+    source: Optional[Source] = None

{anss_formats-0.0.4 → anss_formats-0.1.1}/anssformats/pick.py

@@ -4,13 +4,11 @@ from pydantic import Field
 
 from anssformats.amplitude import Amplitude
 from anssformats.association import Association
-from anssformats.beam import Beam
-from anssformats.machineLearning import MachineLearning
+from anssformats.analytics import Analytics
 from anssformats.filter import Filter
 from anssformats.formatbasemodel import CustomDT, FormatBaseModel
 from anssformats.channel import Channel, ChannelProperties
 from anssformats.source import Source
-from anssformats.quality import Quality
 
 
 class Pick(FormatBaseModel):
@@ -40,20 +38,12 @@ class Pick(FormatBaseModel):
     filterInfo: optional list of Filter objects containing the filter frequencies when the
         pick was made
 
-    amplitude: optional Amplitude object containing the amplitude associated with the
-        pick
-
-    beamInfo: optional Beam object containing the waveform beam information associated with
-        the pick
+    amplitude: optional Amplitude object containing the amplitude associated with the pick
 
     associationInfo: optional Association object containing the association information
         if this pick is used as data in a Detection
 
-    machineLearningInfo: optional machineLearning object containing the machineLearning
-        information of this pick
-
-    qualityInfo: optional quality object containing the quality
-        information of this pick
+    AnalyticsInfo: optional analytics object containing model output attached to this pick
     """
 
     type: Literal["Pick"]
@@ -72,8 +62,6 @@ class Pick(FormatBaseModel):
 
     filterInfo: Optional[List[Filter]] = None
     amplitudeInfo: Optional[Amplitude] = None
-    beamInfo: Optional[Beam] = None
 
     associationInfo: Optional[Association] = None
-    machineLearningInfo: Optional[MachineLearning] = None
-    qualityInfo: Optional[List[Quality]] = None
+    analyticsInfo: Optional[Analytics] = None

{anss_formats-0.0.4 → anss_formats-0.1.1}/pyproject.toml

@@ -1,39 +1,39 @@
-[tool.poetry]
-name = "anss-formats"
-version = "0.0.4" #prev 0.0.1, 0.0.2
-description = "Python implementation of the library used to communicate seismic event detection information between systems"
-authors = ["John Patton <jpatton@usgs.gov>"]
-readme = "README_purpose.md"
-license = "CC0-1.0"
-homepage ="https://gitlab.com/anss-netops/anss-data-formats"
-include = [
-  "LICENSE.md"
-]
-repository="https://gitlab.com/anss-netops/anss-data-formats"
-keywords = ["anss", "earthquakes", "formats", "detection"]
-packages = [
-  {include = "anssformats" }
-]
-
-[tool.poetry.dependencies]
-python = ">3.9.1,<3.12"
-twine = "^5.1.1"
-dparse = "^0.6.2"
-certifi = "^2024.07.04"
-cryptography = "^44.0.1"
-pydantic = "^2.6.0"
-docutils = "!=0.21.post1"
-requests = "^2.32.2"
-
-[tool.poetry.group.dev.dependencies]
-black = "^24.10.0"
-safety = "^2.2.0"
-pytest = "^7.3.1"
-pytest-cov = "^4.1.0"
-
-[tool.poetry.extras]
-pycurl = ["pycurl"]
-
-[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
+[tool.poetry]
+name = "anss-formats"
+version = "0.1.1"
+description = "Python implementation of the library used to communicate seismic event detection information between systems"
+authors = ["John Patton <jpatton@usgs.gov>"]
+license = "CC0-1.0"
+homepage ="https://gitlab.com/anss-netops/anss-data-formats"
+include = [
+  "LICENSE.md"
+]
+repository="https://gitlab.com/anss-netops/anss-data-formats"
+keywords = ["anss", "earthquakes", "formats", "detection"]
+packages = [
+  {include = "anssformats" }
+]
+
+[tool.poetry.dependencies]
+python = ">3.9.1,<3.12"
+twine = "^5.1.1"
+dparse = "^0.6.2"
+certifi = "^2024.07.04"
+cryptography = ">=42.0.5"
+pydantic = "^2.6.0"
+docutils = "!=0.21.post1"
+requests = "^2.32.2"
+urllib3 = "^2.6.0"
+
+[tool.poetry.group.dev.dependencies]
+black = "^24.10.0"
+safety = "^2.2.0"
+pytest = "^7.3.1"
+pytest-cov = "^4.1.0"
+
+[tool.poetry.extras]
+pycurl = ["pycurl"]
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"