|
|
.. highlight:: rst
|
|
|
|
|
|
.. _scmag:
|
|
|
|
|
|
#####
|
|
|
scmag
|
|
|
#####
|
|
|
|
|
|
**Calculates magnitudes of different types.**
|
|
|
|
|
|
|
|
|
Description
|
|
|
===========
|
|
|
|
|
|
The purpose of scmag is to compute magnitudes from pre-computed amplitudes.
|
|
|
Instead it takes amplitudes and origins as input and produces StationMagnitudes
|
|
|
and (network) Magnitudes as output. It does not access waveforms.
|
|
|
The resulting magnitudes are sent to the "MAGNITUDE" group. scmag doesn’t access
|
|
|
any waveforms. It only uses amplitudes previously calculated.
|
|
|
|
|
|
The purpose of scmag is the decoupling of magnitude computation from amplitude
|
|
|
measurements. This allows several modules to generate amplitudes concurrently,
|
|
|
like :ref:`scautopick` or :ref:`scamp`. As soon as an origin comes in, the amplitudes related
|
|
|
to the picks are taken either from the memory buffer or the database to compute
|
|
|
the magnitudes.
|
|
|
|
|
|
|
|
|
Relationship between amplitudes and origins
|
|
|
-------------------------------------------
|
|
|
|
|
|
scmag makes use of the fact that origins sent by :ref:`scautoloc`, :ref:`scolv`
|
|
|
or other modules include
|
|
|
the complete set of arrivals, which reference picks used for origin computation.
|
|
|
The picks in turn are referenced by a number of amplitudes, some of which are
|
|
|
relevant for magnitude computation.
|
|
|
|
|
|
Read the :ref:`scamp` documentation for more details on amplitude measurements.
|
|
|
|
|
|
|
|
|
.. _scmag-primaryM:
|
|
|
|
|
|
Primary magnitudes
|
|
|
------------------
|
|
|
|
|
|
Primary magnitudes are computed from amplitudes and station-event distances.
|
|
|
Currently the following primary magnitude types are implemented.
|
|
|
|
|
|
|
|
|
Local distances
|
|
|
---------------
|
|
|
|
|
|
:term:`Md <magnitude, duration (Md)>`
|
|
|
Duration magnitude as described in HYPOINVERSE (:cite:t:`klein-2002`).
|
|
|
|
|
|
:term:`Mjma <magnitude, JMA (M_JMA)>`
|
|
|
Mjma is computed on displacement data using body waves of period < 30s.
|
|
|
|
|
|
:term:`ML <magnitude, local (ML)>`
|
|
|
Local (Richter) magnitude calculated on the horizontal components using a
|
|
|
correction term to fit with the standard ML (:cite:t:`richter-1935`).
|
|
|
|
|
|
:term:`MLc <magnitude, local custom (MLc)>`
|
|
|
Local custom magnitude calculated on the horizontal components according to
|
|
|
Hessian Earthquake Service and :cite:t:`stange-2006`
|
|
|
|
|
|
:term:`MLh <magnitude, local horizontal (MLh)>`
|
|
|
Local magnitude calculated on the horizontal components according to SED
|
|
|
specifications.
|
|
|
|
|
|
:term:`MLv <magnitude, local vertical (MLv)>`
|
|
|
Local magnitude calculated on the vertical component using a correction term
|
|
|
to fit with the standard ML.
|
|
|
|
|
|
:term:`MLr <magnitude, local GNS/GEONET (MLr)>`
|
|
|
Local magnitude calculated from MLv amplitudes based on GNS/GEONET specifications
|
|
|
for New Zealand (:cite:t:`ristau-2016`).
|
|
|
|
|
|
:term:`MN <magnitude, Nuttli (MN)>`
|
|
|
Nuttli magnitude for Canada and other Cratonic regions (:cite:t:`nuttli-1973`).
|
|
|
|
|
|
|
|
|
Teleseismic distances
|
|
|
---------------------
|
|
|
|
|
|
:term:`mb <magnitude, body-wave (mb)>`
|
|
|
Narrow band body wave magnitude measured on a WWSSN-SP filtered trace
|
|
|
|
|
|
:term:`mBc <magnitude, cumulative body-wave (mBc)>`
|
|
|
Cumulative body wave magnitude
|
|
|
|
|
|
:term:`mB <magnitude, broadband body-wave (mB)>`
|
|
|
Broad band body wave magnitude after :cite:t:`bormann-2008`
|
|
|
|
|
|
:term:`Mwp <magnitude, broadband P-wave moment (Mwp)>`
|
|
|
The body wave magnitude of :cite:t:`tsuboi-1995`
|
|
|
|
|
|
:term:`Ms_20 <magnitude, surface wave (Ms_20)>`
|
|
|
Surface-wave magnitude at 20 s period
|
|
|
|
|
|
:term:`Ms(BB) <magnitude, broadband surface wave (Ms(BB))>`
|
|
|
Broad band surface-wave magnitude
|
|
|
|
|
|
|
|
|
Derived magnitudes
|
|
|
------------------
|
|
|
|
|
|
Additionally, scmag derives the following magnitudes from primary magnitudes:
|
|
|
|
|
|
:term:`Mw(mB) <magnitude, derived mB (Mw(mB))>`
|
|
|
Estimation of the moment magnitude Mw based on mB using the Mw vs. mB
|
|
|
regression of :cite:t:`bormann-2008`
|
|
|
|
|
|
:term:`Mw(Mwp) <magnitude, derived Mwp (Mw(Mwp))>`
|
|
|
Estimation of the moment magnitude Mw based on Mwp using the Mw vs. Mwp
|
|
|
regression of :cite:t:`whitmore-2002`
|
|
|
|
|
|
:term:`M <magnitude, summary (M)>`
|
|
|
Summary magnitude, which consists of a weighted average of the individual
|
|
|
magnitudes and attempts to be a best possible compromise between all magnitudes.
|
|
|
See below for configuration and also scevent for how to add the summary magnitude
|
|
|
to the list of possible preferred magnitudes or how to make it always preferred.
|
|
|
|
|
|
More details are given in the :ref:`section Summary magnitude<scmag-summaryM>`.
|
|
|
|
|
|
Mw(avg)
|
|
|
Estimation of the moment magnitude Mw based on a weighted average of other
|
|
|
magnitudes, currently MLv, mb and Mw(mB), in future possibly other magnitudes as
|
|
|
well, especially those suitable for very large events. The purpose of Mw(avg) is
|
|
|
to have, at any stage during the processing, a “best possible” estimation of the
|
|
|
magnitude by combining all available magnitudes into a single, weighted average.
|
|
|
Initially the average will consist of only MLv and/or mb measurements, but as soon
|
|
|
as Mw(mB) measurements become available, these (and in future other large-event
|
|
|
magnitudes) become progressively more weight in the average.
|
|
|
|
|
|
If an amplitude is updated, the corresponding magnitude is updated as well.
|
|
|
This allows the computation of preliminary, real-time magnitudes even before
|
|
|
the full length of the P coda is available.
|
|
|
|
|
|
|
|
|
.. _scmag-stationM:
|
|
|
|
|
|
Station magnitudes
|
|
|
==================
|
|
|
|
|
|
Station magnitudes of a :ref:`particular magnitude type <scmag-primaryM>` are
|
|
|
calculated based on amplitude values
|
|
|
considered by this magnitude type and the distance between the event and the station
|
|
|
at which the amplitude was measured. Typically, epicentral distance is used.
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
Usually station magnitudes use amplitudes of the same type. However, some magnitude
|
|
|
consider amplitudes of another type. E.g. :term:`MLr <magnitude, local GNS/GEONET (MLr)>`
|
|
|
uses amplitudes computed for :term:`MLv <magnitude, local vertical (MLv)>`.
|
|
|
|
|
|
|
|
|
.. _scmag-networkM:
|
|
|
|
|
|
Network magnitudes
|
|
|
==================
|
|
|
|
|
|
The network magnitude is a magnitude value summarizing several :ref:`station magnitudes <scmag-stationM>`
|
|
|
values of one :term:`origin`.
|
|
|
Different methods are available for summarizing the station magnitudes:
|
|
|
|
|
|
* mean: the usual mean value
|
|
|
* trimmed mean value:
|
|
|
To stabilize the network magnitudes the smallest and the largest 12.5% of the
|
|
|
:term:`station magnitude` values are removed before computing the mean.
|
|
|
* median: the usual median value
|
|
|
* median trimmed mean:
|
|
|
Removing all station magnitudes with a distance greater than 0.5 (default)
|
|
|
from the median of all station magnitudes and computing the mean of all
|
|
|
remaining station magnitudes.
|
|
|
|
|
|
Default values apply for each magnitude type.
|
|
|
In :ref:`scolv` the methods, the stations magnitudes and other parameters can be
|
|
|
selected interactively.
|
|
|
|
|
|
|
|
|
.. _scmag-summaryM:
|
|
|
|
|
|
Summary magnitude
|
|
|
=================
|
|
|
|
|
|
scmag can compute a summary magnitude as a weighted sum from all available
|
|
|
:ref:`network magnitudes <scmag-networkM>`.
|
|
|
This magnitude is typically called **M** as configured in
|
|
|
:confval:`summaryMagnitude.type`.
|
|
|
|
|
|
It is computed as a weighted average over the available magnitudes:
|
|
|
|
|
|
.. math::
|
|
|
|
|
|
M = \frac{\sum w_{i} M_{i}}{\sum w_i}
|
|
|
|
|
|
w_{i} = a_i stationCount(M_{i}) + b_i
|
|
|
|
|
|
The coefficients a and b can be configured per magnitude type by
|
|
|
:confval:`summaryMagnitude.coefficients.a`
|
|
|
and :confval:`summaryMagnitude.coefficients.b`, respectively.
|
|
|
Furthermore each magnitude type can be specifically added to or excluded from the
|
|
|
summary magnitude calculation
|
|
|
as defined in :confval:`summaryMagnitude.whitelist` or
|
|
|
:confval:`summaryMagnitude.blacklist`, respectively.
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
While the magnitudes are computed by scmag the decision about the preferred
|
|
|
magnitude of an :term:`event` is made by :ref:`scevent`.
|
|
|
|
|
|
|
|
|
Preferred Magnitude
|
|
|
===================
|
|
|
|
|
|
The preferred magnitude of an :term:`event` is set automatically by :ref:`scevent`
|
|
|
or interactively in :ref:`scolv`. It can be any network magnitude or the summary
|
|
|
magnitude.
|
|
|
|
|
|
|
|
|
.. _scmag_configuration:
|
|
|
|
|
|
Module Configuration
|
|
|
====================
|
|
|
|
|
|
| :file:`etc/defaults/global.cfg`
|
|
|
| :file:`etc/defaults/scmag.cfg`
|
|
|
| :file:`etc/global.cfg`
|
|
|
| :file:`etc/scmag.cfg`
|
|
|
| :file:`~/.seiscomp/global.cfg`
|
|
|
| :file:`~/.seiscomp/scmag.cfg`
|
|
|
|
|
|
scmag inherits :ref:`global options<global-configuration>`.
|
|
|
|
|
|
|
|
|
|
|
|
.. confval:: magnitudes
|
|
|
|
|
|
Default: ``MLv, mb, mB, Mwp``
|
|
|
|
|
|
Type: *list:string*
|
|
|
|
|
|
The magnitude types to be calculated. Station magnitudes are
|
|
|
computed from their amplitudes, network magnitudes from their
|
|
|
station magnitudes.
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
**magnitudes.\***
|
|
|
*General parameters for computing magnitudes. Others are configured*
|
|
|
*by global binding parameters for specific magnitude types.*
|
|
|
|
|
|
|
|
|
|
|
|
.. confval:: magnitudes.average
|
|
|
|
|
|
Default: ``default``
|
|
|
|
|
|
Type: *list:string*
|
|
|
|
|
|
The methods for computing the network magnitude
|
|
|
from station magnitudes. Exactly one method per
|
|
|
magnitude can be configured.
|
|
|
To define the averaging method per magnitude type append
|
|
|
the type after colon, e.g.:
|
|
|
\"magnitudes.average \= default, MLv:median\"
|
|
|
|
|
|
default: Compute the mean if less than 4 contributed
|
|
|
station magnitudes exist. Otherwise apply a trimmed mean
|
|
|
of 25%.
|
|
|
|
|
|
Options are \"default\", \"mean\",
|
|
|
\"median\", \"trimmedMean\" and
|
|
|
\"medianTrimmedMean\".
|
|
|
|
|
|
|
|
|
.. confval:: connection.sendInterval
|
|
|
|
|
|
Default: ``1``
|
|
|
|
|
|
Type: *int*
|
|
|
|
|
|
Unit: *s*
|
|
|
|
|
|
Interval between 2 sending processes. The interval controls
|
|
|
how often information is updated.
|
|
|
|
|
|
|
|
|
.. confval:: connection.minimumArrivalWeight
|
|
|
|
|
|
Default: ``0.5``
|
|
|
|
|
|
Type: *double*
|
|
|
|
|
|
The minimum weight of an arrival for an associated amplitude
|
|
|
to be used for calculating a magnitude.
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
**summaryMagnitude.\***
|
|
|
*The summary magnitude is the weighted average from all*
|
|
|
*defined network magnitude types: Single network magnitude values*
|
|
|
*are multiplied with their magnitude-type specific weight and*
|
|
|
*summed up. The resulting sum is divided by the sum of all weights.*
|
|
|
|
|
|
|
|
|
|
|
|
.. confval:: summaryMagnitude.enabled
|
|
|
|
|
|
Default: ``true``
|
|
|
|
|
|
Type: *boolean*
|
|
|
|
|
|
Enables summary magnitude calculation.
|
|
|
|
|
|
|
|
|
.. confval:: summaryMagnitude.type
|
|
|
|
|
|
Default: ``M``
|
|
|
|
|
|
Type: *string*
|
|
|
|
|
|
Define the type\/name of the summary magnitude.
|
|
|
|
|
|
|
|
|
.. confval:: summaryMagnitude.minStationCount
|
|
|
|
|
|
Default: ``4``
|
|
|
|
|
|
Type: *int*
|
|
|
|
|
|
This is the minimum station magnitude required for any
|
|
|
magnitude to contribute to the summary magnitude at all. If
|
|
|
this is set to 4, then no magnitude with less than 4 station
|
|
|
magnitudes is taken into consideration even if this results
|
|
|
in no summary magnitude at all. For this reason, the default
|
|
|
here is 1 but in a purely automatic system it should be
|
|
|
higher, at least 4 is recommended.
|
|
|
|
|
|
|
|
|
.. confval:: summaryMagnitude.blacklist
|
|
|
|
|
|
Type: *list:string*
|
|
|
|
|
|
Define the magnitude types to be excluded from the summary
|
|
|
magnitude calculation.
|
|
|
|
|
|
|
|
|
.. confval:: summaryMagnitude.whitelist
|
|
|
|
|
|
Type: *list:string*
|
|
|
|
|
|
Define the magnitude types to be included in the summary
|
|
|
magnitude calculation.
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
**summaryMagnitude.coefficients.\***
|
|
|
*The coefficients defining the weight of network magnitudes*
|
|
|
*for calculating the summary magnitude.*
|
|
|
*Weight = a * magnitudeStationCount + b.*
|
|
|
|
|
|
|
|
|
|
|
|
.. confval:: summaryMagnitude.coefficients.a
|
|
|
|
|
|
Default: ``0, Mw(mB):0.4, Mw(Mwp):0.4``
|
|
|
|
|
|
Type: *list:string*
|
|
|
|
|
|
Define the coefficients a. To define the value per magnitude
|
|
|
type append the type after colon. A value without a
|
|
|
type defines the default value.
|
|
|
|
|
|
|
|
|
.. confval:: summaryMagnitude.coefficients.b
|
|
|
|
|
|
Default: ``1, MLv:2, Mw(mB):-1, Mw(Mwp):-1``
|
|
|
|
|
|
Type: *list:string*
|
|
|
|
|
|
Define the coefficients b. To define the value per magnitude
|
|
|
type append the type after colon. A value without a
|
|
|
type defines the default value.
|
|
|
|
|
|
|
|
|
|
|
|
Command-Line Options
|
|
|
====================
|
|
|
|
|
|
.. program:: scmag
|
|
|
|
|
|
|
|
|
Generic
|
|
|
-------
|
|
|
|
|
|
.. option:: -h, --help
|
|
|
|
|
|
Show help message.
|
|
|
|
|
|
.. option:: -V, --version
|
|
|
|
|
|
Show version information.
|
|
|
|
|
|
.. option:: --config-file arg
|
|
|
|
|
|
Use alternative configuration file. When this option is
|
|
|
used the loading of all stages is disabled. Only the
|
|
|
given configuration file is parsed and used. To use
|
|
|
another name for the configuration create a symbolic
|
|
|
link of the application or copy it. Example:
|
|
|
scautopick \-> scautopick2.
|
|
|
|
|
|
.. option:: --plugins arg
|
|
|
|
|
|
Load given plugins.
|
|
|
|
|
|
.. option:: -D, --daemon
|
|
|
|
|
|
Run as daemon. This means the application will fork itself
|
|
|
and doesn't need to be started with \&.
|
|
|
|
|
|
.. option:: --auto-shutdown arg
|
|
|
|
|
|
Enable\/disable self\-shutdown because a master module shutdown.
|
|
|
This only works when messaging is enabled and the master
|
|
|
module sends a shutdown message \(enabled with \-\-start\-stop\-msg
|
|
|
for the master module\).
|
|
|
|
|
|
.. option:: --shutdown-master-module arg
|
|
|
|
|
|
Set the name of the master\-module used for auto\-shutdown.
|
|
|
This is the application name of the module actually
|
|
|
started. If symlinks are used, then it is the name of
|
|
|
the symlinked application.
|
|
|
|
|
|
.. option:: --shutdown-master-username arg
|
|
|
|
|
|
Set the name of the master\-username of the messaging
|
|
|
used for auto\-shutdown. If \"shutdown\-master\-module\" is
|
|
|
given as well, this parameter is ignored.
|
|
|
|
|
|
.. option:: -x, --expiry time
|
|
|
|
|
|
Time span in hours after which objects expire.
|
|
|
|
|
|
|
|
|
Verbosity
|
|
|
---------
|
|
|
|
|
|
.. option:: --verbosity arg
|
|
|
|
|
|
Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info,
|
|
|
4:debug.
|
|
|
|
|
|
.. option:: -v, --v
|
|
|
|
|
|
Increase verbosity level \(may be repeated, eg. \-vv\).
|
|
|
|
|
|
.. option:: -q, --quiet
|
|
|
|
|
|
Quiet mode: no logging output.
|
|
|
|
|
|
.. option:: --component arg
|
|
|
|
|
|
Limit the logging to a certain component. This option can
|
|
|
be given more than once.
|
|
|
|
|
|
.. option:: -s, --syslog
|
|
|
|
|
|
Use syslog logging backend. The output usually goes to
|
|
|
\/var\/lib\/messages.
|
|
|
|
|
|
.. option:: -l, --lockfile arg
|
|
|
|
|
|
Path to lock file.
|
|
|
|
|
|
.. option:: --console arg
|
|
|
|
|
|
Send log output to stdout.
|
|
|
|
|
|
.. option:: --debug
|
|
|
|
|
|
Execute in debug mode.
|
|
|
Equivalent to \-\-verbosity\=4 \-\-console\=1 .
|
|
|
|
|
|
.. option:: --log-file arg
|
|
|
|
|
|
Use alternative log file.
|
|
|
|
|
|
|
|
|
Messaging
|
|
|
---------
|
|
|
|
|
|
.. option:: -u, --user arg
|
|
|
|
|
|
Overrides configuration parameter :confval:`connection.username`.
|
|
|
|
|
|
.. option:: -H, --host arg
|
|
|
|
|
|
Overrides configuration parameter :confval:`connection.server`.
|
|
|
|
|
|
.. option:: -t, --timeout arg
|
|
|
|
|
|
Overrides configuration parameter :confval:`connection.timeout`.
|
|
|
|
|
|
.. option:: -g, --primary-group arg
|
|
|
|
|
|
Overrides configuration parameter :confval:`connection.primaryGroup`.
|
|
|
|
|
|
.. option:: -S, --subscribe-group arg
|
|
|
|
|
|
A group to subscribe to.
|
|
|
This option can be given more than once.
|
|
|
|
|
|
.. option:: --content-type arg
|
|
|
|
|
|
Overrides configuration parameter :confval:`connection.contentType`.
|
|
|
|
|
|
.. option:: --start-stop-msg arg
|
|
|
|
|
|
Set sending of a start and a stop message.
|
|
|
|
|
|
|
|
|
Database
|
|
|
--------
|
|
|
|
|
|
.. option:: --db-driver-list
|
|
|
|
|
|
List all supported database drivers.
|
|
|
|
|
|
.. option:: -d, --database arg
|
|
|
|
|
|
The database connection string, format:
|
|
|
service:\/\/user:pwd\@host\/database.
|
|
|
\"service\" is the name of the database driver which
|
|
|
can be queried with \"\-\-db\-driver\-list\".
|
|
|
|
|
|
.. option:: --config-module arg
|
|
|
|
|
|
The config module to use.
|
|
|
|
|
|
.. option:: --inventory-db arg
|
|
|
|
|
|
Load the inventory from the given database or file, format:
|
|
|
[service:\/\/]location .
|
|
|
|
|
|
.. option:: --db-disable
|
|
|
|
|
|
Do not use the database at all
|
|
|
|
|
|
|
|
|
Input
|
|
|
-----
|
|
|
|
|
|
.. option:: --ep file
|
|
|
|
|
|
Defines an event parameters XML file to be read and processed. This
|
|
|
implies offline mode and only processes all origins contained
|
|
|
in that file. It computes station magnitudes for all picks associated
|
|
|
with an origin where amplitudes are available and the corresponding
|
|
|
network magnitudes. Station and network magnitudes having the
|
|
|
evaluation status set are ignored. Use the \-\-force to include those
|
|
|
magnitudes. It outputs an XML text adding the station\-
|
|
|
and network magnitudes to the input XML file.
|
|
|
|
|
|
.. option:: --reprocess
|
|
|
|
|
|
Reprocess also station and network magnitudes with an evaluation
|
|
|
status set but do not change original weights. New
|
|
|
contributions are added with weight 0.
|
|
|
|
|
|
|
|
|
Reprocess
|
|
|
---------
|
|
|
|
|
|
.. option:: --static
|
|
|
|
|
|
With that flag all existing station magnitudes are recomputed
|
|
|
based on their associated amplitudes. If an amplitude cannot
|
|
|
be accessed, no station magnitude is updated.
|
|
|
Network magnitudes are recomputed based on their station
|
|
|
magnitude contributions. No new objects will
|
|
|
be created in this mode, it only updates values and weights.
|
|
|
The method to accumulate the station magnitudes to form the network
|
|
|
magnitude will be read from the existing object and replicated.
|
|
|
If it cannot be interpreted then the configured default for this
|
|
|
magnitude type will be used instead. Weights of station magnitudes
|
|
|
will be changed according to the accumulation method of the
|
|
|
network magnitude.
|
|
|
|
|
|
.. option:: --keep-weights
|
|
|
|
|
|
Keep the original weights in combination with \-\-static.
|
|
|
|