npeval

npeval calculates network performance parameters related to the ability to locate earthquakes.

Description

npeval evaluates the network performance parameters.

Overview

The calculated network performance parameters include:

1. the minimum time required to locate seismic events,
2. the minimum magnitude of seismic events for which the network is expected to deliver a location.

The values are calculated for grid points within a configurable region. npeval considers the configured station setup and a configurable minimum of stations. It takes into account data quality control (QC) parameters. The Earth model parameters can be adjusted.

The output parameters can be stored as grid files. For showing the grid files dynamically on maps the plugin mapmultigrid can be configured.

Features

1. Computes the minimum time required to locate a seismic event.
2. Computes the minimum magnitude for which a solution is expected.
3. Considers only stations which are used for the actual event detection based on configurable bindings or stations defined in CSV tables.
4. Dynamically considers enabled or disabled stations and excludes stations given in a file.
5. Dynamically considers changes in the station quality control parameters,
6. Writes Surfer grid files or BNA polygons which can be evaluated on maps.
7. Configurable are among others:
   • detection module from a specific processing pipeline,
   • minimum number of stations for locating earthquakes,
   • region, grid interval and depths for considering earthquakes,
   • delay added to the stations considering data transfer and processing,
   • traveltime table and interface,
   • random station removal simulating stations not having picks (commandline option),
   • intervals and colors of contour lines and fill properties,
   • directory for output,
   • output format: GRD, BNA, PNG.

General Setup

The basic requirement for making an event location and a magnitude estimation is the detection of seismic phases. In a pipeline system, several instances of a picker, e.g. scautopick can be applied to different sets of stations. In order to make npeval specific to a particular pipeline, the involved picker instance must be specified by the parameter setupName. npeval will only consider stations which have bindings for this module and for which the data quality control (QC) parameters are within the ranges defined by the qc.parameters. Therefore npeval can be configured for separate pipelines involving different instances of scautopick.

The station setup is typically read from the SeisComP3 database. However, it can be overwritten by input from a station file when running npeval on the command line.

The minimum number of stations providing potential arrivals to event location must be met for computing any of the configured values. Additionally, networks and stations to be considered or to be excluded can be defined in separate files defined by the parameters stations.file and stations.exclude-file, respectively.

The grid parameters grid.region, grid.spacing and grid.depths provide the considered source locations. Only one region at a time can be currently considered by npeval. In order to consider multiple regions, module aliases can be used. Module aliases can be configured separately and generated by, e.g. for a region named r1:

seiscomp alias create r1npeval npeval

Storing the calculated parameters is controlled by the output control parameters.

Quality control parameters

All QC parameters configured by qc.parameters must be available for the minimum number of stations. The QC parameters can be received in two ways:

1. from the database during startup and updating by the parameters received from the messaging system. When reading from the database npeval may by slow during the startup depending on the size of the database.
2. only from the messaging system (default). When only using QC parameters from the messaging, the initial grid generation depends on the availability of the QC parameters. It is then typically delayed and the grid may be updated several as QC parameters for more and more stations arrive during the first minutes of operating npeval.

Timing

When the QC parameters leave or reach rapidly the configured ranges npeval will recompute the grids. Repeated re-computation in short time intervals may be computational expensive. To control the timing set the parameter grid.update to a reasonable interval to optimize the load.

Methods

npeval provides methods for computing the minimum time and the minimum magnitude related to the network geometry and the data quality. The methods can be applied to the same region simultaneously.

All values are computed, when:

1. npeval is started,
2. the station configuration is changed by enabling or disabling stations.
3. the station quality control parameters formerly within configured values exceed the configured values or the vice versa. Check qc.parameters.

Minimum Location Times

Computing the minimum times to locate events by a network can be deactivated or activated by times.compute.

Important parameters configurable in the times section are:

1. times.file: The basename of the output files. For output in GRD and PNG format, .grd and .png suffixes will be added. For BNA, a sub-directory in the output.directory is created containing the different levels.

2. times.tableType and times.table: Type and name of travel time tables. Typically LOCSAT provides faster travel times than libtau. By setting the table parameter, customized velocity models can be considered. When choosing LOCSAT, the table file for the P wave first arrival times must be stored in @DATADIR@/locsat/tables/, for libtau, the velocity profile is stored in @DATADIR@/ttt.

3. times.dataDelay: The time added to the computed travel times considering the data delay. To read the delay from the SeisComP3 database and to receive dynamic updates

   times.dataDelay = -1.0
   

   Otherwise a static delay is considered.

4. times.processingDelay Data processing time to be added to computed traveltimes accounting for delays due to the data processing by SeisComP3 modules, e.g. the detector or the locator. The amount considers the default time window for AIC for phase picking and the default time window for calculating amplitudes for the mB magnitude used by scautopick as well as the processing required by scautoloc or scanloc. times.processingDelay must be therefore be changed when adjusting those window lengths or module configurations.

Minimum expected times for locating events in Chile by the CX network.

Minimum Magnitude

Computing the minimum magnitude of events expected to be located by a network can be deactivated or activated by minimumMagnitude.compute. Different methods for computing minimum are available.

Important parameters configurable in the minimumMagnitude section are:

1. minimumMagnitude.compute: The basename of the output files. For output in GRD and PNG format, .grd and .png suffixes will be added. For BNA, a sub-directory in the output.directory is created containing the different levels.
2. minimumMagnitude.type: The method considered for computations. Currently, only LF (low-frequency approximation of the source spectrum) is supported and GMPE (Ground Motion Prediction Equation) is for experimental use only.
3. minimumMagnitude.magMin, minimumMagnitude.magMax and minimumMagnitude.magStep: Definition of the magnitude ranges to be tested.
4. minimumMagnitude.minSnr: The minimum signal-to-noise ratio (snr) which the data must exceed for a station to be considered. The snr is calculated by dividing the amplitude predicted by npeval by the data rms received from SeisComP3.
5. low-frequency-approximation: Considered method when LF for minimumMagnitude.type is chosen. Define the Earth’s properties at the hypocentre and along the P wave as well as the stress drop due to the event. The method is adapted from the publication: Tramelli et al., J Pet Environ Biotechnol, 2015, 6:254.
6. GoundMotionPredictionEquetion: Considered method when GMPE for minimumMagnitude.type is chosen. The method uses an internally defined GMPE based on the publication by Cauzzi, C. et al., Bull Earthquake Eng (2015) 13:6. Choosing GMPE is currently experimental only experimental and not recommended for routine processing.

Minimum expected magnitude of events for which a solution can be expected in Chile by the CX network.

Note

Applying the minimum magnitude method requires waveform RMS availbable from real-time station QC messages or from station input file (see command line option file). The minimum magnitude method is not available in offline mode without providing RMS.

Examples

1. Real-time processing on the command line:

   npeval --region 80,150,-20,30 --delta 1 -d localhost/seiscomp3
   

2. Offline processing on the command line with a station file and a station exclude file

   npeval --offline --inventory-db inventory.xml --config-db config.xml --file stations.ini --region 21,27,62,67 --exclude-file stat-excl.ini --debug
   

Output parameters and visualization

The results from all methods can be stored in files with configurable format given in output.format:

1. GRD file (Surfer grid). When choosing GRD for output.format npeval will store the computed values in Surfer grid files. One file is generated per method. For showing the grid files dynamically on maps the plugin mapmultigrid can be configured. Using the mapmultigrid plugin multiple grid files can be simultaneously added as layers to maps in GUIs such as scmv. Files in GRD format are dynamically rendered. Any changes to these files will be immediately visible on the maps. GRD is therefore the preferred format.
2. BNA files. One sub-directory containing the BNA files is generated per method. The BNA files contain open or closed polygons which can be drawn on maps with customized properties. Note: When the BNA format is chosen, the polygons are drawn on maps at startup of the GUI modules, when the output directory is either @DATADIR/bna@ or @CONFIGDIR@/bna. Since the BNA polygons are only drawn once during startup, the GUI modules must be restarted for considering updates of the polygons.
3. PNG image file. One file is generated per method. It is viewable by external image viewers.

The output parameters from the considered methods are stored in directory and in the format given by output.directory and output.format, respectively. By default, the output directory is cleared before updating. Set the configuration parameter output.directory to the directory where the output parameters are stored. Configure different directory when different instances of npeval are executed to avoid deleting the result files.

Note

By default all files and directories existing in output.directory are deleted by npeval when computing any of the desired values. To keep the existing files and directories, uncheck output.clean.

When running npeval in debug mode, an example configuration for the stops parameter of the mapmultigrid plugin in suggested. It can be used to define reasonable color ranges of the shown grid, e.g.:

# example configuration of the stop parameter for the plugin mapmultigrid:
stops = 11:c02f2f30:"major",14:2f5dc030:"minor",17:86c02f30:"major",20:c02fb230:"minor",23:2fc0a630:"major"

Adjust the values and apply the configuration to make the grid visible on maps.

References

npeval has been demonstrated, promoted and discussed with scientists and the SeisComP3 community at international science conferences, e.g.:

1. D. Roessler, B. Weber, E. Ellguth, J. Spazier the team of gempa: Evaluierung der Qualität und Geschwindigkeit von Erdbebendetektionen in SeisComP3, 2017, Bad Breisig, Germany, AG Seismologie meeting
2. D. Roessler, B. Weber, E. Ellguth, J. Spazier the team of gempa: EVALUATION OF EARTHQUAKE DETECTION PERFORMANCE IN TERMS OF QUALITY AND SPEED IN SEISCOMP3 USING NEW MODULES QCEVAL, NPEVAL AND SCEVAL , 2017, New Orleans, USA, AGU Fall Meeting, abstract S13B-0648.

Configuration

etc/defaults/global.cfg

etc/defaults/npeval.cfg

etc/global.cfg

etc/npeval.cfg

~/.seiscomp3/global.cfg

~/.seiscomp3/npeval.cfg

npeval inherits global options.

setupName

Type: string

The module name for testing the bindings. Only stations having bindings to the module will be considered. Typical values are: scautopick, global. Default is scautopick.

qc.parameters

Type: list:string

Defines QC parameters to observe. Each parameter is associated with a value range. If any of the defined ranges is exceeded the corresponding station is disabled. For the ranges use ‘-Inf,Inf’ if no upper or lower limits shall exist.

Typical parameters: rms, latency, delay, availability, gaps count, overlaps count, timing quality, offset, spikes count. Read seiscomp3/etc/defaults/npeval.cfg for examples.

scqc must be running in parallel.

qc.useDatabase

Type: boolean

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

Note

stations.*n Station parameters controlling the stations to be considered.

stations.stationCount

Type: uint

Minimum number of stations that have an arrival for starting the calculations. Default is 4.

stations.file

Type: string

Filename to file in CSV format to read station information from. Each line has the format [NET,STA,LAT,LON,ELEVATION(,RMS)]. RMS in unit of nm/s is optional and required for minimum magnitude calcuation in offline mode. Empty: stations are read from configuration in setupName.

stations.exclude-file

Type: string

Filename to a station blacklist file. Each line has the format [NET.STA]. Wildcards are supported.

Note

grid.*n Parameters controlling the source region to be tested and the update interval.

grid.region

Type: list:float

Unit: degree

Horizontal bounding box for selecting the considered region: LonMin,LonMax,LatMin,LatMax, Unit: degree, required.” Default is 80.0, 150.0, -20.0, 30.0.

grid.spacing

Type: double

Unit: degree

Horizontal grid spacing within the region for assuming events. Default is 1.0.

grid.depths

Type: list:int

Unit: km

Source depths. Can be list of integers, e.g. 10,20,30. Default is 10.

grid.update

Type: double

Unit: s

Minimum time interval between 2 updates. Values < 1 are set to 1.

Note

output.*n Output control parameters.

output.directory

Type: string

Output directory for writing new files. Recommendation for BNA files: @CONFIGDIR@/bna/npeval. Default is /tmp/npeval.

output.clean

Type: boolean

Clean output directory before writing new files. Default is true.

output.format

Type: string

Output format. Options: BNA, PNG, GRD Default is GRD.

output.size

Type: string

Image output size, e.g 1280x1024 Default is 1280x1024.

output.gradient.discrete

Type: boolean

Setting this parameter to true enables color interpolation. Default is true.

output.gradient.stops

Type: gradient

The PNG fill color gradient. Default is 30.00:ff00fa,60.00:f25ffb,90.00:e483fc,120.00:d79cfd,150.00:c9aefe,180.00:9fd7ff,210.00:93dfff,240.00:84e8ff,270.00:6df2ff,300.00:49fdff,600.00:20dbdb,900.00:11b4b7,1200.00:03939a.

Note

times.*n Parameters for calculating the minimum times to locate events by a network.

times.compute

Type: boolean

Allow computing the minimum times. Default is true.

times.file

Type: string

Basename of output file(s) Default is npeval_times.

times.tableType

Type: string

Type of traveltime table, e.g. libtau or LOCSAT. Default is LOCSAT.

times.table

Type: string

Name of traveltime table. Default is iasp91.

times.dataDelay

Type: float

Unit: s

Data delay to be added to computed traveltimes.

-1.0 - get automatically from QC messages per station. Default is -1.0.

times.processingDelay

Type: float

Unit: s

Data processing time to be added to computed traveltimes. The amount considers the default time windows for AIC used by scautopick and mB used by scautoloc. The value must be therefore be changed when adjusting those window lengths. Default is 5.0.

Note

minimumMagnitude.*n Parameters for calculating the minimum magnitude of events that can be detected by a network.

minimumMagnitude.compute

Type: boolean

Allow computing the expected minimum magnitude. Default is false.

minimumMagnitude.file

Type: string

Basename of output file(s) Default is npeval_minmag.

minimumMagnitude.type

Type: string

Type of amplitude calculation:

LF: low-frequency approximation

GMPE: GMPE (trial only) Default is LF.

minimumMagnitude.magMin

Type: float

Minimum earthquake magnitude to be tested. Step size to maximum: 0.1. Default is 2.0.

minimumMagnitude.magMax

Type: float

Maximum earthquake magnitude to be tested. Default is 5.0.

minimumMagnitude.magStep

Type: float

Magnitude step. Default is 0.2.

minimumMagnitude.minSnr

Type: float

Minimum signal-to-noise ratio at the station to accept a magnitude. Default is 5.

Note

minimumMagnitude.lowFrequency.*n Values for calculating the low-frequency amplitude. Default values are from the ak135 standard Earth model at 10 km depth.

minimumMagnitude.lowFrequency.vp

Type: float

Unit: km/s

P-wave velocity at the hypocentre. Default is 5.8.

minimumMagnitude.lowFrequency.vs

Type: float

Unit: km/s

S-wave velocity at the hypocentre. vs = vp/sqrt(3) if not set. Default is 3.2.

minimumMagnitude.lowFrequency.rho

Type: float

Unit: g/cm^3

Density at the hypocentre. Default is 2.6.

minimumMagnitude.lowFrequency.sigma

Type: float

Unit: bar

Stress drop due to the earthquake. Default is 10.

minimumMagnitude.lowFrequency.qp

Type: float

Qp, seismic attenuation along the ray given by the quality factor for P waves. Default is 500.

Note

minimumMagnitude.*n Defines the parameters for calculating the minimum magnitude of events that can be detected by a network.

minimumMagnitude.compute

Type: boolean

Allow computing the expected minimum magnitude. Default is true.

minimumMagnitude.type

Type: string

Type of amplitude calculation:

LF: low-frequency approximation

GMPE: GMPE Default is LF.

minimumMagnitude.magMin

Type: float

Minimum earthquake magnitude to be tested. Step size to maximum: 0.1. Default is 0.0.

minimumMagnitude.magMax

Type: float

Maximum earthquake magnitude to be tested. Default is 5.0.

minimumMagnitude.magStep

Type: float

Magnitude step. Default is 0.1.

minimumMagnitude.minSnr

Type: float

Minimum signal-to-noise ratio at the station to accept a magnitude. Default is 10.

Note

minimumMagnitude.lowFrequency.*n Values for calculating the low-frequency amplitude. Default values are from the IASP91 standard Earth model.

minimumMagnitude.lowFrequency.vp

Type: float

Unit: km/s

P-wave velocity at the hypocentre. Default is 5.8.

minimumMagnitude.lowFrequency.vs

Type: float

Unit: km/s

S-wave velocity at the hypocentre. vs = vp/sqrt(3) if not set.

minimumMagnitude.lowFrequency.rho

Type: float

Unit: g/cm^3

Density at the hypocentre. Default is 2.72.

minimumMagnitude.lowFrequency.sigma

Type: float

Unit: bar

Stress drop due to the earthquake. Default is 10.

minimumMagnitude.lowFrequency.qp

Type: float

Qp: Seismic attenuation given by the quality factor for P waves. Default is 500.

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

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

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

--trace

Trace mode: –verbosity=4 –console=1 –print-component=1 –print-context=1

--log-file arg

Use alternative log file.

Stations

--file arg

Filename to station file. Each line has the format [NET,STA,LAT,LON,ELEVATION(,RMS)]. RMS in unit of nm/s is optional and required of minimum magnitude calcuation in offline mode.

--exclude-file

Filename to station exclude file. Each line has the format [NET.STA]. Wildcards are supported.

--skip arg

Randomly skip the given percentage of stations

Output

-f, --format arg

Specify the output format. Options: BNA, PNG, GRD

--directory arg

Specify the output directory

--size arg

Specify the image output size, e.g 1280x1024 px

--no-clean

Do not clean output directory before writing new output. Otherwise the output directory will be cleaned.

--clean

Clean output directory before writing new output. Overwrites no-clean.

Region

--region arg

Region bounding box: LonMin,LonMax,LatMin,LatMax. Required parameter.

Unit: degree

-s, --spacing arg

Horizontal grid spacing. Default: 1.0.

Unit: degree

--depths arg

Source depths. Default: ‘10’. For series use –depths 10 –depths 20 …

Unit: km

Times

--dataDelay arg

Add a data delay to computed travel times.

-1: Get dataDelay from QC messages.

Unit: s

--procDelay arg

Add a processing delay to computed travel times.

Unit: s

-c, --station-count arg

Minimum number of stations that have an arrival

--times-file arg

Specify the basename of output times file(s)