seiscomp-training/share/doc/seiscomp/html/_sources/apps/scevent_regioncheck.rst.txt

.. _scevent_regioncheck:

###########
RegionCheck
###########

evrc plugin for scevent

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

*evrc* (event region check) is a :term:`plugin` for :ref:`scevent` setting the
event type by comparing the location of the preferred origin with
:ref:`defined regions <sec-evrc-regions>`.

.. note::

   Events for which the mode of the preferred origin is "manual" are by default
   not considered.


.. _sec-evrc-regions:

Definition of regions
---------------------

The regions are defined by closed polygons provided as
:ref:`BNA files <sec-gui_layers>`. Configure :confval:`rc.regions` to consider
a region defined by its name given in the header of the BNA polygon.

There exist **positive and negative regions**:

* **Positive region:** All events within the area enclosed by the polygon are flagged positive,
  all events not enclosed by the polygon are flagged negative.
* **Negative region:** All events within the area enclosed by the polygon are flagged negative,
  all events not enclosed by the polygon are flagged positive.

Regions are negative if the :confval:`name <rc.regions>` of the enclosing polygon
starts with **!** (exclamation mark. Otherwise the region is positive.

If a list of region names is defined, the last matching region in the list takes
priority when treating events.


Treatment of events
-------------------

When the *evrc* plugin is loaded and configured, the location of the preferred origin
of an events is compared with the defined regions.
Events within a positive and a negative region are flagged positive and negative, respectively.
By default it sets the event type to "outside of network interest" if the event is
flagged negative.

#. When activating :confval:`rc.readEventTypeFromBNA` the type of positive events is set according
   to the eventType defined in :ref:`BNA headers <sec-evrc-bna>`.
   The type of negative events is set according to :confval:`rc.eventTypeNegative`.
   Prepend 'accept' to the list of polygons to unset the type of negative events.
#. When :confval:`rc.readEventTypeFromBNA` is inactive, the event type is set
   based on :confval:`rc.eventTypePositive` and :confval:`rc.eventTypeNegative`:

   #. by default the type of all negative events (events within negative regions)
      is set to "outside of network interest".
      Prepend **accept** to :confval:`rc.regions` to unset the event type for negative events.

   #. **positive:** The event type of positive events is set to :confval:`rc.eventTypePositive`.
      For empty :confval:`rc.eventTypePositive` the type is unset.

   #. **negative:** The event type of negative events is set to :confval:`rc.eventTypeNegative`.
      The default type for negative events is "outside of network interest".

Evaluation is made based on the order of the regions names defined in :confval:`rc.regions`.
The last matching criteria applies.
In this way disjunct and overlapping regions with different behavior can be defined.
If events ARE NOT within positive regions their type is set to "outside of network interest".


.. _fig-evrc-region:

.. figure:: media/regions.png
  :align: center
  :width: 10cm

  Disjunct and overlapping regions in front of a default.


Event types
-----------

The event types are either set based the types configured in
:confval:`rc.eventTypePositive` and :confval:`rc.eventTypeNegative`
or based on the type provided by the header of BNA polygons if
:confval:`rc.readEventTypeFromBNA` is active.


Type definition
~~~~~~~~~~~~~~~

For defining the event type, any value defined in :cite:t:`uml`.
The list of valid values can also be found in the Event tab of :ref:`scolv`: Type.

Examples for valid event types:

* earthquake
* quarry blast
* nuclear explosion
* not existing
* ...

Invalid values result in errors which are reported depending on the verbosity
level of :ref:`scevent`.


.. _sec-evrc-bna:

Event type from BNA
~~~~~~~~~~~~~~~~~~~

If :confval:`rc.readEventTypeFromBNA` is active, the event type is read from the
header of the feature. Use a key-value pair in double quotes to specify the type
where the key is "eventType" and the value is the event type. Key and value are
separated by ":".

Example BNA file:

.. code-block:: sh

   "coal","rank 1","eventType: mining explosion",6
   13.392,50.3002
   13.2244,50.4106
   13.4744,50.5347
   13.6886,50.4945
   13.6089,50.358
   13.6089,50.358

where the name of the polygon / region is "coal" and the considered event type
is "mining explosion". The name and the rank are mandatory fields.

The depth of the event can be tested, too. For events within a region but with
depth outside a depth range the type
is not set. The limits of the depth range can be added to the header of the BNA files
using the key words *minDepth* and *maxDepth*. The depth *d* of an event must be
within the range


.. math::

   minDepth \le d \le maxDepth

The depth is only tested if minDepth or maxDepth or both are set and if
:confval:`rc.readEventTypeFromBNA` is active.

Example BNA file:

.. code-block:: sh

   "coal","rank 1","eventType: mining explosion, minDepth: -5, maxDepth: 10",6
   13.392,50.3002
   ...

.. warning::

   * The names of polygons, e.g. coal, are case sensitive and must not contain commas.
   * A hierarchy applies to the reading of BNA files. Read the section
     :ref:`sec-gui_layers-vector` for the details.


Setting up the Plugin
======================

Load the *evrc* plugin: Add to the global configuration or to the
global configuration of :ref:`scevent`  in the order of priority:

.. code-block:: sh

   plugins = ${plugins},evrc

Add BNA polygons by defining :confval:`rc.regions`.
Use the region name to define positive and negative regions. Names with
leading *!* define negative regions.

.. code-block:: sh

   rc.regions = accept,area

.. note::

   :ref:`scevent` stops
   if the *evrc* plugin is loaded but :confval:`rc.regions` is not defined.

Activate :confval:`rc.readEventTypeFromBNA` and add the eventType key-value pair
to the header of the :ref:`BNA polygon <sec-evrc-bna>` if the event type shall
be read from the BNA polygon.


**Examples:**

Set type of events within the positive polygon **germany** but do not change the
type outside:

.. code-block:: sh

   rc.regions = accept,germany

Accept all events without setting the type but set the type for all events within
the positive polygon **germany** but consider negative within the polygon **quarries**:

.. code-block:: sh

   rc.regions = accept,germany,!quarries

Accept all events without setting the type but consider events within the negative polygon **germany**
and events within the positive polygon **saxony**:

.. code-block:: sh

   rc.regions = accept,!germany,saxony

.. _scevent_regioncheck_configuration:

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


.. note::
   **rc.\***
   *Test if events lie within or outside a region.*
   *Events within a region are flagged as positive, outside as negative.*
   *The event type is set accordingly. Add the*
   *plugin "evrc" to the plugins parameter in the*
   *order of priority to make this feature available. Read the*
   *documentation of the RegionCheck for more details.*



.. confval:: rc.setEventType

   Default: ``true``

   Type: *boolean*

   Allow setting the event type.
   The type of events which have manual origins will
   not be changed unless configured explicitely by
   \"overwriteManual\".


.. confval:: rc.overwriteEventType

   Default: ``true``

   Type: *boolean*

   Allow overwriting existing event types. Disabling does not
   allow accounting for changes in source region.


.. confval:: rc.overwriteManual

   Default: ``false``

   Type: *boolean*

   Allow setting the event type if the mode of the preferred
   origin is manual or if the event type was set manually.


.. confval:: rc.regions

   Default: ``!reject``

   Type: *list:string*

   The list of closed BNA polygon names defining regions for
   flagging event as positive or negative.
   A polygon name defines a positive region but names with prefix \!  \(exclamation mark\)
   define negative regions. Evaluation is done in the order of the
   polygons. The last matching criteria applies and the event type
   is set accordingly.
   
   Default: If events are not positive or are negative regions the
   event type is set to \"outside of network interest\".
   Default: \"\!reject\", use \"accecpt\" to overwrite the default.
   
   Examples:
   
   Events are flagged positive within the polygon \"germany\":
   
   germany
   
   All events are flagged positive but events within the polygon \"quarries\" are negative:
   
   accept,\!quarries
   
   Events within the polygon \"germany\" are flagged positive but
   all other events and events within the polygon \"quarries\" are negaitve:
   
   germany,\!quarries
   
   All events are flagged positive but events within the polygon \"germany\"
   are negative and all events within the polygon \"saxony\" are positive:
   
   accept,\!germany,saxony


.. confval:: rc.readEventTypeFromBNA

   Default: ``false``

   Type: *boolean*

   Read the event type, minDepth and maxDepth from the BNA polygon header. The header may contain
   the values, e.g. header of a polygon with name \"quarry\":
   
   \"quarry\",\"rank 1\",\"eventType: quarry blast, minDepth: \-5, maxDepth: 10\",13
   
   When eventType is set, it supersedes eventTypePositive and eventTypeNegative.
   When not set, eventTypePositive and eventTypeNegative are considered.


.. confval:: rc.eventTypePositive

   Type: *string*

   New type of an event which is flagged positive. Ignored
   if readEventTypeFromBNA is active.
   
   Empty: Do not set type


.. confval:: rc.eventTypeNegative

   Default: ``"outside of network interest"``

   Type: *string*

   New type of an event which is flagged negative. Ignored
   if readEventTypeFromBNA is active.
   
   Empty means default: \"outside of network interest\"