Source code for obspy.core.event.magnitude

# -*- coding: utf-8 -*-
"""
obspy.core.event.magnitude - The Magnitude class definition
===========================================================
This module provides a class hierarchy to consistently handle event metadata.
This class hierarchy is closely modelled after the de-facto standard format
`QuakeML <https://quake.ethz.ch/quakeml/>`_.

.. note::

    For handling additional information not covered by the QuakeML standard and
    how to output it to QuakeML see the :ref:`ObsPy Tutorial <quakeml-extra>`.

:copyright:
    The ObsPy Development Team (devs@obspy.org)
:license:
    GNU Lesser General Public License, Version 3
    (https://www.gnu.org/copyleft/lesser.html)
"""
from obspy import UTCDateTime
from obspy.core.event.base import (
    _event_type_class_factory, CreationInfo,
    WaveformStreamID, TimeWindow)
from obspy.core.event import ResourceIdentifier
from obspy.core.event.header import (
    AmplitudeCategory, AmplitudeUnit, EvaluationMode, EvaluationStatus,
    ATTRIBUTE_HAS_ERRORS)


__Magnitude = _event_type_class_factory(
    "__Magnitude",
    class_attributes=[("resource_id", ResourceIdentifier),
                      ("mag", float, ATTRIBUTE_HAS_ERRORS),
                      ("magnitude_type", str),
                      ("origin_id", ResourceIdentifier),
                      ("method_id", ResourceIdentifier),
                      ("station_count", int),
                      ("azimuthal_gap", float),
                      ("evaluation_mode", EvaluationMode),
                      ("evaluation_status", EvaluationStatus),
                      ("creation_info", CreationInfo)],
    class_contains=["comments", "station_magnitude_contributions"])


[docs]class Magnitude(__Magnitude): """ Describes a magnitude which can, but does not need to be associated with an origin. Association with an origin is expressed with the optional attribute originID. It is either a combination of different magnitude estimations, or it represents the reported magnitude for the given event. :type resource_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier` :param resource_id: Resource identifier of Magnitude. :type force_resource_id: bool, optional :param force_resource_id: If set to False, the automatic initialization of `resource_id` attribute in case it is not specified will be skipped. :type mag: float :param mag: Resulting magnitude value from combining values of type :class:`~obspy.core.event.magnitude.StationMagnitude`. If no estimations are available, this value can represent the reported magnitude. :type mag_errors: :class:`~obspy.core.event.base.QuantityError` :param mag_errors: AttribDict containing error quantities. :type magnitude_type: str, optional :param magnitude_type: Describes the type of magnitude. This is a free-text field because it is impossible to cover all existing magnitude type designations with an enumeration. Possible values are: * unspecified magnitude (``'M'``), * local magnitude (``'ML'``), * body wave magnitude (``'Mb'``), * surface wave magnitude (``'MS'``), * moment magnitude (``'Mw'``), * duration magnitude (``'Md'``) * coda magnitude (``'Mc'``) * ``'MH'``, ``'Mwp'``, ``'M50'``, ``'M100'``, etc. :type origin_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier`, optional :param origin_id: Reference to an origin’s resource_id if the magnitude has an associated Origin. :type method_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier`, optional :param method_id: Identifies the method of magnitude estimation. Users should avoid to give contradictory information in method_id and magnitude_type. :type station_count: int, optional :param station_count: Number of used stations for this magnitude computation. :type azimuthal_gap: float, optional :param azimuthal_gap: Azimuthal gap for this magnitude computation. Unit: deg :type evaluation_mode: str, optional :param evaluation_mode: Evaluation mode of Magnitude. See :class:`~obspy.core.event.header.EvaluationMode` for allowed values. :type evaluation_status: str, optional :param evaluation_status: Evaluation status of Magnitude. See :class:`~obspy.core.event.header.EvaluationStatus` for allowed values. :type comments: list of :class:`~obspy.core.event.base.Comment`, optional :param comments: Additional comments. :type station_magnitude_contributions: list of :class:`~obspy.core.event.magnitude.StationMagnitudeContribution`. :param station_magnitude_contributions: StationMagnitudeContribution instances associated with the Magnitude. :type creation_info: :class:`~obspy.core.event.base.CreationInfo`, optional :param creation_info: Creation information used to describe author, version, and creation time. .. note:: For handling additional information not covered by the QuakeML standard and how to output it to QuakeML see the :ref:`ObsPy Tutorial <quakeml-extra>`. """
__StationMagnitude = _event_type_class_factory( "__StationMagnitude", class_attributes=[("resource_id", ResourceIdentifier), ("origin_id", ResourceIdentifier), ("mag", float, ATTRIBUTE_HAS_ERRORS), ("station_magnitude_type", str), ("amplitude_id", ResourceIdentifier), ("method_id", ResourceIdentifier), ("waveform_id", WaveformStreamID), ("creation_info", CreationInfo)], class_contains=["comments"])
[docs]class StationMagnitude(__StationMagnitude): """ This class describes the magnitude derived from a single waveform stream. :type resource_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier` :param resource_id: Resource identifier of StationMagnitude. :type force_resource_id: bool, optional :param force_resource_id: If set to False, the automatic initialization of `resource_id` attribute in case it is not specified will be skipped. :type origin_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier` :param origin_id: Reference to an origin’s ``resource_id`` if the StationMagnitude has an associated :class:`~obspy.core.event.origin.Origin`. :type mag: float :param mag: Estimated magnitude. :type mag_errors: :class:`~obspy.core.event.base.QuantityError` :param mag_errors: AttribDict containing error quantities. :type station_magnitude_type: str, optional :param station_magnitude_type: See :class:`~obspy.core.event.magnitude.Magnitude` :type amplitude_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier` :param amplitude_id: Identifies the data source of the StationMagnitude. For magnitudes derived from amplitudes in waveforms (e.g., local magnitude ML), amplitudeID points to publicID in class Amplitude. :type method_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier` :param method_id: See :class:`~obspy.core.event.magnitude.Magnitude` :type waveform_id: :class:`~obspy.core.event.base.WaveformStreamID`, optional :param waveform_id: Identifies the waveform stream. This element can be helpful if no amplitude is referenced, or the amplitude is not available in the context. Otherwise, it would duplicate the waveform_id provided there and can be omitted. :type comments: list of :class:`~obspy.core.event.base.Comment`, optional :param comments: Additional comments. :type creation_info: :class:`~obspy.core.event.base.CreationInfo`, optional :param creation_info: Creation information used to describe author, version, and creation time. .. note:: For handling additional information not covered by the QuakeML standard and how to output it to QuakeML see the :ref:`ObsPy Tutorial <quakeml-extra>`. """
__StationMagnitudeContribution = _event_type_class_factory( "__StationMagnitudeContribution", class_attributes=[("station_magnitude_id", ResourceIdentifier), ("residual", float), ("weight", float)])
[docs]class StationMagnitudeContribution(__StationMagnitudeContribution): """ This class describes the weighting of magnitude values from several StationMagnitude objects for computing a network magnitude estimation. :type station_magnitude_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier` :param station_magnitude_id: Refers to the resource_id of a StationMagnitude object. :type residual: float, optional :param residual: Residual of magnitude computation. :type weight: float, optional :param weight: Weight of the magnitude value from class StationMagnitude for computing the magnitude value in class Magnitude. Note that there is no rule for the sum of the weights of all station magnitude contributions to a specific network magnitude. In particular, the weights are not required to sum up to unity. .. note:: For handling additional information not covered by the QuakeML standard and how to output it to QuakeML see the :ref:`ObsPy Tutorial <quakeml-extra>`. """
__Amplitude = _event_type_class_factory( "__Amplitude", class_attributes=[("resource_id", ResourceIdentifier), ("generic_amplitude", float, ATTRIBUTE_HAS_ERRORS), ("type", str), ("category", AmplitudeCategory), ("unit", AmplitudeUnit), ("method_id", ResourceIdentifier), ("period", float, ATTRIBUTE_HAS_ERRORS), ("snr", float), ("time_window", TimeWindow), ("pick_id", ResourceIdentifier), ("waveform_id", WaveformStreamID), ("filter_id", ResourceIdentifier), ("scaling_time", UTCDateTime, ATTRIBUTE_HAS_ERRORS), ("magnitude_hint", str), ("evaluation_mode", EvaluationMode), ("evaluation_status", EvaluationStatus), ("creation_info", CreationInfo)], class_contains=["comments"])
[docs]class Amplitude(__Amplitude): """ This class represents a quantification of the waveform anomaly, usually a single amplitude measurement or a measurement of the visible signal duration for duration magnitudes. :type resource_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier` :param resource_id: Resource identifier of Amplitude. :type force_resource_id: bool, optional :param force_resource_id: If set to False, the automatic initialization of `resource_id` attribute in case it is not specified will be skipped. :type generic_amplitude: float :param generic_amplitude: Measured amplitude value for the given waveformID. Note that this attribute can describe different physical quantities, depending on the type and category of the amplitude. These can be, e.g., displacement, velocity, or a period. If the only amplitude information is a period, it has to specified here, not in the period attribute. The latter can be used if the amplitude measurement contains information on, e.g., displacement and an additional period. Since the physical quantity described by this attribute is not fixed, the unit of measurement cannot be defined in advance. However, the quantity has to be specified in SI base units. The enumeration given in attribute unit provides the most likely units that could be needed here. For clarity, using the optional unit attribute is highly encouraged. :type generic_amplitude_errors: :class:`~obspy.core.event.base.QuantityError` :param generic_amplitude_errors: AttribDict containing error quantities. :type type: str, optional :param type: Describes the type of amplitude using the nomenclature from Storchak et al. (2003). Possible values are: * unspecified amplitude reading (``'A'``), * amplitude reading for local magnitude (``'AML'``), * amplitude reading for body wave magnitude (``'AMB'``), * amplitude reading for surface wave magnitude (``'AMS'``), and * time of visible end of record for duration magnitude (``'END'``). :type category: str, optional :param category: Amplitude category. This attribute describes the way the waveform trace is evaluated to derive 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). See :class:`~obspy.core.event.header.AmplitudeCategory` for allowed values. :type unit: str, optional :param unit: Amplitude unit. This attribute provides the most likely measurement units for the physical quantity described in the genericAmplitude attribute. Possible values are specified as combinations of SI base units. See :class:`~obspy.core.event.header.AmplitudeUnit` for allowed values. :type method_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier` :param method_id: Describes the method of amplitude determination. :type period: float, optional :param period: Dominant period in the timeWindow in case of amplitude measurements. Not used for duration magnitude. Unit: s :type snr: float, optional :param snr: Signal-to-noise ratio of the spectrogram at the location the amplitude was measured. :type time_window: :class:`~obspy.core.event.base.TimeWindow`, optional :param time_window: Description of the time window used for amplitude measurement. Recommended for duration magnitudes. :type pick_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier` :param pick_id: Refers to the ``resource_id`` of an associated :class:`~obspy.core.event.origin.Pick` object. :type waveform_id: :class:`~obspy.core.event.base.WaveformStreamID`, :param waveform_id: Identifies the waveform stream on which the amplitude was measured. :type filter_id: :class:`~obspy.core.event.resourceid.ResourceIdentifier` :param filter_id: Identifies the filter or filter setup used for filtering the waveform stream referenced by ``waveform_id``. :type scaling_time: :class:`~obspy.core.utcdatetime.UTCDateTime`, optional :param scaling_time: Scaling time for amplitude measurement. :type scaling_time_errors: :class:`~obspy.core.event.base.QuantityError` :param scaling_time_errors: AttribDict containing error quantities. :type magnitude_hint: str, optional :param magnitude_hint: Type of magnitude the amplitude measurement is used for. This is a free-text field because it is impossible to cover all existing magnitude type designations with an enumeration. Possible values are: * unspecified magnitude (``'M'``), * local magnitude (``'ML'``), * body wave magnitude (``'Mb'``), * surface wave magnitude (``'MS'``), * moment magnitude (``'Mw'``), * duration magnitude (``'Md'``) * coda magnitude (``'Mc'``) * ``'MH'``, ``'Mwp'``, ``'M50'``, ``'M100'``, etc. :type evaluation_mode: str, optional :param evaluation_mode: Evaluation mode of Amplitude. See :class:`~obspy.core.event.header.EvaluationMode` for allowed values. :type evaluation_status: str, optional :param evaluation_status: Evaluation status of Amplitude. See :class:`~obspy.core.event.header.EvaluationStatus` for allowed values. :type comments: list of :class:`~obspy.core.event.base.Comment`, optional :param comments: Additional comments. :type creation_info: :class:`~obspy.core.event.base.CreationInfo`, optional :param creation_info: CreationInfo for the Amplitude object. .. note:: For handling additional information not covered by the QuakeML standard and how to output it to QuakeML see the :ref:`ObsPy Tutorial <quakeml-extra>`. """
if __name__ == '__main__': import doctest doctest.testmod(exclude_empty=True)