seiscomp-training/share/man/man1/scmag.1

.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "SCMAG" "1" "Oct 14, 2025" "6.9.1" "SeisComP"
.SH NAME
scmag \- SeisComP Documentation
.sp
\fBCalculates magnitudes of different types.\fP
.SH DESCRIPTION
.sp
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 \(dqMAGNITUDE\(dq group. scmag doesn’t access
any waveforms. It only uses amplitudes previously calculated.
.sp
The purpose of scmag is the decoupling of magnitude computation from amplitude
measurements. This allows several modules to generate amplitudes concurrently,
like \fI\%scautopick\fP or \fI\%scamp\fP\&. 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.
.SS Relationship between amplitudes and origins
.sp
scmag makes use of the fact that origins sent by \fI\%scautoloc\fP, \fI\%scolv\fP
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.
.sp
Read the \fI\%scamp\fP documentation for more details on amplitude measurements.
.SS Primary magnitudes
.sp
Primary magnitudes are computed from amplitudes and station\-event distances.
Currently the following primary magnitude types are implemented.
.SS Local distances
.INDENT 0.0
.TP
.B \fI\%Md\fP
Duration magnitude as described in HYPOINVERSE (Klein [\fI\%50\fP]).
.TP
.B \fI\%Mjma\fP
Mjma is computed on displacement data using body waves of period < 30s.
.TP
.B \fI\%ML\fP
Local (Richter) magnitude calculated on the horizontal components using a
correction term to fit with the standard ML (Richter [\fI\%57\fP]).
.TP
.B \fI\%MLc\fP
Local custom magnitude calculated on the horizontal components according to
Hessian Earthquake Service and Stange [\fI\%62\fP]
.TP
.B \fI\%MLh\fP
Local magnitude calculated on the horizontal components according to SED
specifications.
.TP
.B \fI\%MLv\fP
Local magnitude calculated on the vertical component using a correction term
to fit with the standard ML.
.TP
.B \fI\%MLr\fP
Local magnitude calculated from MLv amplitudes based on GNS/GEONET specifications
for New Zealand (Ristau \fIet al.\fP [\fI\%58\fP]).
.TP
.B \fI\%MN\fP
Nuttli magnitude for Canada and other Cratonic regions (Nuttli [\fI\%53\fP]).
.UNINDENT
.SS Teleseismic distances
.INDENT 0.0
.TP
.B \fI\%mb\fP
Narrow band body wave magnitude measured on a WWSSN\-SP filtered trace
.TP
.B \fI\%mBc\fP
Cumulative body wave magnitude
.TP
.B \fI\%mB\fP
Broad band body wave magnitude after Bormann and Saul [\fI\%38\fP]
.TP
.B \fI\%Mwp\fP
The body wave magnitude of Tsuboi \fIet al.\fP [\fI\%63\fP]
.TP
.B \fI\%Ms_20\fP
Surface\-wave magnitude at 20 s period
.TP
.B \fI\%Ms(BB)\fP
Broad band surface\-wave magnitude
.UNINDENT
.SS Derived magnitudes
.sp
Additionally, scmag derives the following magnitudes from primary magnitudes:
.INDENT 0.0
.TP
.B \fI\%Mw(mB)\fP
Estimation of the moment magnitude Mw based on mB using the Mw vs. mB
regression of Bormann and Saul [\fI\%38\fP]
.TP
.B \fI\%Mw(Mwp)\fP
Estimation of the moment magnitude Mw based on Mwp using the Mw vs. Mwp
regression of Whitmore \fIet al.\fP [\fI\%65\fP]
.TP
.B \fI\%M\fP
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.
.sp
More details are given in the \fI\%section Summary magnitude\fP\&.
.TP
.B 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.
.UNINDENT
.sp
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.
.SH STATION MAGNITUDES
.sp
Station magnitudes of a \fI\%particular magnitude type\fP are
calculated based on measured amplitudes considered by this magnitude type and
the distance between the \fI\%origin\fP and the station at which the amplitude
was measured. Typically, epicentral distance is used for distance. Magnitudes
may support configurable distance measures, e.g.,
\fI\%MLc\fP\&. 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.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Usually station magnitudes use amplitudes of the same type. However, some magnitude
consider amplitudes of another type. E.g. \fI\%MLr\fP
uses amplitudes computed for \fI\%MLv\fP\&.
.UNINDENT
.UNINDENT
.SS Regionalization
.sp
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 \(dqmagnitude regionalization\(dq. 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 \fB$SEISCOMP_ROOT/etc/global.cfg\fP\&.
.INDENT 0.0
.IP 1. 3
Add magnitude type profile to the magnitudes parameters. The name of the
profile must be the name of the magnitude type.
.IP 2. 3
Add the profile\-specific parameters.
.UNINDENT
.sp
Example for MLc in \fB$SEISCOMP_ROOT/etc/global.cfg\fP the polygon with name
\fItest\fP defined in a \fI\%BNA file\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SH NETWORK MAGNITUDES
.sp
The network magnitude is a magnitude value summarizing several
\fI\%station magnitudes\fP values of one \fI\%origin\fP\&.
Different methods are available for forming network magnitudes from station
magnitudes:
.TS
center;
|l|l|.
_
T{
Method
T}	T{
Description
T}
_
T{
mean
T}	T{
The usual mean value.
T}
_
T{
trimmed mean value
T}	T{
To stabilize the network magnitudes the smallest and the largest 12.5% of the \fI\%station magnitude\fP values are removed before computing the mean.
T}
_
T{
median
T}	T{
The usual median value.
T}
_
T{
median trimmed mean
T}	T{
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.
T}
_
.TE
.sp
Configure the method per magnitude type by \fI\%magnitudes.average\fP\&.
Default values apply for each magnitude type which are defined by the magnitude
itself.
In the \fI\%scolv Magnitudes tab\fP the methods, the
stations magnitudes and other parameters can be selected interactively.
.SH SUMMARY MAGNITUDE
.sp
scmag can compute a summary magnitude as a weighted sum from all available
\fI\%network magnitudes\fP\&.
This magnitude is typically called \fBM\fP as configured in
\fI\%summaryMagnitude.type\fP\&.
.sp
It is computed as a weighted average over the available magnitudes:
.sp
.ce
M &= \efrac{\esum w_{i} * M_{i}}{\esum w_i} \e\e
w_{i} &= a_i * stationCount(M_{i}) + b_i
.ce 0
.sp
The coefficients a and b can be configured per magnitude type by
\fI\%summaryMagnitude.coefficients.a\fP
and \fI\%summaryMagnitude.coefficients.b\fP, respectively.
Furthermore each magnitude type can be specifically added to or excluded from the
summary magnitude calculation
as defined in \fI\%summaryMagnitude.whitelist\fP or
\fI\%summaryMagnitude.blacklist\fP, respectively.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
While the magnitudes are computed by scmag the decision about the preferred
magnitude of an \fI\%event\fP is made by \fI\%scevent\fP\&.
.UNINDENT
.UNINDENT
.SH PREFERRED MAGNITUDE
.sp
The preferred magnitude of an \fI\%event\fP is set automatically by \fI\%scevent\fP
or interactively in \fI\%scolv\fP\&. It can be any network magnitude or the summary
magnitude.
.SH MODULE CONFIGURATION
.nf
\fBetc/defaults/global.cfg\fP
\fBetc/defaults/scmag.cfg\fP
\fBetc/global.cfg\fP
\fBetc/scmag.cfg\fP
\fB~/.seiscomp/global.cfg\fP
\fB~/.seiscomp/scmag.cfg\fP
.fi
.sp
.sp
scmag inherits \fI\%global options\fP\&.
.INDENT 0.0
.TP
.B magnitudes
Default: \fBMLv,mb,mB,Mwp\fP
.sp
Type: \fIlist:string\fP
.sp
The magnitude types to be calculated. Station magnitudes are
computed from their amplitudes, network magnitudes from their
station magnitudes.
.UNINDENT
.INDENT 0.0
.TP
.B minimumArrivalWeight
Default: \fB0.5\fP
.sp
Type: \fIdouble\fP
.sp
The minimum weight of an arrival for an associated amplitude
to be used for calculating a magnitude.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBmagnitudes.*\fP
\fIGeneral parameters for computing magnitudes. Others are configured\fP
\fIby global binding parameters for specific magnitude types.\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B magnitudes.average
Default: \fBdefault\fP
.sp
Type: \fIlist:string\fP
.sp
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.:
\(dqmagnitudes.average = default, MLv:median\(dq
.sp
default: Compute the mean if less than 4 contributed
station magnitudes exist. Otherwise apply trimmedMean(25),
trimmed mean with 25%.
.UNINDENT
.INDENT 0.0
.TP
.B connection.sendInterval
Default: \fB1\fP
.sp
Type: \fIint\fP
.sp
Unit: \fIs\fP
.sp
Interval between 2 sending processes. The interval controls
how often information is updated.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBsummaryMagnitude.*\fP
\fIThe summary magnitude is the weighted average from all\fP
\fIdefined network magnitude types: Single network magnitude values\fP
\fIare multiplied with their magnitude\-type specific weight and\fP
\fIsummed up. The resulting sum is divided by the sum of all weights.\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B summaryMagnitude.enabled
Default: \fBtrue\fP
.sp
Type: \fIboolean\fP
.sp
Enables summary magnitude calculation.
.UNINDENT
.INDENT 0.0
.TP
.B summaryMagnitude.type
Default: \fBM\fP
.sp
Type: \fIstring\fP
.sp
Define the type/name of the summary magnitude.
.UNINDENT
.INDENT 0.0
.TP
.B summaryMagnitude.minStationCount
Default: \fB1\fP
.sp
Type: \fIint\fP
.sp
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.
.UNINDENT
.INDENT 0.0
.TP
.B summaryMagnitude.singleton
Default: \fBtrue\fP
.sp
Type: \fIboolean\fP
.sp
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.
.UNINDENT
.INDENT 0.0
.TP
.B summaryMagnitude.blacklist
Type: \fIlist:string\fP
.sp
Define the magnitude types to be excluded from the summary
magnitude calculation.
.UNINDENT
.INDENT 0.0
.TP
.B summaryMagnitude.whitelist
Type: \fIlist:string\fP
.sp
Define the magnitude types to be included in the summary
magnitude calculation.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBsummaryMagnitude.coefficients.*\fP
\fIThe coefficients defining the weight of network magnitudes\fP
\fIfor calculating the summary magnitude.\fP
\fIWeight = a * magnitudeStationCount + b.\fP
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B summaryMagnitude.coefficients.a
Default: \fB0, Mw(mB):0.4, Mw(Mwp):0.4\fP
.sp
Type: \fIlist:string\fP
.sp
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.
.UNINDENT
.INDENT 0.0
.TP
.B summaryMagnitude.coefficients.b
Default: \fB1, MLv:2, Mw(mB):\-1, Mw(Mwp):\-1\fP
.sp
Type: \fIlist:string\fP
.sp
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.
.UNINDENT
.SH COMMAND-LINE OPTIONS
.SS Generic
.INDENT 0.0
.TP
.B \-h, \-\-help
Show help message.
.UNINDENT
.INDENT 0.0
.TP
.B \-V, \-\-version
Show version information.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-plugins arg
Load given plugins.
.UNINDENT
.INDENT 0.0
.TP
.B \-D, \-\-daemon
Run as daemon. This means the application will fork itself
and doesn\(aqt need to be started with &.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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).
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-shutdown\-master\-username arg
Set the name of the master\-username of the messaging
used for auto\-shutdown. If \(dqshutdown\-master\-module\(dq is
given as well, this parameter is ignored.
.UNINDENT
.INDENT 0.0
.TP
.B \-x, \-\-expiry time
Time span in hours after which objects expire.
.UNINDENT
.SS Verbosity
.INDENT 0.0
.TP
.B \-\-verbosity arg
Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info,
4:debug.
.UNINDENT
.INDENT 0.0
.TP
.B \-v, \-\-v
Increase verbosity level (may be repeated, eg. \-vv).
.UNINDENT
.INDENT 0.0
.TP
.B \-q, \-\-quiet
Quiet mode: no logging output.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-component arg
Limit the logging to a certain component. This option can
be given more than once.
.UNINDENT
.INDENT 0.0
.TP
.B \-s, \-\-syslog
Use syslog logging backend. The output usually goes to
/var/lib/messages.
.UNINDENT
.INDENT 0.0
.TP
.B \-l, \-\-lockfile arg
Path to lock file.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-console arg
Send log output to stdout.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-debug
Execute in debug mode.
Equivalent to \-\-verbosity=4 \-\-console=1 .
.UNINDENT
.INDENT 0.0
.TP
.B \-\-log\-file arg
Use alternative log file.
.UNINDENT
.SS Messaging
.INDENT 0.0
.TP
.B \-u, \-\-user arg
Overrides configuration parameter \fI\%connection.username\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-H, \-\-host arg
Overrides configuration parameter \fI\%connection.server\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-t, \-\-timeout arg
Overrides configuration parameter \fI\%connection.timeout\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-g, \-\-primary\-group arg
Overrides configuration parameter \fI\%connection.primaryGroup\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-S, \-\-subscribe\-group arg
A group to subscribe to.
This option can be given more than once.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-content\-type arg
Overrides configuration parameter \fI\%connection.contentType\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-start\-stop\-msg arg
Set sending of a start and a stop message.
.UNINDENT
.SS Database
.INDENT 0.0
.TP
.B \-\-db\-driver\-list
List all supported database drivers.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-database arg
The database connection string, format:
\fI\%service://user:pwd@host/database\fP\&.
\(dqservice\(dq is the name of the database driver which
can be queried with \(dq\-\-db\-driver\-list\(dq.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-config\-module arg
The config module to use.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-inventory\-db arg
Load the inventory from the given database or file, format:
[\fI\%service://]location\fP .
.UNINDENT
.INDENT 0.0
.TP
.B \-\-db\-disable
Do not use the database at all
.UNINDENT
.SS Input
.INDENT 0.0
.TP
.B \-\-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 \-\-reprocess to include those
magnitudes. It outputs an XML text adding the station\-
and network magnitudes to the input XML file.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-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.
.UNINDENT
.SS Reprocess
.INDENT 0.0
.TP
.B \-\-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.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-keep\-weights
Keep the original weights in combination with \-\-static.
.UNINDENT
.SH AUTHOR
gempa GmbH, GFZ Potsdam
.SH COPYRIGHT
gempa GmbH, GFZ Potsdam
.\" Generated by docutils manpage writer.
.