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