.. highlight:: rst

.. _scdummyloc:

##########
scdummyloc
##########

**Dummy pick associator.**


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

*scdummyloc* is released under the GNU Affero General Public License (Free
Software Foundation, version 3 or later). It uses seismic phase onset picks for 
defining seismic event origins.

Pick association is solely based on simplistic thresholds:
- pick delay (see :confval:`max_pick_delay`) and 
- instrument location distance (see :confval:`max_pick_distance` and :confval:`min_pick_distance`).
   
Pick association supports picking from different instruments at the same station at the level of instrument location (see :confval:`enable_loc_clust`) code and channel code (:confval:`enable_cha_clust`). 

The preliminary origin locations are based on the average of picked instrument location (taking instrument elevation into account) weigthed by normalised arrival time (the earlier the closer to location).
 
.. note::

 *scdummyloc* is under developmnent.

Example for debugging (setup messaging parameters in :file:`scdummyloc.cfg`), origins are sent in messaging system, :ref:`scolv` for viewing and  :ref:`scmm` for inspection:

.. code-block:: sh

 scolv &
 scmm &
 scdummyloc --debug --fake -g GUI

Example for post-processing:

.. code-block:: sh

 scdummyloc --ep <pick file> --playback -d <database connection url> -o <output file> 



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

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

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



.. confval:: max_buffer_interval

   Type: *double*

   Unit: *seconds*

   A buffer of 3 hours in seconds.
   Default is ``10800``.

.. confval:: max_pick_delay

   Type: *double*

   Unit: *seconds*

   Maximal delay between picks in clusters.
   Default is ``120``.

.. confval:: max_pick_distance

   Type: *double*

   Unit: *km*

   Maximal distance between picked streams in clusters. Levels station, location and channel are supported.
   Default is ``50``.

.. confval:: min_pick_distance

   Type: *double*

   Unit: *km*

   Minimal distance between picked streams in clusters.
   Default is ``1``.

.. confval:: default_phase_type

   Type: *string*

   Default phase type in origins.
   Default is ``P``.

.. confval:: min_released_clustered_picks

   Type: *integer*

   Minimal number of picks in clusters.
   Default is ``2``.

.. confval:: test

   Type: *boolean*

   If true nothing get sent \(superseeds all other options\).
   Default is ``false``.

.. confval:: release_todatabase

   Type: *boolean*

   If true origins go only to messaging system, not to database \(no public ID\).
   Default is ``false``.

.. confval:: release_cluster

   Type: *boolean*

   If true clusters are released as preliminary origin.
   Default is ``true``.

.. confval:: release_location

   Type: *boolean*

   If true cluster origin locations \(not implemented\) are released.
   Default is ``false``.

.. confval:: enable_loc_clust

   Type: *boolean*

   Enables clustering using all location codes of the same station as independent picks. Useful if station code is the same for distant instrument with different location code.
   Default is ``true``.

.. confval:: enable_cha_clust

   Type: *boolean*

   Enables clustering using all channel codes of the same station as independent picks. Useful if chanel level has coordinates \(not in SED\-ETHZ\) and location code is the same for distant instrument.
   Default is ``false``.

.. confval:: enable_same_id_clust

   Type: *boolean*

   Enables clustering using picks of the same stream as independent picks. Useful if the same stream should contribute several time to origin.
   Default is ``false``.


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


Generic
-------


Verbosity
---------


Messaging
---------

.. option:: --test

   Do not send any object.

.. option:: --fake

   Do not write to database \(do not create public id for sent object\).


input
-----

.. option:: --ep

   Name of input file with all picks for offline processing. Results are sent in XML to stdout.
   Read picks from file instead of messaging system. Use '\-' to read from stdin. This option
   implies \-\-test.

.. option:: -f, --format

   Input format to use \(xml [default], zxml \(zipped xml\), binary\). Only relevant with \-\-ep.

.. option:: -o, --output

   Write origins to specific XML file instead of stdout. Only relevant with \-\-ep.

.. option:: --playback

   Release origins in real\-time, similar to online processing, else release final origins only.