.. 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 measured amplitudes considered by this magnitude type and
the distance between the :term:`origin` and the station at which the amplitude
was measured. Typically, epicentral distance is used for distance. Magnitudes
may support configurable distance measures, e.g.,
:term:`MLc <magnitude, local custom (MLc)>`. The relation between measured
amplitudes, distance and station magnitude is given by a calibration function
which is specific to a magnitude type and configurable for some magnitudes.

.. 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)>`.


Regionalization
---------------

Depending on the geographic region in which events, stations or entire ray paths
are located, different calibration functions and constraints may apply. This is
called "magnitude regionalization". The region is defined by a polygon stored in
a region file. For a particular magnitude, regionalization can be configured by
global parameters, e.g., in :file:`$SEISCOMP_ROOT/etc/global.cfg`.

#. Add magnitude type profile to the magnitudes parameters. The name of the
   profile must be the name of the magnitude type.
#. Add the profile-specific parameters.

Example for MLc in :file:`$SEISCOMP_ROOT/etc/global.cfg` the polygon with name
*test* defined in a :ref:`BNA file <sec-gui_layers-vector>`:

.. code-block:: properties

   magnitudes.MLc.regionFile = @DATADIR@/spatial/vector/magnitudes/regions.bna
   magnitudes.MLc.region.test.enable = true
   magnitudes.MLc.region.test.A0.logA0 = 0:-1.3, 60:-2.8, 100:-3.0, 400:-4.5, 1000:-5.85


.. _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 forming network magnitudes from station
magnitudes:

.. csv-table::
   :header: Method, Description
   :widths: 20 80
   :align: left
   :delim: ;

   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.

Configure the method per magnitude type by :confval:`magnitudes.average`.
Default values apply for each magnitude type which are defined by the magnitude
itself.
In the :ref:`scolv Magnitudes tab <scolv-sec-magnitude-tab>` 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.


.. confval:: minimumArrivalWeight

   Default: ``0.5``

   Type: *double*

   The minimum weight of an arrival for an associated amplitude
   to be used for calculating a magnitude.


.. 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*

   Values: ``*default,*mean,*median,*trimmedMean(*),*trimmedMedian(*),*medianTrimmedMean(*)``

   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. Example:
   
   \"magnitudes.average \= default, MLv:median\"
   
   default: Compute the mean if less than 4 contributed station
   magnitudes exist. Otherwise apply trimmedMean\(25\), trimmed
   mean with 25%.


.. confval:: connection.sendInterval

   Default: ``1``

   Type: *int*

   Unit: *s*

   Interval between 2 sending processes. The interval controls
   how often information is updated.


.. 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: ``1``

   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.singleton

   Default: ``true``

   Type: *boolean*

   Allow computing the summary magnitude even if only one single
   network magnitude meeting the other criteria is available.
   Unselecting this parameter will suppress computing summary
   magnitudes if only one network magnitude is available.


.. 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 file

   The alternative module configuration file. When this option
   is used, the module configuration is only read from the
   given file and no other configuration stage is considered.
   Therefore, all configuration including the definition of
   plugins must be contained in that file or given along with
   other command\-line options such as \-\-plugins.

.. 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, e.g., \-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`.

   Default: ``binary``


.. option:: --start-stop-msg arg

   Default: ``0``

   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

   Type: *string*

   Defines an event parameters XML file to be read and
   processed. Use '\-' to read from stdin. 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 \-\-reprocess 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.


Output
------

.. option:: -f, --formatted

   Use formatted XML output along with '\-\-ep'. Otherwise XML
   is unformatted.

