quakeml

QuakeML 1.2 input, output, and data model.

This modules provides support to read and write QuakeML version 1.2. It defines a hierarchy of Python objects, closely following the QuakeML data model.

QuakeML is a flexible, extensible and modular XML representation of seismological data which is intended to cover a broad range of fields of application in modern seismology. It covers basic seismic event description, including moment tensors.

For convenience and ease of use, this documentation contains excerpts from the QuakeML Manual. However, this information is not intended to be complete. Please refer to the QuakeML Manual for details.

exception QuakeMLError[source]

Bases: Exception

exception NoPreferredOriginSet[source]

Bases: QuakeMLError

class ResourceIdentifier(...) dummy for str[source]

Bases: StringPattern

Identifies resource origin.

They consist of an authority identifier, a unique resource identifier, and an optional local identifier. The URI schema name smi stands for seismological meta-information, thus indicating a connection to a set of metadata associated with the resource.

class WhitespaceOrEmptyStringType(...) dummy for str[source]

Bases: StringPattern

Any str matching pattern '^\\s*$'.

class OriginUncertaintyDescription(...) dummy for str[source]

Bases: StringChoice

Preferred uncertainty description.

class AmplitudeCategory(...) dummy for str[source]

Bases: StringChoice

Description of the way the waveform trace is evaluated to get an amplitude value.

This can be just reading a single value for a given point in time (point), taking a mean value over a time interval (mean), integrating the trace over a time interval (integral), specifying just a time interval (duration), or evaluating a period (period).

class OriginDepthType(...) dummy for str[source]

Bases: StringChoice

Type of depth determination.

class OriginType(...) dummy for str[source]

Bases: StringChoice

Describes the origin type.

class MTInversionType(...) dummy for str[source]

Bases: StringChoice

Type of moment tensor inversion.

Users should avoid to give contradictory information in MTInversionType and MomentTensor.method_id.

class EvaluationMode(...) dummy for str[source]

Bases: StringChoice

Mode of an evaluation.

Used in Pick, Amplitude, Magnitude, Origin, FocalMechanism.

class EvaluationStatus(...) dummy for str[source]

Bases: StringChoice

Status of an evaluation.

Used in Pick, Amplitude, Magnitude, Origin, FocalMechanism.

class PickOnset(...) dummy for str[source]

Bases: StringChoice

Flag that roughly categorizes the sharpness of the onset.

class EventType(...) dummy for str[source]

Bases: StringChoice

Describes the type of an event.

class DataUsedWaveType(...) dummy for str[source]

Bases: StringChoice

Type of waveform data.

class AmplitudeUnit(...) dummy for str[source]

Bases: StringChoice

Provides the most likely measurement units.

The measurement units for physical quantity are described in the Amplitude.generic_amplitude attribute. Possible values are specified as combination of SI base units.

class EventDescriptionType(...) dummy for str[source]

Bases: StringChoice

Category of earthquake description.

class MomentTensorCategory(...) dummy for str[source]

Bases: StringChoice

Category of moment tensor inversion.

class EventTypeCertainty(...) dummy for str[source]

Bases: StringChoice

Denotes how certain the information on event type is.

class SourceTimeFunctionType(...) dummy for str[source]

Bases: StringChoice

Type of source time function.

class PickPolarity(...) dummy for str[source]

Bases: StringChoice

Any str out of ['positive', 'negative', 'undecidable'].

class AgencyID(...) dummy for str[source]

Bases: String

Undocumented.

class Author(...) dummy for str[source]

Bases: Unicode

Undocumented.

class Version(...) dummy for str[source]

Bases: String

Undocumented.

class Phase(**kwargs)[source]

Bases: Object

Undocumented.

value

str

class GroundTruthLevel(...) dummy for str[source]

Bases: String

Undocumented.

class AnonymousNetworkCode(...) dummy for str[source]

Bases: String

Undocumented.

class AnonymousStationCode(...) dummy for str[source]

Bases: String

Undocumented.

class AnonymousChannelCode(...) dummy for str[source]

Bases: String

Undocumented.

class AnonymousLocationCode(...) dummy for str[source]

Bases: String

Undocumented.

class Type(...) dummy for str[source]

Bases: String

Undocumented.

class MagnitudeHint(...) dummy for str[source]

Bases: String

Undocumented.

class Region(...) dummy for str[source]

Bases: Unicode

Undocumented.

class RealQuantity(**kwargs)[source]

Bases: Object

Undocumented.

value

float

uncertainty

float, optional

lower_uncertainty

float, optional

upper_uncertainty

float, optional

confidence_level

float, optional

class IntegerQuantity(**kwargs)[source]

Bases: Object

Undocumented.

value

int

uncertainty

int, optional

lower_uncertainty

int, optional

upper_uncertainty

int, optional

confidence_level

float, optional

class ConfidenceEllipsoid(**kwargs)[source]

Bases: Object

Representation of the location uncertainty as a confidence ellipsoid with arbitrary orientation in space.

semi_major_axis_length

float

semi_minor_axis_length

float

semi_intermediate_axis_length

float

major_axis_plunge

float

major_axis_azimuth

float

major_axis_rotation

float

class TimeQuantity(**kwargs)[source]

Bases: Object

Representation of a point in time.

It’s given in ISO 8601 format, with optional symmetric or asymmetric uncertainties given in seconds. The time has to be specified in UTC.

value

time_float (pyrocko.guts.Timestamp)

uncertainty

float, optional

lower_uncertainty

float, optional

upper_uncertainty

float, optional

confidence_level

float, optional

class TimeWindow(**kwargs)[source]

Bases: Object

Representation of a time window for amplitude measurements.

Which is given by a central point in time, and points in time before and after this central point. Both points before and after may coincide with the central point.

begin

float

end

float

reference

time_float (pyrocko.guts.Timestamp)

class ResourceReference(...) dummy for str[source]

Bases: ResourceIdentifier

This type is used to refer to QuakeML resources as described in Sect. 3.1 in the QuakeML manual.

class DataUsed(**kwargs)[source]

Bases: Object

Description of the type of data used in a moment-tensor inversion.

wave_type

str (DataUsedWaveType)

station_count

int, optional

component_count

int, optional

shortest_period

float, optional

longest_period

float, optional

class EventDescription(**kwargs)[source]

Bases: Object

Free-form string with additional event description.

This can be a well-known name, like 1906 San Francisco Earthquake. A number of categories can be given in type.

text

str

type

str (EventDescriptionType), optional

class SourceTimeFunction(**kwargs)[source]

Bases: Object

Source time function used in moment-tensor inversion.

type

str (SourceTimeFunctionType)

duration

float

rise_time

float, optional

decay_time

float, optional

class OriginQuality(**kwargs)[source]

Bases: Object

Description of an origin’s quality.

It contains various attributes commonly used to describe the quality of an origin, e. g., errors, azimuthal coverage, etc. Origin objects have an optional attribute of the type OriginQuality.

associated_phase_count

int, optional

used_phase_count

int, optional

associated_station_count

int, optional

used_station_count

int, optional

depth_phase_count

int, optional

standard_error

float, optional

azimuthal_gap

float, optional

secondary_azimuthal_gap

float, optional

ground_truth_level

str (GroundTruthLevel), optional

maximum_distance

float, optional

minimum_distance

float, optional

median_distance

float, optional

class Axis(**kwargs)[source]

Bases: Object

Representation of an eigenvector of a moment tensor.

Which is expressed in its principal-axes system and uses the angles azimuth, plunge, and the eigenvalue length.

azimuth

RealQuantity

plunge

RealQuantity

length

RealQuantity

class Tensor(**kwargs)[source]

Bases: Object

Representation of the six independent moment-tensor elements in spherical coordinates.

These are the moment-tensor elements Mrr, Mtt, Mpp, Mrt, Mrp, Mtp in the spherical coordinate system defined by local upward vertical (r), North-South (t), and West-East (p) directions.

mrr

RealQuantity

mtt

RealQuantity

mpp

RealQuantity

mrt

RealQuantity

mrp

RealQuantity

mtp

RealQuantity

class NodalPlane(**kwargs)[source]

Bases: Object

Description of a nodal plane of a focal mechanism.

strike

RealQuantity

dip

RealQuantity

rake

RealQuantity

class CompositeTime(**kwargs)[source]

Bases: Object

Representation of a time instant.

If the specification is given with no greater accuracy than days (i.e., no time components are given), the date refers to local time. However, if time components are given, they have to refer to UTC.

year

IntegerQuantity, optional

month

IntegerQuantity, optional

day

IntegerQuantity, optional

hour

IntegerQuantity, optional

minute

IntegerQuantity, optional

second

RealQuantity, optional

class OriginUncertainty(**kwargs)[source]

Bases: Object

Description of the location uncertainties of an origin.

The uncertainty can be described either as a simple circular horizontal uncertainty, an uncertainty ellipse according to IMS1.0, or a confidence ellipsoid. If multiple uncertainty models are given, the preferred variant can be specified in the attribute preferred_description.

horizontal_uncertainty

float, optional

min_horizontal_uncertainty

float, optional

max_horizontal_uncertainty

float, optional

azimuth_max_horizontal_uncertainty

float, optional

confidence_ellipsoid

ConfidenceEllipsoid, optional

preferred_description

str (OriginUncertaintyDescription), optional

confidence_level

float, optional

class ResourceReferenceOptional(...) dummy for str[source]

Bases: Union

Undocumented.

class CreationInfo(**kwargs)[source]

Bases: Object

Description of creation metadata (author, version, and creation time) of a resource.

agency_id

str (AgencyID), optional

agency_uri

str (ResourceReference), optional

author

str (Author), optional

author_uri

str (ResourceReference), optional

creation_time

time_float (pyrocko.guts.Timestamp), optional

version

str (Version), optional

class StationMagnitudeContribution(**kwargs)[source]

Bases: Object

Description of the weighting of magnitude values from several StationMagnitude objects for computing a network magnitude estimation.

station_magnitude_id

str (ResourceReference)

residual

float, optional

weight

float, optional

class PrincipalAxes(**kwargs)[source]

Bases: Object

Representation of the principal axes of a moment tensor.

t_axis and p_axis are required, while n_axis is optional.

t_axis

Axis

p_axis

Axis

n_axis

Axis, optional

class NodalPlanes(**kwargs)[source]

Bases: Object

Representation of the nodal planes of a moment tensor.

The attribute preferred_plane can be used to define which plane is the preferred one.

preferred_plane

int, optional

nodal_plane1

NodalPlane, optional

nodal_plane2

NodalPlane, optional

class WaveformStreamID(**kwargs)[source]

Bases: Object

Reference to a stream description in an inventory.

This is mostly equivalent to the combination of networkCode, stationCode, locationCode, and channelCode. However, additional information, e.g., sampling rate, can be referenced by the resourceURI. It is recommended to use resourceURI as a flexible, abstract, and unique stream ID that allows to describe different processing levels, or resampled/filtered products of the same initial stream, without violating the intrinsic meaning of the legacy identifiers (network_code, station_code, channel_code, and location_code). However, for operation in the context of legacy systems, the classical identifier components are supported.

value

str (ResourceReferenceOptional)

network_code

str (AnonymousNetworkCode)

station_code

str (AnonymousStationCode)

channel_code

str (AnonymousChannelCode), optional

location_code

str (AnonymousLocationCode), optional

class Comment(**kwargs)[source]

Bases: Object

Comment to a resource together with author and creation time information.

id

str (ResourceReference), optional

text

str

creation_info

CreationInfo, optional

class MomentTensor(**kwargs)[source]

Bases: Object

Representation of a moment tensor solution for an event.

It is an optional part of a FocalMechanism description.

public_id

str (ResourceReference)

data_used_list

list of DataUsed objects, default: []

comment_list

list of Comment objects, default: []

derived_origin_id

str (ResourceReference), optional

moment_magnitude_id

str (ResourceReference), optional

scalar_moment

RealQuantity, optional

tensor

Tensor, optional

variance

float, optional

variance_reduction

float, optional

double_couple

float, optional

clvd

float, optional

iso

float, optional

greens_function_id

str (ResourceReference), optional

filter_id

str (ResourceReference), optional

source_time_function

SourceTimeFunction, optional

method_id

str (ResourceReference), optional

category

str (MomentTensorCategory), optional

inversion_type

str (MTInversionType), optional

creation_info

CreationInfo, optional

class Amplitude(**kwargs)[source]

Bases: Object

Quantification of the waveform anomaly.

Usually it consists of a single amplitude measurement or a measurement of the visible signal duration for duration magnitudes.

public_id

str (ResourceReference)

comment_list

list of Comment objects, default: []

generic_amplitude

RealQuantity

type

str (Type), optional

category

str (AmplitudeCategory), optional

unit

str (AmplitudeUnit), optional

method_id

str (ResourceReference), optional

period

RealQuantity, optional

snr

float, optional

time_window

TimeWindow, optional

pick_id

str (ResourceReference), optional

waveform_id

WaveformStreamID, optional

filter_id

str (ResourceReference), optional

scaling_time

TimeQuantity, optional

magnitude_hint

str (MagnitudeHint), optional

evaluation_mode

str (EvaluationMode), optional

evaluation_status

str (EvaluationStatus), optional

creation_info

CreationInfo, optional

class Magnitude(**kwargs)[source]

Bases: Object

Description of a magnitude value.

It can, but does not need to be associated with an origin. Association with an origin is expressed with the optional attribute origin_id. It is either a combination of different magnitude estimations, or it represents the reported magnitude for the given event.

public_id

str (ResourceReference)

comment_list

list of Comment objects, default: []

station_magnitude_contribution_list

list of StationMagnitudeContribution objects, default: []

mag

RealQuantity

type

str (Type), optional

origin_id

str (ResourceReference), optional

method_id

str (ResourceReference), optional

station_count

int, optional

azimuthal_gap

float, optional

evaluation_mode

str (EvaluationMode), optional

evaluation_status

str (EvaluationStatus), optional

creation_info

CreationInfo, optional

class StationMagnitude(**kwargs)[source]

Bases: Object

Description of a magnitude derived from a single waveform stream.

public_id

str (ResourceReference)

comment_list

list of Comment objects, default: []

origin_id

str (ResourceReference), optional

mag

RealQuantity

type

str (Type), optional

amplitude_id

str (ResourceReference), optional

method_id

str (ResourceReference), optional

waveform_id

WaveformStreamID, optional

creation_info

CreationInfo, optional

class Arrival(**kwargs)[source]

Bases: Object

Successful association of a pick with an origin qualifies this pick as an arrival.

An arrival thus connects a pick with an origin and provides additional attributes that describe this relationship. Usually qualification of a pick as an arrival for a given origin is a hypothesis, which is based on assumptions about the type of arrival (phase) as well as observed and (on the basis of an earth model) computed arrival times, or the residual, respectively. Additional pick attributes like the horizontal slowness and backazimuth of the observed wave—especially if derived from array data—may further constrain the nature of the arrival.

public_id

str (ResourceReference)

comment_list

list of Comment objects, default: []

pick_id

str (ResourceReference)

phase

Phase

time_correction

float, optional

azimuth

float, optional

distance

float, optional

takeoff_angle

RealQuantity, optional

time_residual

float, optional

horizontal_slowness_residual

float, optional

backazimuth_residual

float, optional

time_weight

float, optional

time_used

int, optional

horizontal_slowness_weight

float, optional

backazimuth_weight

float, optional

earth_model_id

str (ResourceReference), optional

creation_info

CreationInfo, optional

class Pick(**kwargs)[source]

Bases: Object

A pick is the observation of an amplitude anomaly in a seismogram at a specific point in time.

It is not necessarily related to a seismic event.

public_id

str (ResourceReference)

comment_list

list of Comment objects, default: []

time

TimeQuantity

waveform_id

WaveformStreamID

filter_id

str (ResourceReference), optional

method_id

str (ResourceReference), optional

horizontal_slowness

RealQuantity, optional

backazimuth

RealQuantity, optional

slowness_method_id

str (ResourceReference), optional

onset

str (PickOnset), optional

phase_hint

Phase, optional

polarity

str (PickPolarity), optional

evaluation_mode

str (EvaluationMode), optional

evaluation_status

str (EvaluationStatus), optional

creation_info

CreationInfo, optional

class FocalMechanism(**kwargs)[source]

Bases: Object

Description of the focal mechanism of an event.

It includes different descriptions like nodal planes, principal axes, and a moment tensor. The moment tensor description is provided by objects of the class MomentTensor which can be specified as child elements of FocalMechanism.

public_id

str (ResourceReference)

waveform_id_list

list of WaveformStreamID objects, default: []

comment_list

list of Comment objects, default: []

moment_tensor_list

list of MomentTensor objects, default: []

triggering_origin_id

str (ResourceReference), optional

nodal_planes

NodalPlanes, optional

principal_axes

PrincipalAxes, optional

azimuthal_gap

float, optional

station_polarity_count

int, optional

misfit

float, optional

station_distribution_ratio

float, optional

method_id

str (ResourceReference), optional

evaluation_mode

str (EvaluationMode), optional

evaluation_status

str (EvaluationStatus), optional

creation_info

CreationInfo, optional

class Origin(**kwargs)[source]

Bases: Object

Representation of the focal time and geographical location of an earthquake hypocenter, as well as additional meta-information.

Origin can have objects of type OriginUncertainty and Arrival as child elements.

public_id

str (ResourceReference)

composite_time_list

list of CompositeTime objects, default: []

comment_list

list of Comment objects, default: []

origin_uncertainty_list

list of OriginUncertainty objects, default: []

arrival_list

list of Arrival objects, default: []

time

TimeQuantity

longitude

RealQuantity

latitude

RealQuantity

depth

RealQuantity, optional

depth_type

str (OriginDepthType), optional

time_fixed

bool, optional

epicenter_fixed

bool, optional

reference_system_id

str (ResourceReference), optional

method_id

str (ResourceReference), optional

earth_model_id

str (ResourceReference), optional

quality

OriginQuality, optional

type

str (OriginType), optional

region

str (Region), optional

evaluation_mode

str (EvaluationMode), optional

evaluation_status

str (EvaluationStatus), optional

creation_info

CreationInfo, optional

class Event(**kwargs)[source]

Bases: Object

Representation of a seismic event.

The Event does not necessarily need to be a tectonic earthquake. An event is usually associated with one or more origins, which contain information about focal time and geographical location of the event. Multiple origins can cover automatic and manual locations, a set of location from different agencies, locations generated with different location programs and earth models, etc. Furthermore, an event is usually associated with one or more magnitudes, and with one or more focal mechanism determinations. In standard QuakeML-BED, Origin, Magnitude, StationMagnitude, and FocalMechanism are child elements of Event. In BED-RT all these elements are on the same hierarchy level as child elements of EventParameters. The association of origins, magnitudes, and focal mechanisms to a particular event is expressed using references inside Event.

public_id

str (ResourceReference)

description_list

list of EventDescription objects, default: []

comment_list

list of Comment objects, default: []

focal_mechanism_list

list of FocalMechanism objects, default: []

amplitude_list

list of Amplitude objects, default: []

magnitude_list

list of Magnitude objects, default: []

station_magnitude_list

list of StationMagnitude objects, default: []

origin_list

list of Origin objects, default: []

pick_list

list of Pick objects, default: []

preferred_origin_id

str (ResourceReference), optional

preferred_magnitude_id

str (ResourceReference), optional

preferred_focal_mechanism_id

str (ResourceReference), optional

type

str (EventType), optional

type_certainty

str (EventTypeCertainty), optional

creation_info

CreationInfo, optional

region

str (Region), optional

get_pyrocko_event()[source]

Convert into Pyrocko event object.

Uses preferred origin, magnitude, and moment tensor. If no preferred item is specified, it picks the first from the list and emits a warning.

class EventParameters(**kwargs)[source]

Bases: Object

In the bulletin-type (non real-time) model, this class serves as a container for Event objects.

In the real-time version, it can hold objects of type Event, Origin, Magnitude, StationMagnitude, FocalMechanism, Reading, Amplitude and Pick (real-time mode is not covered by this module at the moment).

public_id

str (ResourceReference)

comment_list

list of Comment objects, default: []

event_list

list of Event objects, default: []

description

str, optional

creation_info

CreationInfo, optional

class QuakeML(**kwargs)[source]

Bases: Object

QuakeML data container.

event_parameters

EventParameters, optional

get_pyrocko_events()[source]

Get event information in Pyrocko’s basic event format.

Return type:

List of pyrocko.model.event.Event objects.

get_pyrocko_phase_markers()[source]

Get pick information in Pyrocko’s basic marker format.

Return type:

List of pyrocko.gui.marker.PhaseMarker objects.

classmethod load_xml(stream=None, filename=None, string=None)[source]

Load QuakeML data from stream, file or string.

Parameters:
  • stream (file-like object, optional) – Stream open for reading in binary mode.

  • filename (str, optional) – Path to file to be opened for reading.

  • string (str, optional) – String with QuakeML data to be deserialized.

The arguments stream, filename, and string are mutually exclusive.

Returns:

Parsed QuakeML data structure.

Return type:

QuakeML object