.. _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 identifcation of picks found in real time. .. option:: -r, --region arg Type: *string* Unit: ``deg`` Default: ``-90,-180,90,180`` Region bounding box "lat0,lon0,lat1,lon1" latitude: -90 - +90 longitude: -180 - +360 .. 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 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'. .. option:: --mode arg Default: ``historic`` Type: *string* Values: ``historic, realTime`` Playback mode. 'realTime' mimics current situation, 'historic' preserves all times. .. 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 `. .. 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.