• Antelope Release 5.5 Mac OS X 10.8.5 2015-04-21

 

NAME

extract_events - event extraction program (trexcerpt alternative)

SYNOPSIS

extract_events dbin dbout [-e eventdb -s eventsubset -v -V -pf pfname]

SUPPORT


Contributed code: NO BRTT support.
THIS PIECE OF SOFTWARE WAS CONTRIBUTED BY THE ANTELOPE USER COMMUNITY. BRTT DISCLAIMS ALL OWNERSHIP, LIABILITY, AND SUPPORT FOR THIS PIECE OF SOFTWARE.

FOR HELP WITH THIS PIECE OF SOFTWARE, PLEASE CONTACT THE CONTRIBUTING AUTHOR.

DESCRIPTION

This program should be viewed as an alternative to trexcerpt. One should recognize that it's primary purpose is to prepare raw data to a format that can be more efficiently handled by downstream processing. Thus it can be used to resample all data to a common sample rate and build three-component bundle files that can be used to eliminate baggage needed to handle these issues on raw data. This is in contrast to trexcerpt which seems to have the design goal of being a generic waveform extraction tool. This program is thus more limited in some ways and more complex in others (e.g. resampling).

The program always reads from the input database, dbin, and writes to dbout. The program will exit immediately if you try to use the same database for dbin and dbout. Most options of the program are controlled by the parameter file which are described below. This program centers on the concept of a phase arrival time. That time can be either theoretical (the default) or measured data in an arrival table. The former is most useful for teleseismic data with no prior information. The later is useful when someone else already did the work of picking the data for you and you just want the good stuff. A type example at this writing is phase picks made the ANF for USArray. You can use this program to extract ONLY data with P wave picks in the ANF database. In either case, the program will blindly write overlapping waveforms because the primary waveform indexing for subsequent processing assumed to NOT be the standard wfdisc table but the more generic wfprocess table. The css3.0 as implemented by BRTT depends on the concept of a time range as the key for rows in wfdisc. This creates real havoc in event processing because extracting overlapping waveforms in this fashion is very very common. To avoid this problem this program produces two parallel waveform indexing tables: wfdisc and wfprocess. The wfdisc table is necessary to make it easy to view waveforms with programs like dbpick, but should be viewed here as baggage. The primary waveform index is wfprocess in combination with two tables called sclink and evlink. These link wfprocess to css3.0's sta:chan and evid keys respectively.

Note that there are multiple options for the format of the wfprocess table output. For many applications the most important distinction with wfdisc is that a datatype of "3c" or "c3" are supported for three component bundle data (3c and c3 are used to set byte order). A type example of how this can be useful is to prep data for processing with programs like dbxcor. Using the 3c formats removes the rather elaborate overhead required in css3.0 to associate channels into a three-component bundle. This can dramatically reduce time to read in a block of new data depending on the size of your array and the complexity of the channel mapping (e.g. some GSN station have 9 or more channels that need to be sorted through).

OPTIONS

PARAMETER FILE

First, it is important to recognize key switches that can dramatically change what you get from this program:

Finally, a few ancillary parameters. netname is used as a name to tag the station geometry read internally. It should not normally need to be changed by the user. method and model specify a travel time method and model used with the ttcalc(3) interface to compute theoretical travel times. This is ignored if the data are being accessed by actual arrivals, but are important for defining time segments otherwise. filter can be used to specify a string that defines a filter using the BRTT filter library. If this is NONE no filtering is done. Otherwise the data window (with the tpad applied) is prefiltered with this filter before being cut to the final length. The default is DEMEAN. Finally, the parameter StationChannelMap defines a complicated Arr used to resolve ambiguities in what channel to use for stations with multiple channel or loc codes. For more details see man dbxcor(1) which explains this in detail.

The user should never ever mess with the following parameter: station_mdlist, Ensemble_mdlist, and output_mdlist. These are used by internal generic methods to control what is read and written to the database and should not be adjusted by the user.

SEE ALSO

dbresample(1) and dbxcor(1) have blocks of parameters in common with this program

BUGS AND CAVEATS

I consider the save_files_only option an abomination so it may be removed from future releases of this program.

AUTHOR

Gary L. Pavlis
Dept. of Geological Sciences
1001 East 10th Street
Bloomington, IN 47405
pavlis@indiana.edu

Antelope User Group Contributed Software
Printer icon