[seiscomp, scanloc] Install, add .gitignore

share/doc/scanloc/html/_sources/base/auxiliary.rst.txt

@@ -0,0 +1,392 @@
+.. _sec-scanloc-aux-tools:
+
+Auxiliary Scripts
+=================
+
+The scanloc package also ships with auxiliary scripts for real-time or non-real-time
+playbacks and tuning. For these tools, the usual options (:option:`-h`,
+:option:`--debug`, etc.) apply. Read the :ref:`scanloc-example` section for
+example applications.
+
+
+.. _sec-scanloc-dump_picks:
+
+dump_picks
+----------
+
+:program:`dump_picks` reads picks and amplitudes from a database and writes them
+to file or the command line in the given format, by default XML (:term:`SCML`).
+Control the database request to filter by
+
+* Author (:option:`--author`) contributing the object,
+* Comparison with inventory (:option:`--check-inventory`),
+* Object evaluation mode (:option:`--manual`, :option:`--automatic`),
+* Region of contributing station (:option:`--region`),
+* Time (:option:`--time-window`, :option:`--hours`, :option:`--start`).
+
+Applications
+~~~~~~~~~~~~
+
+* Dump picks and amplitudes in XML for further analysis or feeding into another
+  module such as :ref:`scanloc`.
+* Printing statistics and useful information of the retrieved pick and amplitude
+  set with :option:`--print`.
+* Fetch waveforms for picks from SDS archive, a CAPS or FDSN server by
+  generating stream lists from picks with time windows like with
+  :cite:t:`scevtstreams` but for picks independent of events and origins.
+  Consider the option :option:`--type` for choosing the type and
+  :option:`--margin` for the time margin.
+
+.. hint::
+
+   * For retrieving events or origins with picks, amplitudes, etc. from a
+     database use :cite:t:`scxmldump`.
+   * Multiple :term:`SCML` files can be merged into one using
+     :cite:t:`scxmlmerge`.
+
+
+Examples
+~~~~~~~~
+
+* Print command-line help:
+
+  .. code-block:: bash
+
+     dump_picks -h
+
+* Extract all picks and amplitudes for the given time span made by author
+  'l1autopick':
+
+  .. code-block:: bash
+
+     dump_picks -t 2022-01-20T13:52:00~2022-01-20T13:57:00 -d localhost --author l1autopick
+
+* Dump the streams of picks with time windows fetching the corresponding data
+  from a local CAPS server :cite:p:`caps`.
+
+  .. code-block:: bash
+
+     dump_picks -d localhost --type 2 --margin 60 | capstool -H localhost -o data.mseed
+
+* Dump the streams of picks with time windows fetching the corresponding data
+  from a local SDS archive
+
+  .. code-block:: bash
+
+     dump_picks -d localhost --type 1 --margin 60 | scart -dsE -l - /archive -o data.mseed
+
+
+Command-Line Options
+~~~~~~~~~~~~~~~~~~~~
+
+:program:`dump_picks [options]`
+
+
+Dump
+^^^^
+
+.. option:: --hours arg
+
+   Type: *double*
+
+   Start search hours before now considering object time, not creation time.
+   If set, :option:`--time-window`, :option:`--start`, :option:`--end` are ignored.
+   The hours are added to the minutes if set.
+
+.. option:: --minutes arg
+
+   Type: *double*
+
+   Start search minutes before now considering object time, not creation time.
+   The minutes are added to the hours if set.
+   If set, :option:`--time-window`, :option:`--start`, :option:`--end` are ignored.
+
+.. option:: --start arg
+
+   Type: *string*
+
+   Default: ``1970-01-01 00:00:00.000``
+
+   Start time of search until now considering object time, not creation time.
+   If set, :option:`--time-window` is ignored.
+
+.. option:: --end arg
+
+   Type: *string*
+
+   Default: ``now``
+
+   End time of search considering object time, not creation time. If set,
+   :option:`--time-window` is ignored.
+
+.. option:: -t, --time-window arg
+
+   Type: *string*
+
+   Default: ``1970-01-01T00:00:00~now``
+
+   Specify time window to search picks and amplitudes by their time. Use one
+   single string which must be enclosed by quotes in case of spaces in the time
+   string. Times are of course in UTC and separated by a tilde '~'.
+
+.. option:: --maximum-delay arg
+
+   Type: *double*
+
+   Unit: ``s``
+
+   Maximum allowed delay of picks or amplitudes, hence the difference between
+   creation time and actual time value. Allows identification of picks found in
+   real time.
+
+.. option:: -r, --region arg
+
+   Type: *string*
+
+   Unit: ``deg``
+
+   Default: ``-90,-180,90,180``
+
+   Dump picks only from sensors in given region. Implies loading an inventory.
+
+   Format: minLat,minLon,maxLat,maxLon
+
+   Default: -90,-180,90,180 if not set.
+
+.. option:: -c, --check-inventory
+
+   Dump picks only when corresponding streams are found in inventory.
+
+.. option:: -O, --origin arg
+
+   Type: *string*
+
+   Origin ID. Dump all picks associated with the origin that has the given
+   origin ID.
+
+.. option:: -m, --manual
+
+   Type: *boolean*
+
+   Dump only manual picks.
+
+.. option:: -a, --automatic
+
+   Type: *boolean*
+
+   Dump only automatic picks.
+
+.. option::  -n, --no-amp
+
+   Type: *boolean*
+
+   Do not dump amplitudes from picks. Amplitudes are not required by scanloc.
+
+.. option:: --author arg
+
+   Type: *string*
+
+   Filter picks by author. Author information can be extracted from
+   XML files using the :program:`playback_picks` option :option:`--print`.
+
+.. option:: --net-sta arg
+
+   Type: *string*
+
+   Filter picks and amplitudes by network code or network and station code.
+   Format: NET or NET.STA. Network and station information can be extracted from
+   XML files using the :program:`playback_picks` along with :option:`--print`,
+   or inventory (:cite:t:`scinv`), waveforms (:cite:t:`scart`) or
+   bindings configuration (:cite:t:`scdumpcfg`).
+
+
+Output
+^^^^^^
+
+.. option:: -o, --output arg
+
+   Type: *string*
+
+   Name of output file. If not given, all data is written to stdout.
+
+.. option:: --type arg
+
+   Type: *string*
+
+   Default: ``0``
+
+   Type of output format.
+   0 / scml: SCML containing all objects (default if option is not used)
+
+   1 / streams: Time windows and streams for all picks like in scevtstreams
+
+   2 / caps: Time windows and streams in capstool format
+
+   3 / fdsnws: Time windows and streams in FDSN dataselect webservice POST format
+
+   Except for type 0, only picks are considered ignoring all other objects.
+
+.. option:: -f, --formatted
+
+   Type: *boolean*
+
+   Output formatted XML. Default is unformatted. Applies only for type 0.
+
+.. option:: --margin arg
+
+   Type: *string*
+
+   Unit: ``s``
+
+   Default: ``300``
+
+   Time margin applied around pick times along with --type = [1:]. Use 2
+   comma-separted values (before,after) for asymmetric margins, e.g.
+   --margin 120,300.
+
+
+.. _sec-scanloc-playback_picks:
+
+playback_picks
+--------------
+
+:program:`playback_picks` plays back picks, amplitudes and origins from XML files
+at normal or different speed and sends them to the messaging system. It can also
+be used to print statistics and information extracted from the read XML file.
+:program:`playback_picks` supports multiple pipelines by defining the message
+groups into which objects are injected. The script allows controlling:
+
+* Message groups: Append the message groups for sending picks and amplitudes.
+* Mode (:option:`--mode`): In real-time mode a constant number of seconds is added
+  to the creation and reference times before sending an object to the messaging
+  for mimicking real-time situations at current time. The seconds to add is
+  derived from the time of the first object. Default mode is *historic*.
+* Speed (:option:`--speed`): The speed factor to use.
+* Start (:option:`--jump`): Ignore the first objects within the given number of
+  seconds.
+* Timing (:option:`--timing`): Define the sorting of the objects. Default is
+  *creationTime*. Consider the comments on timing in section
+  :ref:`scanloc-example`.
+
+
+.. important::
+
+   'creationTime' should be considered for playing back origins since their
+   actual origin time values are always before picks and amplitudes.
+
+
+Examples
+~~~~~~~~
+
+* Print the command-line help:
+
+  .. code-block:: sh
+
+     playback_picks -h
+
+* Just print statistics of the read XML including author information and stream
+  codes on which picks and amplitudes were measured. The NSLC information can be
+  used to extract waveforms or to set up corresponding bindings:
+
+  .. code-block:: sh
+
+     playback_picks --print picks.xml
+
+* Make a playback injecting picks and origins into different message groups but
+  amplitudes into the same default group, e.g., of different pipelines.
+  'creationTime' is used as a time reference since origin times are before times
+  of picks and amplitudes and considering 'pickTime' would distort the order of
+  the objects unrealistically:
+
+  .. code-block:: sh
+
+     playback_picks origins.xml l1picks.xml:L1PICK:AMPLITUDE:L1LOCATION --timing creationTime
+
+
+Command-Line Options
+~~~~~~~~~~~~~~~~~~~~
+
+:program:`playback_picks [options]`
+
+
+Playback
+^^^^^^^^
+
+.. option:: --authors arg
+
+   Type: *list:string*
+
+   Default: ``None``
+
+   Author of objects to filter before playing back. Objects from all other
+   authors are ignored. Separate multiple authors by comma.
+
+.. option:: -j, --jump arg
+
+   Type: *double*
+
+   Unit: ``minute``
+
+   Jump in time by given value ignoring the corresponding objects.
+
+.. option:: --list
+
+   Just list important pick information from the read XML file and then exit
+   without playing back. The sorting of the list depends on '--timing'.
+   Information include: phase hint, pick time, stream ID, author, time to
+   previous pick, delay.
+
+.. option:: --mode arg
+
+   Default: ``historic``
+
+   Type: *string*
+
+   Values: ``historic, realTime``
+
+   Playback mode. 'realTime' mimics current situation, 'historic' preserves all
+   times.
+
+.. option:: -o, --object arg
+
+   Type: *list:string*
+
+   Default: ``None``
+
+   Values: ``pick,amplitude,origin``
+
+   Limit the playback to the given list of objects.
+
+.. option:: --print
+
+   Just print some statistics of the read XML file and then exit without playing
+   back. The list of stream codes (NSLC) is printed to stdout. All other
+   information is printed to stderr. The NSLC information can be used, e.g., for
+   filtering waveforms (:cite:t:`scart`) or inventory (:cite:t:`invextr`), for
+   creating global bindings or applying author filtering, e.g., in
+   :ref:`dump_picks <sec-scanloc-dump_picks>`.
+
+.. option:: --speed arg
+
+   Default: ``1``
+
+   Type: *double*
+
+   Speed of playback.
+
+   1: true speed.
+
+.. option:: --timing arg
+
+   Default: ``creationTime``
+
+   Type: *string*
+
+   Values: ``pickTime,creationTime``
+
+   Timing reference: 'pickTime' plays back in order of actual times of picks,
+   amplitudes and origins, 'creationTime' considers their creation times instead.
+   Use 'pickTime' if creation times are not representative of the order of
+   objects, e.g., when created in playbacks. 'creationTime' should be considered
+   for playing back origins since their actual origin time values are always
+   before picks and amplitudes.

share/doc/scanloc/html/_sources/base/changelog.rst.txt

@@ -0,0 +1,3 @@
+.. _sec-changelog:
+
+.. mdinclude:: CHANGELOG.md

share/doc/scanloc/html/_sources/base/gradients.rst.txt

@@ -0,0 +1,304 @@
+.. _gradients:
+
+***************
+Color Gradients
+***************
+
+
+Overview
+========
+
+A number of pre-defined color gradients are available for gempa modules.
+These gradients can be used when displaying color-coded values such as grids,
+spectrograms or heat-maps. The following is an overview of pre-defined
+gradients along with the name of the gradient which can be used in
+configurations. The gradients are grouped into:
+
+* :ref:`gradients-fullspectrum`
+* :ref:`gradients-darkyellow`
+* :ref:`gradients-blackandwhite`
+* :ref:`gradients-singlecolor`
+* :ref:`gradients-threecolor`
+
+
+List of Gradients
+=================
+
+.. _gradients-fullspectrum:
+
+Full spectrum
+-------------
+
+Gradients that use the full spectrum of colors.
+
+
+.. _gradients-default:
+
+Default
+~~~~~~~
+
+* Configuration name: :option:`Default`
+
+.. figure:: media/gradients/Default.*
+   :width: 420 px
+   :alt: overview of the Default color-gradient
+.. figure:: media/gradients/Default_.*
+   :width: 420 px
+   :alt: example spectrogram using the Default gradient
+
+   Example spectrogram using the "Default" color-gradient.
+
+
+.. _gradients-spectrum:
+
+Spectrum
+~~~~~~~~
+
+* Configuration name: :option:`Spectrum`
+
+.. figure:: media/gradients/Spectrum.*
+   :width: 420 px
+   :alt: overview of the Spectrum color-gradient
+.. figure:: media/gradients/Spectrum_.*
+   :width: 420 px
+   :alt: example spectrogram using the Spectrum gradient
+
+   Example spectrogram using the "Spectrum" color-gradient.
+
+
+.. _gradients-circle:
+
+Circle
+~~~~~~
+
+* Configuration name: :option:`Circle`
+
+.. figure:: media/gradients/Circle.*
+   :width: 420 px
+   :alt: overview of the Circle color-gradient
+.. figure:: media/gradients/Circle_.*
+   :width: 420 px
+   :alt: example spectrogram using the Circle gradient
+
+   Example spectrogram using the "Circle" color-gradient.
+
+
+.. _gradients-darkyellow:
+
+Dark to yellow
+--------------
+
+Gradients optically resembling fire with increased energy beeing displayed by
+bright yellow tones.
+
+
+.. _gradients-blackbody:
+
+BlackBody
+~~~~~~~~~
+* Configuration name: :option:`BlackBody`
+
+.. figure:: media/gradients/BlackBody.*
+   :width: 420 px
+   :alt: overview of the BlackBody color-gradient
+.. figure:: media/gradients/BlackBody_.*
+   :width: 420 px
+   :alt: example spectrogram using the BlackBody gradient
+
+   Example spectrogram using the "BlackBody" color-gradient.
+
+
+.. _gradients-inferno:
+
+Inferno
+~~~~~~~
+* Configuration name: :option:`Inferno`
+
+.. figure:: media/gradients/Inferno.*
+   :width: 420 px
+   :alt: overview of the Inferno color-gradient
+.. figure:: media/gradients/Inferno_.*
+   :width: 420 px
+   :alt: example spectrogram using the Inferno gradient
+
+   Example spectrogram using the "Inferno" color-gradient.
+
+
+.. _gradients-plasma:
+
+Plasma
+~~~~~~
+
+* Configuration name: :option:`Plasma`
+
+.. figure:: media/gradients/Plasma.*
+   :width: 420 px
+   :alt: overview of the Plasma color-gradient
+.. figure:: media/gradients/Plasma_.*
+   :width: 420 px
+   :alt: example spectrogram using the Plasma gradient
+
+   Example spectrogram using the "Plasma" color-gradient.
+
+
+.. _gradients-blackandwhite:
+
+Black and white
+---------------
+
+For a maximum contrast there are these two gradients that just use black and
+white.
+
+
+.. _gradients-blackwhite:
+
+BlackWhite
+~~~~~~~~~~
+
+* Configuration name: :option:`BlackWhite`
+
+.. figure:: media/gradients/BlackWhite.*
+   :width: 420 px
+   :alt: overview of the BlackWhite color-gradient
+.. figure:: media/gradients/BlackWhite_.*
+   :width: 420 px
+   :alt: example spectrogram using the BlackWhite gradient
+
+   Example spectrogram using the "BlackWhite" color-gradient.
+
+
+.. _gradients-whiteblack:
+
+WhiteBlack
+~~~~~~~~~~
+
+* Configuration name: :option:`WhiteBlack`
+
+.. figure:: media/gradients/WhiteBlack.*
+   :width: 420 px
+   :alt: overview of the WhiteBlack color-gradient
+.. figure:: media/gradients/WhiteBlack_.*
+   :width: 420 px
+   :alt: example spectrogram using the WhiteBlack gradient
+
+   Example spectrogram using the "WhiteBlack" color-gradient.
+
+
+.. _gradients-singlecolor:
+
+Single color
+------------
+
+The single color gradients have the same benefit as the
+:ref:`black and white gradients <gradients-blackwhite>` and are of a high contrast.
+
+
+.. _gradients-bluepurple:
+
+BluePurple
+~~~~~~~~~~
+
+* Configuration name: :option:`BuPu`
+
+.. figure:: media/gradients/BluePurple.*
+   :width: 420 px
+   :alt: overview of the BluePurple color-gradient
+.. figure:: media/gradients/BluePurple_.*
+   :width: 420 px
+   :alt: example spectrogram using the BluePurple gradient
+
+   Example spectrogram using the "BluePurple" color-gradient.
+
+
+.. _gradients-blues:
+
+Blues
+~~~~~
+
+* Configuration name: :option:`Blues`
+
+.. figure:: media/gradients/Blues.*
+   :width: 420 px
+   :alt: overview of the Blues color-gradient
+.. figure:: media/gradients/Blues_.*
+   :width: 420 px
+   :alt: example spectrogram using the Blues gradient
+
+   Example spectrogram using the "Blues" color-gradient.
+
+
+.. _gradients-purplered:
+
+PurpleRed
+~~~~~~~~~
+
+* Configuration name: :option:`PuRd`
+
+.. figure:: media/gradients/PurpleRed.*
+   :width: 420 px
+   :alt: overview of the PurpleRed color-gradient
+.. figure:: media/gradients/PurpleRed_.*
+   :width: 420 px
+   :alt: example spectrogram using the PurpleRed gradient
+
+   Example spectrogram using the "PurpleRed" color-gradient.
+
+
+.. _gradients-threecolor:
+
+Three color
+-----------
+
+Gradients allowing to distinguish more details than
+:ref:`single colored <gradients-singlecolor>`.
+
+
+.. _gradients-redyellowblue:
+
+RedYellowBlue
+~~~~~~~~~~~~~
+
+* Configuration name: :option:`RdYlBu`
+
+.. figure:: media/gradients/RedYellowBlue.*
+   :width: 420 px
+   :alt: overview of the RedYellowBlue color-gradient
+.. figure:: media/gradients/RedYellowBlue_.*
+   :width: 420 px
+   :alt: example spectrogram using the RedYellowBlue gradient
+
+   Example spectrogram using the "RedYellowBlue" color-gradient.
+
+
+.. _gradients-parula:
+
+Parula
+~~~~~~
+
+* Configuration name: :option:`Parula`
+
+.. figure:: media/gradients/Parula.*
+   :width: 420 px
+   :alt: overview of the Parula color-gradient
+.. figure:: media/gradients/Parula_.*
+   :width: 420 px
+   :alt: example spectrogram using the Parula gradient
+
+   Example spectrogram using the "Parula" color-gradient.
+
+
+.. _gradients-viridis:
+
+Viridis
+~~~~~~~
+
+* Configuration name: :option:`Viridis`
+
+.. figure:: media/gradients/Viridis.*
+   :width: 420 px
+   :alt: overview of the Viridis color-gradient
+.. figure:: media/gradients/Viridis_.*
+   :width: 420 px
+   :alt: example spectrogram using the Viridis gradient
+
+   Example spectrogram using the "Viridis" color-gradient.

share/doc/scanloc/html/_sources/base/introduction.rst.txt

@@ -0,0 +1,84 @@
+Introduction
+============
+
+scanloc for |scname| :cite:p:`seiscomp` is optimzed for monitoring local and
+micro seismicity within small as
+well as large seismic monitoring networks in low and high seismicity environments.
+Typical networks consist of 5 to 20 stations
+and sometimes even many more were the station distances are in the range of
+hundreds of meters to tens of kilometers.
+
+scanloc makes use of the cluster search algorithm DBSCAN :cite:p:`dbscan` to
+associate detected seismic phases to one or many potential seismic events.
+While the cluster search itself is based on P phases only, in a second step S
+picks and more P phases are associated to better locate the event.
+
+In order to provide high-quality picks from S phases, a new
+:ref:`S-phase picker <scanloc-spicker>` is distributed
+along with scanloc. The S picker allows to identify S phases on the horizontal
+components or on the vertical components if the horizontals should be unavailable.
+A :ref:`user-friendly debugger GUI <scanloc-spick-debugger>` allows the interactive
+tuning of the S picker configuration parameters based on waveforms.
+
+:ref:`Additonal auxiliary tools <sec-scanloc-aux-tools>` ship with the scanloc
+package to support detailed tuning and realistic playbacks.
+
+
+Applications
+------------
+
+scanloc is a backbone module in |scname| systems for many applications including
+
+* Real-time monitoring of local and regional earthquakes,
+* Re-processing of historical data for more complete seismicity catalogs,
+* Monitoring of natural and induced seismicity in industrial environments e.g. at
+
+  * geothermal plants,
+  * oil and gas production,
+  * underground gas storages,
+  * open and deep mines,
+
+* Integration of :ref:`teleseismic events<scanloc-zero-weight>` detected by
+  local monitoring networks
+* :ref:`Association of P and S phases <scanloc-assoc>` to detections by other
+  instances e.g. :cite:t:`ccloc` or :cite:t:`lambda`.
+
+
+Examples from science
+---------------------
+
+scanloc has been routinely applied, demonstrated, promoted and discussed with
+scientists and the SeisComP community in scientific publications and at
+international science conferences.
+
+Examples:
+
+#. A.F. Bell, P.C. La Femina, M. Ruiz, F. Amelung, M. Bagnardi, C. J. Bean, B.
+   Bernard, C. Ebinger, M. Gleeson, J. R. Grannell, S. Hernandez, M. Higgins, C.
+   Liorzou, P. Lundgren, N. J. Meier, M. Möllhoff, S.-J. Oliva, A. G. Ruiz and
+   M. J. Stock: Caldera resurgence during the 2018 eruption of Sierra Negra
+   volcano, Galápagos Islands, 2021, Nat. Commun., 12, 1397,
+   `doi: 10.1038/s41467-021-21596-4 <https://doi.org/10.1038/s41467-021-21596-4>`_.
+#. F. Grigoli, L. Scarabello, M. Boese, B. Weber, S. Wiemer, J. F. Clinton:
+   Pick- and waveform-based techniques for real-time detection of induced seismicity,
+   2018, Geophys. J. Int., 213:2, `doi: 0.1093/gji/ggy019 <https://doi.org/10.1093/gji/ggy019>`_.
+#. J. Clinton, F. Grigoli, T. Diehl, T. Kraft, L. Scarabello, M. Hermann, P. Kaestli,
+   M. Boese, S. Wiemer: Advanced  Real-time Monitoring for Natural and Induced
+   seismic sequences, 2018, Geophyscial Research Abracts, EGU General Assembly,
+   Vol. 20,
+   `abstract: EGU2018-9480-2 <https://meetingorganizer.copernicus.org/EGU2018/EGU2018-9480.pdf>`_.
+#. F. Grigoli, M. Boese, L. Scarabello, T. Diehl, B. Weber, S. Wiemer, J. F. Clinton:
+   Picking vs Waveform based detection and location methods for induced seismicity
+   monitoring, 2018, JpGU2018, Japan,
+   `abstract: SSS03-05 <https://confit.atlas.jp/guide/event/jpgu2018/subject/SSS03-05/detail>`_.
+#. F. Grigoli, M. Boese, L. Scarabello, T. Diehl, B. Weber, S. Wiemer, J. F. Clinton:
+   Picking vs Waveform based detection and location methods for induced seismicity
+   monitoring, 2017, Geophyscial Research Abracts, EGU General Assembly, Vol. 19,
+   `abstract: EGU2017-10562 <https://meetingorganizer.copernicus.org/EGU2017/EGU2017-10562.pdf>`_.
+#. D. Roessler, J. Becker, E. Ellguth, R. Henneberger, S. Herrnkind, B. Weber:
+   Cluster-search based monitoring of local earthquakes in SeisComP3, 2016,
+   AG Seismology - 42. meeting, Bad Salzschlirf, Germany
+#. D. Roessler, E. Ellguth, S. Herrnkind, B. Weber, R. Henneberger, H. Blanck:
+   Cluster-search based monitoring of local earthquakes in SeisComP3, 2016,
+   AGU Fall Meeting, San Francisco, USA,
+   `abstract S31E-06 <https://agu.confex.com/agu/fm16/meetingapp.cgi/Paper/119780>`_.

share/doc/scanloc/html/_sources/base/locsat-tables.rst.txt

@@ -0,0 +1,69 @@
+.. _scanloc-ttt:
+
+Dense Travel-Time Tables
+========================
+
+The default travel time tables of SeisComP for :cite:t:`locsat` provide the
+times in intervals of 1 degree epicentral distance. Thus, the curvature of the
+travel-time curve at closer distance is not well imaged potentially resulting in
+wrong locations or missing event solutions. Therefore, the LOCSAT tables,
+*iasp91_scanloc*, based on the IASP91 model with higher spacial sampling are
+added to the scanloc package. The table files are located in
+:file:`$SEISCOMP_ROOT/share/locsat/tables`. They may be used along with scanloc
+and any other module which uses LOCSAT travel-time tables such as :cite:t:`scolv`,
+:cite:t:`scautoloc`, :cite:t:`screloc` or even the locator :cite:t:`stdloc`.
+
+.. note::
+
+   gempa may provide additional travel-time tables as a service based on custom
+   velocity models. `Contact <https://www.gempa.de/contact/>`_ us for any
+   related request.
+
+.. _fig-ttt-scanloc:
+
+.. figure:: ../apps/media/ttt_scanloc_P_5km.png
+   :align: center
+   :width: 18cm
+
+   Differences between P-wave travel times in the standard iasp91 tables for LOCSAT
+   and the iasp91_scanloc tables provided with scanloc for an event at 5 km depth.
+
+
+Application in scanloc
+----------------------
+
+Configure the scanloc parameters :confval:`association.table` and
+:confval:`locator.profile` with *iasp91_scanloc* for using these LOCSAT tables
+in scanloc along with LOCSAT:
+
+.. code-block:: params
+
+   # 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
+
+   # The locator type to use
+   locator.type = LOCSAT
+
+   # The locator profile to use
+   locator.profile = iasp91_scanloc
+
+Alternatively, you may use the tables along with :cite:t:`stdloc`.
+
+
+Application in other modules
+----------------------------
+
+In order to visualize the travel times or for using the tables in applications
+like :cite:t:`scolv` add the tables to your global module configuration:
+
+.. code-block:: params
+
+   ttt.LOCSAT.tables = iasp91_scanloc
+   LOCSAT.profiles = iasp91_scanloc
+
+More specific parameters may exist along with your application.

share/doc/scanloc/html/_sources/base/references.rst.txt

@@ -0,0 +1,4 @@
+References
+==========
+
+.. bibliography::

share/doc/scanloc/html/_sources/base/sphase-detector.rst.txt

@@ -0,0 +1,189 @@
+.. _scanloc-spicker:
+
+Advanced S-Phase Detector
+=========================
+
+The :ref:`scanloc` package provides the enhanced S-phase detectors,
+S-AIC and S-AIC-V, as well as the :ref:`debugger<scanloc-spick-debugger>`.
+
+
+Overview
+--------
+
+The *scanloc* package includes two S phase pickers: S-AIC and S-AIC-V, enhancing the
+performance of the picker with respect to the OpenSource S-L2. Both picker
+apply an AIC algorithm in order to detect S phases after a P pick was maked.
+Therefore S phases are only detected after a P detection.
+Using the S-AIC, S picks are determined on the vectorial sum of the horizontal
+componentes (L2 trace).
+The S-AIC-V works like the S-AIC but it picks S phases on the vertical component.
+
+The method which was applied to make the pick can be read
+
+* In the method column of the arrival table in the Location tab of :cite:t:`scolv`,
+* In the picker window from the letter within brackets following a phase type,
+* In the picker window from the hint which appears when hovering over a
+  pick.
+
+.. _scanloc-fig-picker-method:
+
+.. figure:: ./media/scolv-picker-method.png
+   :align: center
+   :width: 10cm
+
+   Read the method applied to make a pick in the arrival table of scolv or in
+   the picker window.
+
+The performance of the pickers have been tested by comparison of automatic
+with manual picks (see the :ref:`Figure showing the comparison<scanloc-fig-picker-comparison>`).
+
+.. _scanloc-fig-picker-comparison:
+
+.. figure:: ../apps/media/hist_comp_vgt.png
+   :align: center
+   :width: 10cm
+
+   Performance comparison showing the differences in pick time from manual picks
+   and the optimally tuned pickers S-L2, S-AIC and S-AIC-V for local earthquakes
+   in West-Bohemia/Vogtland. The area is typical of local earthquake monitored at
+   short epicentral distances of a few tens of kilometers. The distribution of
+   the differences in the automatic pick times with respect to the manual ones
+   shows the increased performance using the S-AIC.
+
+
+Picker configuration
+--------------------
+
+1. **Global module parameters:** Add the plugin *saic* to the configuration of
+   :program:`scautopick` or the global
+   module configuration for making use of the S-AIC or the S-AIC-V:
+
+   .. code-block:: sh
+
+      plugins = ${plugins},saic
+
+#. **Module parameters:** Activate one of the S-phase ickers (S-L2, S-AIC, S-AIC-V)
+   by changing the name of the S picker in the module
+   configuration of :program:`scautopick`. Deactivating *killPendingSPickers* will allow
+   to pick S phases even if more P phases were detected before:
+
+   .. code-block:: sh
+
+      spicker = "S-AIC"
+      killPendingSPickers = false
+
+#. **Bindings parameters:** Configure the S-picker parameters under *spicker* in
+   global section of the bindings of :program:`scautopick` e.g. for
+   *S-AIC* in local earthquake monitoring. For tuning the values based on actual
+   data you may use the :ref:`graphical debugger <scanloc-spick-debugger>`:
+
+   .. code-block:: sh
+
+      detecFilter = "RMHP(10)>>ITAPER(30)>>BW(4,4,20)>>STALTA(0.2,20)"
+      timeCorr = 0
+
+      spicker.AIC.noiseBegin = -10
+      spicker.AIC.signalBegin = 0.5
+      spicker.AIC.filter = "ITAPER(4)>>BW_HP(4,3)"
+      spicker.AIC.detecFilter = ""
+      spicker.AIC.step = 0.5
+      spicker.AIC.minSNR = 5
+      spicker.AIC.minCnt = 5
+
+   The AIC parameters *spicker.AIC.* are used for *S-AIC* and for *S-AIC-V*.
+   The parameters of the S-phase pickers can be configured in the global section of the
+   bindings profile of :program:`scautopick`. The meaning of some parameters are shared
+   between the S-phase pickers:
+
+   .. _scanloc-table-parameter:
+
+   .. csv-table::
+      :header: "Parameter", "Picker type", "Description"
+      :widths: 15,25,60
+
+      ":confval:`noiseBegin`","S-AIC, S-AIC-V, S-L2","Data window added before the p pick on order to compensate
+      for effects due to the data processing, filtering and to compute the SNR."
+      ":confval:`signalBegin`","S-AIC, S-AIC-V, S-L2","Start of the data processing relative to the reference P pick."
+      ":confval:`signalEnd`","S-AIC, S-AIC-V, S-L2","End of the data processing relative to the reference P pick."
+      ":confval:`filter`","S-AIC, S-L2","Filter applied before forming the L2 trace."
+      ":confval:`detectFilter`","S-AIC, S-AIC-V, S-L2","Filter applied on the L2 trace before AIC analysis."
+      ":confval:`step`","S-AIC, S-AIC-V","Step size in which the time windows are enlarged."
+      ":confval:`minSNR`","S-AIC, S-AIC-V, S-L2","Minimum SNR in order to accept a pick."
+      ":confval:`minCnt`","S-AIC, S-AIC-V","Minimum number the AIC minimum must be found for subsequent time windows."
+      ":confval:`uncertainty`","S-AIC, S-AIC-V","Pick uncertainty. Unused by the picker but part of the output pick element."
+
+
+.. _scanloc-spick-debugger:
+
+Picker tuning: Debugger
+-----------------------
+
+The :ref:`debugger GUI<scanloc-fig-debugger>` allows the graphics-assisted tuning
+of the S pickers, S-L2, S-AIC, S-AIC-V. In order to make use of the S picker
+debugging GUI:
+
+#. **Global module parameters:** Add the plugin *spickdbg* to the global
+   configuration of :cite:t:`scolv` (:file:`scolv.cfg`)
+
+   .. code-block:: params
+
+      plugins = ${plugins}, spickdbg
+
+#. **Global bindings:** Configure the initial parameters in the global bindings
+   of the considered stream. You may adopt parameters from the ones used by the
+   *spicker* for a good inital guess.
+
+The debugger GUI can be started from the picker window of :program:`scolv`.
+If there is an existing P pick, the debugger window can be opened with a
+right click on the P pick. In the dropdown menu the S picker type can be chosen.
+
+.. _scanloc-fig-picker-debugger-menu:
+
+.. figure:: ./media/scolv-picker-debugger-open.png
+   :align: center
+   :width: 10cm
+
+   Selection of S-picker debugger by right-clicking on a P phase.
+
+A new pop-up window opens where the P pick (red line) and the newly determined S
+pick (light blue line) are shown and the parameters can be tested.
+
+.. _scanloc-fig-debugger:
+
+.. figure:: ./media/s-picker-debugger.png
+   :align: center
+   :width: 10cm
+
+   S-picker debugger example showing the filtered horizontal traces, the
+   computed L2 trace and the resulting S pick (light blue line).
+
+The :ref:`example above <scanloc-fig-debugger>` shows the debugger GUI for a local
+earthquake:
+
+* **Top traces:** original filtered data.
+* **Bottom trace:** Resulting trace e.g. L2.
+* **First red line:** the time of the referenced pick. A pick pick should be selected.
+* **Additional phase picks** are shown on top of the data.
+* **Light blue line:** the S pick which would be made based on the selected
+  parameters. The number next to 'AIC' indicates the SNR.
+* **Lower section:** Parameters which can be adjusted.
+
+The initial parameters are read from the global binding configuration from the
+selected stream. Change the parameters to find the optimum
+values. Click on the *Update* button to apply them in the GUI.
+In order to make use of the tested parameters their values must be configured in
+the bindings parameter of :program:`scautopick` or the respective alias.
+
+.. _scanloc-debugger-parameters:
+
+.. csv-table::
+   :header: "Parameter", "Description"
+   :widths: 15,85
+
+   "N","Start of the noise window"
+   "S0","Start of the AIC window"
+   "S1","End of the AIC window"
+   "AIC0","Start of the data processing relative to the reference P pick."
+   "AIC","S pick based on the current parameters with number indicating the SNR."
+   "AIC1","End of the data processing when meeting MinSNR and MinCnt."
+   "Pick","Pick time at AIC."