[installation] Init with inital config for global

share/doc/seiscomp/html/_sources/base/concepts/magnitudes.rst.txt

@@ -0,0 +1,175 @@
+.. _concepts_magnitudes:
+
+Magnitudes
+##########
+
+Magnitudes are computed based on amplitudes measured from waveforms. Different
+types of amplitudes and magnitudes are available which are listed in
+:ref:`scamp` and :ref:`scmag`.
+
+
+Amplitudes
+==========
+
+Amplitudes can be measured automatically from waveforms
+
+* During phase picking by :ref:`scautopick` with generally fixed time windows
+  due to the absence of knowledge about source parameters or by,
+* :ref:`scamp` as soon as :term:`origins <origin>` are available. Depending
+  on the magnitude type, fixed or distance-dependent time windows apply.
+
+and interactively using :ref:`scolv`.
+
+
+Instrument simulation
+---------------------
+
+Amplitude measurements for some magnitude types require or allow the simulation
+of instruments such as :py:func:`Wood-Anderson torsion seismometers <WA>`
+(:cite:t:`richter-1935,uhrhammer-1990`), :py:func:`WWSSN_SP` or :py:func:`WWSSN_LP`.
+The calibration parameters describing the Wood-Anderson seismometer are
+configurable in global bindings or global module configuration:
+:confval:`amplitudes.WoodAnderson.gain`, :confval:`amplitudes.WoodAnderson.T0`,
+:confval:`amplitudes.WoodAnderson.h`. Specifically, the difference in magnitude
+due to configuration using original values listed in
+:cite:t:`richter-1935` and updated ones given in :cite:t:`uhrhammer-1990`
+result in a constant offset of 0.13 in those magnitudes which apply
+Wood-Anderson simulation, e.g. :term:`ML <magnitude, local (ML)>`,
+:term:`MLv <magnitude, local vertical (MLv)>`, :term:`MLc <magnitude, local custom (MLc)>`.
+
+
+Station Magnitudes
+==================
+
+Station magnitudes are computed automatically by :ref:`scmag` or interactively
+by :ref:`scolv` from measured amplitudes based on distance-dependent
+calibration curves which depend on magnitude type. When computing a set of
+magnitudes in :ref:`scolv` which is different from the set configured in
+:ref:`scmag`, then scmag may later add the missing magnitudes automatically.
+Magnitude types for which the evaluation status is set to "rejected", e.g., in
+scolv, will not be recomputed by scmag.
+
+
+.. _concepts-magnitudes-correction:
+
+Station corrections
+-------------------
+
+Linear station corrections applied to station magnitudes can be configured by
+global :ref:`binding parameters <global_bindings_config>`:
+
+#. Add a magnitude type profile where the name of the profile is the name of the
+   magnitude itself,
+#. Configure the correction parameters.
+
+When using binding profiles, all referencing stations will be affected equally
+which is typically not intended. In contrast, applying station bindings requires
+to set up many bindings which may not be intended either.
+
+Therefore, you may add lines to the global module configuration in
+:file:`global.cfg` where one line corresponds to one station with one magnitude
+and the corresponding correction parameter. The groups and the name of the
+parameters are identical to the global bindings parameters. All lines start with
+"*module.trunk*". Example for an offset correction of
+:term:`MLv <magnitude, local vertical (MLv)>` measured station GE.UGM:
+
+.. code-block:: properties
+
+   module.trunk.GE.UGM.magnitudes.MLv.offset = 0.1
+
+.. note::
+
+   The configuration of parameters starting with *module.trunk.* is not
+   supported by :ref:`scconfig`. All corresponding configurations must be done
+   by direclty editing the configuration file, e.g.,
+   :file:`seiscomp/etc/global.cfg`.
+
+
+Network Magnitudes
+==================
+
+Network magnitudes are computed automatically by :ref:`scmag` or interactively
+by :ref:`scolv` from station magnitudes based on averaging station magnitudes.
+The averaging methods applied by :ref:`scmag` are configurable by
+:confval:`magnitudes.average`. Available are (:cite:t:`rosenberger-1983`):
+
+* *mean*: the mean value from all station magnitudes.
+* *median*: the mean value from all station magnitudes.
+* *trimmedMean(X)*: gnores outlier station magnitudes by first removing the
+  largest and the smallest *X* % of the observed values (percentiles). The mean is
+  formed from the remaining station magnitudes.
+* *trimmedMedian(X)*: forms the median from all station magnitudes but returns
+  the uncertainty by ignoring the largest and the smallest *X* % station
+  magnitudes.
+* *medianTrimmedMean(X)*: returns the mean magnitude from all station magnitudes
+  differing less than *X* magnitudes from the median.
+
+
+Aliases
+=======
+
+New magnitude types (aliases) can be created based on existing magnitude and
+amplitude types but configured specifically.
+The setup procedure is outlined in the
+:ref:`tutorial on magnitude aliases <tutorials_magnitude-aliases>`.
+
+
+.. _concepts-magnitudes-regionalization:
+
+Regionalization
+===============
+
+The computation of station magnitudes can be regionalized. This means that for
+a specific region specific conditions apply when computing magnitudes. The
+conditions include any parameter available for configuring a magnitude
+including global binding parameters such as magnitude calibration, distance
+and depth ranges, etc. As an example you may wish to apply different
+attenuation curves for computing MLv magnitudes to earthquakes in Eastern and
+in Western Canada.
+
+Regionalization is achieved by adding magnitude-type profiles in the magnitudes
+section of global module configuration parameters. Regionalization assumes
+defaults from global bindings but overrides the values when configured. The
+setup procedure including
+:ref:`station corrections <concepts-magnitudes-correction>` is outlined in the
+:ref:`tutorial on regionalization <tutorials_magnitude-region-aliases>`.
+
+
+Moment Magnitudes
+=================
+
+Moment magnitudes can be derived from all other network magnitudes by mapping of
+the original network magnitude, e.g., *Mx*, to a new moment magnitude *Mw(Mx)*.
+
+The mapping function can be configured for all original magnitude types except
+:term:`mB <magnitude, derived mB (Mw(mB))>` and
+:term:`Mwp <magnitude, derived Mwp (Mw(Mwp))>` where the mapping is hardcoded.
+Read the :ref:`tutorial on moment magnitudes <tutorials_mags_moment>` for the
+configuration.
+
+
+.. _concepts-magnitudes-summary:
+
+Summary Magnitude
+=================
+
+In order to account for different phenomena related to magnitude computation
+including magnitude saturation and application of different magnitude types at
+specific distance and depth ranges of the sources a summary magnitude can be
+computed from network magnitudes by :ref:`scmag`. The summary magnitude is
+usually referred to as *M*. The name is configurable.
+
+.. note::
+
+   Station, network and summary magnitudes are contained uniquely in one
+   :term:`origin`.
+
+
+Preferred Magnitude
+===================
+
+From the list of computed network magnitudes and the summary magnitude,
+:ref:`scevent` can automatically determine the preferred magnitude of the
+:term:`event`. This may also be done interactively by operators in the
+:ref:`Event tab of scolv <scolv-sec-event-tab>` or by
+:ref:`custom commit buttons in scolv <sec-scolv-custom-commit>`.