393 lines
10 KiB
ReStructuredText
393 lines
10 KiB
ReStructuredText
.. _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.
|