Files
2025/share/doc/seiscomp/html/base/tutorials/magnitude-regionalization.html

406 lines
24 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Magnitudes: Regionalization, Aliases, Mw &#8212; SeisComP Release documentation</title>
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../../_static/seiscomp.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=72bcf2f2" />
<link rel="stylesheet" type="text/css" href="../../_static/seiscomp.css?v=c6da7ce6" />
<link rel="stylesheet" type="text/css" href="../../_static/graphviz.css?v=eafc0fe6" />
<script type="text/javascript" src="../../_static/seiscomp.js"></script>
<script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
<script data-url_root="../../" id="documentation_options" src="../../_static/documentation_options.js?v=823bb831"></script>
<script src="../../_static/doctools.js?v=888ff710"></script>
<script src="../../_static/sphinx_highlight.js?v=4825356b"></script>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Play back archived waveforms" href="waveformplayback.html" />
<link rel="prev" title="Enable local FDSNWS server" href="servefdsnws.html" />
</head>
<body>
<div class="header">
<div class="container">
<div class="brand">
<img class="logo" src="../../_static/brands/seiscomp/text/white.svg"/>
<!-- span class="title">SeisComP Release</span -->
<span class="version">6.9.0</span>
</div>
</div>
</div>
<div class="nav">
<div class="container">
<div class="content"><a class="pull-right" id="sidebar-toggle">TOC</a>
<div class="related" role="navigation" aria-label="related navigation">
<ul>
<li class="right">
<a href="../../genindex.html" title="General Index"
accesskey="I">
index
</a>
</li>
<li class="right">
<a href="waveformplayback.html" title="Play back archived waveforms"
accesskey="N">
next
</a>
</li>
<li class="right">
<a href="servefdsnws.html" title="Enable local FDSNWS server"
accesskey="P">
previous
</a>
</li>
<li class="nav-item nav-item-0">
<a href="../../index.html">Home</a>
</li>
<li class="nav-item nav-item-1">
<a href="../tutorials.html" accesskey="U">Tutorials</a>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="container">
<div class="fitted content" id="anchors-container">
<div class="body" role="main">
<section id="magnitudes-regionalization-aliases-mw">
<span id="tutorials-magnitude-region-aliases"></span><h1>Magnitudes: Regionalization, Aliases, Mw<a class="headerlink" href="#magnitudes-regionalization-aliases-mw" title="Permalink to this heading"></a></h1>
<p>You will …</p>
<ul class="simple">
<li><p>Regionalize magnitude</p></li>
<li><p>Create new magnitude types as aliases from other magnitudes and amplitudes.</p></li>
<li><p>Map magnitudes to the moment magnitude, Mw</p></li>
</ul>
<dl class="field-list simple">
<dt class="field-odd">Pre-requisites for this tutorial<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p>Read the <a class="reference internal" href="../concepts/magnitudes.html#concepts-magnitudes"><span class="std std-ref">concepts section on magnitudes</span></a>.</p></li>
<li><p>Real-time data for the station must be available locally.
See <a class="reference internal" href="waveforms.html#tutorials-waveforms"><span class="std std-ref">Get real-time data from a remote Seedlink server (single station)</span></a> or <a class="reference internal" href="geofon_waveforms.html#tutorials-geofon-waveforms"><span class="std std-ref">Add real-time stations from GEOFON</span></a>.</p></li>
<li><p>Inventory must be loaded locally.</p></li>
</ul>
</dd>
<dt class="field-even">Afterwards/Results/Outcomes<span class="colon">:</span></dt>
<dd class="field-even"><ul class="simple">
<li><p>Regionalized magnitudes,</p></li>
<li><p>New magnitude types as aliases.</p></li>
<li><p>Moment magnitudes</p></li>
</ul>
</dd>
<dt class="field-odd">Time range estimate<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p>30 minutes</p></li>
</ul>
</dd>
</dl>
<hr class="docutils" />
<section id="regionalize-magnitudes">
<span id="tutorials-magnitude-region"></span><h2>Regionalize Magnitudes<a class="headerlink" href="#regionalize-magnitudes" title="Permalink to this heading"></a></h2>
<p>By regionalization, magnitudes can be computed with region-dependent properties.
The procedure to set up magnitude regionalization is:</p>
<ol class="arabic">
<li><p>Create one file which contains the polygons surrounding the regions within
which magnitude parameters shall apply. The polygon files are provided in
<a class="reference internal" href="../../apps/global_gui.html#sec-gui-layers-vector-format-bna"><span class="std std-ref">BNA</span></a> or
<a class="reference internal" href="../../apps/global_gui.html#sec-gui-layers-vector-format-geojson"><span class="std std-ref">GeoJSON format</span></a> and located as
set out in the <a class="reference internal" href="../../apps/global_gui.html#sec-gui-layers"><span class="std std-ref">documentation of map layers</span></a>. The file
can be created from any <cite>SeisComP</cite> GUI application providing maps, e.g.,
<a class="reference internal" href="../../apps/scmv.html#scmv"><span class="std std-ref">scmv</span></a>.</p></li>
<li><p>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., <em>MLc</em> for the <a class="reference internal" href="../../apps/global_mlc.html#global-mlc"><span class="std std-ref">MLc magnitude</span></a>.</p></li>
<li><p>Configure the <code class="xref std std-confval docutils literal notranslate"><span class="pre">magnitudes.MLc.regionFile</span></code> parameter with the full
path and name of the polygon file created above.</p></li>
<li><p>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 <em>world</em> for all regions
not covered by any polygon.</p></li>
<li><p>Configure the regionalized magnitude parameters of the magnitude-region
profile. Activate the <em>enable</em> parameter if you wish to apply this profile.</p></li>
<li><p>Restart the data processing:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>seiscomp<span class="w"> </span>restart
</pre></div>
</div>
<p>or execute a GUI module.</p>
</li>
</ol>
<div class="admonition important">
<p class="admonition-title">Important</p>
<ul class="simple">
<li><p>Parameters which can be configured along with regionalization assume
defaults from global binding parameters but override global bindings
parameters when configured.</p></li>
<li><p>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 “<em>world</em>”.
Magnitudes for events outside any other magnitude-region profile will then
be computed according to this profile.</p></li>
</ul>
</div>
<section id="station-corrections">
<h3>Station corrections<a class="headerlink" href="#station-corrections" title="Permalink to this heading"></a></h3>
<p><a class="reference internal" href="../concepts/magnitudes.html#concepts-magnitudes-correction"><span class="std std-ref">Magnitude station corrections</span></a> 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, <code class="file docutils literal notranslate"><span class="pre">global.cfg</span></code>, for the respective
magnitude type and station. Use comma separation for multiple regions and colon
for separating the region name from the value.</p>
<p>Example for correcting MLv computed at station GE.UGM:</p>
<div class="highlight-properties notranslate"><div class="highlight"><pre><span></span><span class="na">module.trunk.GE.UGM.magnitudes.MLv.offset</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.1, europe:0.2, asia:-0.1</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The configuration of parameters starting with <em>module.trunk.</em> is not
supported by <a class="reference internal" href="../../apps/scconfig.html#scconfig"><span class="std std-ref">scconfig</span></a>. All corresponding configurations must be done
by directly editing the configuration file, e.g.,
<code class="file docutils literal notranslate"><span class="pre">seiscomp/etc/global.cfg</span></code>.</p>
</div>
</section>
</section>
<section id="magnitude-aliases">
<span id="tutorials-magnitude-aliases"></span><h2>Magnitude Aliases<a class="headerlink" href="#magnitude-aliases" title="Permalink to this heading"></a></h2>
<p>New magnitude types (aliases) can be created based on existing magnitude and
amplitude types but configured specifically.</p>
<p>The procedure to set up magnitude aliases is:</p>
<ol class="arabic">
<li><p>Create a magnitude alias in <code class="file docutils literal notranslate"><span class="pre">global.cfg</span></code> by configuring
<a class="reference internal" href="../../apps/global.html#confval-magnitudes.aliases"><code class="xref std std-confval docutils literal notranslate"><span class="pre">magnitudes.aliases</span></code></a>. Example:</p>
<div class="highlight-properties notranslate"><div class="highlight"><pre><span></span><span class="na">magnitudes.aliases</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">MLc1:MLc:MLc</span>
</pre></div>
</div>
</li>
<li><p>Configure the alias magnitudes in either way:</p>
<ul class="simple">
<li><p>Write bindings parameters to global module configuration or</p></li>
<li><p>Set up <a class="reference internal" href="#tutorials-magnitude-region"><span class="std std-ref">regionalization</span></a>:</p></li>
</ul>
<p><strong>Binding parameters in global module configuration:</strong></p>
<ol class="arabic">
<li><p>Read the relevant parameter names of the original magnitude from global
binding, e.g., in <a class="reference internal" href="../../apps/scconfig.html#scconfig"><span class="std std-ref">scconfig</span></a>. The names must include the full
hierarchy including all sections. Example:</p>
<div class="highlight-properties notranslate"><div class="highlight"><pre><span></span><span class="na">magnitudes.MLc01.parametric.c1</span>
</pre></div>
</div>
</li>
<li><p>Open the module configuration file, e.g.,
<code class="file docutils literal notranslate"><span class="pre">seiscomp/etc/global.cfg</span></code> in a text editor.</p></li>
<li><p>Prepend <em>module.trunk.global.</em> to the parameter name and add it along with
its value to the configuration file. Example:</p>
<div class="highlight-properties notranslate"><div class="highlight"><pre><span></span><span class="na">module.trunk.global.magnitudes.MLc01.parametric.c1</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">0.7</span>
</pre></div>
</div>
</li>
<li><p>Add the new magnitude name to the configuration of all relevant modules,
e.g., <a class="reference internal" href="../../apps/scamp.html#scamp"><span class="std std-ref">scamp</span></a>, <a class="reference internal" href="../../apps/scmag.html#scmag"><span class="std std-ref">scmag</span></a>, <a class="reference internal" href="../../apps/scevent.html#scevent"><span class="std std-ref">scevent</span></a>, <a class="reference internal" href="../../apps/scolv.html#scolv"><span class="std std-ref">scolv</span></a>.</p></li>
</ol>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The parameters starting with <em>module.trunk.</em> are not available for
configuration in <a class="reference internal" href="../../apps/scconfig.html#scconfig"><span class="std std-ref">scconfig</span></a>.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Binding parameters configured in global module configuration should only
be considered exceptionally. These parameters will</p>
<ul class="simple">
<li><p>Override the corresponding parameters configured by regionalization
using the region <em>world</em>.</p></li>
<li><p>Not be written to the database and cannot be accessed by SeisComP
modules running on other computers.</p></li>
</ul>
</div>
<p><strong>Regionalization:</strong></p>
<ul>
<li><p>Consider the tutorial on
<a class="reference internal" href="#tutorials-magnitude-region"><span class="std std-ref">magnitude regionalization</span></a> above.</p></li>
<li><p>For the name of the new magnitude-type profile now use the alias name.</p>
<div class="admonition hint">
<p class="admonition-title">Hint</p>
<p>When adding the magnitude-region profile in
<a class="reference internal" href="../../apps/scconfig.html#scconfig"><span class="std std-ref">scconfig</span></a>, 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.</p>
<ol class="arabic simple">
<li><p>Close scconfig</p></li>
<li><p>Open the configuration file <code class="file docutils literal notranslate"><span class="pre">global.cfg</span></code></p></li>
<li><p>Rename the name of the referenced magnitude in the parameters to the
name of the alias.</p></li>
</ol>
</div>
</li>
</ul>
</li>
</ol>
</section>
<section id="moment-magnitudes">
<span id="tutorials-mags-moment"></span><h2>Moment Magnitudes<a class="headerlink" href="#moment-magnitudes" title="Permalink to this heading"></a></h2>
<p>All magnitudes, Mx, can be mapped to a moment magnitude, Mw(Mx).
The configuration procedure is:</p>
<ol class="arabic">
<li><p>Set up a magnitude-type profile for the original magnitude type in global
module configuration. Use <a class="reference internal" href="../../apps/scconfig.html#scconfig"><span class="std std-ref">scconfig</span></a> for creating the profile.</p></li>
<li><p>Configure the parameter <em>MwMapping</em>, which will become available along with
the new profile, e.g., <code class="xref std std-confval docutils literal notranslate"><span class="pre">magnitudes.MLc.MwMapping</span></code>. Alternatively,
add the parameter to <code class="file docutils literal notranslate"><span class="pre">seiscomp/etc/global.cfg</span></code>. 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:</p>
<div class="highlight-properties notranslate"><div class="highlight"><pre><span></span><span class="na">magnitudes.MLc.MwMapping</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">MLc_0:Mw(MLc)_0,MLc_1:Mw(MLc)_1,...,MLc_N:Mw(MLc)_N</span>
</pre></div>
</div>
<p>Any magnitude value outside the configured range is ignored.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Do not map the magnitudes <a class="reference internal" href="../glossary.html#term-magnitude-broadband-body-wave-mB"><span class="xref std std-term">mB</span></a>
and <a class="reference internal" href="../glossary.html#term-magnitude-broadband-P-wave-moment-Mwp"><span class="xref std std-term">Mwp</span></a> to Mw since
this is hardcoded already and done automatically by <a class="reference internal" href="../../apps/scmag.html#scmag"><span class="std std-ref">scmag</span></a>.</p>
</div>
</li>
</ol>
<p>The new moment magnitudes will be available along with the original magnitudes
and can be viewed in <span class="xref std std-ref">scolv`or :ref:`scesv</span> and considered by <a class="reference internal" href="../../apps/scmag.html#scmag"><span class="std std-ref">scmag</span></a>
or <a class="reference internal" href="../../apps/scevent.html#scevent"><span class="std std-ref">scevent</span></a>.</p>
<p>In order to avoid that <a class="reference internal" href="../concepts/magnitudes.html#concepts-magnitudes-summary"><span class="std std-ref">summary magnitudes</span></a>
are computed from original magnitudes and mapped Mw together and biased to both,
the original magnitudes can be blocklisted in <a class="reference internal" href="../../apps/scmag.html#scmag"><span class="std std-ref">scmag</span></a>
(<a class="reference internal" href="../../apps/scmag.html#confval-summaryMagnitude.blacklist"><code class="xref std std-confval docutils literal notranslate"><span class="pre">summaryMagnitude.blacklist</span></code></a>).</p>
</section>
<section id="final-tests">
<span id="tutorials-mags-regionalize-testing"></span><h2>Final Tests<a class="headerlink" href="#final-tests" title="Permalink to this heading"></a></h2>
<ul>
<li><p>Regionalization:</p>
<ol class="arabic">
<li><p>Start <a class="reference internal" href="../../apps/scolv.html#scolv"><span class="std std-ref">scolv</span></a> with the option <code class="xref std std-option docutils literal notranslate"><span class="pre">--debug</span></code> and load an event of
interest</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>scolv<span class="w"> </span>--debug
</pre></div>
</div>
</li>
<li><p>Relocate the event for generating a new origin.</p></li>
<li><p>Compute magnitudes selecting the magnitude of interest.</p></li>
<li><p>Inspect the computed magnitudes in the
<a class="reference internal" href="../../apps/scolv.html#scolv-sec-magnitude-tab"><span class="std std-ref">Magnitude tab of scolv</span></a> or read the
debug output listing the considered magnitudes and stations along with
the regionalized parameters.</p></li>
</ol>
</li>
<li><p>Magnitude aliases:</p>
<ol class="arabic">
<li><p>Start <a class="reference internal" href="../../apps/scolv.html#scolv"><span class="std std-ref">scolv</span></a> with the option <code class="xref std std-option docutils literal notranslate"><span class="pre">--debug</span></code> and load an event of
interest</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>scolv<span class="w"> </span>--debug
</pre></div>
</div>
</li>
<li><p>Relocate the event for generating a new origin.</p></li>
<li><p>Compute magnitudes selecting the magnitude of interest including the new
alias.</p></li>
<li><p>Inspect the computed magnitudes in the
<a class="reference internal" href="../../apps/scolv.html#scolv-sec-magnitude-tab"><span class="std std-ref">Magnitude tab of scolv</span></a> 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:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>...
<span class="m">13</span>:30:46<span class="w"> </span><span class="o">[</span>debug<span class="o">]</span><span class="w"> </span>GE.UGM:<span class="w"> </span>MLc1:<span class="w"> </span>effective<span class="w"> </span>correction<span class="w"> </span><span class="o">(</span>no<span class="w"> </span>locale<span class="o">)</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="m">1</span>.00:0.00
<span class="m">13</span>:30:46<span class="w"> </span><span class="o">[</span>debug<span class="o">]</span><span class="w"> </span>Parameters<span class="w"> </span><span class="k">for</span><span class="w"> </span>magnitude<span class="w"> </span>MLc1
<span class="m">13</span>:30:46<span class="w"> </span><span class="o">[</span>debug<span class="o">]</span><span class="w"> </span>+<span class="w"> </span>maximum<span class="w"> </span>depth:<span class="w"> </span><span class="m">50</span>.000<span class="w"> </span>km
<span class="m">13</span>:30:46<span class="w"> </span><span class="o">[</span>debug<span class="o">]</span><span class="w"> </span>+<span class="w"> </span>distance<span class="w"> </span>mode:<span class="w"> </span>hypocentral
<span class="m">13</span>:30:46<span class="w"> </span><span class="o">[</span>debug<span class="o">]</span><span class="w"> </span>+<span class="w"> </span>minimum<span class="w"> </span>distance:<span class="w"> </span>-1.000<span class="w"> </span>km
<span class="m">13</span>:30:46<span class="w"> </span><span class="o">[</span>debug<span class="o">]</span><span class="w"> </span>+<span class="w"> </span>maximum<span class="w"> </span>distance:<span class="w"> </span><span class="m">889</span>.561<span class="w"> </span>km
...
</pre></div>
</div>
</li>
</ol>
</li>
</ul>
</section>
</section>
<div id="anchors-bottom"></div>
</div>
<div class="sidebar" role="navigation" aria-label="main navigation">
<div id="anchors-top"></div>
<div id="anchors" class="content">
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
<div>
<h3><a href="../../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Magnitudes: Regionalization, Aliases, Mw</a><ul>
<li><a class="reference internal" href="#regionalize-magnitudes">Regionalize Magnitudes</a><ul>
<li><a class="reference internal" href="#station-corrections">Station corrections</a></li>
</ul>
</li>
<li><a class="reference internal" href="#magnitude-aliases">Magnitude Aliases</a></li>
<li><a class="reference internal" href="#moment-magnitudes">Moment Magnitudes</a></li>
<li><a class="reference internal" href="#final-tests">Final Tests</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="servefdsnws.html"
title="previous chapter">Enable local FDSNWS server</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="waveformplayback.html"
title="next chapter">Play back archived waveforms</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/base/tutorials/magnitude-regionalization.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<div class="container">
<div class="horizontal layout content">
<a class="fade-in" href="https://www.gempa.de" target="_blank">
<img class="brand" src="../../_static/brands/gempa.svg"/>
</a>
<div class="stretched align-center fitted content">
<div>
Version <b>6.9.0</b> Release
</div>
<div class="copyright">
Copyright &copy; gempa GmbH, GFZ Potsdam.
</div>
</div>
<a class="fade-in" href="https://www.gfz-potsdam.de" target="_blank">
<img class="brand" src="../../_static/brands/gfz.svg"/>
</a>
</div>
</div>
</div>
</body>
</html>