.. highlight:: rst

.. _scqceval:

########
scqceval
########

**Station - QC - Evaluator and Re-Configurator based on QC messages and configured thresholds.**


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

*scqceval* dynamically re-configures the network processing based on waveform quality
(QC) parameters. These data are typically provided by the SeisComP module :cite:t:`scqc`.
In case of inhomogeneous stations geometry of an earthquake monitoring setup where,
e.g. an array is included within a network,
the earthquake solution may be biased. Therefore only a subset of the station, e.g. the
reference station of the array, may be used for the monitoring network. However, this or
other stations may be of variable data quality. In case of low data quality alternative
stations should be used. scqceval realizes such a re-configuration in real time
based on the data quality parameters.
Therefore scqceval allows to maintain homogeneous networks with high monitoring quality.
The changes in the network configuration effects other parameters such as the amount of time
required to locate events or the minimum magnitude which can be detected. Such changes
in network performance are automatically monitored and reported by
`npeval <https://docs.gempa.de/npeval/current/>`_.


.. _scqceval-sec-features:

Features
========

*scqceval* dynamically re-configures the data processing of a |scname| system in real time by:

* Evaluating **station quality (QC) parameters**. It can take any QC parameters delivered
  by any plugin for :cite:t:`scqc`.
* Activation and deactivation (enable / disable) of **single stations** with their location
  and streams based on the QC parameters
* **Dynamic switching** between a primary and a secondary station or even station chains
  based on the QC parameters
* Considering **interactive re-configurations** by other modules, e.g.

  * scrttv.


.. _scqceval-sec-config:

Setup
=====

scqceval requires:

* Waveform QC parameters, typically provided by :cite:t:`scqc`.
  Thus, configure and start :program:`scqc` in real-time applications.

* Bindings configuration:

  * create scqceval bindings for each station to be considered by
    scqceval
  * enable or disable the stations for control by scqceval.

* Module configuration:

  * defined primary and seconday stations by :confval:`qc.pairs`. Station not
    being members of pairs but having scqceval bindigs will be enabled or disabled
    depending on their QC parameters without considering alternatives.
  * set the time which prevents scqceval from reconfiguration after an initial
    reconfiguration by other modules: :confval:`qc.resetAuthorAfter`
  * decide which QC parameters define enabling a stations:
    :confval:`qc.parameters` within the configured ranges. Stations with QC parameter
    values outside the ranges are disabled by scqceval.

    :confval:`qc.parameters` can be either configured with:

    * a list of :ref:`bolean expressions of QC parameters<scqceval-bolean-expressions>`
      This option allows to consider multiple parameter ranges as required for
      some intervals or
    * a list of :ref:`simple QC parameter ranges <scqceval-simple-ranges>`.


.. _scqceval-bolean-expressions:

QC: Boolean expressions
-----------------------

**Boolean expressions** allow the definition of advanced conditions for QC parameters
including multiple ranges, e.g. for intervals or spikes, gaps, overlaps.

As an alternative of specifying individual rules, :confval:`qc.parameters`
can be set to a single boolean expression. This expression is evaluated as
a whole to determine whether a station can be enabled or needs to be disabled.

The following operators are available:

- Arithmetic operators:

  - :code:`+a`
  - :code:`-a`
  - :code:`a + b`
  - :code:`a - b`
  - :code:`a * b`
  - :code:`a / b`

  All operators return the result of their specific arithmetic operation.
  The common precedence rules apply when combining different operators.

- Comparison operators:

  - :code:`a < b`  - Evaluates to true if and only if :code:`a` is less than :code:`b`.
  - :code:`a > b`  - Evaluates to true if and only if :code:`a` is greater than :code:`b`.
  - :code:`a <= b` - Evaluates to true if and only if :code:`a` is less than or equal to :code:`b`.
  - :code:`a >= b` - Evaluates to true if and only if :code:`a` is greater than or equal to :code:`b`.
  - :code:`a == b` - Evaluates to true if and only if :code:`a` is equal to :code:`b`.
  - :code:`a != b` - Evaluates to true if and only if :code:`a` is not equal to :code:`b`.

- Logical operators (ordered by precedence):

  - :code:`!a` - Evaluates to true if and only if the operand is false.
  - :code:`a && b` - Evaluates to true if and only if both operands are true.
  - :code:`a || b` - Evaluates to true if and only if at least one operand is true.

Predefined precedence rules can be overridden by parentheses.

Examples:

- :code:`(latency < 600 || delay < 60) && (gaps count > 0 && gaps count <= 1)`
- :code:`gaps count + overlaps count < 20`

Configuration with (conservative) choices resembling the default range but **adding
ranges for intervals** of gaps, spikes and overlaps: ::

  qc.parameters = "(availability>=40)" \
                  "&& (gaps count<=1)" \
                  "&& (overlaps count<=1)" \
                  "&& (timing quality>=40)" \
                  "&& (rms>=20)" \
                  "&& (spikes count<=60)" \
                  "&& (gaps interval>=60 || gaps interval<=0)" \
                  "&& (spikes interval>=60 || spikes interval<=0)" \
                  "&& (overlaps interval>=60 || overlaps interval<=0)"

.. hint ::

   Double quotes around the parameters are mandatory for correctly reading the
   parameter names.


.. _scqceval-simple-ranges:

QC: simple ranges
-----------------

Parameter ranges define the start and the end of intervals which are exceptable
for enabling a station. Stations are disbaled if they have any QC parameter outside
the range.

Configuration with default (conservative) choices are: ::

   qc.parameters = "availability: 40.0,100.0",\
                   "gaps count: 0,1",\
                   "overlaps count: 0,1",\
                   "timing quality: 40,Inf",\
                   "rms: 20,Inf",\
                   "spikes count: -Inf,60"

.. hint ::

   Double quotes around the parameters are mandatory for correctly reading the
   parameter names.

Other recommendations are:

- availability: 40.0,100.0
- gaps count: 0,10
- overlaps count: 0,10
- latency: -Inf,600
- delay: 0,60
- timing quality: 90,Inf
- offset: -700000,700000
- spikes count: -Inf,0
- timing quality: 40,Inf
- rms: 20,Inf
- gaps length: -Inf,60
- overlaps length: 0,60

.. warning ::

   The intervals of QC measures such as spikes, gaps and overlaps
   is *0 s* if the measure is found only once. While accepting stations with
   spikes, gaps, overlaps at large intervals, a *0 s* interval may also be
   acceptable. Use :ref:`boolean expressions <scqceval-bolean-expressions>`
   to define multiple acceptance intervals.
   Otherwise, stations may be disabled unexpectedly.


.. _scqceval-sec-examples:

Examples
========

* The stations GE.VAL and GE.RGN are automatically disabled by scqceval and their
  alternatives are activated.

  .. _fig-scqceval-scqc1:

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

     Primary:secondary configuration: **GE.VAL** : GE.WLF ; **GE.RGN** : GE.SBV : GE.UGM

  .. _fig-scqceval-scqc2:

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

     Switch to secondary configuration due to exceedance of QC parameters gaps and delay:
     GE.VAL : **GE.WLF** ; GE.RGN : GE.SBV : **GE.UGM**


Playbacks
=========

In real-time waveform playbacks the waveforms are fed to the data server, e.g.
using :program:`msrtsimul`.
The QC parameters can then be provided by :program:`scqc`.
However, :program:`scqc` reports the parameters in intervals and based on buffer
periods which are specific to each QC parameter. These report parameters are
configured in :program:`scqc`. Read the
documentation of :cite:t:`scqc`
or the tool tips in scconfig for the module parameters of :program:`scqc` for
the details.

In order to be able to provide the configured QC parameters to :program:`scqceval`,
an amount of data sufficient to fill the buffer for these QC parameters must be
provided to :program:`scqc`. Configure the :program:`scqceval` parameter
:confval:`qc.ignoreMissingParametersAfter` to allow initialisation and to ignore
QC parameters missing thereafter, e.g.::

   qc.ignoreMissingParametersAfter = 600

Actual waveform playback:

#. Start all required data acquisition and processing modules including :program:`scqc`
   and :program:`scqceval`,
#. Inject the waveform data to the data server using :program:`msrtsimul`,
#. Observe the enabled and disabled stations in scqcv, scrttv and scmv or
   read the debug output of data processing modules.



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

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

scqceval 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:: 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. Use
   '\-Inf' resp. 'Inf' if no upper or lower bound should exist.
   Supported QC parameters are availability, gaps count,
   overlaps count, latency, delay, timing quality, offset, rms
   and spikes count.
   
   Example:
   
   qc.parameters \= \"availability: 40.0,100.0\", \"gaps count: 0,1\", \"overlaps count: 0,1\"
   
   Alternatively, it is possible to define a single boolean
   expression which will be evaluated by scqceval.
   A station is disabled if the given expression
   evaluates to false. See section \"Setup\"
   for a list of available operators.
   
   Example:
   
   qc.parameters \= \"\(availability >\= 40\) \&\& \(gaps count <\= 1\) \&\& \(overlaps count <\= 1\) \&\& \(spikes interval <\= 0 \|\| spikes interval >\= 60\)\"


.. confval:: qc.pairs

   Type: *list:string*

   Define the primary and secondary station sorted by their
   priority in descending order. The station with the highest
   priority that fulfills all QC parameters is enabled.
   Primary stations outside a QC parameter range are disabled.
   Stations not listed here are simply enabled or disabled
   based on the QC parameters
   without a replacement by a secondary station. All stations
   to be considered must be enabled by scqceval bindings.
   
   Example:
   
   qc.pairs \= GE.VAL : GE.WLF, GE.UGM : GE.SBV : GE.RGN, GE.UGM : GE.WLF


.. confval:: qc.resetAuthorAfter

   Default: ``-1``

   Unit: *s*

   Type: *int*

   Allow control over foreign stations after the specified time
   following a reconfiguration. A re\-configuration can be e.g.
   enabling or disabling of a station in scrttv or scqcv.
   which have not been modified within the given number of seconds.
   
   0: immediate control over all reconfigured stations
   
   \-1: control is disabled, scqceval will not reconfigure a
   foreign station


.. confval:: qc.ignoreMissingParametersAfter

   Default: ``0``

   Unit: *s*

   Type: *int*

   On startup, wait the given number of seconds to retrieve QC messages for all of the configured parameters
   before toggling a station. After this period, QC parameters without a value will be ignored. Use
   \-1 to wait indefinitely.


.. confval:: qc.useDatabase

   Default: ``false``

   Type: *bool*

   Load initial QC parameters from the database.



Bindings Parameters
===================


.. confval:: enable

   Default: ``true``

   Type: *boolean*

   Enables\/disables usage of station with qceval.