anss-formats 0.0.1__py3-none-any.whl

anss_formats-0.0.1.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: anss-formats
+Version: 0.0.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 (>=44.0.1,<45.0.0)
+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)
+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.0.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+anssformats/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+anssformats/amplitude.py,sha256=DCtkc6siT8dj0C3ynBM01rfaSpKOeHTc-51CDmspELg,647
+anssformats/association.py,sha256=UjDmr213kSzCCIWHMDce06Xjzut3-l1IYKexxJR_C_I,1173
+anssformats/beam.py,sha256=lKmdXi_9Y9kglXPrsDG8WT2_41ssX92PrLxxjws7wT4,1004
+anssformats/channel.py,sha256=AQ6wrBCtMhXwN3gdxWQKkiutqnVB9H2FmbMrOY6CTC8,2240
+anssformats/eventType.py,sha256=6DHjovVVGug5AU1WRKX3RxQbrnwSPlg2KNtH2sLX1Q0,1216
+anssformats/filter.py,sha256=uOAUteSWeBvDcB12_9E_9sqe0wb6iR_lHZdjLv5agNM,675
+anssformats/formatbasemodel.py,sha256=naZFyuL6YOIMdpYpxD91l7MbbG6eafz3-itzLilSoG8,1933
+anssformats/machineLearning.py,sha256=6xwmv_F2VuxZl-ng7qUKlV7Mrlw6aQ-LKg6A6x3vdfo,3261
+anssformats/pick.py,sha256=Spaw7Paw_UCkVxNSJxJSirmiXM3e2KEY8-nIwVgk2Vg,2867
+anssformats/quality.py,sha256=PK5sPAoJTUgCrmQkiWTerEB2klWbR1ECAU-qIABpcjA,389
+anssformats/source.py,sha256=G78YUwY2fimi8Uy0d1mKjaIIsEDUue50wdHpACQsSMU,398
+anss_formats-0.0.1.dist-info/METADATA,sha256=zs6fyxG-cyhnIQb6n3wqGM0JDo8p0RnLEoNnwUerKMo,1006
+anss_formats-0.0.1.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+anss_formats-0.0.1.dist-info/RECORD,,

anss_formats-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.2.1
+Root-Is-Purelib: true
+Tag: py3-none-any

anssformats/amplitude.py

@@ -0,0 +1,24 @@
+from typing import Optional
+
+from pydantic import Field
+
+from anssformats.formatbasemodel import FormatBaseModel
+
+
+class Amplitude(FormatBaseModel):
+    """A conversion class used to create, parse, and validate amplitude data as part of
+    detection data.
+
+    Attributes
+    ----------
+
+    amplitude: optional float containing the amplitude
+
+    period: optional float containing the period
+
+    snr: optional float containing the signal to noise ratio, capped at 1E9
+    """
+
+    amplitude: Optional[float] = None
+    period: Optional[float] = Field(None, ge=0.0)
+    snr: Optional[float] = Field(None, ge=0.0, le=1e9)

anssformats/association.py

@@ -0,0 +1,35 @@
+from typing import Optional
+
+from pydantic import Field
+
+from anssformats.formatbasemodel import FormatBaseModel
+
+
+class Association(FormatBaseModel):
+    """A conversion class used to create, parse, and validate association data as part
+    of detection data.
+
+    Attributes
+    ----------
+
+    phase: optional string containing the associated phase name
+
+    distance: optional float containing the associated distance in degrees between the
+        detection's and the data's locations if associated
+
+    azimuth: optional float containing the associated azimuth in degrees between the
+        detection's and the data's locations if associated
+
+    residual: optional float containing the associated residual in seconds of the data
+        if associated
+
+    sigma: optional float containing the number of standard deviations of the data from
+        the calculated value if associated
+    """
+
+    phase: Optional[str] = Field(None, pattern=r"^[A-Za-z]+$")
+
+    distance: Optional[float] = Field(None, ge=0.0)
+    azimuth: Optional[float] = Field(None, ge=0.0)
+    residual: Optional[float] = None
+    sigma: Optional[float] = None

anssformats/beam.py

@@ -0,0 +1,34 @@
+from typing import Optional
+
+from pydantic import Field
+
+from anssformats.formatbasemodel import FormatBaseModel
+
+
+class Beam(FormatBaseModel):
+    """A conversion class used to create, parse, and validate beam detection data.
+
+    Attributes
+    ----------
+
+    backAzimuth: float containing the back azimuth in degrees
+
+    backAzimuthError: optional float containing the back azimuth error
+
+    slowness: float containing the horizontal slowness
+
+    slownessError: optional float containing the horizontal slowness error
+
+    powerRatio: optional float containing the power ratio
+
+    powerRatioError: optional float containing the power ratio error
+    """
+
+    backAzimuth: float = Field(ge=0.0)
+    backAzimuthError: Optional[float] = Field(None, ge=0.0)
+
+    slowness: float = Field(ge=0.0)
+    slownessError: Optional[float] = Field(None, ge=0.0)
+
+    powerRatio: Optional[float] = Field(None, ge=0.0)
+    powerRatioError: Optional[float] = Field(None, ge=0.0)

anssformats/channel.py

@@ -0,0 +1,76 @@
+from typing import Optional, List, Literal
+
+from pydantic import Field, field_validator, ValidationInfo
+from anssformats.formatbasemodel import FormatBaseModel
+
+
+class ChannelGeometry(FormatBaseModel):
+    """A class holding the geojson geometry for the channel
+
+    type: string containing the type of this geometry
+
+    coordinates: List of floats containing the longitude in degrees, latitude in degrees, and elevation in meters, 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 bother validating elevation
+        # value[2]
+
+        return value
+
+
+class ChannelProperties(FormatBaseModel):
+    """A class holding the channe 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: ChannelGeometry object containing the geojson geometry for this feature
+
+    properties: ChannelProperties object containing the channel properties
+    """
+
+    type: str = "Feature"
+
+    geometry: ChannelGeometry
+    properties: ChannelProperties

anssformats/eventType.py

@@ -0,0 +1,37 @@
+from typing import Literal, Optional
+
+from anssformats.formatbasemodel import FormatBaseModel
+
+
+class EventType(FormatBaseModel):
+    """A conversion class used to create, parse, and validate source data as part of
+    detection data. Detection formats supports a subset of the QuakeML 1.2 event types
+    that are automatically classifiable.
+
+    Attributes
+    ----------
+
+    type: optional string containing the type of detection that was found; allowed type
+        strings are: "Earthquake", "MineCollapse", "NuclearExplosion", "QuarryBlast",
+        "InducedOrTriggered", "RockBurst", "FluidInjection", "IceQuake", and
+        "VolcanicEruption"
+
+    certainty: optional string containing the certainty of the event type; allowed
+        strings are "Suspected" and "Confirmed"
+    """
+
+    type: Optional[
+        Literal[
+            "Earthquake",
+            "MineCollapse",
+            "NuclearExplosion",
+            "QuarryBlast",
+            "InducedOrTriggered",
+            "RockBurst",
+            "FluidInjection",
+            "IceQuake",
+            "VolcanicEruption",
+        ]
+    ] = None
+
+    certainty: Optional[Literal["Suspected", "Confirmed"]] = None

anssformats/filter.py

@@ -0,0 +1,25 @@
+from typing import Optional
+
+from anssformats.formatbasemodel import FormatBaseModel
+
+
+class Filter(FormatBaseModel):
+    """A conversion class used to create, parse, and validate filter data as part of
+    detection data.
+
+    Attributes
+    ----------
+
+    type: optional string containing the type of filter
+
+    highPass: optional float containing the high pass frequency
+
+    lowPass: optional float containing the low pass frequency
+
+    units: optional string containing the filter frequency units
+    """
+
+    type: Optional[str] = None
+    highPass: Optional[float] = None
+    lowPass: Optional[float] = None
+    units: Optional[str] = None

anssformats/formatbasemodel.py

@@ -0,0 +1,57 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, GetCoreSchemaHandler
+from pydantic_core import CoreSchema, core_schema
+
+
+def convert_datetime_to_iso8601_with_z_suffix(dt: datetime) -> str:
+    """Convert provided datetime to an ISO 8601 UTC time string
+
+    Parameters
+    ----------
+    dt: Datetime containing the date time to convert
+
+    Returns
+    -------
+    A str containing the ISO 8601 UTC formatted time string
+    """
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+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)
+
+    def model_dump_json(self):
+        """Override the default model_dump_json method to always exclude None values"""
+        return super().model_dump_json(exclude_none=True)
+
+
+class CustomDT(datetime):
+    """A convenience class used to strip all datetime objects of timezone information,
+    required to bypass Pydantic's automatic inclusion of timezone when parsing JSON
+    strings.
+    """
+
+    @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)
+
+    @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
+        )

anssformats/machineLearning.py

@@ -0,0 +1,89 @@
+from typing import Optional
+
+from pydantic import Field
+
+from anssformats.eventType import EventType as EventTypeFormat
+from anssformats.formatbasemodel import FormatBaseModel
+from anssformats.source import Source as SourceFormat
+
+
+class MachineLearning(FormatBaseModel):
+    """A conversion class used to create, parse, and validate value added MachineLearning
+    data from advanced algorithms such as machine learning as part of detection formats
+    data.
+
+    Attributes
+    ----------
+
+    phase: optional string containing MachineLearning phase name
+
+    phaseProbability: optional float containing the probability of the MachineLearning
+        phase name
+
+    distance: optional float containing the MachineLearning distance in degrees
+
+    distanceProbability: optional float containing the probability of the MachineLearning
+        distance
+
+    backAzimuth: optional float containing the MachineLearning back azimuth in degrees
+
+    backAzimuthProbability: optional float containing the probability of the
+        MachineLearning back azimuth
+
+    magnitude: optional float containing the MachineLearning magnitude
+
+    magnitudeType: optional string containing the MachineLearning magnitude type
+
+    magnitudeProbability: optional float containing the probability of the
+        MachineLearning magnitude
+
+    depth: optional float containing the MachineLearning depth in kilometers
+
+    depthProbability: optional float containing the probability of the MachineLearning
+        depth
+
+    eventType: optional EventType object containing the MachineLearning event type
+
+    eventTypeProbability: optional float containing the probability of the
+        MachineLearning event type
+
+    repickShift: optional float containing the repick shift value in seconds
+
+    repickSTD: optional float containing the repick shift standard deviation
+
+    repickCredibleIntervalLower: optional float containing the repick shift lower credible interval
+
+    repickCredibleIntervalUpper: optional float containing the repick shift upper credible interval
+
+    source: optional Source object containing the source of the MachineLearning
+        information
+    """
+
+    phase: Optional[str] = Field(None, pattern=r"^[A-Za-z]+$")
+    phaseProbability: Optional[float] = None
+
+    distance: Optional[float] = Field(None, ge=0.0)
+    distanceProbability: Optional[float] = None
+
+    backAzimuth: Optional[float] = Field(None, ge=0.0)
+    backAzimuthProbability: Optional[float] = None
+
+    magnitude: Optional[float] = Field(None, ge=-2.0, le=10.0)
+    magnitudeType: Optional[str] = None
+    magnitudeProbability: Optional[float] = None
+
+    depth: Optional[float] = Field(None, ge=-100.0, le=1500.0)
+    depthProbability: Optional[float] = None
+
+    eventType: Optional[EventTypeFormat] = None
+    eventTypeProbability: Optional[float] = None
+
+    distanceRangeHalfWidth: Optional[float] = None
+    distanceRangeSigma: Optional[float] = None
+
+    repickShift: Optional[float] = None
+    repickSTD: Optional[float] = None
+    repickCredibleIntervalLower: Optional[float] = None
+    repickCredibleIntervalUpper: Optional[float] = None
+
+    source: Optional[SourceFormat] = None

anssformats/pick.py

@@ -0,0 +1,79 @@
+from typing import List, Literal, Optional
+
+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.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):
+    """A conversion class used to create, parse, and validate pick detection data.
+
+    type: string identifying this message as a pick
+
+    id: string containing a unique identifier for this pick
+
+    channel: Channel object containing the station where the pick was made
+
+    source: Source object containing the source of the pick
+
+    time: datetime containing the arrival time of the phase that was picked
+
+    phase: optional string containing the seismic phase that was picked
+
+    polarity: optional string containing the phase polarity; allowed strings are "up"
+        and "down"
+
+    onset: optional string containing the phase onset; allowed strings are "impulsive",
+        "emergent", and "questionable"
+
+    pickerType: optional string containing the type of picker; allowed strings are "manual",
+        "raypicker", "filterpicker", "earthworm", and "other"
+
+    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
+
+    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
+    """
+
+    type: Literal["Pick"]
+    id: str
+
+    channel: Channel
+    source: Source
+    time: CustomDT
+
+    phase: Optional[str] = Field(None, pattern=r"^[A-Za-z]+$")
+    polarity: Optional[Literal["up", "down"]] = None
+    onset: Optional[Literal["impulsive", "emergent", "questionable"]] = None
+    pickerType: Optional[
+        Literal["manual", "raypicker", "filterpicker", "earthworm", "other"]
+    ] = None
+
+    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

anssformats/quality.py

@@ -0,0 +1,17 @@
+from anssformats.formatbasemodel import FormatBaseModel
+
+
+class Quality(FormatBaseModel):
+    """A conversion class used to create, parse, and validate Quality data as part of
+    detection data.
+
+    Attributes
+    ----------
+
+    standard: string containing the name of the quality standard used
+
+    value: float containing the Quality value
+    """
+
+    standard: str
+    value: float

anssformats/source.py

@@ -0,0 +1,17 @@
+from anssformats.formatbasemodel import FormatBaseModel
+
+
+class Source(FormatBaseModel):
+    """A conversion class used to create, parse, and validate source data as part of
+    detection data.
+
+    Attributes
+    ----------
+
+    agencyID: string containing the originating agency FDSN ID
+
+    author: string containing the source author
+    """
+
+    agencyID: str
+    author: str