• Antelope Release 5.2-64 Linux Red Hat Enterprise Workstation release 6.2 (Santiago) 2.6.32 2012-04-24

 

NAME

trintro - introduction to trace manipulation routines

DESCRIPTION

Trace data is the primary seismic information; associated with it is a lot of parametric information, which is most conveniently and usefully kept in a relational database. The db routines provide methods for using and manipulating the parameter information. However, there are a wide range of operations on trace data which need to be available. The goal of the trace library is to conveniently support all these kinds of operations.

Following are some classes of operations of interest:

It is convenient to keep all the parameter information in a database even as the trace data is transformed. This allows all the db routines to be used against transformed data, without developing brand new routines.

However, some parameters change during the various filtering/transformation operations. For example, a rotation changes vang and hang; an fft transforms the time and signal axes to frequency and amplitude. This information should not be put back into the original database; instead, it is kept in new, transient, processing tables.

Some filters or their results have specialized parameters which ought to be kept in the parameter information; these parameters may not be in the original database, however.

Always copying all the data for each trace might be expensive; also it would be good to be able to find the original data.

It's not at all clear how to save the modified data, either.

A SOLUTION

The trace library tries to achieve these objectives at a reasonable cost. Basically, the idea is to provide a separate processing schema (Trace4.1) with special transient tables for holding the parameter data during trace processing. Parameters which change during processing (like vang and hang) may be changed as needed in the transient tr tables. When a new parameter is needed for a particular filter or process, it can be easily added to the tr schema (without breaking the currently existing binary applications), and/or new tables can be easily added. Alternatively, different schemas might be developed; provided the trace table maintained a base set of fields, the standard filters would all work.

If the results are to be saved, they should ultimately be copied to a separate database, which might well be a standard CSS database.

All operations on trace data should then be viewed (and written) as filters on the tr tables.

The Trace4.1 schema can be viewed with dbhelp.

The central table "trace" in the tr schema has fields related to memory management, as well as fields from the wfdisc, site, sitechan, and instrument tables.

Records in the trace table initially typically correspond to single records in the original wfdisc table. However, many kinds of processing require data for time ranges which overlap multiple wfdisc records. (Filters exist to clip out and paste together segments from multiple wfdisc records.) Other filters may intermix signals from several instruments -- either different components for a rotation, or multiple locations with time delays to form a beam, or ???. In all these cases, the relationship between the original wfdisc records and the ultimate waveform data becomes much more difficult to understand and represent.

In order to perform various kinds of processing, the individual waveforms must be grouped according to various criteria. For instance, data from the same station/channel may need to be organized by time, the three channels corresponding to different components may need to be grouped together, and the stations which make up an array may need to be grouped together. This function is provided by a hierarchy of database tables. At the lowest level is the (sorted) trace table. At the next higher level, there might be a table which only had unique station/channel pairs -- each row in this table would refer to a range of rows in the original trace table corresponding to that station/channel. Above this might be a table that grouped 3-component instruments -- each row in this table would correspond to all three components of a single instrument. And so on. There may be other interesting ways of grouping the data also.

As a simple method of keeping track of the processing steps, a history table is provided. Each processing step might add a line to the history table, and it might then be possible to reproduce the processing, following the recipe in the history table.

PROGRAMMING INTERFACE

Trace processing should be regarded as the application of a series of filters to the data. Following are some goals for filters:

Each filter typically takes as input a trace object -- that is a database pointer to a table in a (usually transient) tr database, as well as parameters directly related to the filter.

Filter parameters should have an ascii representation. (This makes it convenient to provide a tcl/tk interface, as well as to ultimately document a processing sequence.) The ascii representation may be short -- e.g., a few parameters suffice to specify a band pass filter. However, the parameters may be quite large -- for instance, a convolution filter. In this case, they may appear in a separate file. If the separate file is ASCII, then it should be a "parameter" file -- see pf(3).

A filter should return zero for success, -1 for failure. Error messages should be recorded with register_error(3).

The input trace object, tr, may refer directly to a trace table; more commonly, it refers to some table higher in the hierarchy. The filter routine must figure out (using the bundletype field) what level in the hierarchy it is at, and work down to the level it needs.

A filter should recognize two types of input database pointers : a full table, and a range of a table. The former is indicated by db.record == dbALL. In the latter case, db.record is the first record to be processed, db.field is the record number one greater than the last record to be processed. As a special case, db.field may be dbALL, in which case only one record is to be processed. (Note that this is one record at whatever level in the hierarchy dbin is at; this may represent many records in the trace table.) See dbget_range(3).

Depending on the filter, the routine may simply modify the input table(s) (and/or data), or it may create new tables. If it creates new tables, it must ensure that the trace object stays consistent.

If the filter modifies the data, it may copy the data to a new buffer during modification, or modify the data in place. It is the calling routine's responsibility to save the original data in case it is ever needed. Each row in the trace table corresponds to one memory buffer which has been allocated with malloc. If the field data is non-zero, the routine trfree frees the data buffer as well as (possibly) freeing the memory used to represent the table itself.

A filter should try very hard not to fail, and at worst do nothing (return its input unchanged). Detailed error messages should be left on the error log.

TYPES OF FILTERS

UNSPECIFIED

There are a few things which might be specified about each filter:

If all these things were present for each filter, as an extern string or integer following some naming convention, then it might be easier to write an interactive tool which would apply filters or sets of filters interactively against an input database. A command line tool would also be useful.

If the tr library were dynamic, then this (speculative) tool and other tools would not need to be relinked after the trace library were updated. (This would be useful for the db library now).

A processing history ought to be kept for each trace.

OPTIONS

While the trace library, and the schema are oriented towards the CSS database schema, there is no underlying reason why there could not be routines to read sac, ah, or other formats into the trace schema, and then use all the exact same code to manipulate and display the trace data. To accomplish this, it would be necessary to create trload_sac, trload_ah, and so on.

LIBRARY

$(TRLIBS)

SEE ALSO

dbintro(3)

BUGS AND CAVEATS

The trace library is far from complete. Filtering may be done in a separate library.

AUTHOR

Daniel Quinlan
Printer icon