.. 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 ` Duration magnitude as described in HYPOINVERSE (:cite:t:`klein-2002`). :term:`Mjma ` Mjma is computed on displacement data using body waves of period < 30s. :term:`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 ` Local custom magnitude calculated on the horizontal components according to Hessian Earthquake Service and :cite:t:`stange-2006` :term:`MLh ` Local magnitude calculated on the horizontal components according to SED specifications. :term:`MLv ` Local magnitude calculated on the vertical component using a correction term to fit with the standard ML. :term:`MLr ` Local magnitude calculated from MLv amplitudes based on GNS/GEONET specifications for New Zealand (:cite:t:`ristau-2016`). :term:`MN ` Nuttli magnitude for Canada and other Cratonic regions (:cite:t:`nuttli-1973`). Teleseismic distances --------------------- :term:`mb ` Narrow band body wave magnitude measured on a WWSSN-SP filtered trace :term:`mBc ` Cumulative body wave magnitude :term:`mB ` Broad band body wave magnitude after :cite:t:`bormann-2008` :term:`Mwp ` The body wave magnitude of :cite:t:`tsuboi-1995` :term:`Ms_20 ` Surface-wave magnitude at 20 s period :term:`Ms(BB) ` Broad band surface-wave magnitude Derived magnitudes ------------------ Additionally, scmag derives the following magnitudes from primary magnitudes: :term:`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) ` Estimation of the moment magnitude Mw based on Mwp using the Mw vs. Mwp regression of :cite:t:`whitmore-2002` :term:`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`. 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 ` 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 `. 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 ` uses amplitudes computed for :term:`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 `: .. 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 ` 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 ` 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 `. 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`. .. 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* 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.: \"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: ``4`` 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.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 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. .. 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, eg. \-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`. .. option:: --start-stop-msg arg 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 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. .. 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.