.. highlight:: rst

.. _scanloc:

#######
scanloc
#######

**Module for locating local earthquakes and man-made seismicity by DBSCAN
cluster search.**


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

Low-threshold monitoring
------------------------

*scanloc* associates detected P and S phases from local and regional earthquakes
and other seismic events for locating. It determines initial hypocenter
solutions by cluster search based on DBSCAN :cite:p:`dbscan`. Additional P and S phases are associated
to existing internal solutions from cluster search or solutions incoming through the messaging
system from external modules.

Due to the clustering and subsequent phase association scanloc facilitates low-threshold
monitoring of high- and low-rate seismicity with high accuracy.

.. _fig-scolv-location-tab:

.. figure:: media/scolv-location-tab.png
   :align: center
   :width: 16cm

   scolv Location tab with an automatic earthquake solution from scanloc based on
   P and S phases.


Teleseismic events
------------------

For teleseismic events *scanloc* can also be used to:

* :ref:`Associate more picks from P and S phases <scanloc-assoc>` to external origins,
* Suppress fake events due to detections from large earthquakes recorded by dense local networks at teleseismic distances.
  A :ref:`dedicated section<scanloc-zero-weight>` explains the setup and the requirements.


Travel-time tables
------------------

The scanloc package ships with :ref:`densely sampled travel-time tables <scanloc-ttt>` for
LOCSAT :cite:p:`locsat` based on the IASP91 Earth model to enhance locating local earthquakes.


S phases
--------

In order to deliver high-quality picks from S phases, the :ref:`scanloc` package
also includes the *saic* plugin with the enhanced :ref:`S-phase picker<scanloc-spicker>`.
The S-phase picker can be applied to detect S phases on the horizontal components
or on the vertical component in case of 1-component sensors. In addition the scanloc
package comes with the :ref:`graphical debugger for the S-phase picker<scanloc-spick-debugger>`
provided by the *spickdbg* plugin.


Auxiliary tools
---------------

The scanloc package also ships with auxiliary Python script for
:ref:`real-time or non-real-time playbacks <scanloc-example>` or tuning. Read the
:ref:`dedicated section <sec-scanloc-aux-tools>` for more details.


Workflow
========

#. Buffering of :ref:`picks and origins <scanloc-buffer>`,
#. :ref:`Clustering<scanloc-clustering>` of P picks:

   * cluster formation,
   * splitting of clusters in case of multiple P picks from the same station.

   Clustering is skipped in case of an external origin.
#. :ref:`Association<scanloc-assoc>` of P and S picks to clusters and external
   origins.
#. :ref:`Locating origins <scanloc-locator>` and formation of
   :ref:`internal events <scanloc_internal>`,
#. Evaluation and :ref:`sending<scanloc-send>` of origins.

.. _fig-scanloc-workflow:

.. figure:: media/workflow.png
   :align: center
   :width: 16cm

   Simplified work flow of scanloc.


.. _scanloc-buffer:

Pick and origin buffering
-------------------------

The entry point of *scanloc* is the addObject method which handles incoming
objects from the messaging system. By default it is subscribed to the messaging
group **PICK** and **LOCATION**. Depending on which object type (pick or origin)
is incoming different working steps are proceeded.

* In case a **pick** arrives, *scanloc*

  * tests the evaluation status. Rejected picks are ignored unless the
    command-line option ``--allow-rejected-picks`` is given.
  * adds the pick to the pick buffer keeping it for the time given by
    :confval:`buffer.pickKeep` or ``--pick-keep``,
  * tries to use the pick for :ref:`clustering <scanloc-clustering>`,
  * checks if the pick can be :ref:`associate to origins <scanloc-assoc>` in the
    origin buffer exceeding a configurable :confval:`minScore`.
    In case the pick can be associated, the scores for all new origins are
    calculated and the origin with the highest score is selected.

* In case an **origin** arrives, *scanloc*

  * tests the evaluation mode. Manual origins are ignored unless
    :confval:`buffer.ignoreManualOrigins` = *false*,
  * adds the origin to the origin buffer keeping it the time given by
    :confval:`buffer.originKeep` or ``--origin-keep`` seconds,
  * tries to :ref:`associate additional picks <scanloc-assoc>` to the origin.

Adjust the :confval:`buffer.*` parameters according to the times these objects
are required for processing.


.. _scanloc-clustering:

Clustering
----------

In case the pick cannot be associated, the cluster search is started. The
cluster search is based on the algorithm DBSCAN :cite:p:`dbscan` which
takes the required number of neighbours (:confval:`clusterSearch.minSize`)
and :confval:`clusterSearch.maxSearchDist` as configuration parameters.

The algorithm forms clusters of picks by searching for neighboring stations
that have picks. :ref:`Internal origins <scanloc_internal>` are formed from clusters.
The number of origins from cluster search is limited by the configuration parameter
:confval:`clusterSearch.maxOrigins`.

The cluster search considers picks from stations by :math:`distance` with:

.. math::

  distance \le maxSearchDist

where maxSearchDist is given by the configurable parameter :confval:`clusterSearch.maxSearchDist`.
:math:`distance` is the vector sum of the time difference :math:`\Delta t`
between the picks in units of seconds and of a potential travel time
:math:`tt` between the stations in units of seconds:

.. math::

  distance = \sqrt{\Delta t^2 + tt^2}

and

.. math::

  tt = \Delta x / v

where :math:`\Delta x` is the spatial distance between the stations in units of km and
:math:`v` is the :confval:`clusterSearch.averageVelocity` in units of km/s. Therefore
:math:`distance` and :confval:`clusterSearch.maxSearchDist` take units of seconds.

As the cluster search is done over time and location, the additional configurable
velocity parameter, :confval:`clusterSearch.averageVelocity`, is required to transform
the input parameters of the cluster search in the same dimension (time).
The velocity should represent the average apparent horizontal P-wave velocity of
the crust.

.. warning::

   When the number of buffered cluster origins reaches :confval:`clusterSearch.maxOrigins`,
   no more new origins can be formed and warnings are issued. Adjust accordingly:

   * :confval:`clusterSearch.maxOrigins`,
   * :confval:`buffer.pickKeep`.


.. _sec-scanloc-cluster-time:

Limiting in time
^^^^^^^^^^^^^^^^

In real time picks are received in the order of their creation times. They are
considered for clustering if their pick times are within a time window
before the **cluster reference time**. The time window is defined by
:confval:`clusterSearch.maxPickDelay` but the **cluster reference time** is defined
either by the

* Pick time of the latest pick of the received picks when
  :confval:`clusterSearch.referenceTimeMode` = 'LastPick' (default),
* Pick time of the latest received pick which defines are group of :confval:`clusterSearch.minSize`
  picks within :confval:`clusterSearch.maxPickDelay` when
  :confval:`clusterSearch.referenceTimeMode` = 'MaxPickDelay'. **This mode is relevant
  if only very few stations with significantly different data delay provide the
  picks.** Otherwise picks may not be available for clustering at the same time
  preventing to form clusters and new origins.

Thus, when setting :confval:`clusterSearch.referenceTimeMode` = 'MaxPickDelay' re-setting
the cluster reference time is delayed depending on the amount and density of incoming picks.
With this option picks which have a larger delay can be considered. Such delays
occur e.g. due to larger data delays or larger record lengths.

.. math::

   pick delay = creationTime - pickTime

where

* :math:`pick.creationTime`:time at which the pick was made,
* :math:`pickTime`: actual time of the phase arrival.

Picks available within a trapezoid-like time window are considered for
clustering.
For a pick with zero delay, the cluster reference time is initially set and picks
within the **blue trapezoid** (figure below) are considered.
Normally, picks have some delay which delays defining the trapezoid. This makes accessible
other picks available with some delay, too, allowing these picks to be considered
(**green trapezoid**). Subsequently, the trapezoid is extended until the
cluster reference time is updated.
This may be the next pick with a larger pick time
(**olive trapezoid**, :confval:`clusterSearch.referenceTimeMode` = 'LastPick') or
the time of the pick which is preceded by at least :confval:`clusterSearch.minSize`
picks within :confval:`clusterSearch.maxPickDelay` (**yellow trapezoid**,
:confval:`clusterSearch.referenceTimeMode` = 'MinPickDelay').
Thus, picks which have a long delay do not fall within the relevant trapezoid and
cannot be considered for clustering as they are not available at the time of clustering.

The trapezoid is set with respect to the cluster reference time, CRT1 in the figure below,
considering the delay of the defining pick and the time until the next relevant
pick which updates the reference time (CRT2):

* CRT2 with :confval:`clusterSearch.referenceTimeMode` = 'LastPick' or
* Deleyed CRT2 since :confval:`clusterSearch.referenceTimeMode` = 'MaxPickDelay'.

The longer the time until the update, the
more picks with larger delays can be considered for clustering, e.g. the delayed
clustered pick in the figure below.

.. figure:: media/cluster-reference.png
   :align: center
   :width: 18cm

   Pick time vs. pick delay time for of picks for clustering.
   The cluster reference time determines the trapezoid within which picks can be
   considered for clustering.
   Here, the delayed clustered pick only becomes part of the cluster with
   :confval:`clusterSearch.referenceTimeMode` = 'MaxPickDelay'.


.. note ::

   * For small and similar delays of all P picks, :confval:`clusterSearch.maxPickDelay`
     can be directly read from travel-time curves. A small margin should be added
     account for differences in delay.
   * In offline XML playbacks, the creation times may not be representative of
     real-time conditions. Therefore, pick times may be used for the timing instead
     of creation times. Read the section :ref:`scanloc-example` for more details
     and the consequences.

If picks arrive with a larger delay than others, there is a risk that they cannot
be condsidered anymore for the cluster. When only few picks are available the events
may then be missed. To overcome the issue, you may increase :confval:`clusterSearch.maxPickDelay`
or set the parameter :confval:`clusterSearch.referenceTimeMode` = "MaxPickDelay".
While increasing :confval:`clusterSearch.maxPickDelay` may slow down the clustering
and increase the risk to cluster unrelated picks,
:confval:`clusterSearch.referenceTimeMode` = "MaxPickDelay" will only increase the
cluster reference time if at least :confval:`clusterSearch.minSize` P picks are
available in the considered time window. Run :program:`scanloc` on the command line
with the ``--cluster-search-log-file`` to learn about the cluster reference
times and the considered picks. For more options read the section :ref:`sec-scanloc-tuning`.

Within one cluster, the difference in the pick times between the
cluster reference time and any other pick must thus not exceed :confval:`clusterSearch.maxPickDelay`.
Otherwise the pick is rejected from clustering. The parameter :confval:`clusterSearch.maxPickDelay`
has a big impact on the performance of the cluster search. Choosing the parameter
as small as possible will speed up scanloc and will reduce the complexity of the
cluster search.

The DBSCAN algorithm can deliver multiple pick clusters. The cluster search can
be disabled using :confval:`clusterSearch.maxPickDelay`:

.. code-block:: sh

   # Maximum allowed difference between P pick and cluster reference time(latest pick time).
   # The cluster search ignores all picks which exceed the value. Using "-1" enables all picks
   # regardless of the delay. Unit: seconds.

   clusterSearch.maxPickDelay = 0

Then, only external origins can be considered for :ref:`phase association<scanloc-assoc>`.


Limiting in space
^^^^^^^^^^^^^^^^^

The cluster search can be constraint to stations within a region given by the
coordinate of a central point and the radius around that point. The region constraint
is configured through :confval:`clusterSearch.regionFilter`. Applying this parameter
will disregard picks from stations outside the region for cluster search increasing
the speed and the complexity. Nevertheless, the excluded picks are available for
:ref:`phase association <scanloc-assoc>`.

For running the cluster search in several regions in parallel, different instances
of scanloc taking picks from the same of different pickers can be created and started.


Cluster splitting
^^^^^^^^^^^^^^^^^

Clusters may contain P picks from the same station. Therefore, the clusters are
split separating clusters with only one pick per stations. All new clusters are
considered new origins. By activating :confval:`clusterSearch.checkOrigins`, all
new clusters are checked again
and clusters not meeting the configured cluster criteria are removed from the buffer.
The check imposes an additional overhead on the cluster search but it typically
lowers the chance for fake solutions and it also lowers the load on the
:ref:`phase association <scanloc-assoc>`.


.. _sec-scanloc-tuning:

Tuning and optimization
^^^^^^^^^^^^^^^^^^^^^^^

Use the option :confval:`cluster-search-log-file` to store detailed information
on the clustering process in a file, e.g. *cluster.log*. The given values can be
used to optimize the cluster search parameters.

.. code-block:: sh

   scanloc --ep picks.xml -d [database] --cluster-search-log-file cluster.log > origins.xml

For optimizing the configuration of the parameter :confval:`clusterSearch.maxPickDelay`
use the default value first:

.. code-block:: sh

   clusterSearch.maxPickDelay = -1

The given output file contains the clusters with the pick details. After each cluster
the maximum time interval between the first and the last pick
in the cluster is provided. A summary at the end of the file shows the largest value, e.g.:

.. code-block:: sh

   + cluster source: -69.6279, -21.4715, 1231891115.191
    + pick ID: *20090113.235827.36-AIC-CX.PB01..HHZ X: -69.4874 Y: -21.0432 time: 1231891107.368 distance: 14.715 s
    + pick ID:  20090113.235832.91-AIC-CX.PB02..HHZ X: -69.8960 Y: -21.3197 time: 1231891112.918 distance: 8.443 s
    + pick ID:  20090113.235839.53-AIC-CX.PB07..HHZ X: -69.8862 Y: -21.7267 time: 1231891119.538 distance: 10.677 s
    + pick ID:  20090113.235840.94-AIC-CX.PB09..HHZ X: -69.2419 Y: -21.7964 time: 1231891120.940 distance: 14.645 s
      + 1 split cluster
        + cluster
          + 20090113.235827.36-AIC-CX.PB01..HHZ
          + 20090113.235832.91-AIC-CX.PB02..HHZ
          + 20090113.235839.53-AIC-CX.PB07..HHZ
          + 20090113.235840.94-AIC-CX.PB09..HHZ
          + maximum pick time interval for this cluster: 13.572 s
        + end
      + end
     + end
    + end
    + summary:
      + maxPickDelay: maximum experienced value: 40.840 s

The summary value can be used as a lower proxy to set :confval:`clusterSearch.maxPickDelay`.


Locating
^^^^^^^^

Clusters are located by the configured :ref:`locator <scanloc-locator>`. If the
location fails, the origin is ignored unless :confval:`clusterSearch.preliminary`
is active. Then, preliminary values are chosen:

* Origin location is the center of the detecting stations,
* Origin time is the time of the first phase pick,
* Status is set to `preliminary`.

The status will be unset if more phases can be associated and the new origin can
be located.

.. _scanloc-assoc:

Phase Association
-----------------

When a cluster of P picks meeting :confval:`association.minPhase` is found
or an external origins arrives, :program:`scanloc` associates additional picks
from P and S waves which are :ref:`buffered <scanloc-buffer>`.
The new set of picks are used for :ref:`relocating <scanloc-locator>`.

In case the buffered pick is a P pick the algorithm
directly attempts to associate the pick solely based on the residual. It tries
to relocate
the solution after each successful association. P picks with travel-time
residuals larger than :confval:`association.maxResidual` are rejected.
After the P-picks are associated and relocated, *scanloc* tries to associate the
S picks. This association is not based
on the residual but on the P pick referenced by the S pick. The S pick is
only associated in case the reference P pick is already associated to the
origin. Also after each S pick a relocation is done. In case the relocation
fails or the event residual is larger than :confval:`maxRMS`,
the S pick is associated with a weight of 0. The score of the resulting
origin is compared with scores of origins belonging to the same event. In case
the score is higher than the rest of the origins, the origin is send out.

In addition to origins from the cluster search, *scanloc* can also treat external
origins that are created by other associators, e.g. :program:`scautoloc`
:cite:p:`scautopick`.
In case an such origin is received *scanloc* tries to associate all picks in the
buffer to the origin. The association and the following processes are the same as
described above. See figure :ref:`fig-scanloc-workflow` for an overview.

Only picks from stations within a configured time window and a maximum epicentral
distance range are considered. The time windows are computed from the predicted
arrival times of P and S waves and the margins given by :confval:`association.maxPResidual`
and :confval:`association.maxPResidual`, respectively.
The maximum expicentral distance is configured for all stations by
:confval:`association.maxDist`. However, this parameter can be overruled per
network and station by providing a station table in a file. The file name is
configured by
:confval:`association.stationConfig`. As in scautoloc each line of the table
consists of the network code, the station code, a switch and the maximum epicentral
distance in degrees. Wildcards can be used for the network and the station code.
The switch causes the associator to consider (=1) or to ignore (=0) a network or
a station.
The last occurrence of an item in a table overrules previous ones, e.g.

.. code-block:: sh

   * * 1 180
   GR * 1 60
   GR GRA1 1 20
   Z3 * 0 180

For associating the picks, travel times from look-up tables are used. The
:confval:`association.tableType` and the :confval:`association.table` can be
configured to provide specific tables which may be more appropriate for specific
regions. Currently, only travel-time tables of :confval:`association.tableType`
from LOCSAT and libtau are supported. scanloc provides
:ref:`densely-sampled travel-time tables <scanloc-ttt>` for LOCSAT.

Travel times from other sources can be considered by a plugin exposing
the travel times to the travel-time interface.
The considered table must provide the time for all considered phases.

Example configuration (:file:`scanloc.cfg`):

.. code-block:: sh

   # Type of travel-time tables for phase association. May be different from locator.
   # Use e.g. libtau or LOCSAT.
   association.tableType = LOCSAT

   # Name of travel-time table used for phase association. May be different from locator
   # profile.
   association.table = iasp91_scanloc

.. csv-table::
   :header: ":confval:`association.tableType`", "location of :confval:`tables<association.table>`"
   :widths: 15,100

   "libtau","@DATADIR@/ttt"
   "LOCSAT","@DATADIR@/locsat/tables"


.. note::

   Travel-time tables used during association and location may be different.
   Therefore the travel-time residuals visible after relocating may be different
   from the travel-time residuals considered during association.
   The differences must be considered when configuring :confval:`association.maxPResidual`
   and :confval:`association.maxSResidual`.

In order to make the alternative locator available to *scanloc*, the respective
plugin must be loaded. The list of available locators can be provided by *scanloc*:

.. code-block:: sh

   seiscomp exec scanloc --locator-list

**Note:** Computational speed can be an issue when alternative locators are used
and when many picks are to be tested during association. In this case *scanloc*
can be configured with LocSAT but screloc :cite:p:`screloc` may be used
along with the preferred locator and profile to relocate the origin. The locator
NonLinLoc :cite:p:`nonlinloc` is certainly too slow for being used in
:program:`scanloc` but is a good option for :program:`screloc`.


.. _scanloc-origin-status:

Status of origins
-----------------

The status of origins can be set during pick processing

* Normally, the status of origins is **unset**.
* The status of origins from cluster search which cannot be relocated is **preliminary**.
* The status of origins which can be located is set to **unset** if the origin status
  of the origin was previously set.

However, the evaluation status may be later changed at
different times by different modules, e.g. the gempa module :program:`sceval`.
In order to track this history a journal entry is created and sent
when running scanloc with a connection to the messaging or added to the
XML output long with the origins.
In future versions of SeisComP such journal entries will be made accessible in
:program:`scolv`.


.. _scanloc-send:

Sending of origins
------------------

Before sending a new :ref:`internal origin <scanloc_internal>` to the messaging
or to XML output (--ep) it is tested against the configuration:

* Picks are removed when their travel-time residual > :confval:`association.maxResidual`
  and origins are :ref:`relocated <scanloc-locator>`,
* Origins are skipped when the score < :confval:`minScore`,
* Origins are skipped when the depth > :confval:`ignoreDepth`.

The remaining internal origins are evaluated based on :ref:`scoring <scanloc_scoring>`.
The best origin of the same :ref:`internal event <scanloc_internal>` is the one
which has the highest score at the time of availability. When meeting the parameters
:confval:`ignoreDepth`, :confval:`maxRMS` and :confval:`minScore` it is sent to the
SeisComP messaging :cite:p:`messaging` or to stdout in case of XML playbacks
(`--ep`).

The sending of origins may be delayed allowing to find new origins with higher score.
The delay reduces the amount of origins in the SeisComP system and the load of other modules.
It is controlled by the :confval:`publication.*` configuration parameters.

.. note::

   In XML-based playbacks, the :confval:`publication.*` configuration parameters
   are ignored and all origins are sent.


.. _scanloc_internal:

Internal Origins and Events
===========================

*scanloc* forms

* **Internal origins** from the locations and the associated picks (arrivals) of
  new arrival sets,
* **Internal events** are formed from the internal origins based on the
  :confval:`eventAssociation.*` parameters. Only if the :ref:`score <scanloc_scoring>`
  of a new origin exceeds the score of the last sent origin of the same internal
  event, the new origin is :ref:`send out<scanloc-send>`.


.. _scanloc-locator:

Locating Origins
================

scanloc locates internal origins based on the configuration by the :confval:`locator.*`
parameters.
Consider a fast locator (:confval:`locator.type`), e.g. LOCSAT or Hypo71 :cite:p:`hypo71`
and appropriate travel-time tables :confval:`locator.profile`,
e.g. the provided :ref:`dense travel-time tables <scanloc-ttt>`.
If the location fails and :confval:`locator.fixDepth` is active, the location
depth is fixed to :confval:`defaultDepth` and the origin is relocated.

Example configuration (:file:`scanloc.cfg`):

.. code-block:: sh

   # The locator type to use
   locator.type = LOCSAT

   # The locator profile to use
   locator.profile = iasp91_scanloc


.. _scanloc_scoring:

Scoring Origins
===============

Each :ref:`internal origin <scanloc_internal>` is evaluated by calculating a
:math:`score`.
The :math:`score` is calculated as a weighted sum from the number of associated
P and S picks (pCount and pCount), of loosely associated P and S picks
(p0Count and s0Count) which are not used for locating, depth (depthFactor) and
residual (residualFactor):

.. math::

   score =\  &score.weights.p \times pCount + score.weights.p0 \times p0Count \\
		+\ &score.weights.s \times sCount + score.weights.s0 \times s0Count \\
		+\ &score.weights.depth \times depthFactor \\
		+\ &score.weights.residual \times residualFactor;

The weight factors  :confval:`score.weights.p` , :confval:`score.weights.p0` ,
:confval:`score.weights.s` , :confval:`score.weights.s0`
:confval:`score.weights.depth` and :confval:`score.weights.residual`
can be configured.

The values for depthFactor and residualFactor are derived from considered
depth and residual and the configured values for
:confval:`ignoreDepth` and :confval:`association.maxResidual`.
Higher weight is given to origins with shallower depth. Adjust
:confval:`score.weights.depth` to form the score
independent of depth, e.g. in regions with shallow and deep seismicity: ::

   score.weights.depth = 0


.. _scanloc-zero-weight:

Association of Teleseismic Phases
=================================

Dense local networks used to monitor local seismicity are often able to catch
also a significant number of phases from earthquakes at teleseismic distances.
Such phases include Pdiff or PKP.
Especially PKP may contain a significant amount of energy at higher frequencies.
Therefore PKP is often detected by networks that are tuned to detect
local earthquakes.
Due to the steep incidence and the low horizontal slowness of these phases, they
are sometimes located as fake deep earthquakes below the network.
*scanloc* can be used to suppress this type of fake events.

In a 2-pipeline setup, *scanloc* can associcate such teleseismic phases recorded
by the local network with origins that were found by the pipeline for
monitoring teleseismic earthquakes. Then :program:`scevent` :cite:p:`scevent`
will associate
the origins from the teleseismic pipeline with the fake origins from the
pipeline for local monitoring to the same event. The assumption is that the origins
from the teleseismic pipeline win over the origins from pipeline for local monitoring
because they have more associated arrivals. In this case the origins from pipeline
for teleseismic monitoring that has most phases becomes the preferred origin for
the event. This :ref:`scanloc` feature requires an extended license.

*Setup of a 2-pipeline system*

1. Generate a 2-pipeline system involving at least scautopick :cite:p:`scautopick`,
   :program:`scanloc` and scevent :cite:p:`scevent` :

   - **Pipeline 1** monitors teleseismic earthquakes using :program:`scautopick`,
     :program:`scautoloc`, :program:`scanloc` and default message groups.

   - **Pipeline 2** monitors local earthquakes using *l1autopick*, *l1autoloc*
     and *l1scanloc* using the message groups L1PICK and L1LOCATION.

#. Let *scanloc* not perform cluster search (:confval:`clusterSearch.maxOrigins` = 0)
   but allow *scanloc* to only associate P picks from pipelines 2 based on origins
   from :program:`scautoloc` (connection.subscriptions = "LOCATION, L1PICK" in the global
   module parameters). Configure *scanloc* to associate the picks from pipeline 2
   as picks with zero weight when they are, e.g., in the PKP or Pdiff distance
   range. Use one zeroWeight profiles per phase.

   In order to facilitate association of teleseismic picks, the picks and the origins
   must be kept in memory for sufficient time. Increase :confval:`buffer.pickKeep`
   and :confval:`buffer.originKeep` accordingly, e.g. to 1800 s.

   In this way zero-weight picks will not be used for locating the event but are
   part of the origin and can be considered by *scevent*.

#. Configure *scevent* to listen to the message groups from both pipelines (e.g.
   LOCATION and L1LOCATION) and activate the *scevent* module parameter
   *eventAssociation.allowLooseAssociatedArrivals* (:file:`scevent.cfg`).

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

      Parameter exchange in a 2-pipeline system. The messaging system, responsible
      for the parameter exchange, is representated by the circles, indicating the
      message groups. Teleseismic monitoring is configured with scautopick,
      scanloc, scautoloc and local monitoring with l1autopick,
      l1scanloc, l1autoloc.

*Playback using picks and amplitudes from 2-pipeline system (real-event examples)*

.. _fig-zeroweight1:

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

   Location tab in *scolv* with zero-weight picks associated by *scanloc* as PKP phases.

.. _fig-zeroweight2:

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

   Event tab in *scolv* showing the origins from the pipelines for local and
   teleseseismic monitoring. The preferred origin located near the Solomon
   Islands is shown in bold on top. Fake origins in Europe located by pipeline
   for local monitoring based on PKP phases falsely considered P phases are
   associated to the event but do not form the preferred origin at any time.


.. _scanloc-example:

Examples and Playbacks
======================

- Run *scanloc* during real-time processing:

  .. code-block:: sh

     seiscomp start scanloc


- Run *scanloc*  on the command line for pick playbacks or debugging output:

  .. code-block:: sh

     scanloc --debug

.. note ::

   In playbacks of picks in XML files the performance of scanloc may differ
   from real-time operation based on messaging:

   * In real-time operation, the picks are made e.g. by :program:`scautopick` at
     some time and considered by scanloc according to
     their creation times. Delayed picks may become irrelevant for the processing.
     Configure :confval:`buffer.pickKeep` and :confval:`buffer.originKeep` accordingly.

     However, the **creation times of picks may be obscured** when created in a
     :program:`scautopick` playback and picks may have almost identical creation times
     independent of their pick times.

   * :ref:`In message-based playbacks <sec-scanloc-rt-playbacks>`, picks are
     provided to scanloc via the messaging system. When created in real time,
     the **creation times** of picks form a
     realistic time reference for scanloc and is therefore considered.

   * :ref:`In offline XML playbacks <sec-scanloc-xml-playbacks>` (``--ep``),
     scanloc considers picks by default according to their actual **pick times**.
     For picks created in an offline playback this is most reasonable as creation
     time is not a valid time reference anymore.
     **However, referencing to pick time may result in a behavior which is
     different from real-time conditions.**

     Therefore, for mimicking real-time conditions in playbacks of picks obtained
     in real-time conditions consider the command-line option ``--timing creationTime``.


.. _sec-scanloc-rt-playbacks:

Real-time XML playbacks
-----------------------

Real-time playbacks are useful to test the behavior of scanloc in real time based
on picks generated before. This type of playbacks is supported by
:ref:`auxialiary scripts <sec-scanloc-aux-tools>` shipped with the scanloc package.

- Use phase picks obtained in real-time

  #. Read real-time picks from the database and store them in :file:`picks.xml` for later playback:

     .. code-block:: sh

        dump_picks -r -90,-180,90,180 -d [database] -t "2015-08-17 08:03:00.00~2015-08-17 08:04:00.00" -o picks.xml

  #. Play back picks stored in XML format at normal speed (with seiscomp
     messaging), start *scanloc* separately for debug messages on the command line
     **considering default timing by creation time of the picks**:

     .. code-block:: sh

        seiscomp stop
        seiscomp start scmaster scamp scmag scevent

        scanloc --debug
        playback_picks picks.xml

- Play back picks with amplitudes originating from different
  pipelines :cite:p:`pipeline` at normal speed (with SeisComP messaging).
  Picks and amplitudes in XML format
  are sent to the separated message groups PICK, AMPLITUDE and L1PICK.
  scanloc and l1scanloc listen to picks from PICK and L1PICKS, respectively.
  scautoloc :cite:p:`scautoloc` additionally needs the pick amplitudes from the
  subscribed amplitude groups.

  #. Create the pick XML files including the pick amplitudes in an offline playback
     by the modules as in your 2-pipeline system.
  #. Start all required modules including the scanloc instances
  #. Execute *playback_picks* with ``--timing pickTime`` for sending the picks and
     amplitudes created by different pickers at different times.

  .. code-block:: sh

     scautopick --ep --playback -I [your_file] -d [database] > picks.xml
     l1autopick --ep --playback -I [your_file] -d [database] > l1picks.xml

     seiscomp start scmaster scamp scmag scevent scautoloc l1autoloc scanloc l1scanloc

     playback_picks picks.xml:PICK:AMPLITUDE l1picks.xml:L1PICK:AMPLITUDE --timing pickTime


.. _sec-scanloc-xml-playbacks:

Offline XML playbacks
---------------------

In offline XML playbacks (``--ep``), the picks are provided to scanloc in an XML file.
scanloc write the results in XML format to stdout which can be re-directed into XML files.

.. note::

   When picks are created in an offline playback use scanloc with default timing
   based on pick time corresponding to ``--timing pickTime``! Otherwise you may
   use scanloc with the command-line option ``--timing creationTime``.

- Play back picks stored in XML format to locate events and to determined
  the magnitude. Intermediate results are stored in XML files.

  #. Events do not exist in the database, use scdb :cite:p:`scdb` to populate the database
     with events in :file:`events.xml`.
     The messaging system is not running.

     .. code-block:: sh

        scautopick --ep --playback -I [your_file] -d [database] > picks.xml
        scanloc --ep picks.xml -d [database] > origins.xml
        scamp --ep origins.xml -d [database] -I [your_file] > amps.xml
        scmag --ep amps.xml -d [database] > mags.xml
        scevent --ep mags.xml -d [database] > events.xml

        scdb -i events.xml -d [database]

  #. New events not existing yet in the database shall be created, existing ones
     shall be updated with new origins. Run the messaging system and all
     modules that shall process the new parameters of the origin, e.g.
     scamp :cite:p:`scamp` scmag :cite:p:`scmag` , scevent :cite:p:`scevent`.
     Use scdispatch :cite:p:`scdispatch` to send the new objects to
     the messaging system. Get the picks from a scautopick playback or use
     *dump_picks*. Execute scanloc with the appropriate timing.**

     .. code-block:: sh

        # either
        scanloc --ep picks.xml -d [database] > origins.xml
        # or
        scanloc --ep picks.xml -d [database] --timing creationTime > origins.xml

        seiscomp start scmaster scamp scmag scevent
        scdispatch -H host -i origins.xml

     Instead of the origins, other parameters created by the
     procedures in (1.) may be dispatched, e.g. :file:`mags.xml`.

- Play back picks stored in XML format, without a database.

  #. Store the station inventory and the
     binding configuration from a database in an XML file.

     .. code-block:: sh

        scxmldump -fI -o inventory.xml -d [database]
        scxmldump -fC -o config.xml -d [database]


  #. Continue with the examples above replacing the database parameter
     ``-d [database]`` with ``--inventory-db inventory.xml --config-db config.xml``.



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

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

scanloc inherits :ref:`global options<global-configuration>`.

.. note::

   Modules/plugins may require a license file. The default path to license
   files is :file:`@DATADIR@/licenses/` which can be overridden by global
   configuration of the parameter :confval:`gempa.licensePath`. Example: ::

      gempa.licensePath = @CONFIGDIR@/licenses



.. confval:: ignoreOrigins

   Type: *boolean*

   Ignore external origins received from messaging or from XML
   playback.
   
   Default: Accept external origins from messaging and associate
   more phases.
   Default is ``false``.

.. confval:: defaultDepth

   Type: *float*

   Unit: *km*

   Default used for locating.
   Default is ``5.0``.

.. confval:: ignoreDepth

   Type: *float*

   Unit: *km*

   Depths larger than ignoreDepth will be ignored.
   Default is ``650.0``.

.. confval:: maxRMS

   Type: *float*

   Unit: *s*

   Maximum allowed overall residual.
   Default is ``1.5``.

.. confval:: minScore

   Type: *float*

   Score to be reached to send origin.
   Default is ``0.0``.

.. confval:: buffer.pickKeep

   Type: *float*

   Unit: *s*

   Time to keep picks in the internal buffer. Time comparison
   is based on the pick times. In non\-real time
   playbacks the time to keep picks is usually compressed.
   Default is ``180.0``.

.. confval:: buffer.ignoreManualOrigins

   Type: *boolean*

   Ignore manual external origins received from messaging or
   from XML playback.
   
   The parameter \"ignoreOrigins\" must be inactive for
   this option to be effective.
   Default is ``true``.

.. confval:: buffer.originKeep

   Type: *float*

   Unit: *s*

   Time to keep origins in the internal buffer. Time comparison
   is based on the origin times. In non\-real time
   playbacks the time to keep orgins is usually compressed.
   Default is ``180.0``.

.. note::
   **clusterSearch.\***
   *Parameters controlling the cluster search based on P phase*
   *picks.*



.. confval:: clusterSearch.minSize

   Type: *int*

   Minimum number of core points \(P picks\) to form a cluster.
   Default is ``4``.

.. confval:: clusterSearch.maxPickDelay

   Type: *float*

   Unit: *s*

   Maximum allowed difference between P picks and cluster reference
   time \(latest pick time\). Optimum values can be derived from
   travel times.The cluster search ignores all
   picks which exceed the value. Using \"\-1\" enables all picks
   regardless of the delay.
   Default is ``-1.0``.

.. confval:: clusterSearch.referenceTimeMode

   Type: *string*

   Mode to set the cluster reference time. Read the documentation
   for the details. Available modes:
   
   LastPick: The pick time of the last incoming P pick is the
   cluster reference time.
   
   MaxPickDelay: Setting the cluster reference time is delayed
   until clusterSearch.minSize picks are available.
   Default is ``LastPick``.

.. confval:: clusterSearch.regionFilter

   Type: *list:double*

   Cluster only picks which sensor locations are inside
   the defined region. The region is defined by latitude,
   longitude and a radius in km. By default the region filter
   is disabled.
   
   Example: 50.1,12.3,20


.. confval:: clusterSearch.averageVelocity

   Type: *float*

   Unit: *km/s*

   Average velocity used for distance calculation.
   Default is ``4.0``.

.. confval:: clusterSearch.maxSearchDist

   Type: *float*

   Unit: *s*

   Maximum allowed distance over all core points and
   maximum allowed distance for neighborhood search. Both account
   for traveltime difference, inter\-station distance and the
   configured averageVelocity.
   Default is ``60``.

.. confval:: clusterSearch.maxOrigins

   Type: *uint*

   Maximum allowed origins derived from cluster search. Set this
   option to zero to disable the cluster search completly.
   Default is ``128``.

.. confval:: clusterSearch.preliminary

   Type: *boolean*

   Send origins based on cluster search as preliminary origins
   if the location fails. Otherwise those origins are ignored.
   Consider activating \"checkOrigins\".
   Default is ``false``.

.. confval:: clusterSearch.checkOrigins

   Type: *boolean*

   Check, if derived origins fulfill the cluster search criteria
   anymore. Activating this option may lower the number of events
   and suppress fake events.
   Default is ``false``.

.. confval:: clusterSearch.ignorePicks

   Type: *float*

   Unit: *s*

   By default the algorithm creates a new arrival set when there
   is already a pick with the same stream id assigned.
   Use this option to ignore surrounding picks.
   Default is ``0.0``.

.. note::
   **association.\***
   *Parameters controlling the association of P and S phases to cluster*
   *origins or external origins.*



.. confval:: association.minPhase

   Type: *int*

   Number picks in cluster origin to be reached for starting to
   associate more P nd S picks.
   Default is ``4``.

.. confval:: association.maxDist

   Type: *float*

   Unit: *km*

   Maximum epicentral distance to associate P and S picks.
   Default is ``1000.0``.

.. confval:: association.stationConfig

   Type: *path*

   The station configuration file contains lines consisting of
   network code, station code, weight \(0 or 1\) and maximum
   association distance given in degree. The maximum association
   distance is the distance in degrees from the origin up to
   which this station may contribute to a new origin. This
   parameter overrides the global parameter association.maxDist.
   If this distance is 180 deg, this station may contribute to
   new origins world\-wide. However, if the distance is only 10
   degree, the range of this station is limited. This is a helpful
   setting in case of mediocre stations in a region where there
   are numerous good and reliable stations nearby. The station
   will then not pose a risk for locations generated
   outside the maximum association distance. The last item found
   in the list overrules previous ones.
   Network and station codes may be wildcards \(\*\)
   for convenience. E.g.:
   
   \* \* 1 10
   
   GE \* 1 180


.. confval:: association.maxPResidual

   Type: *float*

   Unit: *s*

   Maximum allowed difference between measured and predicted arrival
   times for associating P phases to origin.
   Larger values allow significant correction of initial locations.
   Default is ``4.0``.

.. confval:: association.maxSResidual

   Type: *float*

   Unit: *s*

   Maximum allowed difference between measured and predicted arrival
   time for associating S phases to origins. Larger values allow
   significant correction of initial locations.
   Default is ``4.0``.

.. confval:: association.maxResidual

   Type: *float*

   Unit: *s*

   Maximum allowed time residuals of picks after association and
   relocation. Picks will be removed at exceedance starting with
   largest residual and origins will be relocated.
   Default is ``2.0``.

.. confval:: association.tableType

   Type: *string*

   Type of traveltime tables for phase association.
   May be different from locator. Use e.g. libtau or LOCSAT.
   Default is ``LOCSAT``.

.. confval:: association.table

   Type: *string*

   Name of traveltime table used for phase association.
   May be different from locator profile. Using a different
   table\/profile may result in increased runtime.
   Default is ``iasp91``.

.. confval:: association.zeroWeightProfiles

   Type: *list:string*

   zeroWeight\-profile name for associating the configured phases
   with zero weight to origins. Multiples profile names may be set
   separated by comma. The order of names determines order of
   checked phases. Each profile can have different parameters.


.. note::
   **association.zeroWeight.\***
   *zeroWeight profiles containing the parameters for associating*
   *phases with zero weight to origins.*



.. note::

   **association.zeroWeight.$name.\***
   $name is a placeholder for the name to be used and needs to be added to :confval:`zeroWeight.profiles` to become active.

   .. code-block:: sh

      zeroWeight.profiles = a,b
      association.zeroWeight.a.value1 = ...
      association.zeroWeight.b.value1 = ...
      # c is not active because it has not been added
      # to the list of zeroWeight.profiles
      association.zeroWeight.c.value1 = ...


.. confval:: association.zeroWeight.$name.phaseType

   Type: *String*

   One phase type to be associated with zero weight.
   Examples: PKP or Pdiff.


.. confval:: association.zeroWeight.$name.minDistance

   Type: *float*

   Unit: *degree*

   Minimum epicentral distance.
   Default is ``120.0``.

.. confval:: association.zeroWeight.$name.maxResidual

   Type: *float*

   Unit: *s*

   Maximum time residual of the associated phase.
   Default is ``5.0``.

.. note::
   **locator.\***
   *Parameters controlling the locator for locating scanloc*
   *origins.*



.. confval:: locator.type

   Type: *string*

   The locator type to be used. Use e.g. LOCSAT or Hypo71.
   Default is ``LOCSAT``.

.. confval:: locator.profile

   Type: *string*

   The locator profile to be used. Using a different profile\/table
   for locating and associating may result in increased runtime.
   Default is ``iasp91``.

.. confval:: locator.fixDepth

   Type: *boolean*

   If enabled, the locator fixes the depth to the configured
   default value \"defaultDepth\" in case that all
   previous attempts to relocate fail.
   This option may result in many more origins. It
   prevents \"ignoreDepth\" from beeing
   effective if \"defaultDepth\" < \"ignoreDepth\".
   Default is ``false``.

.. note::
   **eventAssociation.\***
   *Parameters controlling the association of interal scanloc origins*
   *to internal scanloc events.*



.. confval:: eventAssociation.compareAllArrivalTimes

   Type: *boolean*

   This parameter is only used in conjunction with
   eventAssociation.maximumMatchingArrivalTimeDiff.
   If a station has multiple associated arrivals for a
   particular event, this flag defines if the time distance
   of a new pick to all arrivals must be within
   eventAssociation.maximumMatchingArrivalTimeDiff
   or if one matching arrival is enough.
   Default is ``false``.

.. confval:: eventAssociation.minMatchingArrivals

   Type: *int*

   Minimum number of matching picks between two origins to be
   associated to the same event.
   Default is ``3``.

.. confval:: eventAssociation.maxMatchingArrivalTimeDiff

   Type: *float*

   Unit: *s*

   If this time window in seconds is negative, pickIDs
   are compared to find matching arrivals. A non negative
   value \(including 0\) compares pick times regardless
   of the pickID. Pass: \|pick1.time \- pick2.time\| <\= threshold.
   Default is ``-1``.

.. confval:: eventAssociation.maxDist

   Type: *double*

   Unit: *km*

   Allowed location difference between an incoming origin compared
   with preferred origins to get associated.
   Default is ``500.0``.

.. confval:: eventAssociation.maxTimeSpan

   Type: *double*

   Unit: *s*

   Associates an origin with an existing event if the origin
   time differs not more than 60 seconds unless the
   minimumMatchingArrivals criteria matches.
   Default is ``60.0``.

.. note::
   **score.\***
   *Formula to calculate the internal origin score. Configurable are*
   *the weighting factors for the following components:*
   *used P-phase (score.weights.p), unused P-phase (score.weights.p0),*
   *used S-phase (score.weights.s), unused S-phase (score.weights.0),*
   *depth (score.weights.depth) and residual (score.weights.residual).*



.. confval:: score.weights.p

   Type: *float*

   Defines the weight of p arrivals for scoring.
   Default is ``1.0``.

.. confval:: score.weights.p0

   Type: *float*

   Defines the weight of p arrivals with a weight of zero
   for scoring.
   Default is ``0.5``.

.. confval:: score.weights.s

   Type: *float*

   Defines the weight of s arrivals for scoring.
   Default is ``2.0``.

.. confval:: score.weights.s0

   Type: *float*

   Defines the weight of s arrivals with a weight of zero
   for scoring.
   Default is ``0.5``.

.. confval:: score.weights.depth

   Type: *float*

   Defines the weight of the depth for scoring.
   Default is ``1.0``.

.. confval:: score.weights.residual

   Type: *float*

   Defines the weight of the residual for scoring
   Default is ``1.0``.

.. confval:: score.weights.increaseManual

   Type: *boolean*

   Increase the weight for manual picks by a factor of 1.001.
   This gives preference to manual picks in case
   automatic ones co\-exist for the same station.
   Default is ``false``.

.. note::
   **publication.\***
   *Parameters controlling the publication of internal scanloc*
   *events as new origins to the messaging system.*



.. confval:: publication.intervalTimeSlope

   Type: *double*

   Unit: *s/count*

   Parameter \"a\" in the equation t \= aN + b.
   
   t: time interval between sending updates of an origin
   
   N: arrival count of the origin
   
   Increasing the value reduces the amount of sent origins.
   With the option \-\-ep \(playback mode\) this value is set to 0.
   Default is ``0.5``.

.. confval:: publication.intervalTimeIntercept

   Type: *double*

   Unit: *s*

   Parameter \"b\"  in the equation t \= aN + b.
   
   t: time interval between sending updates of an origin
   
   N: arrival count of the origin
   
   Increasing the value reduces the amount of sent origins.
   With the option \-\-ep \(playback mode\) this value is set to 0.
   Default is ``0.0``.

.. confval:: publication.wakeUpInterval

   Type: *int*

   Unit: *s*

   Integer interval to check the origin buffer for sending origins if no
   other origins have been created.
   
   Reducing the value may be required in EEW: it increases the
   load on scanloc but allows to send origins more rapidly.
   Default is ``5``.


Command-Line Options
====================

:program:`scanloc [options]`


Generic
-------

.. option:: -h, --help

   show help message.

.. option:: -V, --version

   show version information

.. option:: --config-file arg

   Use alternative configuration file. When this option is used
   the loading of all stages is disabled. Only the given configuration
   file is parsed and used. To use another name for the configuration
   create a symbolic link of the application or copy it,
   e.g. scautopick \-> scautopick2.

.. option:: --plugins arg

   Load given plugins.

.. option:: -D, --daemon

   Run as daemon. This means the application will fork itself and
   doesn't need to be started with \&.


Verbosity
---------

.. option:: --verbosity arg

   Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info, 4:debug

.. option:: -v, --v

   Increase verbosity level \(may be repeated, eg. \-vv\)

.. option:: -q, --quiet

   Quiet mode: no logging output

.. option:: --print-component arg

   For each log entry print the component right after the
   log level. By default the component output is enabled
   for file output but disabled for console output.

.. option:: --component arg

   Limits the logging to a certain component. This option can
   be given more than once.

.. option:: -s, --syslog

   Use syslog logging back end. The output usually goes to \/var\/lib\/messages.

.. option:: -l, --lockfile arg

   Path to lock file.

.. option:: --console arg

   Send log output to stdout.

.. option:: --debug

   Debug mode: \-\-verbosity\=4 \-\-console\=1

.. option:: --trace

   Trace mode: \-\-verbosity\=4 \-\-console\=1 \-\-print\-component\=1 \-\-print\-context\=1

.. option:: --log-file arg

   Use alternative log file.


Messaging
---------

.. option:: -u, --user arg

   Overrides configuration parameter :confval:`connection.username`.

.. option:: -H, --host arg

   Overrides configuration parameter :confval:`connection.server`.

.. option:: -t, --timeout arg

   Overrides configuration parameter :confval:`connection.timeout`.

.. option:: -g, --primary-group arg

   Overrides configuration parameter :confval:`connection.primaryGroup`.

.. option:: -S, --subscribe-group arg

   A group to subscribe to. This option can be given more than once.

.. option:: --start-stop-msg arg

   Sets sending of a start\- and a stop message.


Database
--------

.. option:: --db-driver-list

   List all supported database drivers.

.. option:: -d, --database arg

   The database connection string, format:
   service:\/\/user:pwd\@host\/database.
   \"service\" is the name of the database driver which
   can be queried with \"\-\-db\-driver\-list\".

.. option:: --config-module arg

   The configmodule to use.

.. option:: --inventory-db arg

   Load the inventory from the given database or file, format: [service:\/\/]location

.. option:: --db-disable

   Do not use the database at all


Input
-----

.. option:: --pick-keep arg

   Overrides configuration parameter :confval:`pickKeep`.

.. option:: --origin-keep arg

   Overrides configuration parameter :confval:`originKeep`.

.. option:: --allow-rejected-picks

   Allow processing of picks with evaluation status 'rejected'.
   Otherwise these picks are ignored.

.. option:: --filter-pick-author

   Filter picks by author and only consider picks created by
   the given author. Empty string considers all authors.
   The option allows operation of
   scanloc based on picks from a specific picker module
   where only picks from one picker should be used, e.g.
   in tuning scanloc for a pipeline.

.. option:: --ep arg

   Name of input XML file \(SCML\) with all picks and origins
   for offline processing. The database connection is not
   received from messaging and must be provided. Results
   are sent as XML to stdout.

.. option:: --timing arg

   Offline processing reference timing mode: Use pickTime and
   creationTime for sorting picks according to pick time and
   creation time, respectively. scanloc uses creationTime in
   real\-time processing.
   
   Default: pickTime


Locator
-------

.. option:: --locator-type arg

   Overrides configuration parameter :confval:`locator.type`.
   The locator type to use. Default: LOCSAT.

.. option:: --locator-profile arg

   Overrides configuration parameter :confval:`locator.profile`.
   The locator profile to use. Default: iasp91.

.. option:: --locator-list

   List all registered locators.


Output
------

.. option:: --final-only

   Limit result set to final origins only. This option is
   available for offline processing only.

.. option:: --dump-origins

   Don't publish origins, write them to stdout. Useful for
   tuning.

.. option:: --cluster-search-log-file arg

   File name to output detailed cluster search information.
   Useful for tuning.