• Antelope Release 5.10 Linux CentOS release 7.6.1810 (Core) 3.10.0 2020-05-12

 

NAME

trexcerpt - extract waveform segments from a database

SYNOPSIS

trexcerpt
	[-AaDdEegOpvV]
        [-c sta/chan/instrument-subset]
        [-j origin/site_subset]
        [-m {time|convert|event|arrival|explicit}]
        [-o datatype]
        [-s event-subset]
        [-w wfname]
        [-W waveform_database]
        input-db output_db [start_time {end_time|duration}]

DESCRIPTION

It's often useful to create a small database with a restricted set of waveforms, often from a continuous database. This new database may be smaller, more focused, have a special output format (e.g., sac), or be useful for export to another site. trexcerpt attempts to automate this process in a flexible but convenient fashion.

Modes

trexcerpt has five basic modes of operation, which determine how the waveform segments of interest are selected, and the interpretation of the start_time and end_time command line parameters:

Process

Conceptually, there are three views which trexcerpt reads or constructs:

The process of generating the output consists of the following steps:

OPTIONS

PARAMETER FILE

The trexcerpt parameter file is fairly complex, so it should be edited with caution. It is primarily a method of configuring the program, rather than a means to specify a single run.

Many entries specify a list of views, rather than a single view. This is an attempt to accommodate more and less complete databases. The first view which when evaluated has at least one row is used.

EXAMPLE

event mode

arrival mode

convert mode

explicit mode

RETURN VALUES

trexcerpt returns 0 for success, 2 if some errors occurred; fatal errors should return 1.

SEE ALSO

dbwfexcerpt_dep(1)

BUGS AND CAVEATS

trexcerpt requires a complete and correct input database to figure out the stations and channels to copy to the output. If the input database is missing stations or channels in the site, sitechan or sensor table, then these channels (somewhat mysteriously) do not appear in the output, even if they are present in the wfdisc.

The css3.0 schema limits the number of samples which can be represented in a single wfdisc record: the nsamp field is 8 characters wide, so the maximum number of samples is 99,999,999. At 200 samples/sec, this is close to six days. The typical size of a waveform file is 1 day. The user must not request more than the maximum number of samples in the output records. If the limit is exceeded, trexcerpt complains and does not create the requested output.

When creating the station and event sides of the output database, trexcerpt does not copy external files, specifically the response files.

When using the -j option with the -d or -e options, while the waveforms are the appropriate subset, the event and station sides of the database are likely to be larger than required, as the -j subset is not applied to the event and station views used to construct the output.

When creating miniseed files, the net and loc codes are filled in using the routines seed_net(3) and seed_loc(3). See trdefaults.pf(5) for more information about how these routines use the foreignkeys database.

When writing sac format data, trexcerpt attempts to fill in event data by looking for an arrival at the station in the waveform segment being written, and using that arrival to look up origin information (through the assoc table). Thus origin information is not saved into the waveforms when there is no picked arrival in the data, even in event mode.

Some additional information is printed when writing sac data if a file named verbose exists in the current directory, showing what arrival matches were found for particular data segments.

For a plain waveform copy, where the input parameters (time, endtime, datatype) match the output parameters, trexcerpt attempts to just use cp(1) instead of reading and uncompressing the waveform, and then recompressing and writing the waveform. This improves the speed dramatically, but prevents processing to eliminate marked gaps. Thus if -g is specified, this optimization is omitted. It could also potentially copy a much larger file than necessary, if the waveform file were referenced by multiple wfdisc records.

AUTHOR

Daniel Quinlan
Printer icon