.. highlight:: rst

.. _sceewenv:

########
sceewenv
########

**The generic pre-processing module for EEW algorithms. It is required by scvsmag for the Virtual Seismologist (VS). In FinDer, the same core processing library is integrated into scfinder, the wrapper for the Finite-Fault Rupture Detector (FinDer).**


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

Part of the :ref:`EEW<EEW>` package (in :ref:`VS<VS>`).

*sceewenv* is released under the GNU Affero General Public License (Free
Software Foundation, version 3 or later). It provides in effect continuous
real-time streams of envelope values for horizontal and vertical acceleration,
velocity and displacement from raw acceleration and velocity waveforms.
*sceewenv* was extended from the original SED-ETHZ VS-specific pre-processing
module `scenvelope`, implemented to handle the waveform pre-processing necessary
for the :ref:`scvsmag` module (`Virtual Seismologist`_). Further parameters can also being calculated
using the core library included in *sceewenv*, such as spectral amplitudes and
tauP, though these are not accessible via the current *sceewenv* implementation.

The processing procedure for envelope computation is as follows:

#. gain correction
#. baseline correction
#. combination of the two horizontal components to a root-mean-squared horizontal component
#. integration or differentiation to velocity, acceleration and displacement (both velocity and displacement are high pass pre-filtered over 0.075 Hz)
#. high-pass filter with a corner frequency of 3 s period
#. computation of the absolute value within 1 s intervals

In the example below, the resulting envelope values are sent as messages to the 
messaging system via the "EEW" message group. Depending on the number of streams 
that are processed this can result in a significant number of messages 
(#streams/s).

In order to save the messages in the database and to provide them to other
modules, the messaging system must to be able to handle these messages.
Therefore, the plugins *dmvs* must be available to :ref:`seiscomp:scmaster`  and the "EEW"
group must be added.

The plugins can be most easily **added** through the configuration parameters
in :file:`global.cfg`:

.. code-block:: sh

   plugins = ${plugins}, dmvs

**Add** the "ENVELOPE" group the the other message groups defined by
:ref:`scmaster` in :file:`scmaster.cfg`:

.. code-block:: sh

   defaultGroups = ${defaultGroups}, ENVELOPE

and let *sceewenv* send the messages to the "ENVELOPE" group instead of
"AMPLITUDE". Adjust :file:`sceewenv.cfg`:

.. code-block:: sh

   connection.primaryGroup = ENVELOPE

.. note::

   When changing :confval:`connection.primaryGroup`, the "ENVELOPE" group must
   also be added to the subscriptions in :ref:`scvsmag`.

References
==========

.. target-notes::

.. _`Virtual Seismologist` : http://www.seismo.ethz.ch/en/knowledge/earthquake-data-and-analysis-tools/EEW/Virtual-Seismologist/index.html



Configuration
=============

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

sceewenv inherits `global options <https://docs.gempa.de/seiscomp/current/apps/global.html>`_.



.. confval:: eewenv.saturationThreshold

   Type: *double*

   Unit: *percent*

   Relative saturation threshold in percent. If the absolute raw amplitude
   exceeds X% of 2\*\*23 counts the station will be excluded from processing. This
   assumes a 24bit datalogger. The default is 80.
   Default is ``80``.

.. confval:: eewenv.baselineCorrectionBuffer

   Type: *double*

   Unit: *s*

   Length in seconds of the baseline correction buffer. A running average is
   computed and removed from the current sample. The default is 60s.
   Default is ``60``.

.. confval:: eewenv.horizontalBuffer

   Type: *double*

   Unit: *s*

   Length of buffer for horizontal components. Because horizontal components
   are being received separately they must be buffered to align them properly.
   Sets the buffer size for each component to compensate for
   data acquisition latencies. Each component is buffered for
   at least as long as \\p ts seconds before single records
   are being removed. This buffer size correlates to the maximum latency of
   one horiontal component with respect to the other. A too short buffer size
   will lead to gaps in the combined data stream. bufferSize is as time span
   \(in seconds with fractional part\). The default is 60s.
   Default is ``60``.

.. confval:: eewenv.taperLength

   Type: *double*

   Unit: *s*

   Length in seconds of the taper that is applied to the beginning of the
   trace.
   Default is ``60``.

.. note::
   **eewenv.streams.\***
   *Defines the white- and blacklist of data streams to be used. The*
   *rules to decide if a stream is used or not are the following:*
   **
   *1. if whitelist is not empty and the stream is not on the whitelist,*
   *don't use it, ok otherwise*
   **
   *2. if blacklist is not empty and the stream is on the blacklist,*
   *don't use it, ok otherwise*
   **
   *Both checks are made and combined with AND. Either whitelist or*
   *blacklist contains a list of patterns (wildcard allowed as * and ?),*
   *eg GE.*.*.*, *, GE.MORC.*.BH? Each stream id (NET.STA.LOC.CHA) will*
   *be checked against the defined patterns.*



.. confval:: eewenv.streams.whitelist

   Type: *list:string*

   The stream whitelist


.. confval:: eewenv.streams.blacklist

   Type: *list:string*

   The stream blacklist


.. note::
   **eewenv.vsfndr.\***
   *VS and FinDer configuration*



.. confval:: eewenv.vsfndr.envelopeInterval

   Type: *double*

   Unit: *s*

   Interval length for envelope computation. The default is 1s.
   
   Interval of the envelope computation. The maximum is taken with that
   data interval and declared as envelope value. The intervals do not overlap.
   Default is ``1.0``.

.. confval:: eewenv.vsfndr.filterAcc

   Type: *boolean*

   Enable acceleration filter, default is false.
   Default is ``false``.

.. confval:: eewenv.vsfndr.filterVel

   Type: *boolean*

   Enable velocity filter, default is false.
   Default is ``false``.

.. confval:: eewenv.vsfndr.filterDisp

   Type: *boolean*

   Enable displacement filter, default is true.
   Default is ``true``.

.. confval:: eewenv.vsfndr.filterCornerFreq

   Type: *double*

   Unit: *Hz*

   Sets the corner frequency of the Butterworth \(4 poles\) high\-pass filter, default is 1\/3 Hz.
   Default is ``1/3``.

.. confval:: eewenv.debug.maxHorizontalGap

   Type: *double*

   Unit: *s*

   Sets the maximum combined horizontal channels delay before issuing a warning. That
   parameter does not configure buffers as such but only a threshold \(in seconds with
   fractional part\) to warn the user that something is not real\-time anymore. The
   default is 30s.
   Default is ``30``.

.. confval:: eewenv.debug.maxDelay

   Type: *double*

   Unit: *s*

   Sets the maximum absolute value of packet delay before issuing a warning. That
   parameter does not configure buffers as such but only a threshold \(in seconds
   with fractional part\) to warn the user that something is not real\-time anymore.
   The default is 3s.
   Default is ``3``.


Command Line
============


Generic
-------

.. option:: -x, --expiry time

   Time span in hours after which objects expire.

.. option:: -O, --origin-id publicID

   OriginID to calculate amplitudes for and exit.

.. option:: --dump-records

   Dumps the filtered traces to ASCII when using \-O.


Verbosity
---------


Messaging
---------

.. option:: --test

   Test mode where no messages are sent.


Database
--------


Records
-------


Offline
-------

.. option:: --offline

   Do not connect to the messaging. This mode requires
   either an explicit database connection to read the
   inventory from or an inventory XML file. This option
   implies \-\-test.

.. option:: --dump-config

   Show configuration in debug log and stdcerr and exit.

.. option:: --ts

   Start time of data acquisition time window, requires also \-\-te

.. option:: --te

   End time of data acquisition time window, requires also \-\-ts


Streams
-------

.. option:: --dump

   Enables dumping of incoming, transformed and combined records to stdout. This
   mode is for debugging. The default is false.

