scautopick

Makes picks on waveforms.

Description

scautopick searches for waveform anomalies in form of changes in amplitude. It basically applies a robust sta/lta algorithm to the waveform streams which have been filtered before with a Butterworth filter of third order with corner frequencies of 0.7 and 2 Hz. Once the sta/lta ratio reached a specific value (by default 3) for a particular stream, a pick is set to the time when this threshold is exceeded. Once the ratio reaches a factor of 3, a pick is created and the picker is set inactive. The picker is reactivated for this stream once the sta/lta ratio falls to the value of 1.5.

The second task of scautopick is to calculate amplitudes for given magnitude types where the time window starts at the pick time. For example mb is calculated for a fixed time window of 30s after the pick, mB for time window of 60s, for MLv a time window of 150s is estimated to make sure that S-arrivals are inside this time window. The precalculated amplitudes are sent out and received by the magnitude tool.

scautopick usually runs in the background connected to a real-time data source such as Seedlink. This is referred to as online mode. Another option to run scautopick is on offline mode with files.

Online mode

In online mode the workflow draws like this:

• scautopicks reads all of its bindings and subscribes to stations where detecEnable is set to true
• the data time window requested from the data source is [system-leadTime, NULL] meaning an open end time that causes Seedlink to stream real-time data if no more data are in the buffers
• each incoming record is filtered according to detecFilter
• the samples are checked for exceedance of trigOn and in the positive case either a post picker (picker) is launched or a Pick object will be sent
• if sendDetections is set to true trigger will be sent in any case for e.g. debugging
• after the primary stage has finished (detector only or picker) a secondary picker will be launched if configured with spicker

These steps repeat for any incoming record.

Offline mode

Note

Due to code changes in the file data source the command line option –playback is essential otherwise a real-time time window is set and all records are most likely filtered out.

To tune scautopick or to do playbacks it is helpful to run scautopick not with a real-time data source but on a data set, e.g. a multiplexed sorted MiniSEED volume. scautopick will apply the same workflow as in online mode but the acquisition of data records has to change. If the input data (file) has been read scautopick will exit and furthermore it must not ask for a particular time window, especially not for a real-time time window. To accomplish that the command line parameter --playback has to be used.

$ scautopick --playback -I data.mseed

This call will process all records in data.mseed for which bindings exist and send the results to the messaging. If all data records are processed scautpick will exit. The processing steps are similar to the online mode.

Configuration

etc/defaults/global.cfg

etc/defaults/scautopick.cfg

etc/global.cfg

etc/scautopick.cfg

~/.seiscomp3/global.cfg

~/.seiscomp3/scautopick.cfg

scautopick inherits global options.

filter

Type: string

Defines the default filter used for picking. Station specific configurations will override this value.

timeCorrection

Type: double

Unit: s

Time correction applied for each pick made. Station specific values override this value. Default is -0.8.

ringBufferSize

Type: int

Unit: s

Defined the record ringbuffer size in seconds. Default is 300.

leadTime

Type: int

Unit: s

The leadTime defines the time in seconds to start picking on waveforms before current time. Default is 60.

initTime

Type: int

Unit: s

The initTime defines a timespan in seconds for that the picker is blind after initialization. This time is needed to initialize the filter and depends on it. Default is 60.

gapInterpolation

Type: boolean

Interpolate gaps linearily? This is valid for gaps shorter than thresholds.maxGapLength. Default is false.

amplitudes

Type: list:string

Defines the amplitude types to be computed by the picker as well. Default is MLv, mb, mB.

picker

Type: string

Configures the picker to use. By default only a simple detections are emitted as picks. To enable real picking on a time window around the detection, an algorithm (plugin) can be defined with this parameter.

spicker

Type: string

Configures the secondary picker to use.

fx

Type: string

Configures the feature extraction type to use.

useAllStreams

Type: boolean

If enabled the all streams are used for picking that are received by the picker. This option has only effect if a file is used as input which contains more data than the picker requests. If connected to a waveform server such as SeedLink the picker will only receive the data it subscribed to. Default is true.

killPendingSPickers

Type: boolean

If enabled the all secondary pickers that were triggered by a previous pick will be terminated when a new detection or pick has been found. This aims to avoid the case where an S phase is wrongly picked as P but would also be picked as S by the secondary picker. But suppressing the S pick can lead to undesired results. It might be better in some situations to have two picks (P and S) instead only a wrong P. Default is true.

sendDetections

Type: boolean

If enabled and picker is configured, then detections are sent as well. To distinguish between detections and picks the evaluation mode of the pick is set to manual. This is meant to be a debug option which can be used to compare detections and picks by their evaluation mode. Default is false.

extraPickComments

Type: boolean

If enabled and picker or spicker is configured, then extra comments will be added to the resulting pick.

Supported comments:

SNR: added if SNR >= 0, comment id is “SNR” Default is false.

playback

Type: boolean

If enabled, picks can be made on waveforms which are older than current time - leadTime. Current time is the time when the module was started. This allows to pick historic data in real-time playbacks which are preserving the record times. See e.g. the msrtsimul module. This option deactivates leadTime. Activate only for playbacks. Default is false.

thresholds.triggerOn

Type: double

For which value on the filtered waveforms is a pick detected. Station specific values override this value. Default is 3.

thresholds.triggerOff

Type: double

The value the filtered waveforms must reach to enable detection again. Between triggerOn and triggerOff the picker is blind and does not produce picks. Station specific values ovveride this value. Default is 1.5.

thresholds.maxGapLength

Type: double

Unit: s

The maximum gap length in seconds to handle. Gaps larger than this will cause the picker to be resettet. Default is 4.5.

thresholds.amplMaxTimeWindow

Type: double

Unit: s

The time window used to compute a maximum (snr) amplitude on the filtered waveforms. Default is 10.

thresholds.deadTime

Type: double

Unit: s

The dead time in seconds. Default is 30.

thresholds.minAmplOffset

Type: double

Default is 3.

connection.amplitudeGroup

Type: string

Group used to send amplitudes to. Default is AMPLITUDE.

Bindings

Configuration

detecEnable

Type: boolean

Enables/disables picking on a station. Default is true.

detecFilter

Type: string

Defines the filter to be used for picking. Default is "RMHP(10)>>ITAPER(30)>>BW(4,0.7,2)>>STALTA(2,80)".

trigOn

Type: double

For which value on the filtered waveform is a pick detected. Default is 3.

trigOff

Type: double

The value the filtered waveform must reach to enable a detection again. Default is 1.5.

timeCorr

Type: double

Unit: s

The time correction applied to a detected pick. Default is -0.8.

sensitivityCorrection

Type: boolean

Defines whether the detector applies sensitivity correction (applying the gain) or not in advance to filter the data. 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.

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

Records

--record-driver-list

List all supported record stream drivers

-I, --record-url arg

The recordstream source URL, format: [service://]location[#type]. “service” is the name of the recordstream driver which can be queried with “–record-driver-list”. If “service” is not given “file://” is used.

--record-file arg

Specify a file as record source.

--record-type arg

Specify a type for the records being read.

Mode

--offline

Do not connect to a messaging server and do not use the database.

--playback

Switches to playback mode which does not request a particular time window from the input data source. This implies that all records are forwarded to scautopick if files are being used. Without this option scautopick sets the requested start time to NOW-leadTime and therefore would not work anymore with older datasets in offline mode or when running playbacks.

--ep

Outputs an XML event parameters file containing all picks and amplitudes. This option implies offline.

--amplitudes arg

Enables or disables computation of amplitudes.

--test

Runs the picker as usual but does not send any messages. This can be useful to test the picker within a running system.

--dump-config

Dumps the current configuration and exits. Station configuration is only read if the picker connects to the messaging and the database. In offline mode it will only dump the application specific setting unless a station.conf file is provided.

--dump-records

This option only works in combination with --offline. It will dump the data of an amplitude processor if it completed processing successfully and a new amplitude is available. The output format is a simple ASCII format.

Settings

--filter filter

Overrides configuration parameter filter.

--time-correction time

Overrides configuration parameter timeCorrection.

--buffer-size timespan

Overrides configuration parameter ringBufferSize.

--before timespan

Overrides configuration parameter leadTime.

--init-time timespan

Overrides configuration parameter initTime.

--trigger-on arg

Overrides configuration parameter thresholds.triggerOn.

--trigger-off arg

Overrides configuration parameter thresholds.triggerOff.

--trigger-dead-time arg

Overrides configuration parameter thresholds.deadTime.

--ampl-max-time-window arg

Overrides configuration parameter thresholds.amplMaxTimeWindow.

--min-ampl-offset arg

Overrides configuration parameter thresholds.minAmplOffset.

--gap-tolerance arg

Overrides configuration parameter thresholds.maxGapLength.

--gap-interpolation arg

Overrides configuration parameter gapInterpolation.

--any-stream arg

Overrides configuration parameter useAllStreams.

--send-detections

Overrides configuration parameter sendDetections.

--extra-comments

Overrides configuration parameter extraPickComments.