.. _tutorials_magnitude-region-aliases:

****************************************
Magnitudes: Regionalization, Aliases, Mw
****************************************

You will ...

* Regionalize magnitude
* Create new magnitude types as aliases from other magnitudes and amplitudes.
* Map magnitudes to the moment magnitude, Mw


:Pre-requisites for this tutorial:

  * Read the :ref:`concepts section on magnitudes <concepts_magnitudes>`.
  * Real-time data for the station must be available locally.
    See :ref:`tutorials_waveforms` or :ref:`tutorials_geofon_waveforms`.
  * Inventory must be loaded locally.


:Afterwards/Results/Outcomes:

  * Regionalized magnitudes,
  * New magnitude types as aliases.
  * Moment magnitudes


:Time range estimate:

  * 30 minutes


-----------


.. _tutorials_magnitude-region:

Regionalize Magnitudes
======================

By regionalization, magnitudes can be computed with region-dependent properties.
The procedure to set up magnitude regionalization is:

#. Create one file which contains the polygons surrounding the regions within
   which magnitude parameters shall apply. The polygon files are provided in
   :ref:`BNA <sec-gui_layers-vector-format-bna>` or
   :ref:`GeoJSON format <sec-gui_layers-vector-format-geojson>` and located as
   set out in the :ref:`documentation of map layers <sec-gui_layers>`. The file
   can be created from any |scname| GUI application providing maps, e.g.,
   :ref:`scmv`.
#. For the desired magnitude type create a magnitude-type profile in global
   module configuration. The name of the profile matches the name of the
   magnitude, e.g., *MLc* for the :ref:`MLc magnitude <global_mlc>`.
#. Configure the :confval:`magnitudes.MLc.regionFile` parameter with the full
   path and name of the polygon file created above.
#. Within the magnitude-type profile create one or more magnitude-region
   profile(s) for defining the regionalized parameters applied to the region(s).
   The name of a profile corresponds to the name of the polygon contained in the
   polygon file to which the parameters shall apply. Use *world* for all regions
   not covered by any polygon.
#. Configure the regionalized magnitude parameters of the magnitude-region
   profile. Activate the *enable* parameter if you wish to apply this profile.
#. Restart the data processing:

   .. code-block:: sh

      seiscomp restart

   or execute a GUI module.

.. important::

   * Parameters which can be configured along with regionalization assume
     defaults from global binding parameters but override global bindings
     parameters when configured.
   * Once regionalization is active, magnitudes for events outside the
     defined region(s) will not be computed. For considering such events add
     another magnitude-region profile with the name "*world*".
     Magnitudes for events outside any other magnitude-region profile will then
     be computed according to this profile.


Station corrections
-------------------

:ref:`Magnitude station corrections <concepts-magnitudes-correction>` can also
be applied in case of regionalization. Simply add the names of the
magnitude-region profile along with the correction parameter to the original
parameter in global module configuration, :file:`global.cfg`, for the respective
magnitude type and station. Use comma separation for multiple regions and colon
for separating the region name from the value.

Example for correcting MLv computed at station GE.UGM:

.. code-block:: properties

   module.trunk.GE.UGM.magnitudes.MLv.offset = 0.1, europe:0.2, asia:-0.1

.. note::

   The configuration of parameters starting with *module.trunk.* is not
   supported by :ref:`scconfig`. All corresponding configurations must be done
   by directly editing the configuration file, e.g.,
   :file:`seiscomp/etc/global.cfg`.


.. _tutorials_magnitude-aliases:

Magnitude Aliases
=================

New magnitude types (aliases) can be created based on existing magnitude and
amplitude types but configured specifically.

The procedure to set up magnitude aliases is:

#. Create a magnitude alias in :file:`global.cfg` by configuring
   :confval:`magnitudes.aliases`. Example:

   .. code-block:: properties

      magnitudes.aliases = MLc1:MLc:MLc

#. Configure the alias magnitudes in either way:

   * Write bindings parameters to global module configuration or
   * Set up :ref:`regionalization <tutorials_magnitude-region>`:

   **Binding parameters in global module configuration:**

   #. Read the relevant parameter names of the original magnitude from global
      binding, e.g., in :ref:`scconfig`. The names must include the full
      hierarchy including all sections. Example:

      .. code-block:: properties

         magnitudes.MLc01.parametric.c1

   #. Open the module configuration file, e.g.,
      :file:`seiscomp/etc/global.cfg` in a text editor.

   #. Prepend *module.trunk.global.* to the parameter name and add it along with
      its value to the configuration file. Example:

      .. code-block:: properties

         module.trunk.global.magnitudes.MLc01.parametric.c1 = 0.7

   #. Add the new magnitude name to the configuration of all relevant modules,
      e.g., :ref:`scamp`, :ref:`scmag`, :ref:`scevent`, :ref:`scolv`.

   .. note::

      The parameters starting with *module.trunk.* are not available for
      configuration in :ref:`scconfig`.

   .. warning::

      Binding parameters configured in global module configuration should only
      be considered exceptionally. These parameters will

      * Override the corresponding parameters configured by regionalization
        using the region *world*.
      * Not be written to the database and cannot be accessed by SeisComP
        modules running on other computers.

   **Regionalization:**

   * Consider the tutorial on
     :ref:`magnitude regionalization <tutorials_magnitude-region>` above.
   * For the name of the new magnitude-type profile now use the alias name.

     .. hint::

        When adding the magnitude-region profile in
        :ref:`scconfig`, scconfig does not know about the referenced original
        magnitude. Therefore, not all possible configuration parameters may be
        listed depending on the magnitude, e.g. for MLc. For getting the full
        list, first create and configure a magnitude-region profile for the
        referenced magnitude.

        #. Close scconfig
        #. Open the configuration file :file:`global.cfg`
        #. Rename the name of the referenced magnitude in the parameters to the
           name of the alias.


.. _tutorials_mags_moment:

Moment Magnitudes
=================

All magnitudes, Mx, can be mapped to a moment magnitude, Mw(Mx).
The configuration procedure is:

#. Set up a magnitude-type profile for the original magnitude type in global
   module configuration. Use :ref:`scconfig` for creating the profile.
#. Configure the parameter *MwMapping*, which will become available along with
   the new profile, e.g., :confval:`magnitudes.MLc.MwMapping`. Alternatively,
   add the parameter to :file:`seiscomp/etc/global.cfg`. The parameter is
   configured as a list of sample points of a piecewise linear function mapping
   from the original magnitude, Mx, to Mw(Mx).
   Example for Mw(MLc) based on MLc:


   .. code-block:: properties

      magnitudes.MLc.MwMapping = MLc_0:Mw(MLc)_0,MLc_1:Mw(MLc)_1,...,MLc_N:Mw(MLc)_N

   Any magnitude value outside the configured range is ignored.

   .. warning::

      Do not map the magnitudes :term:`mB <magnitude, broadband body-wave (mB)>`
      and :term:`Mwp <magnitude, broadband P-wave moment (Mwp)>` to Mw since
      this is hardcoded already and done automatically by :ref:`scmag`.

The new moment magnitudes will be available along with the original magnitudes
and can be viewed in :ref:`scolv`or :ref:`scesv` and considered by :ref:`scmag`
or :ref:`scevent`.

In order to avoid that :ref:`summary magnitudes <concepts-magnitudes-summary>`
are computed from original magnitudes and mapped Mw together and biased to both,
the original magnitudes can be blocklisted in :ref:`scmag`
(:confval:`summaryMagnitude.blacklist`).


.. _tutorials_mags_regionalize_testing:

Final Tests
===========

* Regionalization:

  #. Start :ref:`scolv` with the option :option:`--debug` and load an event of
     interest

     .. code-block:: sh

        scolv --debug

  #. Relocate the event for generating a new origin.
  #. Compute magnitudes selecting the magnitude of interest.
  #. Inspect the computed magnitudes in the
     :ref:`Magnitude tab of scolv <scolv-sec-magnitude-tab>` or read the
     debug output listing the considered magnitudes and stations along with
     the regionalized parameters.

* Magnitude aliases:

  #. Start :ref:`scolv` with the option :option:`--debug` and load an event of
     interest

     .. code-block:: sh

        scolv --debug

  #. Relocate the event for generating a new origin.
  #. Compute magnitudes selecting the magnitude of interest including the new
     alias.
  #. Inspect the computed magnitudes in the
     :ref:`Magnitude tab of scolv <scolv-sec-magnitude-tab>` or read the
     debug output listing the considered magnitude names and aliases along with
     the considered parameters and their values. Example where MLc1 is derived
     from MLc with a modified maximum depth:

     .. code-block:: sh

        ...
        13:30:46 [debug] GE.UGM: MLc1: effective correction (no locale) = 1.00:0.00
        13:30:46 [debug] Parameters for magnitude MLc1
        13:30:46 [debug]   + maximum depth: 50.000 km
        13:30:46 [debug]   + distance mode: hypocentral
        13:30:46 [debug]   + minimum distance: -1.000 km
        13:30:46 [debug]   + maximum distance: 889.561 km
        ...