scanloc: Phase Associator 2025.296#76adc9190

# 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 (`-h`, `--debug`, etc.) apply. Read the Real-Time Applications section for example applications.

## dump_picks

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 (SCML). Control the database request to filter by

- Author (`--author`) contributing the object,

- Comparison with inventory (`--check-inventory`),

- Object evaluation mode (`--manual`, `--automatic`),

- Region of contributing station (`--region`),

- Time (`--time-window`, `--hours`, `--start`).

### Applications

- Dump picks and amplitudes in XML for further analysis or feeding into another module such as scanloc.

- Printing statistics and useful information of the retrieved pick and amplitude set with `--print`.

- Fetch waveforms for picks from SDS archive, a CAPS or FDSN server by generating stream lists from picks with time windows like with scevtstreams [20] but for picks independent of events and origins. Consider the option `--type` for choosing the type and `--margin` for the time margin.

Hint

- For retrieving events or origins with picks, amplitudes, etc. from a database use scxmldump [26].

- Multiple SCML files can be merged into one using scxmlmerge [27].

### Examples

- Print command-line help:

      dump_picks -h

- Extract all picks and amplitudes for the given time span made by author ‘l1autopick’:

      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 [1].

      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

      dump_picks -d localhost --type 1 --margin 60 | scart -dsE -l - /archive -o data.mseed

### Command-Line Options

dump_picks [options]

#### Dump

--hours arg

  Type: double

  Start search hours before now considering object time, not creation time. If set, `--time-window`, `--start`, `--end` are ignored. The hours are added to the minutes if set.

--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, `--time-window`, `--start`, `--end` are ignored.

--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, `--time-window` is ignored.

--end arg

  Type: string

  Default: `now`

  End time of search considering object time, not creation time. If set, `--time-window` is ignored.

-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 ‘~’.

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

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

-c, --check-inventory

  Dump picks only when corresponding streams are found in inventory.

-O, --origin arg

  Type: string

  Origin ID. Dump all picks associated with the origin that has the given origin ID.

-m, --manual

  Type: boolean

  Dump only manual picks.

-a, --automatic

  Type: boolean

  Dump only automatic picks.

-n, --no-amp

  Type: boolean

  Do not dump amplitudes from picks. Amplitudes are not required by scanloc.

--author arg

  Type: string

  Filter picks by author. Author information can be extracted from XML files using the playback_picks option `--print`.

--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 playback_picks along with `--print`, or inventory (scinv [21]), waveforms (scart [13]) or bindings configuration (scdumpcfg [18]).

#### Output

-o, --output arg

  Type: string

  Name of output file. If not given, all data is written to stdout.

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

-f, --formatted

  Type: boolean

  Output formatted XML. Default is unformatted. Applies only for type 0.

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

## playback_picks

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. 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 (`--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 (`--speed`): The speed factor to use.

- Start (`--jump`): Ignore the first objects within the given number of seconds.

- Timing (`--timing`): Define the sorting of the objects. Default is creationTime. Consider the comments on timing in section Real-Time Applications.

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:

      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:

      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:

      playback_picks origins.xml l1picks.xml:L1PICK:AMPLITUDE:L1LOCATION --timing creationTime

### Command-Line Options

playback_picks [options]

#### Playback

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

-j, --jump arg

  Type: double

  Unit: `minute`

  Jump in time by given value ignoring the corresponding objects.

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

--mode arg

  Default: `historic`

  Type: string

  Values: `historic, realTime`

  Playback mode. ‘realTime’ mimics current situation, ‘historic’ preserves all times.

-o, --object arg

  Type: list:string

  Default: `None`

  Values: `pick,amplitude,origin`

  Limit the playback to the given list of objects.

--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 (scart [13]) or inventory (invextr [9]), for creating global bindings or applying author filtering, e.g., in dump_picks.

--speed arg

  Default: `1`

  Type: double

  Speed of playback.

  1: true speed.

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