sceval

gempa module to evaluate the goodness of origins setting the origin status or comments

Description

sceval provides multiple evaluation methods to identify and to flag real and fake origins or to identify origins that have particular properties. Flagging is achieved by changing the origin evaluation status by one of the available methods. Comments are added to the evaluated origins for documenting the evaluation method along with properties. Only origin passing configurable filters are considered.

The evaluation status for origins considered real or false are flagged as confirmed or rejected, respectively. Origins that cannot be flagged by one of the evaluation methods are kept unflagged.

sceval also provides the plugin evsceval for scevent [5] for evaluating origin evaluation status and comments set by sceval to determine the event type and certainty, respectively.

Filtering

Origins

Origins are filtered before evaluation and only origins passing the configurable filters are evaluated:

  • Author of origin: origin.authorWhiteList allows setting the author(s) of incoming origins. Origins from all other authors are ignored.

  • Origin evaluation mode: origin.manual allows treating manual origins. Without activating the parameter, manual origins are ignored.

  • Origin evaluation status: origin.ignoreStatus determines that origins with the given evaluation status are ignored. By default, any origin having already an evaluation status is ignored and the evaluation status is not set again by sceval. An important use case is the application of sceval to origins created by ccloc [1] or XXL origins from scautoloc [3]. These origins received the evaluation status ‘preliminary’ by the creating module and it may be undesired to change status. Read the documentation of the corresponding module and remove the evaluation status from origin.ignoreStatus for evaluating such origins.

Picks

Phase picks, hence arrivals, are considered used when any of the parameter pick time, slowness or backazimuth is used.

Evaluation Methods

Various evaluation methods evaluate the quality of the origins setting either the evaluation status of the origin or adding a comment to the origin. The status is either set to ‘rejected’ or ‘confirmed’. The comment can be evaluated by scevent [5] using the plugin evsceval. The plugin is provided by the sceval package.

The origin evaluation is performed in the following methods in the given order:

  1. minPhase: Set origin status to ‘rejected’.

  2. minDepth: Set origin status to ‘rejected’.

  3. maxDepth: Set origin status to ‘rejected’.

  4. maxRMS: Set origin status to ‘rejected’.

  5. minPhaseConfirm: Set origin status to ‘confirmed’.

  6. maxGap: Add an origin comment.

  7. Station - distance evaluation (main evaluation method): Set origin status to ‘rejected’ or ‘confirmed’.

  8. Extended gap criterion: Set origin status to ‘confirmed’.

The evaluation is finished when one method explicitly declares the evaluation status of an origin. If the methods neither allow confirmation nor rejection, the origin status remains unchanged. Only the extended gap criterion check may re-evaluate origins after the station - distance evaluation. The re-evaluation by the extended gap check allows to confirm origins which where rejected before. Such origins are typically found in remote areas, e.g., mid-ocean ridges.

../_images/evaluation.png

Figure 1: Methods for origin evaluation.

By default manually processed origins are excluded from evaluation. Manually processed origins can be explicitly evaluated by setting the origin.manual parameter.

For evaluation of origins by their arrivals only arrivals with weight > 0 are considered.

minPhase

Sets origin evaluation status: rejected

Minimum number of used phases: An origin is rejected if the number of used phases (arrivals) is less than minPhase. Unused phases, i.e. phases with zero weight, are not counted.

minPhase may be over-ruled by distanceProfilesMinPhase: Unless distanceProfilesMinPhase <= 0, the test is skipped if the number of used phases >= distanceProfilesMinPhase allowing for the station - distance evaluation.

Background

Setting minPhase allows locator tools such as scautoloc [3] or scanloc [2] to publish origins with only few arrivals. Those origins can be later safely rejected by sceval but are kept in the database for manual evaluation.

minDepth

Sets origin evaluation status: rejected

Minimum origin depth: An origin is rejected if the depth of the origin is less than minDepth.

Background

Some locators may map poorly constrained origins at negative source depths, hence above datum or origins at shallow depth shall be treated specifically by other applications such as [5]. Such origins can be flagged and given the evaluation status rejected.

maxDepth

Sets origin evaluation status: rejected

Maximum origin depth: An origin is rejected if the depth of the origin is larger than maxDepth.

Background

Seismic networks sometimes detect teleseismic phases from large events. The location from such detections may result in very deep events. The same is true for networks monitoring mines or blasts. Those origins can be later safely rejected by sceval but are kept in the database for manual evaluation.

maxRMS

Sets origin evaluation status: rejected

Maximum RMS residual: An origin is rejected if the RMS residual of the origin is larger than maxRMS.

Background

Large RMS residuals may be indicative of low-quality origins. While modules like scautoloc [3] or scanloc [2] check the RMS as a quality measure before sending an origin others may not do so. Origins with large RMS can be safely rejected by sceval but are kept in the database for later evaluation.

minPhaseConfirm

Sets origin evaluation status: confirmed

Number of used phases reaches a threshold: An origin is confirmed if the number of used phases (arrivals) is equal or larger than minPhaseConfirm. Unused phases, i.e. phases with zero weight, are not counted.

Background

The methods applies to areas with dense station coverage but variable data quality. It usually happens that origins with few arrivals nearby the event are confirmed by the Station - evaluation. If the event is large enough it may be recorded at more stations with sufficiently low background noise while others with higher noise at similar do not provide detections. In such cases sceval may not confirm such origins and scevent [5] may prefer the confirmed origin with viewer arrivals over the origin with more arrivals. However, if the number of arrivals is large, you may wish to safely confirm an origin. Set minPhaseConfirm sufficiently high and according to the network layout and quality to cope with such situations.

maxGap

Declares: property - sets the comment maxGap.

Maximum azimuthal gap: Origins receive the comment “maxGap” if the maximum azimuthal gap exceeds maxGap. The comment is evaluated by scevent [5] if the plugin evsceval loaded.

Background

The maximum azimuthal gap is the largest azimuthal between two neighboring stations with respect to the origin. The stations are sorted by their azimuth (Figure: Gap criterion).

../_images/gapcriterion.png

Station - distance evaluation

Sets origin evaluation status: rejected or confirmation

The station - distance evaluation is only performed if distanceProfiles contains at least one valid profile and if the origin has a higher number of arrivals with non-zero weight than distanceProfilesMinPhase. sceval currently only evaluates stations that have P-wave arrivals.

The number of available stations within configurable distance intervals are compared with the number of stations that have picked arrivals of P waves associated to the tested origin. By default, epicental distance is considered as a distance measure. Activate mismatchScore.useHypocentral for considering hypocentral distance.. The distance intervals and the weights for the intervals are given by distanceProfile.$name.weights.

Background

For real origins, thus real seismic events, the number of arrivals typically decreases with distance as compared to the number of available stations (Figure: real event).

../_images/sceval_real_event.png

Example of an origin for a real seismic event with number of available stations, picks (arrivals) and the distance-dependent weights (distanceProfile.$name.weights).

For fake origins, distant stations may have a proportionally higher number of arrivals as compared to close stations (Figure: fake event).

../_images/sceval_fake_event.png

Example of a fake origin with number of available stations, picks (arrivals) and the distance-dependent weights (distanceProfile.$name.weights).

Based on the distance profile a mismatchScore is computed and compared against limits in order to origins confirm as real seismic events or to reject origins. For a mismatchScore lower or equal to mismatchScore.confirmed, the origin is flagged confirmed. For a mismatchScore lower or equal to mismatchScore.rejected, the origin is flagged rejected.

It is expected that closer stations have a higher chance to detect real earthquakes thus have a higher chance to have arrivals.

The mismatchScore is therefore calculated as a distance-dependent weighted mismatchScore comparing the number of available stations with the number of stations that have arrivals in a weighted scheme.

mismatchScore =\ &\frac{\sum_{i=1}^{10}weight_i*\frac{stationCount_i - arrivalCount_i}{stationCount_i}}{\sum_{i=1}^{10}weight_i}

where

  • i is the index over the intervals within the configurable distance range,

  • stationCount is the number of available stations,

  • arrivalCount is the number of associated arrivals and

  • weight is the configurable weight (distanceProfile.$name.weights)

within a defined distance interval.

Setup

Distance-dependent weight profiles for distances less than distanceProfile.$name.max can be defined and included by the profile name given using distanceProfiles.

The usage of the distance-dependent weight profile is controlled by the largest epicentral distance of stations with P phase picks for a considered event. The profile among all profiles is used that has the smallest distanceProfile.$name.max that is larger than the largest epicentral distance. If the largest epicentral distance is larger than the largest distanceProfile.$name.max from all available profiles, then the default profile is used as non-configurable fallback.

Note

Parameters of the default profile:

distanceProfile.$name.max = 180.0
distanceProfile.$name.weights = "1.0,0.75,0.5,0.25,0.01,0.01,0.01,0.01,0.01,0.01".

The weights (distanceProfile.$name.weights) are configured for equally-spaced distance intervals. The distance intervals are dynamically bound between 0 degree and the maximum epicentral distance for a considered event. The number of distance intervals is given by the number of weights (distanceProfile.$name.weights). Typically, 10 intervals are used. Higher weight should be given to lower distances.

Extended gap

Sets origin evaluation status: confirmed

Extended gap criterion: Origins are confirmed if the number of used observed phases (arrivals) \ge: gapMinPhase AND the maximum azimuthal gap \le: maxGap. Setting gapMinPhase <= 0 disables the extended gap criterion. Unused phases, i.e. phases with zero weight, are not counted. The confirmation overwrites the origin status if set to rejected by the station - distance evaluation.

Background

Origins meeting the gap criterion may be later rejected, e.g. by the station - distance evaluation. Rejection may even happen for real events when the epicentral distances to the closest stations are large, e.g. for remote earthquakes at mid-ocean ridges.

Origins of those events may be explicitly confirmed by the extended gap criterion.

Origin Evaluation Status

The evaluation status of an origin will be updated upon its change due to the evaluation methods and a descriptive origin comment is written to the origin.

However, the evaluation status may be changed at different times by different modules. In order to track this history a journal entry is created and sent when running sceval with a connection to the SeisComP messaging or added to the XML output long with the origins. In future versions of SeisComP such journal entries will be accessible in scolv [7].

Origin Comments in Events List

The different algorithms add comment fields to the origin objects which can be used to identify the processing. When an evaluation method triggers an action, a comment indicating the algorithm is added to the origin parameters:

  1. scevalMethod - the evaluation algorithm that has changed the origin status

  2. mismatchScore - the mismatch score resulting from the Station - Distance evaluation

  3. maxGap - comment indicating that the station GAP exceeds the configured maxGap.

The comments can be shown in the Events list, e.g. of scolv, in a custom column.

../_images/sceval_scolv_custom_column.png

Figure 5: scolv with a custom column showing the mismatchScore.

Configuration of Events list:

  • Showing the mismatchScore in the Events table. Add to scolv.cfg or to global.cfg:

    eventlist.customColumn.name = "mismatchScore"

# Define the default value if no comment is present
eventlist.customColumn.default = "-"

# Define the comment id to be used
eventlist.customColumn.originCommentID = mismatchScore

  • Show the comment scevalMethod in the Events table.

    eventlist.customColumn.name = "evaluation method"

# Define the default value if no comment is present
eventlist.customColumn.default = "-"

# Define the comment id to be used
eventlist.customColumn.originCommentID = scevalMethod

Station selection by QC parameters

During real-time evaluation of origins by station - distance statistics sceval [4] accounts for relevant data conditions given by the waveform quality control (QC) parameters and the bindings configuration (CONFIG). Only stations with status enabled and which have a binding of the setup configured by setupName are considered. Typically, setupName defines the phase detector, e.g. :cite::t`scautopick`. Use default for all streams configured by the global bindings. Thus, setupName is used to define the module which delivers the picks. The restriction to a pick module allows to confine sceval specifically to a particular processing pipeline. From the accepted streams only those are considered where the QC parameters meet the value ranges defined in qc.parameters.

Station status updates (station enabled or disabled) are received and considered through the message group CONFIG. When origins arrive with arrivals from disabled stations, then the stations are automatically activated.

In real time, the QC parameters are provided by scqc [9] through the QC message groups of the SeisComP messaging. sceval must therefore subscribe to the message groups of the sending QC system and of the modules sending the origins and arrivals, e.g.:

  • QC

  • CONFIG

  • LOCATION

Note

  1. The names of the message groups may be different by configuration of scmaster [6] and the sending modules.

  2. scqc [9] must be running at all times when running sceval in real time and it must compute the requested QC parameters.

  3. To ignore unavailable QC parameters activate

    • qc.sloppy: only consider available QC parameter but ignore missing ones or

    • qc.noQC: ignore all QC parameters.

Pipelines, Redundancy/Import

In systems with multiple processing pipelines or where external origins are imported from other SeisComP systems origins may have been generated with unconsidered setups (setupName). Typically, they shall not be evaluated.

Pipelines

In a pipeline system generate multiple instances of sceval, one for each pipeline. Example:

seiscomp alias create l1sceval sceval

Configure each instance separately. Consider setupName and connection.subscriptions as well as the message group parameters, connection.subscriptions and connection.primaryGroup.

External origins

External origins can be received from another system, e.g. by the LOCATION or the IMPORT_GROUP message groups. On the other system, the station setup, waveform QC parameters and the configurations in general may be different. Therefore, the local instance of sceval may be inappropriate for processing the external origins. Confinement to origins from particular systems and modules can can be achieved by configuration of origin.agencyWhiteList and origin.authorWhiteList. Whitelist either agencies or authors or both for ignoring origins from other agencies or authors, respectively.

Fast Setup

For a fast initial configuration of sceval consider the following steps:

  1. Define the evaluation methods to be considered and configure the corresponding parameters.

  2. If applying the station - distance evaluation configure

    • setupName according to module providing phase picks,

    • qc.parameters for setting the conditions when to expect phase picks,

    • qc.sloppy for starting the method even if the list of value received for some QC parameters is incomplete. If stations are automatically enabled or disabled by scqceval [8] you may even disable the QC check by activating qc.noQC.

  3. Configure the message group parameters, connection.subscriptions and connection.primaryGroup if sceval is used in a pipeline with non-standard message groups. Consider creating aliases for specific pipelines.

  4. Define evaluation of external origins and origins with given evaluation status by configuration of origin.authorWhiteList and origin.ignoreStatus, respectively.

For a more detailed configuration consider results from playbacks and results from runtime experiences and assisted tuning.

Playbacks

sceval can be used in real-time playbacks or XML-based offline playbacks.

Considerations

  1. At the time of the playback, some waveform QC parameters, e.g. latency, availability, delay, measured at the time of waveform recording may not be available preventing stations to be active for evaluation. The data availability, delay and latency are generally different from values at the time of the data recording.

    Activate qc.sloppy or use --sloppy to activate stations as soon as waveform QC parameters are received and they are in range.

  2. In XML-based real-time playbacks without waveform and offline XML playbacks the waveform QC parameters are generally unavailable for the considered XML data.

    Activate qc.noQC or use --noQC to ignore all QC messages and to activate all stations which have bindings parameters defined by setupName.

  3. In tuning mode or when using XML playback, QC messages are generally ignored and all stations which have bindings parameters defined by setupName are active.

Real-time playbacks

sceval can be used in real-time playbacks of waveforms or in XML playbacks using playback_picks provided with the scanloc package. Waveform QC parameters may be unrealistic during such playbacks. Therefore, the QC parameter ranges defined in qc.parameters should be configured with -inf,inf and the parameter qc.sloppy should be activated by configuration or as command-line option.

XML-based offline playbacks

sceval can be used in offline playbacks for fast data processing of event XML files. The evaluation of waveform QC parameters is inactive during XML-based offline playbacks.

scevent [5] considers the origin status when determining the preferred origin. With the evsceval plugin it may also set the event certainty and type. Therefore, in XML-based playbacks sceval should be executed after running the locator, e.g. scanloc [2], but before scevent (compare with scanloc playbacks [2]):

scanloc --ep picks.xml -d type://user:passwd@host/database --debug > origins.xml
sceval --ep origins.xml -d type://user:passwd@host/database --debug > origins_eval.xml
...
scmag ...
scevent --ep mags.xml -d type://user:passwd@host/database --debug > events.xml

You may also confine evaluation to one or more origins. Provide the option -O with a comma-separated list of their IDs, e.g.:

sceval -d localhost --ep origins.xml -O Origin/abc,Origin/xyz > origins_sceval.xml

Tuning: Station-Distance evaluation

Runtime experiences

The results from the station - distance evaluation, specifically the mismatchScore can be observed during runtime without setting the origin status. The mismatchScore can be observed and compared with the event status set by operators. Eventually, the score limits, mismatchScore.confirmed and mismatchScore.rejected can be configured after a comparison.

Deactivate mismatchScore.use to calculate the mismatchScore without setting the event status. Active a custom column in the Events table in scolv to view the mismatchScore.

Assisted tuning

sceval has a tuning mode for finding an optimum weight profile and thresholds parameters for the station - distance evaluation which can be used to eventually configure sceval:

For convenience the auxiliary tool sceval-tune is provided as a wrapper to run sceval in tuning mode. sceval-tune considers

Invoke the help (-h) to learn about command-line options

sceval-tune -h

Known limitations

In the current version the tuning mode has limitations:

  • QC parameters are not considered.

Work Flow

Recommended work flow for tuning:

  1. Identify the sceval instance to be tuned.

  2. Adjust the configuration of this instance. Set the parameters which are unrelated to the station - distance evaluation and which will evaluate origins before the station - distance evaluation takes an effect (understand figure Methods for origin evaluation. ).

  3. Manually review and evaluate the origin status for many events. Choose “confirmed”, “rejected” or leave the Origin status unflagged.

    Use scolv to manually evaluate the preferred origins of events by setting the origin status. During evaluation set the origin status to confirmed, rejected or unset (if flagging is not reasonable). For tuning of sceval do not add new picks on stations that were not picked and associated by the automatic system. Otherwise the origins with arrivals will not be representative of the automatic system. The considered time window should be long enough to contain a significant number of each rejected and confirmed origins, e.g. 50 rejected and 50 confirmed origins.

  4. Create an event XML file from the events that are manually reviewed.

    Generate the event XML file, e.g. eventlist.xml, from the evaluated events. Choose any file name. The file name is provided through parameters.

    Use scxmldump [10] to dump the events into a XML file. Choose any file name. The file name is provided to sceval through parameters.

  5. Create a configuration XML file containing the bindings configuration.

    Use scxmldump -C to dump the binding configuration into a XML file. Choose any file name. The file name is provided to sceval through parameters.

  6. Create an inventory XML file

    Use scxmldump -I to dump the station inventory into a XML file. Choose any file name. The file name is provided to sceval through parameters.

    Example code for generating the XML files in the previous steps:

    #!/bin/bash

# database
db=mysql://sysop:sysop@localhost/seiscomp

# dump events
evtList=`scevtls -d $db --begin '2021-05-22 12:00:00' --end '2021-06-30 23:59:59' |\
awk '{for (i=1;i<=NF;i++)  printf("%s,", $i)}' | sed 's/,$//'`

scxmldump -d $db -E $evtList -PAMf -o eventlist.xml
# dump configuration
scxmldump -d $db -C -o config.xml
# dump inventory
scxmldump -d $db -I -o inventory.xml

  7. Generate the list of weight profiles.

    Use sceval-tune to create a list of profiles considered for finding the best-performing weight profiles. Choose a sufficient number of distance intervals, e.g. 5 - 10 intervals and a list of weight values. sceval-tune will find all meaningful permutations of weights for all distance intervals. Default value may be used. Save the profile list in a file. Review and adjust the profile list if desired.

    Required parameters for generating the list of profiles by sceval-tune:

    • -g

      Generate the list of profiles.

    • -f arg

      arg: Name of the file containing the created profile list.

    Optional parameters:

    • -n arg

      arg: Maximum number of distance intervals. Uses default if -n is not set. Default: 10

    • -w arg

      arg: Weight profile to be tested. Uses default if -w is not set. Default: 1,0.75,0.5,0.25,0.1,0.01

    Example for creating the list of weight profiles:

    sceval-tune -f profiles.txt -g -n 6 -w 1,0.5,0.1

  8. Tune the configuration parameters for the distance profile also defined in the distanceProfiles.

    Run sceval-tune in a command-line terminal to find the optimum configuration parameters for one of the distance profiles given in distanceProfiles. Repeat the tuning for all profiles individually. The tuning is relies on a sufficient number of manually confirmed and rejected events.

    For tuning provide the considered weight profiles in the profile list file. These weight profiles are evaluated identifying the best-performing weight profile and the associated threshold values mismatchScore.confirmed and mismatchScore.rejected. The best-performing weight profile and the threshold values are determined by optimizing the automatic w.r.t. the manual evaluation. As a measure, the misfit is minimized.

    The configuration parameters and quality parameters are printed on the command line. Based on the suggested configuration parameters, the percentages indicate the number of events that would be confirmed or rejected by the automatic system w.r.t. the manual evaluation. The main plot figure is generated to review the performance of the tuning and the configuration parameters. The optional additional plot figure shows the results for the 9 best-performing weight profiles.

    Two possible values for mismatchScore.rejected are provided based on the confirmed or on the unflagged origins. Both values should be similar but the value for the confirmed origins should typically be chosen.

    If mismatchScore.confirmed and mismatchScore.rejected are largely separated, many origins may remain unflagged by sceval. Increasing mismatchScore.confirmed or decreasing mismatchScore.rejected will reduce the number of unflagged origins but will possibly result in wrong automatic flagging of real and fake events.

    Required parameters for tuning by sceval-tune:

    • -p arg

      arg: Bame of the distance profile that is to be tuned. The profile must be configured. The name must be contained in the configuration parameter distanceProfile.

    • -f arg

      arg: Name of the file containing the profile list.

    • --ep arg

      arg: name of event XML file

    • --config-db arg

      arg: name of the configuration XML file.

    • --inventory-db arg

      arg: Name of the inventory XML file.

    Optional parameters:

    • --time-window arg

      arg: Time window of the considered events.

    • --use-defaults arg

      Ingore the configuration of the tuned sceval instance and use defaults.

    • --addplots

      Show results from the 9 best-matching weight profiles.

    • --debug

      Print all debug output from sceval.

    Example:

    sceval-tune -f profiles.txt --inventory-db inventory.xml --config-db config.xml --ep events.xml -p 180 --addplots

  9. Configuration of sceval

    Configure the distance profile of the tuned sceval instance using the proposed parameter values.

Results

sceval-tune provides the configuration parameters and the tuning statistics on the command terminal where it was executed. In addition, one main and one additional (--addplots) figure are created for visual inspection of the tuning results.

../_images/sceval_tune_main.png

Figure 6: Main figure showing results for the best-performing weight profile. Solid line: mismatchScore values based on flagged events. Dashed line: mismatchScore values based on flagged and unflagged events.

../_images/sceval_tune_add.png

Figure 7: Additional figure showing results for the 9 best-performing weight profiles. Generated when using --addplots. Solid line: mismatchScore values based on flagged events. Dashed line: mismatchScore values based on flagged and unflagged events.

Module Configuration

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

sceval inherits global options.

Note

Modules/plugins may require a license file. The default path to license files is @DATADIR@/licenses/ which can be overridden by global configuration of the parameter gempa.licensePath. Example:

gempa.licensePath = @CONFIGDIR@/licenses
minPhase

Default: 0

Type: integer

Minimum number of phase arrivals (P or S) used for locating. Origins with arrivals fewer than minPhase and fewer then distanceProfilesMinPhase are rejected. Only consider arrivals with weight > 0.

minDepth

Default: -10.0

Unit: km

Type: double

Minimum depth criterion: origins with depth less than minDepth are rejected.

maxDepth

Default: 745.0

Unit: km

Type: double

Maximum depth criterion: origins with depth greater than maxDepth are rejected.

maxRMS

Default: 3.5

Unit: s

Type: double

Maximum RMS: origins with RMS residual larger than maxRMS are rejected.

maxGap

Default: 360.0

Unit: deg

Type: double

Gap criterion: maximum allowed azimuthal gap between adjacent stations providing arrivals to one origin. Origins with a larger gap receive a comment. The status remains unchanged. Only consider arrivals with weight > 0.

minPhaseConfirm

Default: -1

Type: integer

Minimum phase confirmation: Origins having at least the configured number of arrivals (associated phase picks) are confirmed. -1 disables the method.

gapMinPhase

Default: -1

Type: integer

Extended gap criterion: Origins with gap lower than maxGap and more than gapMinPhases arrivals are confirmed.

gapMinPhase <= 0: ignore check.

distanceProfiles

Type: list:string

Registration of distance profiles for station - distance evaluation. An empty list disables the station - distance evaluation.

distanceProfilesMinPhase

Default: 0

Type: integer

Minimum number of P-phase arrivals for applying the station - distance evaluation. Only consider arrivals with weight > 0.

distanceProfilesMinPhase <= 0: ignore parameter.

setupName

Default: scautopick

Type: list::string

List of configuration setup names used for the initial setup of the active station list. Use commas to separate names. E.g. in pipelines use the names of all modules contributing picks.

"scautopick": consider all stations with scautopick bindings and the streams defined therein.

"default" or "global": consider all stations with global bindings and the streams defined therein.

Note

qc.* Waveform quality control (QC) parameters. Ensure sceval subscribes to the message groups, e.g. QC, CONFIG, LOCATION.

qc.parameters

Type: list:string

Defines QC parameters to observe and the value ranges to consider streams. Each QC parameter is associated with a value range. If any of the defined ranges is exceeded, the corresponding station is disabled. Use ‘-Inf’ resp. ‘Inf’ if no upper or lower bound should exist. scqc must be running. Typical parameters: rms, latency, delay, availability, gaps count, overlaps count, timing quality, offset, spikes count. Find the examples in $SEISCOMP_ROOT/etc/defaults/sceval.cfg.

To effectively disable QC parameters set the ranges to -Inf,Inf.

qc.sloppy

Default: false

Type: boolean

At startup of sceval waveform QC parameters may be initially missing preventing immediate station evaluation. If sloppy is active, a station is activated as soon as one QC parameter arrives which is in range. Out-of-range parameters deactivate the station.

Recommended use: waveform playbacks, frequent restarts of sceval. Consider adjusting qc.parameters, e.g. disable the availability check.

qc.noQC

Default: false

Type: boolean

Do not consider QC parameters. This will activate all stations which have a binding configuration defined by setupName.

Activate in real-time playbacks without waveforms.

qc.useDatabase

Default: false

Type: boolean

Load QC parameters from the database during startup. Setting to true may slow down the start up.

Note

origin.* Limit the range of origins to be evaluated.

origin.agencyWhiteList

Type: list:string

Agency IDs for filtering origins. Separate by comma. Only evaluate origins with one of the given agency ID. If unset, no filtering is applied.

origin.authorWhiteList

Type: list:string

Author names for filtering origins. Separate by comma. Only evaluate origins with one of the given author names. If unset, no filtering is applied.

origin.ignoreStatus

Default: rejected,reported,preliminary,confirmed,reviewed,final

Type: list:string

Values: rejected,reported,preliminary,confirmed,reviewed,final

Ignore an origin if its status has any of the given states. The option is ignored for manual origins if origin.manual = true.

origin.manual

Default: false

Type: boolean

Enable evaluation of origins where the evaluation mode is set MANUAL. Default: disable. Check the box to enable the evaluation.

Note

mismatchScore.* Threshold parameters for the station-distance evaluation. They apply to all distance weight profiles.

mismatchScore.confirmed

Default: 0.5

Type: double

Mismatch between active stations and used stations. If the score is less than or equal to the evaluation status is set to CONFIRMED.

mismatchScore.rejected

Default: 0.7

Type: double

Mismatch between active stations and used stations. If the score is greater than or equal to the evaluation status is set to REJECTED.

mismatchScore.use

Default: true

Type: boolean

Calculate the mismatch score and set the origin status. Deactivating only calculates the score without setting the status. Deactivating is useful for testing and tuning. View the score in scolv.

mismatchScore.useHypocentral

Default: false

Type: boolean

Calculate hypocentral distances. Otherwise, horizontal distances are considered. Activate for situations of 3D networks such as in deep mines.

Note

distanceProfile.* Distance-weight profiles for the station-distance evaluation.

Note

distanceProfile.$name.* $name is a placeholder for the name to be used and needs to be added to distancesProfiles to become active.

distancesProfiles = a,b
distanceProfile.a.value1 = ...
distanceProfile.b.value1 = ...
# c is not active because it has not been added
# to the list of distancesProfiles
distanceProfile.c.value1 = ...
distanceProfile.$name.max

Unit: deg

Type: double

Upper epicentral distance of stations for using this profile.

distanceProfile.$name.weights

Type: list:double

Weights to use. The number of weights determine the number of distance intervals.

Command-Line Options

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. Example: 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 &.

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.

--print-component arg

For each log entry print the component right after the log level. By default the component output is enabled for file output but disabled for console output.

--component arg

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

-s, --syslog

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

-l, --lockfile arg

Path to lock file.

--console arg

Send log output to stdout.

--debug

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

--trace

Execute in trace mode. Equivalent to --verbosity=4 --console=1 --print-component=1 --print-context=1 .

--log-file arg

Use alternative log file.

Origin

--agencies list

Agency IDs for filtering origins. Separate by comma. Only evaluate origins with one of the given agency ID. If unset, no filtering is applied.

--authors list

Author names for filtering origins. Separate by comma. Only evaluate origins with one of the given author names. If unset, no filtering is applied.

-O, --origins string

origin ID(s). Only process origins which have one of the given IDs. Provide a comma-separated list for multiple IDs. Only in offline playbacks with --ep.

--manual

Enable evaluation of origins where the evaluation mode is MANUAL.

Mode

--ep XML file

Read event parameters from XML file in offline processing.

--sloppy

Enable if sceval is used in a real-time waveform playback to disable waiting for waveform QC messages. Waveform QC messages may be missing or take some time to be created. Arteficial gaps may result from repeated real-time waveform playbacks. Consider adjusting qc.parameters, e.g. disable the availability check.

Playbacks without waveforms: Set qc.parameter ranges to -inf,inf.

--noQC

Do not consider QC parameters.

--force

For evaluation of all origins. Use this optiom to evaluate origins which have already been evaluated or which are manual. Use the option for testing the configuration.

Output

--formatted

Use formatted XML output along with ‘--ep’. Otherwise XML is unformatted.

Tuning

-f, --filename profiles file

File to read tuning parameters from. e.g. profiles.

-p, --profile name

Name of the distance profile which should be tuned. If ommitted, the default profile is used.

-t, --time-window time range

Specify time window as one properly quoted string. Times are in UTC and separated by a tilde ~ e.g. "2016-01-01 00:00:00~2016-01-02 00:00:00".

--use-defaults

Use default configuration of sceval in tuning mode. Default: use configuration.