RegionCheck¶

evrc plugin for scevent

Description¶

evrc (event region check) is a plugin for scevent setting the event type by comparing the location of the preferred origin with defined regions.

Note

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

Definition of regions¶

The regions are defined by closed polygons provided in GeoJSON or BNA files. Configure rc.regions to consider a region defined by its region name. The name is given either

As a property of the polygon when given in GeoJSON format,
Or in the header when given in BNA format.

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

Note

When regions are defined or configured multiple times by polygons or rc.regions, respectively, the region is not unique and the region check is entirely inactive.
When a region is not defined but configured in rc.regions, the region check remains active but the region is ignored.

In both cases, error log message are printed.

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 rc.readEventTypeFromBNA the type of positive events is set according to the eventType defined in polygon. The type of negative events is set according to rc.eventTypeNegative. Prepend ‘accept’ to the list of polygons to unset the type of negative events.
When rc.readEventTypeFromBNA is inactive, the event type is set based on rc.eventTypePositive and rc.eventTypeNegative:
1. by default the type of all negative events (events within negative regions) is set to “outside of network interest”. Prepend accept to rc.regions to unset the event type for negative events.
2. positive: The event type of positive events is set to rc.eventTypePositive. For empty rc.eventTypePositive the type is unset.
3. negative: The event type of negative events is set to 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 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”.

../_images/regions.png — Disjunct and overlapping regions in front of a default.¶

Event types¶

The event types are either set based the types configured in rc.eventTypePositive and rc.eventTypeNegative or based on the type provided in the polygon files if rc.readEventTypeFromBNA is active.

Type definition¶

For defining the event type, any value defined in SeisComP UML diagram [23]. The list of valid values can also be found in the Event tab of scolv: Type.

Examples for valid event types:

earthquake
quarry blast
nuclear explosion
not existing
…

Invalid values result in errors or debug messages which are reported depending on the verbosity level of scevent as given logging.level or --verbosity/-v.

Event type from polygon¶

If rc.readEventTypeFromBNA is active, the event type is read from the polygon defining a region. Use a key-value pair in double quotes to specify the type where the key is “eventType” and the value is the event type. The formatting depends on the file format.

The depth of the event can be tested, as well. 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 polygons using the key words minDepth and maxDepth. For considering a polygon, the depth d of the preferred origin of an event must be within the range

$minDepth \le d \le maxDepth$

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

Warning

The names of polygons, e.g. coal, are case sensitive and must not contain commas.
A hierarchy applies to the reading of GeoJSON/BNA files. Read the section Vector layers for the details.

Example polygon in BNA format:

"coal","rank 1","eventType: mining explosion, minDepth: -5, maxDepth: 10",6
392,50.3002
2244,50.4106
4744,50.5347
6886,50.4945
6089,50.358
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. All key-value pairs for eventType, minDepth and maxDepth are written within one single field enclosed by double quotes.

Example polygon in GeoJSON format:

Single Feature

For a single Feature and Poylgon, eventType, minDepth are maxDepth are added as key-value pair to the properities of the feature:

{
    "type": "Feature",
    "geometry": {
        "type": "Polygon",
        "coordinates": [
            [
                [-77.075, -37.7108], [-76.2196, -21.2587], [-69.0919, -7.10994]
            ]
        ]
    },
    "properties": {
        "name": "mines",
        "rank": 1,
        "eventType": "mining explosion",
        "minDepth": -5,
        "maxDepth": 10
    }
}

Single Feature and MultiPoylgon

For a single Feature and a MultiPoylgon, eventType, minDepth are maxDepth are added as key-value pair to the properities of the MultiPoylgon:

{
  "type": "Feature"
  "properties": {
      "name": "mines",
      "rank" : 1,
      "eventType": "mining explosion",
      "minDepth": -5,
      "maxDepth": 10
  },
  "geometry": {
      "type": "MultiPolygon",
      "coordinates": [
           [
                [
                  [ 10.0, -25.0 ],
                  [ 13.0, -25.0 ],
                  [ 13.0, -22.0 ],
                  [ 10.0, -25.0 ]
                ]
           ], [
                [
                  [ 20.0, -25.0 ],
                  [ 23.0, -25.0 ],
                  [ 23.0, -22.0 ],
                  [ 20.0, -25.0 ]
                ]
           ]
      ]
  }
}

FeatureCollection

For a FeatureCollection, the key-value pairs may be added to the properties of each individual feature:

{
    "type": "FeatureCollection",
    "features": [
        { "type": "Feature",
          "properties": {
              "name": "Krakatau",
              "rank": 1,
              "eventType": "mining explosion",
              "minDepth": -5,
              "maxDepth": 10
          },
          "geometry": {
              "type": "Polygon",
              "coordinates": [ ... ]
            }
        },
        { "type": "Feature",
          "properties": {
              "name": "Batu Tara",
              "rank": 1,
              "eventType": "mining explosion",
              "minDepth": -5,
              "maxDepth": 10
          },
          "geometry": {
              "type": "Polygon",
              "coordinates": [ ... ]
            }
        },
    }
}

Setting up the Plugin¶

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

plugins = ${plugins},evrc

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

rc.regions = accept,area

Note

scevent stops if the evrc plugin is loaded but rc.regions is not defined.

Activate rc.readEventTypeFromBNA and add the eventType key-value pair to the polygons if the event type shall be read from GeoJSON or BNA polygon.

Examples:

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

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:

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:

rc.regions = accept,!germany,saxony

Module Configuration¶

Note

rc.* Test if events lie within or outside geographic regions defined by polygons. 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.

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

rc.overwriteEventType¶

Default: true

Type: boolean

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

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.

rc.regions¶

Default: !reject

Type: list:string

The list of closed 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

rc.readEventTypeFromBNA¶

Default: false

Type: boolean

Consider the event type, minDepth and maxDepth values from the polygons defined by GeoJSON or BNA files. Read the documentation of the RegionCheck plugin for the details.

When eventType is defined in the polygons, the value supersedes values of ‘eventTypePositive’ and ‘eventTypeNegative’. If not set, ‘eventTypePositive’ and ‘eventTypeNegative’ are considered.

rc.eventTypePositive¶

Type: string

New type of an event which is flagged positive. Ignored if ‘readEventTypeFromBNA’ is active and the polygons define eventType.

Empty: Do not set type.

rc.eventTypeNegative¶

Default: "outside of network interest"

Type: string

New type of an event which is flagged negative. Ignored if ‘readEventTypeFromBNA’ is active and the polygons define eventType.

Empty means default: "outside of network interest"

RegionCheck¶

Description¶

Definition of regions¶

Treatment of events¶

Event types¶

Type definition¶

Event type from polygon¶

Setting up the Plugin¶

Module Configuration¶

Table of Contents

Previous topic

Next topic

This Page