.. highlight:: rst

.. _npeval:

######
npeval
######

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


Description
===========

*npeval* evaluates and reports the station status and network performance parameters
based on network geometry and real-time waveform quality.
It generates reports of station status and waveform quality.

* The calculated network performance parameters include:

  #. The :ref:`minimum time<npeval-sec-loctimes>` required to locate seismic
     events in an area,
  #. The :ref:`minimum magnitude<npeval-sec-minmag>` of seismic events in an
     area for which the network is expected to deliver a location.
  #. The :ref:`S-P travel times <npeval-sec-sp>` from events in a grid to
     configurable points of interest.

* Independent of the network performance parameters the station status and
  waveform quality control (QC) parameters can be
  :ref:`reported to external applications <npeval-sec-reports>`, e.g. to GDS
  :cite:p:`gds` for dissemination.


Features
--------

#. Computes the minimum time required to locate a seismic event.
#. Computes the minimum magnitude for which a solution is expected.
#. Computes the S-P travel-time differences at points of interest.
#. 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 (QC) parameters.
#. Computation is triggered by significant changes in station status.
#. Writes computed parameters to Surfer grid files, BNA polygons which can be
   evaluated on SeisComP maps, PNG images or CSV files.
#. 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,
   * travel-time 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,
   * format of generated files: GRD, BNA, PNG, CSV,
   * output processing script.


Methods and 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., :cite:t:`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 :confval:`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 :confval:`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 :confval:`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 configured by :confval:`stations.stationCount`
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 :confval:`stations.file` and
:confval:`stations.exclude-file`, respectively.

The grid parameters :confval:`grid.region`, :confval:`grid.spacing` and
:confval:`grid.depths` define the considered source locations. Only one region
at a time can be taken into account. Create module aliases for considering
multiple regions. Module aliases can be generated and configured separately,
e.g., for a region named *r1*:

.. code-block:: sh

   seiscomp alias create r1npeval npeval

Storing the calculated parameters is controlled by the
:ref:`output control parameters <npeval-sec-output>`.

In real-time conditions a typical minimum configuration includes:

* Station setup by :confval:`setupName`: Global or other name of a picker module
  with bindings to stations,
* Definition of the monitoring region by :confval:`grid.region`.
* The choice of the methods, e.g. :confval:`times.compute` or :confval:`minimumMagnitude.compute`
  or the report generation by setting :confval:`output.script`.


.. _npeval-sec-qc-params:

Quality control parameters
--------------------------

All QC parameters configured by :confval:`qc.parameters` must be available for
the :confval:`minimum number of stations<stations.stationCount>`. 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
:confval:`setupName` are considered internally for further computations.

.. note::

   Real-time QC parameters are ignored in :ref:`offline mode <npeval-offline>`.


.. _npeval-sec-triggering:

Triggering and Timing
---------------------

npeval re-computes the grids by the :ref:`configured methods <npeval-sec-methods>`
or :ref:`generates reports <npeval-sec-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 :ref:`waveform QC parameters <npeval-sec-qc-params>` are found.
  That is the QC parameters of stations enter or leave the ranges configured in :confval:`qc.parameters`.
* Stations are actively enabled or disabled.

Repeated re-computation in short time intervals may be computational
expensive. Set the parameter :confval:`grid.update` to a reasonable interval to
control the timing and to optimize the load.


.. _npeval-sec-methods:

Methods
-------

*npeval* provides methods for computing performance parameters that characterize
seismic monitoring networks:

* :ref:`Minimum time<npeval-sec-loctimes>`: The minimum time which is required
  for locating events.
* :ref:`Minimum magnitude<npeval-sec-minmag>`: The minimum magnitude of events
  that can be located.
* :ref:`S-P travel times <npeval-sec-sp>`: The difference of travel times
  between P and S phases observed at a point of interest.

related to the network geometry and the data quality. The methods are applied
to the same region simultaneously.

The performance parameters 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 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 :ref:`output parameters can be stored <npeval-sec-output>` as surfer GRD, PNG
  image, BNA or CSV files. For
  :ref:`visualizing the grid files dynamically on maps <npeval-sec-vizualization>`,
  the plugin *mapmultigrid* :cite:p:`mapmultigrid` has been developed.


.. _npeval-sec-loctimes:

Minimum location time
.....................

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

Important parameters configurable in the **times** section are:

#. :confval:`times.file`: The base name 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 :confval:`output.directory` is created containing the different levels.
#.  Set the parameters for :ref:`computing the travel times <npeval-sec-travel-times>`.
#. :confval:`times.dataDelay`: The time added to the computed travel times
   considering the data delay measured by :cite:t:`scqc`.
   To read the delay from the SeisComP database and to receive dynamic updates

   .. code-block:: params

      times.dataDelay = -1.0

   Otherwise a static delay is considered.
#. :confval:`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 :cite:t:`scautoloc` or :cite:t:`scanloc`.
   :confval:`times.processingDelay` must be therefore be changed
   when adjusting those window lengths or module configurations.

.. _fig-npeval-times:

.. figure:: media/npeval_scmv_times.png
   :align: center
   :width: 16cm

   Minimum expected times for locating events in SE-Asia by the GE network.


.. _npeval-sec-minmag:

Minimum magnitude
.................

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

Important parameters configurable in the **minimumMagnitude** section are:

#. :confval:`minimumMagnitude.compute`: The base name 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 :confval:`output.directory` is created containing the
   different levels.
#. :confval:`minimumMagnitude.type`: The Types considered for computations.
   Currently, supported types are:

   * **MDD** (magnitude-detection-distance)
   * **LF** (low-frequency approximation of the source spectrum, experimental)
   * **GMPE** (Ground Motion Prediction Equation, experimental).

**Types:**

.. warning::

   The types LF and GMPE are currently experimental and may produce results with
   large uncertainties.

* **MDD - magnitude-detection distance** Considered when
  :confval:`minimumMagnitude.type` = **MDD**. The method assumes that for a
  given magnitude, P and S phases can be detected up to some hypocentral
  distance. The magnitude-distance relation is given by (:cite:t:`valtonen-2013`):

  .. math::

     M = b * log10(D) + a * D + c

  where:

  * *M:* magnitude
  * *D*: hypocentral distance enclosing a minimum of stations. The number is
    configured by :confval:`stations.stationCount`,
  * *a*: :confval:`minimumMagnitude.magnitudeDetectionDistance.a`,
  * *b*: :confval:`minimumMagnitude.magnitudeDetectionDistance.b`,
  * *c*: :confval:`minimumMagnitude.magnitudeDetectionDistance.c`.

  The parameters may be determined from optimization :cite:p:`valtonen-2013`
  based on reference events for the area of interest.
  The default values originate from :cite:t:`valtonen-2013` for a site in
  Finnland. Examples from previous optimizations are:

  .. csv-table::
    :align: center
    :widths: 10, 10, 10, 10
    :header: region, a, b, c

    Finland :cite:p:`valtonen-2013`, 0.001514, 0.9327, -1.306
    Chile [a]_, 0.001272, 0.887049, -0.065408
    Germany/Vogtland [a]_, 0.001639, 1.297967, -1.28476

  .. figure:: media/npeval-minmag-mdd-vogtland.png
     :align: left
     :width: 16cm

     Parameter optimization based on events in Germany/Vogtland [a]_.

  .. [a] Unpublished testbed studies by :cite:t:`gempa`.

* **LF - low-frequency-approximation**: Considered when
  :confval:`minimumMagnitude.type` = **LF**. Results are specifically sensitive
  to:

  * 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 Tramelli et al. (2015) :cite:p:`tramelli-2015`.
  * :ref:`travel times computation <npeval-sec-travel-times>` to account for
    anelastic attenuation.
  * magnitude range defined by :confval:`minimumMagnitude.magMin` and
    :confval:`minimumMagnitude.magMax` and the intervals by
    :confval:`minimumMagnitude.magStep`.
  *. :confval:`minimumMagnitude.minSnr` defining 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  measured by scqc :cite:p:`scqc`.
* **GMPE - GoundMotionPredictionEquation**: Considered when
  :confval:`minimumMagnitude.type` = **GMPE**. The method uses an internally
  defined GMPE based on the publication by :cite:t:`cauzzi-2015`.
  Choosing GMPE is currently experimental only experimental and not recommended
  for routine processing.

.. _fig-npeval-magnitudes:

.. figure:: media/npeval_scmv_magnitude.png
   :align: center
   :width: 16cm

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

.. note::

   Applying the type *LF* to the minimum magnitude method requires waveform RMS
   to be available from real-time station QC messages or from a station input
   file (see command line option :option:`--file`).


.. _npeval-sec-sp:

S-P travel times
................

The travel-time differences between first arriving P and S phases are computed at
points of interest (POIs) assuming events defined on the configured grid.
In an earthquake early warning (EEW) system, the method may be used to estimate
the remaining alert time at a POI in case a P phase was detected.

Configuration;

* Adjust the parameters controlling the travel-times computations in the *travelTimes*
  parameter groups,
* Add profiles of points of interest with activate
  :confval:`POIs.profiles.$name.computeSP` for the respective profile,
* Add the profile name to :confval:`POIs.poiProfiles`.

.. figure:: media/npeval_sp.png
   :align: center
   :width: 16cm

   S-P travel-time differences for a POI in Potsdam, Germany and a given travel-time
   table.


.. _npeval-sec-travel-times:

Travel-time computation
.......................

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


*  :confval:`travelTimes.tableType` and :confval:`travelTimes.table`: Type of
   the interface and name of the travel time tables. Typically, the
   :cite:t:`locsat` interface provides faster travel times than libtau. By
   setting the :confval:`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 :file:`@DATADIR@/locsat/tables/`,
   for **libtau**, the velocity profile is stored in :file:`@DATADIR@/ttt`.
   Both travel-time interfaces do not consider stations elevations.

*  Correction parameters: Travel-time corrections :math:`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
   :confval:`travelTimes.velocityCorrection`.

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

   .. math::

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

   .. note::

      For :math:`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. :program:`npeval` will stop providing and an error message.
      Then consider lowering :confval:`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 :confval:`travelTimes.elevationCorrection`. The travel-time tables
   must then be computed with respect to this elevation where 0 km depth corresponds to the correction.


.. _npeval-offline:

Offline processing
------------------

npeval can be used in offline processing mode without messaging and real-time data
acquisition. Execute npeval on the command line together with other appropriate
options

.. code-block:: sh

   npeval --offline

In this case, waveform QC messages are ignored. This requires the configuration
of :confval:`times.dataDelay` must be configured for computing the
:ref:`minimum location times <npeval-sec-loctimes>` and the RMS must be set for
computing the :ref:`minimum magnitudes <npeval-sec-minmag>`. More command-line options
are available.


.. _npeval-network-design:

Designing Networks
==================

In :ref:`offline processing mode <npeval-offline>`, npeval supports you in
designing and optimizing of networks by predicting the performance parameters
based on a generic station list:

#. Configure the required :ref:`methods <npeval-sec-methods>`
#. Create a file, :file:`station.txt`, containing the station coordinates and QC
   parameters in the format [NET,STA,LAT,LON,ELEVATION,RMS] where RMS is
   measured in the unit of counts. Example:

   .. code-block:: params

     CX, PB01, -21.04, -69.49, 320, 150
     CX, PB02, -21.32, -69.90, 470, 250

   An example script for generating the station table is available in
   :file:`@DATADIR@/npeval/tools/npeval-make-station-file.sh.example`.

#.  Run npeval and generate the output

    .. code-block:: sh

       npeval --offline --file stations.txt


.. _npeval-sec-output:

Output
======


File formats
------------

The the output parameters resulting from the considered
:ref:`methods <npeval-sec-methods>` are stored in the directory and in the file
format configured by :confval:`output.directory` and :confval:`output.format`,
respectively. By default, the output directory is cleared before updating the
files. The supported output formats, defined in :confval:`output.format` are:

* **BNA** files. File suffix: *bna*.

  One sub-directory of :confval:`output.directory` is generated per
  method containing all BNA files. The BNA files contain polylines or closed
  polygons which can be drawn as layers on map with customized properties
  :cite:p:`gui`. The lines represent minimum values.

  The layers are drawn at startup of a GUI module, when the
  :confval:`output directory <output.directory>` is either
  :file:`@DATADIR/spatial/vector@` or :file:`@CONFIGDIR@/spatial/vector`. A GUI
  module must therefore be restarted for considering any file update.
* **CSV** comma-separated text file. File suffix: *csv*.

  One file is generated per configured method. Line format:

  .. code-block:: params

     longitude0, latitude0, value0
     longitude1, latitude1, value1
      ...

* **GRD (default)** file (Surfer grid). File suffix: *grd*.

  One file is generated per method. Grid files can be rendered and
  dynamically updated on maps by the plugin :cite:t:`mapmultigrid`.
  **GRD is therefore the preferred format.** The configuration of the rendering
  is described in section :ref:`npeval-sec-visualization`.
* **PNG** image file. File suffix: *png*.

  One file is generated per method. The colors and contour lines represent
  minimum values.It is viewable by external image viewers.

.. note::

   * By default all files and directories existing in :confval:`output.directory`
     are deleted by npeval when computing any of the desired values. To keep the
     existing files and directories, uncheck :confval:`output.clean`.
   * When running different instances of npeval, configure different output
     directories which are specific to an instance avoiding to mutually delete
     the result files.


.. _npeval-sec-visualization:

Grid visualization
------------------

Grid files can be dynamically rendered on maps, e.g., of :cite:t:`scmv` by
configuration of the plugin :cite:t:`mapmultigrid` forming an individual map
layer. Multiple grid files can be rendered simultaneously. Upon any changes the
grids will be immediately updated on the maps. Read the documentation of
:cite:t:`mapmultigrid` for the complete configuration steps and examples.


.. _npeval-sec-steps:

Stops/colors
------------

The contours in PNG images and BNA files and the colors (PNG and grids,
visualized by the plugin :cite:t:`mapmultigrid`) represent minimum values. They
can be configured by stops which are pairs of computed value and color. The
additional attribute "major" or "minor" controls drawing the contour lines in
PNG images or the grids.

The stops are configurable in npeval by :confval:`output.gradient.stops` for PNG
or BNA output format. For grid visualization configure the *stops* parameter
along with the  plugin :cite:t:`mapmultigrid`.

A suggestion for the stops configuration stops is printed when running npeval
with debug logging output. Example:

.. code-block:: sh

   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 and apply the values to the configuration. The number of printed stops
can be controlled by the command-line option :option:`--suggest-color-intervals`.
Example:

.. code-block:: sh

   npeval --debug --suggest-color-intervals 10


.. _npeval-sec-reports:

Reports: Station QC and grids
-----------------------------

Reports are generated upon
:ref:`significant changes in QC parameters and/or when triggering of the parameter computation <npeval-sec-triggering>`.
If an executable script is defined in :confval:`output.script`, e.g.

.. code-block:: params

   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 containing:

* 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 :confval:`output.reportAllStations`.

Example:

.. code-block:: params

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

The JSON data is provided via stdout to the script in :confval:`output.script`
which is executed. The exit code of the script is evaluated and an error message
is printed if the exit code is not *0*.

An example script for processing the JSON data is provided in
:file:`@DATADIR@/npeval/tools/npeval-report.sh.example`. The raw JSON format
contains no line breaks but it can be converted by other tools, e.g.,
:program:`jsonlint` for better human readability.

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


Getting Started
===============

For computing **values related to events** a minimum configuration is
recommended:

#. Define the events by grid region, depths and spacing: :confval:`grid.region`,
   :confval:`grid.depths`, :confval:`grid.spacing`,
#. Adjust the minimum number of stations which are expected to provide phase
   detections: :confval:`stations.stationCount` considering the module creating
   origins.
#. Configure the stations to consider:

   * **normal processing:** Configure :confval:`setupName` for defining the set
     of stations which has a particular set of bindings. Use *global* for all
     stations having global bindings. Setting the value to the instance of
     :cite:t:`scautopick` providing the phase picks allows the specific
     consideration of pipelines.

   * **network designing:** If no inventory or system setup is availble, you may
     generate a simple text file containing the station names, coordinates and
     an optional characteristic data RMS value. Format:

     .. code-block:: params

        network code, station code, latitude, longitude, elevation, RMS

     Provide the station file by configuration of :confval:stations.file` or on
     the command line via :option:`--file`.
#. Define the output format: :confval:`output.format`. For *BNA* or *PNG*
   additionaly provide the stops: :confval:`output.gradient.stops`
#. Configure the methods to be considered: :confval:`times.*` and
   :confval:`minimumMagnitude.*`.

   * For specific points of interest configuring the POIs parameters,
     :confval:`POIs`.

For sending **reports on significant changes** of station parameters and
updates configure:

#. The waveform QC paramters to be considered: :confval:`qc.parameters`.
#. The report script to handle the reports: :confval:`output.script`.


.. _npeval-sec-example:

Examples
========

#. Real-time processing on the command line considering waveform QC messages:

   .. code-block:: sh

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

#. Real-time processing on the command line considering constant RMS (*nm/s*):

   .. code-block:: sh

      npeval -d localhost/seiscomp --rms 500

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

   .. code-block:: sh

      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:

   .. code-block:: sh

      npeval --offline --file stations.ini --rms 300



Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/npeval.cfg`
| :file:`etc/global.cfg`
| :file:`etc/npeval.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/npeval.cfg`

npeval inherits :ref:`global options<global-configuration>`.

.. note::

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

      gempa.licensePath = @CONFIGDIR@/licenses



.. confval:: setupName

   Default: ``scautopick``

   Type: *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 npeval subscribes*
   *to basic message groups, e.g. QC, CONFIG.*


.. confval:: qc.parameters

   Type: *list:string*

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


.. confval:: qc.useDatabase

   Default: ``false``

   Type: *boolean*

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


.. note::

   **stations.\***
   *Parameters controlling the stations to be considered.*


.. confval:: stations.stationCount

   Default: ``4``

   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.


.. confval:: stations.file

   Type: *string*

   Name of CSV file 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.


.. confval:: stations.exclude-file

   Type: *string*

   Filename to a station blocklist file. Each line has the format
   [NET].[STA] supporting wildcards. Example:
   
   CX.PB01
   
   GE.\*


.. note::

   **grid.\***
   *Parameters controlling the source region grid and the update*
   *interval. Grid points represent hypocenters.*


.. confval:: grid.region

   Default: ``80.0, 150.0, -20.0, 30.0``

   Unit: *deg*

   Type: *list:float*

   Horizontal bounding box for selecting the considered region:
   LonMin,LonMax,LatMin,LatMax. Required parameter.


.. confval:: grid.spacing

   Default: ``1.0``

   Unit: *deg*

   Type: *double*

   Horizontal grid spacing for assuming events.


.. confval:: grid.depths

   Default: ``10.0``

   Unit: *km*

   Type: *list:double*

   Source depths. Use comma seperation for a list of values.


.. confval:: grid.update

   Default: ``60``

   Unit: *s*

   Type: *double*

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


.. note::

   **output.\***
   *Output control parameters.*


.. confval:: output.directory

   Default: ``/tmp/npeval``

   Type: *string*

   Output directory for writing new files. Recommendation for
   BNA files: \@DATADIR\@\/spatial\/vector\/npeval.


.. confval:: output.clean

   Default: ``true``

   Type: *boolean*

   Clean output directory before writing new files.


.. confval:: output.format

   Default: ``GRD``

   Type: *string*

   Range: ``BNA,PNG,GRD,CSV``

   Output file format.


.. confval:: output.size

   Default: ``1280x1024``

   Unit: *px*

   Type: *string*

   PNG image size.


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


.. confval:: output.reportAllStations

   Default: ``false``

   Type: *boolean*

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


.. confval:: output.gradient.discrete

   Default: ``true``

   Type: *boolean*

   Setting this parameter to true enables color interpolation.


.. confval:: output.gradient.stops

   Default: ``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``

   Type: *gradient*

   The colors at given levels for drawing PNG images.
   Use hexadecimal color values.


.. note::

   **travelTimes.\***
   *Parameters for calculating the travel times which are used by the*
   *methods minimum time, minimum magnitude and S-P travel times.*


.. confval:: travelTimes.tableType

   Default: ``LOCSAT``

   Type: *string*

   Values: ``libtau, LOCSAT``

   Type of travel\-time table \(interface\).


.. confval:: travelTimes.table

   Default: ``iasp91``

   Type: *string*

   Name of travel\-time table \(interface profile\).


.. confval:: travelTimes.velocityCorrection

   Default: ``-1.0``

   Unit: *km/s*

   Type: *double*

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


.. confval:: travelTimes.elevationCorrection

   Default: ``0.0``

   Unit: *km*

   Type: *double*

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


.. note::

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


.. confval:: times.compute

   Default: ``true``

   Type: *boolean*

   Allow computing the minimum times.


.. confval:: times.file

   Default: ``npeval_times``

   Type: *string*

   Basename of output file\(s\) for the times grid.


.. confval:: times.dataDelay

   Default: ``-1.0``

   Unit: *s*

   Type: *float*

   Data delay to be added to computed traveltimes.
   
   \-1.0 \- get automatically from QC messages per station.


.. confval:: times.processingDelay

   Default: ``5.0``

   Unit: *s*

   Type: *float*

   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.


.. note::

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


.. confval:: minimumMagnitude.compute

   Default: ``false``

   Type: *boolean*

   Allow computing the expected minimum magnitude.


.. confval:: minimumMagnitude.file

   Default: ``npeval_minmag``

   Type: *string*

   Basename of output file\(s\) for the magnitudes grid.


.. confval:: minimumMagnitude.type

   Default: ``LF``

   Type: *string*

   Type of amplitude calculation:
   
   LF: low\-frequency approximation
   
   MDD: magnitude\-detection distance
   
   GMPE: GMPE \(trial only\).


.. confval:: minimumMagnitude.magMin

   Default: ``2.0``

   Type: *float*

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


.. confval:: minimumMagnitude.magMax

   Default: ``5.0``

   Type: *float*

   Maximum earthquake magnitude to be tested.


.. confval:: minimumMagnitude.magStep

   Default: ``0.2``

   Type: *float*

   Magnitude step.


.. confval:: minimumMagnitude.minSnr

   Default: ``5``

   Type: *float*

   Minimum signal\-to\-noise ratio at the station to accept a
   magnitude.


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


.. confval:: minimumMagnitude.lowFrequency.vp

   Default: ``5.8``

   Unit: *km/s*

   Type: *float*

   P\-wave velocity at the hypocentre.


.. confval:: minimumMagnitude.lowFrequency.vs

   Default: ``3.2``

   Unit: *km/s*

   Type: *float*

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


.. confval:: minimumMagnitude.lowFrequency.rho

   Default: ``2.6``

   Unit: *g/cm^3*

   Type: *float*

   Density at the hypocentre.


.. confval:: minimumMagnitude.lowFrequency.sigma

   Default: ``10``

   Unit: *bar*

   Type: *float*

   Stress drop due to the earthquake.


.. confval:: minimumMagnitude.lowFrequency.qp

   Default: ``500``

   Type: *float*

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


.. note::

   **minimumMagnitude.magnitudeDetectionDistance.\***
   *Values for calculating the expected magnitude based on*
   *based on the regression of M = b*log10(distance) + a * distance + c.*
   *Defaults are from Valtonen et al. (2013).*


.. confval:: minimumMagnitude.magnitudeDetectionDistance.a

   Default: ``0.001514``

   Unit: *1/km*

   Type: *float*

   The a parameter in the regression equation.


.. confval:: minimumMagnitude.magnitudeDetectionDistance.b

   Default: ``0.9327``

   Type: *float*

   The b parameter in the regression equation.


.. confval:: minimumMagnitude.magnitudeDetectionDistance.c

   Default: ``-1.306``

   Type: *float*

   The c parameter in the regression equation.


.. note::

   **POIs.\***
   *Compute paramters for individual points of interest (POI).*


.. confval:: POIs.file

   Default: ``npeval_poi``

   Type: *string*

   Base name of output file\(s\) for the POIs grid. The profile
   name will be appended.


.. confval:: POIs.poiProfiles

   Type: *list:string*

   Registration of POI profiles.
   An empty list disables all POIs.


.. note::

   **POIs.profiles.$name.\***
   $name is a placeholder for the name to be used and needs to be added to :confval:`poiProfiles` to become active.

   .. code-block:: sh

      poiProfiles = a,b
      POIs.profiles.a.value1 = ...
      POIs.profiles.b.value1 = ...
      # c is not active because it has not been added
      # to the list of poiProfiles
      POIs.profiles.c.value1 = ...


.. confval:: POIs.profiles.$name.latitude

   Unit: *deg*

   Type: *double*

   Latitude.


.. confval:: POIs.profiles.$name.longitude

   Unit: *deg*

   Type: *double*

   Longitude.


.. confval:: POIs.profiles.$name.elevation

   Unit: *km*

   Type: *double*

   Elevation above above sea level \(WGS84\).


.. confval:: POIs.profiles.$name.computeSP

   Default: ``false``

   Type: *boolean*

   Select to compute S\-P travel time differences.




Command-Line Options
====================


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

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

.. option:: --plugins arg

   Load given plugins.

.. option:: -D, --daemon

   Run as daemon. This means the application will fork itself
   and doesn't need to be started with \&.


Verbosity
---------

.. option:: --verbosity arg

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

.. option:: -v, --v

   Increase verbosity level \(may be repeated, eg. \-vv\).

.. option:: -q, --quiet

   Quiet mode: no logging output.

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

.. option:: --component arg

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

.. option:: -s, --syslog

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

.. option:: -l, --lockfile arg

   Path to lock file.

.. option:: --console arg

   Send log output to stdout.

.. option:: --debug

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

.. option:: --trace

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

.. option:: --log-file arg

   Use alternative log file.


Stations
--------

.. option:: --file arg

   Overrides configuration parameter :confval:`stations.file`.


.. option:: --exclude-file arg

   Overrides configuration parameter :confval:`stations.exclude-file`.


.. option:: --skip arg

   Default: ``0.0``

   Unit: *%*

   Type: *double*

   Randomly skip the given percentage of stations.


Output
------

.. option:: -f, --format arg

   Overrides configuration parameter :confval:`output.format`.


.. option:: --directory arg

   Overrides configuration parameter :confval:`output.directory`.


.. option:: --size arg

   Overrides configuration parameter :confval:`output.size`.


.. option:: --no-clean

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

.. option:: --clean

   Overrides configuration parameter :confval:`output.clean`.

   Overrides \-\-no\-clean.

.. option:: --suggest-color-intervals arg

   Default: ``5``

   Type: *int*

   The number of contour intervals and related color to suggest
   together along with debug logging output.


Region
------

.. option:: --region arg

   Overrides configuration parameter :confval:`grid.region`.


.. option:: -s, --spacing arg

   Overrides configuration parameter :confval:`grid.spacing`.


.. option:: --depths arg

   Overrides configuration parameter :confval:`grid.depths`.

   For series use \-\-depths 10 \-\-depths 20 ...


Times
-----

.. option:: --dataDelay arg

   Overrides configuration parameter :confval:`times.dataDelay`.


.. option:: --procDelay arg

   Overrides configuration parameter :confval:`times.processingDelay`.


.. option:: -c, --station-count arg

   Overrides configuration parameter :confval:`stations.stationCount`.


.. option:: --times-file arg

   Overrides configuration parameter :confval:`times.file`.