npeval¶

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

Description¶

npeval evaluates the station status and network performance parameters.

Overview¶

The calculated network performance parameters include:

the minimum time required to locate seismic events,
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 waveform quality control (QC) parameters which determine the station status. Changes in station status trigger the re-computation of the performance parameters. The Earth model parameters can be adjusted.

Upon computation of the parameters

The output parameters can be stored as surfer GRD, PNG image or BNA files. For visualizing the grid files dynamically on maps, the plugin mapmultigrid [2] has been developped.
The station status can be reported to external applications, e.g. to GDS [1] for dissemination.

Features¶

Computes the minimum time required to locate a seismic event.
Computes the minimum magnitude for which a solution is expected.
Considers only stations which are used for the actual event detection based on configurable bindings or stations defined in CSV tables.
Dynamically considers enabled or disabled stations and excludes stations given in a file.
Dynamically considers changes in the station quality control parameters.
Computation is triggered by changes in station status.
Writes Surfer grid files or BNA polygons which can be evaluated on maps and PNG images.
Station status can be reported to external applications
Configurable are among others:
- detection module from a specific processing pipeline or explicit station lists,
- 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 (command-line option),
- intervals and colors of contour lines and fill properties,
- directory for output,
- minimum update interval
- output format: GRD, BNA, PNG,
- output processing script.

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 [3] 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 layout is typically read from the SeisComP database. Then, only stations matching setupName, that is they have the configured bindings, are considered internally for further computations. However, the layout can be overridden by input from a station file.

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.

In real-time conditions a typical minimum configuration includes:

Global or other module bindings along with the definition of the station setup by setupName.
Definition of the monitoring region by grid.region.
The choice of the methods, e.g. times.compute or minimumMagnitude.compute or the report generation by setting output.script.

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:

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

Only stations with QC parameters inside the configured ranges and with a matching setupName are considered internally for further computations.

Triggering and Timing¶

npeval re-computes the grids by the configured methods or generates reports if the internally considered status of one or more stations changes. This may be when:

npeval is started. The internally considered status is initially set to disabled.
Significant changes in waveform QC parameters are found. That is the QC parameters of stations enter or leave the ranges configured in qc.parameters.
Stations are actively enabled or disabled.

Repeated re-computation in short time intervals may be computational expensive. Set the parameter grid.update to a reasonable interval to control the timing and 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.

Minimum location time¶

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:

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.
Set the parameters for computing the travel times.
times.dataDelay: The time added to the computed travel times considering the data delay [5]. To read the delay from the SeisComP database and to receive dynamic updates
```
times.dataDelay = -1.0
```
Otherwise a static delay is considered.
times.processingDelay Data processing time to be added to computed traveltimes accounting for delays due to the data processing by SeisComP 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 [6] or scanloc [7]. times.processingDelay must be therefore be changed when adjusting those window lengths or module configurations.

Minimum expected times for locating events in SE-Asia by the GE 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:

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

# If LF is selected, travel-times are computed to account for anelastic attenuation.: In this case also set the parameters for computing the travel times.

minimumMagnitude.magMin, minimumMagnitude.magMax and minimumMagnitude.magStep: Definition of the magnitude ranges to be tested.
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 [8] received from SeisComP.
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 by Trampelli et al. (2015) [11].
GoundMotionPredictionEquetion: Considered method when GMPE for minimumMagnitude.type is chosen. The method uses an internally defined GMPE based on the publication by Cauzzi et al. (2015) [12]. 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 to be available 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.

Travel-time computation¶

Depending on the method travel times are computed based on the confiugured travel-time interface, the table and correction parameters.

travelTimes.tableType and travelTimes.table: Type of the interface and name of the travel time tables. Typically, LOCSAT [4] interface provides faster travel times than libtau. By setting the travelTimes.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. Both travel-time interfaces do not consider stations elevations.
Correction parameters: Travel-time corrections $t_{corr}$ may be applied based on a configurable average velocity to compensate for station elevation. The average velocity is typically the P-wave speed at shallow depth as configured in travelTimes.velocityCorrection.

The velocity $v$ is applied to the station elevation $e$ and the slowness $s$ of the first-arrival phase from a grid point to the station given the travel-time interface and the table configured by travelTimes.tableType and travelTimes.table, respectively:

$t_{corr} = \frac{e}{v(1-(s*v)^2)}$

Note

For $s*v > 1$ the correction is negative corresponding to a complex-valued incidence angle. This case may occur if the correction velocity is larger then the velocity of the upper layer assumed for computing the travel-time tables. npeval will stop providing and an error message. Then consider lowering travelTimes.velocityCorrection.

Alternatively, an average station elevation may be compensated for by a correction with respect to sea level. The correction elevation is configured in travelTimes.elevationCorrection. The travel-time tables must then be computed with respect to this elevation where 0 km depth corresponds to the correction.

Output formats¶

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

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 [9]. 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.
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 [10]. 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.
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.

Output visualization¶

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

npeval --debug

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

Grid and Station Reports¶

Reports are generated upon triggering of the parameter computation if an executable script is defined in output.script, e.g.

output.script = @DATADIR@/scripts/sendtoGDS.py

The script can be used to process and disseminate the station report or to process the generated files.

The reports are created in JSON format. The contain:

Details on the location and the format of the output files generated by the configured methods, if any.
Stream information of stations with information about the station status, available QC parameters and whether it can be considered for grid computation or not. By default only stations with significant updates are reported. To report all stations configure output.reportAllStations.

Example

{
  "minimum times": "/tmp/npeval/npeval_times"
  "minimum magnitudes": "/tmp/npeval/npeval_minmag"
  "output format": "GRD"
  "streams": [
    {
      "net.stat.loc.stream": "CX.PB06..HHZ"
      "significant update": "true"
      "considered": "true"
      "availability": "100"
      "delay": "1.05254"
      "rms": "330.684"
    },
    {
      "net.stat.loc.stream": "CX.PB09..HHZ"
      "significant update": "true"
      "considered": "false"
      "availability": "100"
      "delay": "1.99461"
      "rms": "1619.25"
    },
  ]
}

The JSON data are provided to the script in output.script which is executed. The raw JSON format contains no line breaks but is can be converted by other tools, e.g. jsonlint for better human readabilty.

Note

If the station status does not change, the streams item may be empty during the first few grid generations after starting npeval. Initially, grid computations are triggered as more QC parameters arrive for the stations even if the station status does not change.

Examples¶

Real-time processing on the command line considering waveform QC messages:
```
npeval --region 80,150,-20,30 --delta 1 -d localhost/seiscomp
```
Real-time processing on the command line considering constant RMS (nm/s):
```
npeval -d localhost/seiscomp --rms 500
```

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

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

Offline processing on the command line with a station file and station RMS in nm/s overwriting all other RMS values:
```
npeval --offline --file stations.ini --rms 300
```

Publications¶

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

D. Roessler, B. Weber, E. Ellguth, J. Spazier and the team of gempa: Evaluierung der Qualität und Geschwindigkeit von Erdbebendetektionen in SeisComP3, 2017, Bad Breisig, Germany, AG Seismologie meeting
D. Roessler, B. Weber, E. Ellguth, J. Spazier and 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.

References¶

[1]	https://gempa.de/products/gds/

[2]	https://docs.gempa.de/plugins/current/base/global_multigrid.html

[3]	https://docs.gempa.de/seiscomp/4/current/apps/scautopick.html

[4]	https://docs.gempa.de/seiscomp/4/current/apps/global_locsat.html

[5]	https://docs.gempa.de/seiscomp/4/current/apps/scqc.html

[6]	https://docs.gempa.de/seiscomp/4/current/apps/scautoloc.html

[7]	https://docs.gempa.de/scanloc/current/

[8]	https://docs.gempa.de/seiscomp/4/current/apps/scqc.html

[9]	https://docs.gempa.de/seiscomp/4/current/apps/scmv.html

[10]	https://docs.gempa.de/seiscomp/4/current/apps/global_gui.html

[11]	Tramelli et al., A FORTRAN Code for the Sensitivity Estimate of a Seismic Network: An Application to Campi Flegrei, 2015, J Pet Environ Biotechnol, 6:254, DOI: 10.4172/2157-7463.1000254

[12]	Cauzzi, C. et al., Updated predictive equations for broadband (0.01–10 s) horizontal response spectra and peak ground motions, based on a global dataset of digital acceleration records, 2015, Bull Earthquake Eng, 13:6, DOI: 10.1007/s10518-014-9685-y

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 $SEISCOMP_ROOT/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.* Parameters controlling the stations to be considered.

stations.stationCount¶

Type: uint

Minimum number of stations that have an arrival for starting the calculations. This mimics the confiugration of the phase associator, e.g. scanloc or scautoloc. Default is 4.

stations.file¶

Type: string

Filename to file in CSV format to read station information from instead of considering “setupName”. Use the option for designing new networks without inventory and global bindings. One line per station.

Format: NET,STA,LAT,LON,ELEVATION,RMS

RMS (nm/s) is optional and required for minimum magnitude calcuation in offline mode.

stations.exclude-file¶

Type: string

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

Note

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

grid.region¶

Type: list:float

Unit: deg

Horizontal bounding box for selecting the considered region: LonMin,LonMax,LatMin,LatMax. Required parameter. Default is 80.0, 150.0, -20.0, 30.0.

grid.spacing¶

Type: double

Unit: deg

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.* 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: GRD (surfer grid), BNA (polygons), PNG (image file). Default is GRD.

output.size¶

Type: string

Unit: px

PNG image size, e.g 1280x1024 px. Default is 1280x1024.

output.script¶

Type: string

Path to the script which is executed when the network parameters are computed. Station reports and output files are provided to the script.

output.reportAllStations¶

Type: boolean

Report all stations and not just those with significant updates. output.script must be configured for this paramters to be effective. Default is false.

output.gradient.discrete¶

Type: boolean

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

output.gradient.stops¶

Type: gradient

The colors at given levels for drawing PNG images. Use hexadecimal color values. 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

travelTimes.* Parameters for calculating the travel times which are used by the methods minimum times and minimum magnitude.

travelTimes.tableType¶

Type: string

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

travelTimes.table¶

Type: string

Name of traveltime table. Default is iasp91.

travelTimes.velocityCorrection¶

Type: double

Unit: km/s

Correction velocity added to travel times in oder to account for station elevation which is currently not accounted for by LOCSAT and libtau. Applying a positive value deactivates “elevationCorrection” Default is -1.0.

travelTimes.elevationCorrection¶

Type: double

Unit: km

An elevation of stations added to the event depth for computing travel times. The travel-time table should start at this elevation correction. Currently, LOCSAT and libtau do not correct for sensor elevation.

The parameter is deactivated by “velocityCorrection”. Default is 0.0.

Note

times.* 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.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 must considers time windows for AIC used by scautopick and mB when using scautoloc with mB amplitudes. The value must be therefore be changed when adjusting those window lengths. Default is 5.0.

Note

minimumMagnitude.* 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.* Values for calculating the low-frequency amplitude. The method is used when “minimumMagnitude.type” = LF. Default values are from the ak135 standard Earth model at 10 km depth. The method requires travel times considering the parameters configured in the section “travelTime”.

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.

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¶

Format: NET,STA,LAT,LON,ELEVATION,RMS

RMS (nm/s) is optional and required for 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)

npeval¶

Description¶

Overview¶

Features¶

General Setup¶

Quality control parameters¶

Triggering and Timing¶

Methods¶

Minimum location time¶

Minimum magnitude¶

Travel-time computation¶

Output formats¶

Output visualization¶

Grid and Station Reports¶

Examples¶

Publications¶

References¶

Configuration¶

Command-line¶

Generic¶

Verbosity¶

Stations¶

Output¶

Region¶

Times¶

Table of Contents

This Page