anss-formats 0.1.2

Python implementation of the library used to communicate seismic event detection information between systems

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 for formatting.
• ANSS Formats was written in Python 3.6
• ANSS Formats uses poetry 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.

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 - A format for unassociated picks from a waveform arrival time picking algorithm.
• Detection Format - A format for an earthquake detection picks from a seismic detection algorithm.

Supporting format objects:

• Amplitude Object - An object that contains information about an amplitude as part of a pick.
• Analytics Object - An object that holds extensible information from model outputs or other processing tags.
• Association Object - An object that contains associated information if a pick is included in a detection.
• Channel Object - A geoJSON object that contains channel/location information as part of a pick.
• EventType Object - An object that defines the event type for a detection.
• Filter Object - An object that contains filter information as part of a pick.
• Hypocenter Object - A geoJSON object that contains the hypocentral location, arrival time, and error information as part of a detection.
• Magnitude Object - An object that defines an earthquake magnitude estimation for a detection.
• Source 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 Format. Amplitude uses the JSON standard.

Usage

The Amplitude object is intended for use as part of the Pick Format in seismic data messaging between seismic applications and organizations.

Output

    {
       "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. Model outputs are stored as a list of Predictions. Suitable for retaining output of pickers, analytical models, AI/ML predictors, etc. Analytics uses the JSON standard.

Usage

Analytics is intended for use as part of the Pick format in seismic data messaging between seismic applications and organizations.

Output

{
    "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

Association Object Specification

Description

The Association object is an object designed to encode information provided when a group of Pick are associated for an event. Association uses the JSON standard.

Usage

Association is intended for use as part of the Pick Format in seismic data messaging between seismic applications and organizations.

Output

    {
       "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 message. Channel uses the JSON and GeoJSON standards.

Usage

Channel is intended for use as part of the Pick Format in seismic data messaging between seismic applications and organizations.

Output

{
  "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.

Usage

Detection is intended for use in seismic data messaging between seismic applications.

Output

    {
      "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.
• hypocenter - An object containing the hypocenter of the Detection, see Hypocenter.

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.
• 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 objects used to generate this Detection.
• magnitudeData - An array of Magnitude objects for this Detection.
• analyticsInfo - An object containing analytical information from one or more models/algorithms, see Analytics.

EventType Object Specification

Description

The EventType object is an object designed to define the phenomena causing a seismic detection. EventType uses the JSON standard.

Usage

EventType is intended for use as part of the Detection object in seismic data messaging between seismic applications and organizations.

Output

    {
      "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 Format. Filter uses the JSON standard .

Usage

The Filter object is intended for use as part of the Pick Format in seismic data messaging between seismic applications and organizations.

Output

   {
      "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 message. Hypocenter uses the JSON standard and GeoJSON standards.

Usage

Hypocenter is intended for use as part of the Detection Format in seismic data messaging between seismic applications and organizations.

Output

    {
      "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. Magnitude uses the JSON standard.

Usage

Magnitude is intended for use as part of the Detection Format in seismic data messaging between seismic applications and organizations.

Output

    {
      "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.
• 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.

Usage

Pick is intended for use in seismic data messaging between seismic applications and organizations.

Output

    {
      "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.
• source - An object containing the source of the pick, see Source.
• 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.
• amplitude - An object containing the amplitude associated with the pick, see Amplitude.
• associationInfo - An object containing the association information if this pick is used as data in a Detection, see Association.
• analyticsInfo - An object containing analytical information from one or more models/algorithms, see Analytics.

Source Object Specification

Description

The Source object is an object designed to define the originating seismic organization that produced a Pick message. Source uses the JSON standard.

Usage

Source is intended for use as part of the Pick Format in seismic data messaging between seismic applications and organizations.

Output

    {
      "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.