scautopick¶

Phase detection and picking on waveforms.

Description¶

scautopick applies threshold monitoring by searching for waveform anomalies in form of changes in amplitudes. It is applied for detecting phase arrivals creating phase picks and for measuring related features and amplitudes. The picks and associated amplitudes and features are typically provided to modules like scautoloc for locating the source.

Note

Instead of detecting phase arrivals for source location, scautopick can also be applied for detecting simple amplitude exceedence applying filters like the MAX() filter. Exceedences are reported as picks and can be processed further, e.g. by scalert.

Phase Detections¶

scautopick detects phase onsets for generating picks. Initally, it searches for detections on the waveform streams defined by global bindings.

P picks¶

A primary detector is applied first. When a detection is found, ‘P’ is by default assigned to the guess of the phase type (phaseHint). The actual guess can be configured by phaseHint. By default the primary detector applies a robust STA/LTA detector (STALTA() filter) to waveforms for making detections. Other detection filters and filter chains can be choosen from the list of SeisComP filters. A guess of the pick type may be defined by phaseHint.

Waveforms are typically pre-filtered before the actual STALTA() filter. Without further configuration a running-mean highpass, a cosine taper and a Butterworth bandpass filter of third order with corner frequencies of 0.7 and 2 Hz are applied before the STALTA() filter. The entire filter sequence is configurable by filter, module configuration, or detecFilter, binding configuration.

Once the STA/LTA ratio has reached a configurable threshold (by default 3) for a particular stream, a pick is set to the time when this threshold is exceeded (pick time) 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 (default).

The trigger thresholds are configurable:

Trigger on: thresholds.triggerOn in module configuration or trigOn in binding configuration,
Trigger off: thresholds.triggerOff, module configuration or trigOff, binding configuration.

Initial detections can be further adjusted by a second-stage phase re-picker (post picker) as defined by picker. The re-picker should be tuned carefully and global bindings parameters picker.* should be configured accordingly.

After having detected a phase, the re-picker will be inactive and accept no further detection until

The amplitudes measured after filtering (filter in module configuration or detecFilter in binding configuration) fall below the thresholds.triggerOff (module configuration) or trigOff (binding configuration) and
Amplitudes, $A_{trigger}$ , measured after filtering reach or exceed a threshold determined by $T_{minOffset}$ (thresholds.minAmplOffset), $T_{dead}$ (thresholds.deadTime) and the amplitude of the previous pick, $A_{prev}$ :

$A_{trigger} \ge T_{minOffset} + A_{prev} * exp\left(-(dt/T_{dead})^2\right)$

if $T_{dead} > 0$ . Otherwise:

$A_{trigger} \ge T_{minOffset}$

Here, $dt$ is the time passed since the last pick. $T_{minOffset}$ (thresholds.minAmplOffset) is typically similar to the trigger threshold, thresholds.triggerOn (module configuration) or trigOn (binding configuration).

S picks¶

Based on the inital detection or pick a secondary picker may applied be applied, e.g., for picking S phases as defined by spicker. The secondary picker is halted as soon as new detections are made unless killPendingSPickers is inactive.

As for the re-picker also the spicker should be tuned carefully and global bindings parameters spicker.* should be set.

Second-stage pickers available by configuration of `picker` or `spicker`¶
picker name	phase	picker	spicker	global bindings parameters
AIC	P, configurable: `phaseHint`	x		picker.AIC.*
BK	P, configurable: `phaseHint`	x		picker.BK.*
S-L2	S		x	spicker.L2.*

Feature extraction¶

For extracting features related to picks such as polarization parameters configure fx and the related global bindings parameters fx.*.

Amplitude Measurements¶

The second task of scautopick is to calculate amplitudes of a given type for the corresponding magnitude type (see scamp for a list of amplitude types and scmag for the magnitude types). Such amplitudes are required by:

scautoloc for associating phase picks and generating a source location
EEW (earthquake early warning) systems in order to provide rapid amplitudes for magnitudes as soon as source locations are available.

The time window for measuring amplitudes starts at the pick time. The window length is constant and specific to the amplitude type. It can be adjusted in global bindings. For example mb is calculated for a fixed time window of 30 s after the pick, mB for time window of 60s, for MLv a time window of 150 s is estimated to make sure that S-arrivals are inside this time window. The pre-calculated amplitudes are sent out and received by the magnitude tool, scmag. The fixed time window poses a limitation to EEW system. Howver, a speed-up is available with amplitudes.enableUpdate. Read the scamp documentation for more details on amplitude measurements.

PublicID Generation¶

There are two modes of publicID generation of the resulting objects, picks and amplitudes:

Generate standard publicIDs based on publicIDPattern. In addition to the available pattern tokens, scautopick adds four new tokens: @net@, @sta@, @loc@ and @cha@ which are replaced with the corresponding identifiers of the stream the pick or amplitude has been declared on. Furhtermore the new token @type@ was added which refers to the processor type used to create the pick or amplitude. If a pick is created from a detection then the type is “D”. For amplitudes the type is effectively the amplitude type, e.g. “MLv”. Example: the pattern @classname@/@time/%Y%m%d%H%M%S.%f@.@id@/@net@.@sta@.@loc@.@cha@/@type@ results in Pick/20260210.123456.89.321/GE.MORC..BHZ/AIC.
Generate simplified publicIDs as with SeisComP3 with pattern @time@-@type@-@sid@. Example: 20260210.123456.89-P-GE.MORC..BHZ. To enable that mode, set simplifiedIDs to true.

Modes of Operation¶

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.

Real-time¶

In real-time mode the workflow draws like this:

scautopick reads all of its binding parameters and subscribes to stations defined by global binding parameters 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, a trigger will be sent in any case for e.g. debugging.
After the primary stage has finished (detector only or picker) secondary pickers will be launched if configured with spicker.

These steps repeat for any incoming record.

To run scautopick in the background as a daemon module enable and start it

$ seiscomp enable scautopick
$ seiscomp start scautopick

For executing on the command line simply call it with appropriate options, e.g.

$ seiscomp exec scautopick -h

Non-real-time¶

Note

Due to code changes in the file data source, the command line option --playback is essential for non-real-time operation. 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 defined 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. Example:

$ 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, scautopick will exit. The processing steps are similar to the online mode.

Use the --ep for offline processing without messaging. The results are printed in SCML format. Example:

$ scautopick --playback -I data.mseed --ep -d [type]://[host]/[database] > picks.xml

Module Configuration¶

etc/defaults/global.cfg
etc/defaults/scautopick.cfg
etc/global.cfg
etc/scautopick.cfg
~/.seiscomp/global.cfg
~/.seiscomp/scautopick.cfg

scautopick inherits global options.

ringBufferSize¶

Default: 300

Type: int

Unit: s

Defined the record ringbuffer size in seconds.

leadTime¶

Default: 60

Type: int

Unit: s

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

playback¶

Default: false

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.

initTime¶

Default: 60

Type: int

Unit: s

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

gapInterpolation¶

Default: false

Type: boolean

Interpolate gaps linearly? This is valid for gaps shorter than thresholds.maxGapLength.

useAllStreams¶

Default: true

Type: boolean

If enabled, all streams that are received by the picker are used for picking. 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 is subscribed to.

filter¶

Default: "RMHP(10)>>ITAPER(30)>>BW(4,0.7,2)>>STALTA(2,80)"

Type: string

The default filter used for making detections. Station-specific configurations (bindings) override this value.

timeCorrection¶

Default: -0.8

Type: double

Unit: s

The time correction applied for a pick. Station-specific values (bindings) override this value.

picker¶

Type: string

Values: AIC,BK,GFZ

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

More options may be available by plugins. Configure related parameters in global bindings.

phaseHint¶

Default: P

Type: string

Phase hint to be assigned to the pick made by the primary picker.

sendDetections¶

Default: false

Type: boolean

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

spicker¶

Type: string

Values: S-L2,S-V

The secondary picker to use, e.g., for picking S-phases.

More options may be available by plugins. Configure related parameters in global bindings.

killPendingSPickers¶

Default: true

Type: boolean

If enabled, 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.

allowSPickersWithDetections¶

Default: false

Type: boolean

If a picker is configured and does not create a pick due to low snr and if this flag is set to true then a secondary picker will nevertheless be created triggered at the detection time. This allows S picks without having P picks.

extraPickComments¶

Default: false

Type: boolean

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

Supported comments:

SNR: added if SNR >= 0, comment id is "SNR"

duration: added if the duration has been computed at the time of the pick creation, which actually requires "thresholds.maxDuration" to be configured with a non-negative value.

simplifiedIDs¶

Default: false

Type: boolean

If enabled, then simplified pick and amplitude IDs will be created. Rather than the configured publicID pattern, the following pattern will be used: "%Y%m%d.%H%M%S.%f-@net.sta.loc.cha@".

fx¶

Type: string

Values: DFX

Configures the feature extraction method to be used. Currently available: "DFX". Other methods may be available by plugins. Configure DFX-related parameters in global bindings.

When configured, the usability of the features for locating events depends on locator, e.g., LOCSAT may consider slowness and backazimuth depending on the configuration of LOCSAT but other locators such as Hypo71 or NonLinLoc do not. Read the locator’s documentation and configuration parameters.

amplitudes¶

Default: MLv, mb, mB

Type: list:string

The amplitude types to be computed by the picker based on picks. Fix and potentially long time windows will apply for amplitude measurements. scamp may be the preferable module reducing the amount of amplitudes measured and stored in database and allowing for distance-dependent time windows.

However, scautoloc needs mb amplitudes by default. mb amplitudes should therefore be measured by scautopick.

Note

thresholds.* Threshold parameters for the primary picker.

thresholds.triggerOn¶

Default: 3

Type: double

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

thresholds.triggerOff¶

Default: 1.5

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 override this value.

thresholds.maxGapLength¶

Default: 4.5

Type: double

Unit: s

The maximum gap length in seconds to handle. Gaps larger than this will cause the picker to be reset.

thresholds.amplMaxTimeWindow¶

Default: 10

Type: double

Unit: s

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

thresholds.deadTime¶

Default: 30

Type: double

Unit: s

The time used together with measured amplitude and thresholds.minAmplOffset for scaling the amplitude below which the picker is inactive after a P pick. Read the documentation!

thresholds.minAmplOffset¶

Default: 3

Type: double

The amplitude used together with measured amplitude and thresholds.deadTime for scaling the amplitude below which the picker is inactive after a P pick. The value is typically similar to the trigger threshold. Read the documentation!

thresholds.minDuration¶

Default: -1

Type: double

Unit: s

The minimum duration to reach. The duration is measured as the time between trigger on and trigger off. If this value is configured, the detection (pick) will be delayed in order to compute and check the duration.

The duration will be reported as comment to the pick when activating "extraPickComments" allowing the tuning of the acceptable duration range.

thresholds.maxDuration¶

Default: -1

Type: double

Unit: s

The maximum duration allowed. The duration is measured as the time between trigger on and trigger off. If this value is configured, the detection (pick) will be delayed in order to compute and check the duration. Negative values deactivate the check.

The duration will be reported as comment to the pick when activating "extraPickComments" allowing the tuning of the acceptable duration range.

amplitudes.enableUpdate¶

Type: list:string

Configure a list of amplitude types to be updated and sent as soon as data is available. Prevents waiting for complete data within time windows speeding up magnitude computation. This option therefore supports rapid magnitude estimation for EEW but its configuration increases the load on your SeisComP system!

Note: Amplitude types configured here must also be configured in "amplitudes"

connection.amplitudeGroup¶

Default: AMPLITUDE

Type: string

Message group for sending amplitudes to.

Note

comment.* Properties of a custom comment added to a pick. It requires both ID and text to be configured.

comment.ID¶

Type: string

The ID of a custom comment.

comment.text¶

Type: string

The text of a custom comment.

Bindings Parameters¶

detecEnable¶

Default: true

Type: boolean

Enables/disables picking on a station.

detecFilter¶

Default: "RMHP(10)>>ITAPER(30)>>BW(4,0.7,2)>>STALTA(2,80)"

Type: string

Defines the filter to be used for picking.

trigOn¶

Default: 3

Type: double

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

trigOff¶

Default: 1.5

Type: double

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

timeCorr¶

Default: -0.8

Type: double

Unit: s

The time correction applied to a pick.

sensitivityCorrection¶

Default: false

Type: boolean

Defines whether the detector applies sensitivity correction (applying the gain) or not in advance to filter the data.

Command-Line Options¶

Generic¶

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

--config-file file¶: The alternative module configuration file. When this option is used, the module configuration is only read from the given file and no other configuration stage is considered. Therefore, all configuration including the definition of plugins must be contained in that file or given along with other command-line options such as --plugins.

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

-h, --help¶: Show help message.

--plugins arg¶: Load given plugins.

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

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

-V, --version¶: Show version information.

Verbosity¶

--component arg¶: Limit the logging to a certain component. This option can be given more than once.

--console arg¶: Send log output to stdout.

--debug¶: Execute in debug mode. Equivalent to --verbosity=4 --console=1 .

--log-file arg¶: Use alternative log file.

-l, --lockfile arg¶: Path to lock file.

-q, --quiet¶: Quiet mode: no logging output.

-s, --syslog¶: Use syslog logging backend. The output usually goes to /var/lib/messages.

-v, --v¶: Increase verbosity level (may be repeated, e.g., -vv).

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

Messaging¶

--content-type arg¶

Overrides configuration parameter connection.contentType.

Default: binary

-H, --host arg¶: Overrides configuration parameter connection.server.

-g, --primary-group arg¶: Overrides configuration parameter connection.primaryGroup.

--start-stop-msg arg¶

Default: 0

Set sending of a start and a stop message.

-S, --subscribe-group arg¶: A group to subscribe to. This option can be given more than once.

-t, --timeout arg¶: Overrides configuration parameter connection.timeout.

-u, --user arg¶: Overrides configuration parameter connection.username.

Database¶

--config-module arg¶: The config module to use.

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

--db-driver-list¶: List all supported database drivers.

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

--record-file arg¶: Specify a file as record source.

-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 and simply the name of a miniSEED file can be given.

--record-type arg¶: Specify a type for the records being read.

Mode¶

--amplitudes arg¶

Default: 1

Enables or disables computation of amplitudes.

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

--ep¶: Outputs an XML event parameters file containing all picks and amplitudes. This option implies ‘--offline’. Consider ‘--playback’ or configure accordingly for processing data from the past.

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

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

Settings¶

--ampl-max-time-window arg¶: Overrides configuration parameter thresholds.amplMaxTimeWindow.

--any-stream arg¶: Overrides configuration parameter useAllStreams.

--before timespan¶: Overrides configuration parameter leadTime.

--buffer-size timespan¶: Overrides configuration parameter ringBufferSize.

--extra-comments¶: Overrides configuration parameter extraPickComments.

--filter filter¶: Overrides configuration parameter filter.

--gap-interpolation arg¶: Overrides configuration parameter gapInterpolation.

--gap-tolerance arg¶: Overrides configuration parameter thresholds.maxGapLength.

--init-time timespan¶: Overrides configuration parameter initTime.

--min-ampl-offset arg¶: Overrides configuration parameter thresholds.minAmplOffset.

--send-detections¶: Overrides configuration parameter sendDetections.

--time-correction time¶: Overrides configuration parameter timeCorrection.

--trigger-dead-time arg¶: Overrides configuration parameter thresholds.deadTime.

--trigger-off arg¶: Overrides configuration parameter thresholds.triggerOff.

--trigger-on arg¶: Overrides configuration parameter thresholds.triggerOn.

Output¶

-f, --formatted¶: Use formatted XML output along with ‘--ep’. Otherwise XML is unformatted.

scautopick¶

Description¶

Phase Detections¶

P picks¶

S picks¶

Feature extraction¶

Amplitude Measurements¶

PublicID Generation¶

Modes of Operation¶

Real-time¶

Non-real-time¶

Module Configuration¶

Bindings Parameters¶

Command-Line Options¶

Generic¶

Verbosity¶

Messaging¶

Database¶

Records¶

Mode¶

Settings¶

Output¶

Table of Contents

Previous topic

Next topic

This Page