[seiscomp, scanloc] Install, add .gitignore
This commit is contained in:
392
share/doc/scanloc/html/_sources/base/auxiliary.rst.txt
Normal file
392
share/doc/scanloc/html/_sources/base/auxiliary.rst.txt
Normal file
@ -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.
|
||||
Reference in New Issue
Block a user