Help: mars-event v.1

Description

Contents

• Introduction
• Service Overview
• Specifying the catalog version
• Querying and filtering events
  • Type Selection
    • Event Type
    • Location Quality
    • Magnitude Type
  • Unique Identifiers
    • Event Name
    • Public ID
  • Time Bounds
  • Location Search
    • Bounding Box
    • Bounding Radius
• Customizing the HTTP response
  • Format
    • XML
    • Text
  • nodata Status Codes
• References

Introduction

The NASA InSight mission installed a single seismic station on the surface of Mars in 2019. Known as SEIS, the instrument was designed and produced by the French Space Agency (CNES), the Institut de physique du globe de Paris, and SEIS international partners and is key to the mission’s investigation of the planet’s interior.

The Mars Seismic Catalog comprises information from seismic events recorded during this two year mission and includes the first marsquake ever located on the planet. It is created and curated by the Marsquake Service (MQS), a collaborative ground service operation led by Eidgenössische Technische Hochschule (ETH) Zürich that includes seismologists from across the InSight team. The list of on-duty seismologists can be found at the DOI landing page for each release. Waveforms of these events and all other SEIS waveform data have been generated by the InSight Mars SEIS Data Service with acknowledgement reference to be found at the corresponding DOI landing page (see References).

Service Overview

The mars-event web service provides an interface to the Mars Seismic Catalog. It is an implementation of the FDSNWS-event version 1.2 specification adapted for Martian seismic events known as marsquakes.

The catalog is provided in XML format, although a text representation may also be requested. It validates against the QuakeML (BED) version 1.2 schema and includes Mars-specific data under the namespace prefix mars:.

Summary of mars-event Web Service Endpoints

¹ The only contributor listed in the catalog is the Marsquake Service whose organizational identifier is mqs. This value is found in the agencyID element in the creationInfo of a QuakeML event.

Specifying the catalog version

The catalog will be updated every three-months, with a three-month lag behind real-time, for the duration of the mission in-sync with waveform data releases. New versions are provided by MQS and may include revisions to previous content as well as newly detected events.

The service is updated concurrently to make the latest version of the catalog available by default. However, any version may be accessed by specifying the version parameter.

Available Versions of the Mars Seismic Catalog

¹ default – current data release

Querying and filtering events

The /query? endpoint returns the entire catalog of events.

• To include pick and arrival information with an event, set includearrivals=true
• To limit to preferred origin estimates, set includeallorigins=false
• To limit to preferred magnitude estimates, set includeallmagnitudes=false

Note the inclueall* parameters are unavailable for text format, which can only represent preferred magnitude and origin estimates (see Text for more information).

Type Selection

Events are classified based on the nature of their seismic signal.

Event Type

A seismic signal is assigned an event type according to its frequency content. These types belong to one of three families: the low frequency family (those dominated by long periods), the high frequency family (those dominated by high frequencies), and the recently identified super high frequency family.

The service allows one to select events by type using the eventtype parameter. It works case-insensitively and accepts a comma-separated list of event types.

Example Retrieve all events in the Low Frequency family whose signals are predominately characterized by energies below 2.4Hz:
…/query?eventtype=LF,BB&format=text

Event types in the latest catalog version

Location Quality

An event is assigned a quality based on the strength of its seismic signal and the ability to identify and interpret its phase arrivals.

The service allows one to filter events by this characterization using the locationquality parameter. It matches case-insensitively against a comma-separated list of these values.

Example Query for events with clearly identifiable phases (e.g., A and B quality events):
…/query?locationquality=A,B

Location qualities in the latest catalog version

Magnitude Type

Magnitude scales used in the latest catalog version, V7, are described in Bose et al (2021). These were initially developed in Böse et al (2018) before the landing with synthetic waveforms in the absence of a priori seismic data and were recalibrated in Giardini et al (2020). Descriptions of scales used since the third catalog version can found in Clinton et al. (2021). It is possible these will continue to be revised as new events are observed and more is learned about the specific transmission properties of Mars.

The service allows one to filter events by associated magnitude type with the magnitudetype parameter. It accepts a comma-separated list of these values and works case-insensitively.

Example Query for only those events with P and S body phase amplitude magnitude estimates, MbS and MbP:
…/query?magnitudetype=mbp,mbs

Magnitude types in latest catalog version

¹ Assigned to all events

¹ The preferred magnitude, when available

Unique Identifiers

There are two ways with which to uniquely identify events: event name and publicID, using the parameters eventname and eventid respectively.

Event Name

Event names are unique across catalog versions and encode information about when the event occurred. They are generated during event creation, using the following format: [y][xxxx][z], where [y] indicates the family to which the event belongs (‘S’ = Low and High Frequency families and ‘T’ = Super High Frequency family), [xxxx] is the sol (Martian day) on which the event begins (starting from sol 0, when InSight landed on Mars), and [z] is a letter used to ensure uniqueness if multiple events occur on a single Sol.

The eventname parameter performs a case-insensitive search for events with names matching the given value. The following glob-style wildcard characters can be used in the expression to select sets of events with similar names:

¹ Note that the question-mark (?) must be URL-encoded as ASCII (%3F) when entered directly into search bar.

Public ID

Public identifiers are used as a resource reference to an event and updated when information about that event changes. In the QuakeML formulation, the identifier follows the first forward slash in the “publicID” attribute of an event tag, after the authority ID. This service uses identifiers assigned by the insight.mqs authority.

Example Find an event by its publicID:
…/query?version=3&eventid=Event/20200626-143806/f90a7e36&format=text

Time Bounds

The service offers the ability to select events occurring between a starttime and endtime, inclusive. The parameters accept a date and time; if only the former is given, a time of 00:00:00 (“start of day”) is assumed.

All values are interpreted as Coordinated Universal Time (UTC) with a zero timezone offset, according to the ISO 8601 standard. The timezone designator (‘Z’) should be omitted. The representation can be summarized as follows: YYYY-MM-DD[Thh:mm:ss], where [..] is optional.

Example The following queries retrieve equivalent results:
…/query?starttime=2019-09-30T00:00:00
…/query?starttime=2019-09-30

Location Search

Single seismic stations pose unique challenges to location estimation, and these determinations are typically associated with great uncertainties. Only events with distance and back-azimuth calculations have location estimates. MQS notes that:

Only a handful of events in the catalog include a computed latitude/longitude location. A location is required for a valid QuakeML origin, so by default all other events are assigned the location of the lander at, lat=4.5024, long=135.6234.

The service provides two methods to select events by location: bounding box or bounding radius; parameters from these methods should not be mixed in any single request.

Orientation values used are consistent with IAU (International Astronomical Union) standards for Mars. Longitude increases to the East, and latitude is planetocentric. Coordinate values are expressed in decimal degrees, and referenced to the Martian Equator at 0° and Prime Meridian at ±90°.

Bounding Box

The four parameters – minlatitude, maxlatitude, minlongitude, and maxlongitude – work together to specify a latitude-longitude bounding rectangle on the surface of Mars using decimal degrees. By definition, an event is contained within the selection if, 1) sweeping north (increasing latitude) from minlat to maxlat traverses the event’s latitude, and 2) sweeping east (increasing longitude, possibly crossing antemeridian at ±180°) from the minlong to maxlong traverses event’s longitude.

Example
…/query?minlatitude=2&maxlatitude=60&minlongitude=-150&maxlongitude=160

Example The following query retrieves a list of the events in the catalog without a computed latitude/longitude (i.e. those assigned to the location of the lander):
…/query?minlatitude=4.5024&maxlatitude=4.5024&minlongitude=135.6234&maxlongitude=135.6234

Bounding Radius

The four parameters – latitude, longitude, maxradius and minradius – allow one to select a circular or donut-shaped area on the surface of the planet. The latitude and longitude parameters represent a location on Mars in spherical coordinates. The minradius and maxradius parameters set minimum and maximum great circle distances between the location defined by latitude and longitude and that of an event. All values should be given in decimal degrees. The calculation presumes a spherical Mars with an equatorial radius of 3306.2 km. The Haversine formula is used for great circle distance determinations, and results are rounded to the picometer (10¹²) before comparison.

Example
…/query?latitude=40.0&longitude=-100.0&minradius=18.0&maxradius=180

Customizing the HTTP response

Format

The format of the data returned can be specified using the format parameter or by setting the Accept header of the request. The value of the query parameter is favored when both are provided.

Data formats supported by the mars-event service

¹ default

XML

By default, the service returns QuakeML, an XML representation of seismological data originally created at ETH Zurich and collaboratively developed with international partners. Specifically, it validates against a variant of the QuakeML 1.2 Basic Event Description (BED) schema with mars-specific extensions. These tags are prefixed with the mars namespace.

Sample output: …/query?format=xml&eventid=mqs2019onhx

<q:quakeml xmlns=“http://quakeml.org/xmlns/bed/1.2” xmlns:q=“http://quakeml.org/xmlns/quakeml/1.2” xmlns:mars=“http://quakeml.org/xmlns/bed/1.2/mars”>
    <eventParameters publicID=“smi:insight.mqs/EventParameters”>
        <event publicID=“smi:insight.mqs/mqs2019onhx”>
            <description>
                <text>S0235b</text>
                <type>earthquake name</type>
            </description>
            <description>
                <text>Elysium Southeast</text>
                <type>region name</type>
            </description>
            <typeCertainty>suspected</typeCertainty>
            <creationInfo>
                <agencyID>mqs</agencyID>
                <author>scevent@sc3mars-op</author>
                <creationTime>2019-10-28T14:45:42.361542Z</creationTime>
            </creationInfo>
            <origin publicID=“smi:insight.mqs/origin/20201007-202124/e21efa19”>
                …
                <mars:locationQuality>http://quakeml.org/vocab/marsquake/1.0/MarsLocationQualityType#A</mars:locationQuality>
                <mars:distance>
                    <mars:value>27.85</mars:value>
                    <mars:upperUncertainty>14.77</mars:upperUncertainty>
                    <mars:lowerUncertainty>14.77</mars:lowerUncertainty>
                </mars:distance>
                <mars:azimuth>
                    <mars:value>74.0</mars:value>
                </mars:distance>
            </origin>
            <origin publicID=“smi:insight.mqs/origin/20210326-123537/62af9073”> … </origin>
            …
            <magnitude publicID=“smi:insight.mqs/Magnitude/20210326-123541/9f26b049”>
                <mag>
                    <value>3.5</value>
                </mag>
                <type>MFB</type>
                …
            </magnitude>
            <magnitude publicID=“smi:insight.mqs/Magnitude/20201007-202127/6b1384d0”> … </magnitude>
            <preferredOriginID>smi:insight.mqs/origin/20201007-202124/e21efa19</preferredOriginID>
            <preferredMagnitudeID>ami:insight.mqs/Magnitude/20210326-123541/9f26b049</preferredMagnitudeID>
            <type>other event</type>
            <mars:type>http://quakeml.org/vocab/marsquake/1.0/MarsEventType#BROADBAND</mars:type>
            <mars:typeCertainty>suspected</mars:typeCertainty>
            <mars:snr snrMQS=“12.6” snrPressure=“22.93” snrWind=“18.87”/>
        </event>
    </eventParameters>
</q:quakeml>

Text

The text format is originally defined in the FDSNWS-event specification. It provides a tabular summary of events and is especially useful to quickly reference the catalog or when viewing requests directly in-browser or from a command-line interface.

Sample output: …/query?format=text&eventname=S0235b

EventID|Time|Latitude|Longitude|Depth/km|Author|Catalog|Contributor|ContributorID|MagType|Magnitude|MagAuthor|EventLocationName|EventType
mqs2019onhx|2019-07-26T12:15:36.7000Z|11.1821|161.492||scevent@sc3mars-op||mqs|S0235b|MFB|3.5||Elysium Southeast|BROADBAND

Attributes in the text representation are delineated by pipe (|) characters; this is also known as pipe-separated values (PSV) format. Each row represents an event in the output – except for the first line (i.e. the header), which contains the column names in input order.

Columns in the text output of the mars-event web service

Note This format only encodes preferred origin and magnitude estimate and cannot display pick or arrival information. As such, when requesting format=text, the parameters includearrivals, includeallmagnitudes and includeallorigins cannot be used.

nodata Status Codes

By default, when no events match the request, the service returns a response with no content and an HTTP status code of 204. The page will not reload, because 204 messages do not have a response body. To receive a page update, use either 200 or 404. The 200 response body will always have a content-length of 0, while a 404 will provide a response body with an error message indicating not found.

No data HTTP status codes accepted by mars-event web service

Url: ../query?eventid=cat&nodata=204&format=text
Protocol: HTTP/1.1 
Status: 204 NO CONTENT

Url: ../query?eventid=cat&nodata=404&format=text
Protocol: HTTP/1.1 
Status: 404 NOT FOUND
Content-Type: text/plain;charset=UTF-8
Content-Length: 262

Url: ../query?eventid=cat&nodata=200&format=text
Protocol: HTTP/1.1 
Status: 200 OK
Content-Type: text/plain;charset=UTF-8
Content-Length: 0

References

Additional Resources

Computing Distances
FDSN (International Federation of Digital Seismograph Networks) Web Services
IETF RFC 7230 – HTTP: Message Syntax and Routing
IETF RFC 7231 – HTTP Semantics and Content
International System of Units
ISO 8601 C.1.3.2 Date and Time
QuakeML

Problems with this service?