scvsmag

Computes VS magnitudes based on envelopes calculated by scenvelope.

Description

Part of the VS package.

scvsmag is part of a new SeisComP implementation of the Virtual Seismologist [1] (VS) Earthquake Early Warning algorithm (Cua, 2005; Cua and Heaton, 2007) released under the SED Public License for SeisComP Contributions [2]. For a given origin it estimates single station magnitudes and a network magnitude based on the envelope attenuation relationship and ground motion amplitude ratio derived by Cua (2005). The original VS algorithm applies the Bayesian theorem by defining magnitude as the value that maximizes the product of a likelihood function and a prior probability density function. In the current version of scvsmag only the likelihood function is implemented and no prior information is used at this stage.

Logging

Apart from the standard log messages in scvsmag.log, processing log messages are also written to scvsmag-processing-info.log every time the VS Magnitude of an event is re-evaluated. A typical entry is shown below.

1  2013/06/28 10:51:01 [processing/info/VsMagnitude] Start logging for event: sed2012cyqr
2  2013/06/28 10:51:01 [processing/info/VsMagnitude] update number: 0
3  2013/06/28 10:51:01 [processing/info/VsMagnitude] Sensor: CH..BNALP.HH; Wavetype: P-wave; Soil class: rock; Magnitude: 3.47
4  2013/06/28 10:51:01 [processing/info/VsMagnitude] station lat: 46.87; station lon: 8.43; epicentral distance: 32.26;
5  2013/06/28 10:51:01 [processing/info/VsMagnitude] PGA(Z): 3.57e-03; PGV(Z): 6.91e-05; PGD(Z): 1.62e-06
6  2013/06/28 10:51:01 [processing/info/VsMagnitude] PGA(H): 2.67e-03; PGV(H): 3.44e-05; PGD(H): 1.02e-06
7  2013/06/28 10:51:01 [processing/info/VsMagnitude] Sensor: CH..MUO.HH; Wavetype: S-wave; Soil class: rock; Magnitude: 3.83
8  2013/06/28 10:51:01 [processing/info/VsMagnitude] station lat: 46.97; station lon: 8.64; epicentral distance: 22.45;
9  2013/06/28 10:51:01 [processing/info/VsMagnitude] PGA(Z): 8.19e-03; PGV(Z): 2.12e-04; PGD(Z): 6.91e-06
10 2013/06/28 10:51:01 [processing/info/VsMagnitude] PGA(H): 2.18e-02; PGV(H): 5.00e-04; PGD(H): 1.72e-05
11 2013/06/28 10:51:01 [processing/info/VsMagnitude] Sensor: CH..WILA.HH; Wavetype: P-wave; Soil class: rock; Magnitude: 3.50
12 2013/06/28 10:51:01 [processing/info/VsMagnitude] station lat: 47.41; station lon: 8.91; epicentral distance: 41.16;
13 2013/06/28 10:51:01 [processing/info/VsMagnitude] PGA(Z): 4.38e-03; PGV(Z): 6.42e-05; PGD(Z): 1.85e-06
14 2013/06/28 10:51:01 [processing/info/VsMagnitude] PGA(H): 3.35e-03; PGV(H): 6.40e-05; PGD(H): 1.88e-06
15 2013/06/28 10:51:01 [processing/info/VsMagnitude] Sensor: CH..ZUR.HH; Wavetype: S-wave; Soil class: rock; Magnitude: 3.79
16 2013/06/28 10:51:01 [processing/info/VsMagnitude] station lat: 47.37; station lon: 8.51; epicentral distance: 23.99;
17 2013/06/28 10:51:01 [processing/info/VsMagnitude] PGA(Z): 9.17e-02; PGV(Z): 1.03e-03; PGD(Z): 1.64e-05
18 2013/06/28 10:51:01 [processing/info/VsMagnitude] PGA(H): 9.63e-02; PGV(H): 2.12e-03; PGD(H): 5.31e-05
19 2013/06/28 10:51:01 [processing/info/VsMagnitude] VS-mag: 3.69; median single-station-mag: 3.79; lat: 47.15; lon: 8.52; depth : 25.32 km
20 2013/06/28 10:51:01 [processing/info/VsMagnitude] creation time: 2012-02-11T22:45:40.00Z; origin time: 2012-02-11T22:45:26.27Z; t-diff: 13.73; time since origin arrival: 0.864; time since origin creation: 0.873
21 2013/06/28 10:51:01 [processing/info/VsMagnitude] # picked stations: 6; # envelope streams: 79
22 2013/06/28 10:51:01 [processing/info/VsMagnitude] Distance threshold (dt): 44.68 km; # picked stations < dt: 4; # envelope streams < dt: 4
23 2013/06/28 10:51:01 [processing/info/VsMagnitude] Stations not used for VS-mag: CH.HASLI CH.LLS
24 2013/06/28 10:51:01 [processing/info/VsMagnitude] Magnitude check: 0.027; Arrivals check: 0.000; Azimuthal gap: 34.992
25 2013/06/28 10:51:01 [processing/info/VsMagnitude] likelihood: 0.99
26 2013/06/28 10:51:01 [processing/info/VsMagnitude] End logging for event: sed2012cyqr

Explanation

The following table comments each line in the above output.

Line Description
1 Start of the log message for the event with the given event ID
2 Update counter for this event.
3 - 18 Information about the stations that contribute to a VS magnitude estimate. Each station has four lines with the first line giving the stream name, the wavetype of the contributing amplitude, the soil type at the site and the single station magnitude. The next line shows the location and epicentral distance of the sensor. On the two following lines peak-ground-acceleration (PGA) -velocity (PGV) and -displacement (PGD) are given in SI units for vertical and the root-mean-square horizontal component.
19 The VS magnitude, the median of the single station magnitudes, the cordinates of the hypocenter
20 The creation time of the magnitude, the origin time and the difference between the two (‘tdiff’); also given are the time since origin arrival and time since origin creation which is a measure of how long it took to evaluate the first magnitude estimate.
21 The number of stations contributing to an origin (‘# picked stations’) and the number of envelope streams available (‘# envelope streams’).
22 Distance threshold from epicenter within which the relative difference between picked stations and envelope streams is evaluated (see line 24). Also shown is the number of picked stations and envelope streams within this distance threshold.
23 Stations that were used for picking but not for the magnitude estimation.
24 ‘Magnitude check’ is the relative difference between the VS magnitude and the median of the single station magnitudes. ‘Arrivals check’ is the relative difference between the number of picked stations and the number of envelope streams available within as certain epicentral distance. The ‘Azimuthal gap’ is the largest difference in azimuth between the picked stations.
25 The ‘likelihood’ is the product of the quality checks described above. See Computing the likelihood value for more details
26 End of the log message for the event with the given event ID.

Logging envelope messages

The envelope messages received by scvsmag can optionally be written to the log-file envelope-logging-info.log by setting:

vsmag.logenvelopes=true

The format of envelope-logging-info.log is self-explanatory, note however that the timestamp of the envelope value marks the start time of the 1 s waveform window over which the envelope value was computed. Depending on the size of your seismic network, envelope-logging-info.log might quickly use a lot of disk space.

Computing the likelihood value

The likelihood is computed as follows:

likelihood = Magnitude check * Arrivals check * Azimuthal Gap Check

If the magnitude check exceeds a magnitude dependent threshold its value is set to 0.4, otherwise it is 1.0. The thresholds are defined as follows:

Magnitude Threshold
<1.5 0.5
<2.0 0.4
<2.5 0.3
<3.0 0.25
<4.0 0.2
>4.0 0.18

If the arrivals check exceeds a value of 0.5 (i.e. more than half of the real-time stations within a certain epicentral distance have not contributed picks to the location) its value is set to 0.3, otherwise it is 1.0. The epicentral distance threshold is the middle between the maximum and the average epicentral distance of the stations contributing picks to the location.

The permissible azimuthal gap can be configured (default is 300). If it is exceeded, ‘Azimuthal Gap Check’ is set to 0.2, otherwise it is set to 1.0.

A likelihood of 0.024, therefore, indicates, that all three quality checks failed. If all quality checks succeeded the likelihood is set to 0.99.

scvsmag configuration

scvsmag receives the amplitudes from scenvelope via the messaging system. When the scenvelope is configured to send the amplitudes to the “VS” group instead of “AMPLITUDE”, the configuration must be adjusted. In this case, replace the “AMPLITUDE” group with the “VS” message group in connection.subscriptions:

connection.subscriptions = VS, EVENT, LOCATION, PICK

Consider also the remaining configuration parameters.

scautoloc configuration

Because scautoloc was not designed with EEW in mind, there are a few settings necessary to ensure that location estimates are sent to scvsmag as quickly as possible:

# If this string is non-empty, an amplitude obtained from an amplitude object
# is used by ... . If this string is "mb", a period obtained from the amplitude
# object is also used; if it has some other value, then 1 is used. If
# this string is empty, then the amplitude is set to 0.5 * thresholdXXL, and 1
# is used for the period.
autoloc.amplTypeAbs = snr

# This is the parameter "a" in the equation Δt = aN + b for the time interval
# between origin updates.
autoloc.publicationIntervalTimeSlope = 0

# This is the parameter "b" in the above mentioned equation for the update
# interval Δt.
autoloc.publicationIntervalTimeIntercept = 0

# Minimum number of phases.
autoloc.minPhaseCount = 6

For scautoloc to provide locations with 6 stations, its grid configuration file requires to be setup with equal or lower minimum pick count, and with a corresponding maximum station distance to avoid false alerts.

For scautopick to provide snr amplitudes quickly requires the following setting:

# The time window used to compute a maximum (snr) amplitude on the filtered
# waveforms.
thresholds.amplMaxTimeWindow = 1

scevent configuration

For scevent to create an event from an origin with 6 phases requires the following setting:

# Minimum number of Picks for an Origin that is automatic and cannot be
# associated with an Event to be allowed to form an new Event.
eventAssociation.minimumDefiningPhases = 6

scautoloc also has a so-called XXL feature that allows you to create a location estimate with 4 P-wave detections (otherwise 6 is the minimum). Although this feature is reserved for large magnitude events you can, in principle, adapt the XXL thresholds to also locate moderate seismicity with the first four picks. This may, however, lead to a larger number of false alerts and it is, therefore, recommended to used this feature only as intended.

Note

If scvsmag receives identical picks from different pipelines, the internal buffering fails. The missing picks are automatically retrieved from the database if necessary and if a connection to the database has been established. Alternatively, if picking is done on the same streams in several pipelines, they can be distinguished by modifying their respective public IDs.

References

Borcherdt, R. D., 1994: Estimates of Site-Dependent Response Spectra for Design (Methodology and Justification), Earthquake Spectra

[1]http://www.seismo.ethz.ch/en/research-and-teaching/products-software/EEW/Virtual-Seismologist/
[2]http://www.seismo.ethz.ch/static/seiscomp_contrib/license.txt

Configuration

etc/defaults/global.cfg
etc/defaults/scvsmag.cfg
etc/global.cfg
etc/scvsmag.cfg
~/.seiscomp3/global.cfg
~/.seiscomp3/scvsmag.cfg

scvsmag inherits global options.

vsmag.siteEffect

Type: boolean

Choose whether to use Vs30 base site effect corrections (see also the option ‘vsmag.vs30filename’). Default is false.

vsmag.vs30filename

Type: string

A ascii grid file of Vs30 values conforming to the standard ShakeMap format. Each line contains a comma separated list of longitude, latitude and the VS30 value for one grid point. Longitudes and latitudes have to increase with longitudes increasing faster than latitudes. Default is your-vs30-gridfile.txt.

vsmag.vs30default

Type: double

Define a default Vs30 value for points not covered by the grid file given with ‘vsmag.vs30filename’. Default is 910.

vsmag.eventExpirationTime

Type: int

This defines the time-span after an event’s origin time during which the VS magnitude is re-evaluated every second. After origin-time + eventExpirationTime the evaluation will stop. Default is 45.

vsmag.ExpirationTimeReference

Type: string

Choose whether to time the event expiration time with respect to the origin time (‘ot’) or the time of the first VS estimates creation time (‘ct’). Default is ct.

vsmag.clipTimeout

Type: int

Define the number of seconds following a clipped record that a stream is not used for magnitude estimation. Default is 30.

vsmag.twstarttime

Type: int

These two parameters define the timewindow around picks in which scvsmag looks for maximum amplitudes. twstarttime defines the time before the pick and twendtime the time after the pick Default is 4.

vsmag.twendtime

Type: int

These two parameters define the timewindow around picks in which scvsmag looks for maximum amplitudes. twstarttime defines the time before the pick and twendtime the time after the pick Default is 35.

vsmag.mode

Type: string

You can choose between ‘realtime’ and ‘playback’ mode. In ‘realtime’ mode VS magnitudes are evaluated based on a realtime timer. In ‘playback’ mode the timing is determined by incoming envelope values (i.e. the internal timing is always set to the latest envelope arrival. Default is realtime.

vsmag.backslots

Type: int

Time in seconds with respect to the current Time that envelope values are kept in memory. Envelope values with a timestamp that is older than current Time - vsmag.backslots will be deleted/rejected. Default is 6000.

vsmag.headslots

Type: int

Time in seconds in the future with respect to the current Time that envelope values are kept in memory. This feature can be of interest if scenvelope and scvsmag do not run on the same machine. A difference between the internal clocks can generate envelope messages with a timestamp in the future relative to the receiving machine. Default is 65.

vsmag.maxepicdist

Type: double

This defines a cutoff epicentral distance in kilometers; stations further than that won’t be used for magnitude computation; a negative value means no cutoff is applied. Default is 200.

vsmag.maxazgap

Type: double

This defines a cutoff azimuthal gap in degrees. For origins with a larger azimuthal gap the likelihood will be very small. If you don’t want to apply this criterion set it to 360. Default is 300.

vsmag.logenvelopes

Type: boolean

This toggles envelope logging. Note that this will produce very large files and may fill up your disk if left on for too long. Default is false.

Command-line

Generic

-h, --help

show help message.

-V, --version

show version information

--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, eg scautopick -> scautopick2.

--plugins arg

Load given plugins.

-D, --daemon

Run as daemon. This means the application will fork itself and doesn’t need to be started with &.

--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).

--shutdown-master-module arg

Sets 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.

--shutdown-master-username arg

Sets 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.

Verbosity

--verbosity arg

Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info, 4:debug

-v, --v

Increase verbosity level (may be repeated, eg. -vv)

-q, --quiet

Quiet mode: no logging output

--component arg

Limits the logging to a certain component. This option can be given more than once.

-s, --syslog

Use syslog logging back end. The output usually goes to /var/lib/messages.

-l, --lockfile arg

Path to lock file.

--console arg

Send log output to stdout.

--debug

Debug mode: –verbosity=4 –console=1

--log-file arg

Use alternative log file.

Messaging

-u, --user arg

Overrides configuration parameter connection.username.

-H, --host arg

Overrides configuration parameter connection.server.

-t, --timeout arg

Overrides configuration parameter connection.timeout.

-g, --primary-group arg

Overrides configuration parameter connection.primaryGroup.

-S, --subscribe-group arg

A group to subscribe to. This option can be given more than once.

--encoding arg

Overrides configuration parameter connection.encoding.

--start-stop-msg arg

Sets sending of a start- and a stop message.

--test

Test mode, no messages are sent

Database

--db-driver-list

List all supported database drivers.

-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”.

--config-module arg

The configmodule to use.

--inventory-db arg

Load the inventory from the given database or file, format: [service://]location

--db-disable

Do not use the database at all