.. _sec-scevalplugin:

Plugin: evsceval
================

**evsceval** is a plugin provided by :ref:`sceval` for :cite:t:`scevent`.


Description
-----------

*evsceval* sets the type and the certainty of an event by:

1. **Comments check:** If the preferred origin of an event contains the *maxGap*
   comment, the event type is set according to :confval:`sceval.maxGap` unless
   disabled by configuration. The configured event type may take any string
   value defined in the
   `EventType documentation <https://docs.gempa.de/seiscomp/current/base/api-python.html#api-python-datamodel-eventtype>`_.
   The *maxGap* comment itself is set by *sceval* as configured by
   :confval:`maxGap`.

#. **Percentage check:** The percentage of rejected origins of an event is
   calculated if the event has no manual origins. If the percentage exceeds
   :confval:`mismatchScore.rejected`, the event certainty is set to *suspected*
   unless disabled by configuration.

#. **Multiple-agency check:** The plugin tests the agency ID of all origins
   associated to an event. If the event contains origins with multipls agency
   IDs defined in :confval:`sceval.multipleAgency.targetAgency` and the origin
   is neither manual nor the status is *rejected*, *confirmed* or *final*, the
   origin status is set to the value configured in
   :confval:`sceval.multipleAgency.originStatus`. The changed origin status can
   be used as an additional criterion for further processing such as publication
   on websites or for setting the event type by :cite:t:`scevent`.

.. note::

   * Setting event type and certainty correctly requires SeisComP in version >=
     5.0.0. In lower version, values from manual processing may be overwritten
     by automatic ones.
   * Besides *evsceval*, :cite:t:`scevent` can load other plugins such as *evrc*
     that comes with *scevent*. If other plugins also set the event type, the
     event type is overwritten in the order of which the plugins are configured
     and loaded by *scevent*.


Setup
-----

The *evsceval* plugin is configured in the module configuration of
:cite:t:`scevent`. To make the plugin available add the plugin *evsceval* to the
plugins parameter. The plugins are executed in the order of configuration. In
case of multiple listings in :file:`global.cfg` or :file:`scevent.cfg`
only the first occurrence is considered. Thus, if other plugins exist which set
event parameters, the order determines the priority.

Adjust :file:`scevent.cfg`:

1. Load the *evsceval* plugin: Add to the global configuration or to the
   global configuration of *scevent* in the order of priority.

   .. code-block:: params

      plugins = ${plugins}, evsceval

      sceval.setEventType = true

#. Configure :confval:`sceval.maxGap` defining the event type set if the
   preferred origin of an event has a *maxGap* comment. *sceval* sets the maxGap
   comment if the GAP criterion is met. Currently supported value are listed
   as string values in the
   `EventType documentation <https://docs.gempa.de/seiscomp/current/base/api-python.html#api-python-datamodel-eventtype>`_.

   .. code-block:: sh

      sceval.maxGap = "not locatable"

#. Configure :confval:`sceval.rejected` to set the event certainty.

   .. code-block:: params

      sceval.rejected = 25

#. Configure the parameters related to the multiple-agency check.

   .. code-block:: params

      sceval.multipleAgency.targetAgency = agency, agency1
      sceval.multipleAgency.originStatus = reported

.. note::

   *scevent* fails to set the event type if the *evsceval* plugin is loaded
   but :confval:`sceval.maxGap` is not defined.

   The plugin overwrites the event type set before.
   The type of events which have manual origins will not be changed.