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 Examples and Playbacks 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

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 identifcation of picks found in real time.

-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

-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 Examples and Playbacks.

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

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

--mode arg

Default: historic

Type: string

Values: historic, realTime

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

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