NAME
trdefaults.pf - default initialization values for the trace library
DESCRIPTION
The trace library specializes in the manipulation of trace data,
especially reading and writing data between databases on disk
and an internal database specially designed for trace manipulation.
A few of the default values may occasionally need to be overridden
for some special purpose. The trdefaults parameter file provides a
central location to perform such modifications. It also figures in the
procedure for adding a new waveform type.
-
waveform_types
This table lists waveform types which are recognized by the library.
As delivered, all of the types have routines for reading the waveform
type, and most have corresponding routines for writing. However, it's
possible to add new types, or perhaps add the capability of writing some
type which is not currently supported. Refer to addwf(5) for more information.
-
tick_tolerance
When splicing together waveform segments, several tests are performed to ensure
that the segments are truly contiguous. The common tolerance in these tests is
the fraction of a sample period by which adjacent samples can vary from the computed
value and still be considered contiguous. The default is 1/2 sample.
-
samprate_tolerance
A second test is sample rate, which is much more strict: the default tolerance
is "ABS(1-s1/s2) < .0001".
-
wfdisc_roundoff
This number indicates the time accuracy of the wfdisc time field, 1/2 of the minimum
significant figure: 5 msec.
-
msd_tolerance
The time tags inside miniseed may be slighltly less accurate than the time tags
saved in the wfdisc file, because these internal times may have been projected using
a sample rate which varies from the wfdisc samprate. This parameter allows setting the
tolerance somewhat higher when checking miniseed internal times, as they're read by
programs like dbpick(1).
-
verbose_splicing
If splicing fails mysteriously, one can optionally print some potentially
interesting numbers by repeating the operation with the verbose_splicing
parameter set to yes.
-
max_open_files
Some of the routines underlying trsave_wf might potentially open very many files,
causing the process to run out of file descriptors. Setting a limit prevents
this. Typically the limit is calculated dynamically using getrlimit(2), but an
explicit number may be put in here instead.
-
default_datatype
trsave_wf(3) (and most Antelope programs) save data in this
default format (sd) if no other format is specified.
-
default_waveform_pattern
default naming pattern for waveforms (see trwfname(3))
-
multiply_calib_in_sac_output
SAC format does not include a calib value (at least one that is normally used.)
This leaves open the question of how to deal with calib when creating sac output format.
One approach is to always save the raw data into the sac output, ignoring calib.
Another approach is to multiply the waveforms by calib, presumably converting
the output to velocity units (or acceleration or displacement, depending on segtype).
This behavior may be specified using the flag multiply_calib_in_sac_output from
trdefaults.pf.
Foreign Keys
When importing and exporting data, some data may use keys other
than station and channel codes
to uniquely identify a datastream. SEED uses net and loc codes to
disambiguate these situations; autodrm uses net and aux codes.
The css 3.0 and 3.1 schemas use only sta and chan to uniquely identify a data stream,
and does not include net and loc codes.
This leads to multiple different data streams with the same sta and chan codes,
as for example with station PFO.
Antelope addresses this problem by providing a mechanism for
folding the network code into the station key, and the loc/aux code
into the channel key, when required. This is handled by the routines
map_autodrm_netsta(3), map_seed_chanloc(3), map_autodrm_chanaux(3),
map_seed_netsta(3), autodrm_net(3), seed_net(3), autodrm_aux(3),
and seed_loc(3).
These routines first consult the foreign keys tables: snetsta and schanloc
or anetsta and achanaux,
which provide
explicit mappings between foreign and local keys.
When no
mapping exists in the tables, the routines construct a mapping using defaults from
trdefaults.pf.
These default mappings are specified in the Tbl
lists seed_net_sta, seed_sta_chan_loc, autodrm_net_sta, and autodrm_sta_chan_aux.
Each entry in the list consists of a regular expression followed by the appropriate remapping. (See morphtbl(3)
for more examples).
For each list, a
name is formed by joining the appropriate keys (i.e., net and foreign station code fsta) with underscores
(i.e., net_fsta). Then
the list is inspected for a matching regular expression.
If a match is found, the corresponding remapping is
used to obtain the local key (either sta or chan).
For the mapping from seed snet and fsta to local css3.0 sta, the resulting code
may be too long for the css3.0 sta field: the sta field is only 6 characters, while seed snet
is 2 characters. If an underscore separates fsta and snet, that leaves only 3 characters for the
sta code, whereas SEED allows 5 and many sta codes are longer than 3. In this situation,
map_seed_netsta resorts to a hard coded strategy, trying one of
-
sta_snet
sta and snet codes separated by an underscore
-
stanet
sta and snet codes are concatenated
-
stan
sta and the first character of the snet code are concatenated
When a potential code of the right length is found, it is tested for uniqueness
in the snetsta table. When no code can be constructed or the constructed code
is not unique, then the strategy is to construct a code of the right length
and try sequential characters from the string "0123456789!@#$%^&*();:'<>,.?/{}[]=\|`~-_=+"
as the last character of the prospective
code, until a unique candidate is found.
When a suitable match is found, an appropriate entry is added to the snetsta table,
provided the table is writable.
A similar strategy is followed for autodrm anet and the anetsta table,
and also for schanloc and achanloc, though it should never be necessary for
chan codes or in css3.1, since the fields are sufficiently long to accommodate
simple concatenation strategies.
-
Reverse mapping
When mapping from
local keys into foreign keys, the foreign keys tables are first consulted.
If no match is found, then the values of
default_autodrm_network, default_aux_code, default_seed_network, and default_loc_code
from trdefaults.pf are used.
Unlike the the foreign to local mapping,
entries are not automatically added to foreign keys tables by
the inverse (local to foreign) mapping.
You can interactively query the foreign keys tables (or add to them)
with the program trmapnames(1).
-
foreignkeys_database (deprecated)
this specifies a default database to use for transformations between external
(SEED and autoDRM) net/sta, chan/loc and local sta, chan. The database
is relative to ANTELOPE; the default is in $ANTELOPE/data/site/foreignkeys. However,
programs should use tables in the local databases where they are working,
not this global database.
-
seed_net_sta
-
seed_sta_chan_loc
-
autodrm_net_sta
-
autodrm_sta_chan_aux
When mapping from foreign keys into local keys, the
lists seed_net_sta, seed_sta_chan_loc, autodrm_net_sta, and autodrm_sta_chan_aux
provide default mappings using regular expressions. Each entry in the list consists of
a regular expression followed by the appropriate remapping. (See morphtbl(3)
for more examples).
-
default_autodrm_network
-
default_aux_code
-
default_seed_network
-
default_loc_code
When mapping from local keys into foreign keys,
the default parameters above are used only when
lookup in the foreignkeys database fails.
autodrm
-
reference_coordinates
autodrm(1) requires filling in a "reference_coordinates" field in
various parts of its output. This parameter is not present in any CSS
table, nor is it commonly maintained anywhere else. A default value
is kept here, where it is used to fill in the waveform headers used by
autodrm. The default is WGS-84.
Miniseed generation
-
miniseed_record_size
The default record size of 4096 for steim compressed data may be
overridden with this parameter. The value must be a power of 2,
and at least 128.
-
miniseed_dataformat
The default dataformat is 11, corresponding to steim compression level 2.
Steim compression level 1 may be forced by setting this parameter to 10.
-
miniseed_has_b100
By default, the software inserts a blockette 100, providing sample rate
at a higher resolution (and in a more convenient format) than the
standard miniseed header. However, this blockette uses one more 64 byte
frame of a miniseed record. Set this value to no to suppress
the generation of blockette 100's.
-
miniseed_has_b1001
The 1001 blockette allows specifying microsecond precision in the time
tags for a miniseed block, as well as a "timing quality" and a frame count.
If miniseed_has_b1001 is set to yes, then Antelope provides a 1001 blockette
with time specified to the microsecond (typically exceeding the accuracy
of the timing measurement). The "timing quality" is filled in with a
default number specified in trdefaults.pf: miniseed_timing_quality.
-
miniseed_timing_quality
This is the default value filled in for the "timing quality". The default value
49 is not one that the Quanterra baler will ever produce.
-
miniseed_quality_codes
The seventh character in data headers is a "Quality" code. Periodically,
the acceptable characters in this position change; current 'D', 'M', 'Q' and 'R'
are ok; others are errors. You can add new acceptable characters by changing
this parameter.
-
ignore_miniseed_errors
Antelope is insistent that miniseed be properly written. However, some
miniseed incorporates errors, but may nonetheless be readable. This
will turn off the error detection. This should only be done with caution
and for a particular dataset, not as a routine practice. Instead, the
source of the bad miniseed should be determined and corrected.
-
miniseed_ignore_chanid
When msd2wf is used to scan miniseed files and create wfdisc records, it attempts to
fillin chanid by looking up the station and channel in sensor and sitechan. This
can be wasted effort if there is no sensor or sitechan table, and can be suppressed
to streamline the process somewhat.
-
ignore_seed_code_errors
SEED specifies that channel names are three characters, net and loc codes are 2 characters,
and sta codes are 5 characters maximum. CSS 3.0 allows longer codes, but orb2db and other
programs presume that all codes in packets follow the SEED standard. When this presumption
fails, library routines which translate between SEED and CSS 3.0 codes complain. Setting
this parameter to yes suppresses these complaints. Set it at your peril if you
know what you're doing, as it may cause problems in the generated miniseed or when
creating SEED volumes.
-
miniseed_segment_seconds
When generating wfdisc records for large miniseed volumes, one can cause the
wfdisc records to occur at approximate day or hour boundaries by
setting this parameter appropriately. The default value of 86400 selects
day boundaries; zero would eliminate boundaries. The boundaries always
fall on miniseed record boundaries, so the boundaries will seldom be exactly
as requested, but only as close as possible. The first miniseed record following
a boundary should get a wfdisc record.
-
trGuess_b1000_datatype
When miniseed lacks the 1000 blockette -- this is usually found in miniseed from before
around 2000 -- some basic information necessary for decoding the data is missing.
The record size can (usually) be inferred from peeking forward in the file, and
sparc order is just assumed, but the datatype can't be easily figured out.
In a full SEED volume, the datatype, record size, and byte order are specified in
030, 050 and 052 blockettes, but they all are fairly stable and depend primarily on
the network. This table provides a way for the user to specify the miniseed dataformat
for a particular net, sta, chan and loc code. Each entry is a regular expressions which should match
the net_sta_chan_loc, followed by a number corresponding to
the allowed datatypes in the 1000 blockette. Antelope understands the following datatypes.
code |
description |
1 |
16 bit integers |
2 |
24 bit integers |
3 |
32 bit integers |
4 |
IEEE 32 bit floats |
10 |
Steim 1 compressed |
11 |
Steim 2 compressed |
16 |
CDSN 16 bit gain ranged |
33 |
RTSN 16 bit gain ranged |
30 |
SRO format |
In practice, most networks used Steim 1 compression, so that is the default guess.
-
maximum_plausible_data_value
After guessing a datatype, the waveform reading routines perform some plausibility
tests on decoded data; a complaint is made if the data is outside the range
from maximum_plausible_data_value to -maximum_plausible_data_value + 1. (The
data is still returned, however).
-
wfdisc_units
Assignment of a segtype and units for a particular type of data. Originally,
the segytpe attribute indiciated if a waveform were o(original), v(virtual),
s(segmented) or d(duplicate). However, in Antelope datasets, it indicates
the natural units of the detector -- A (acceleration), V (velocity), D (displacement), I (infrasound), or H (hydroacoustic), and more recently a host of other non-seismic measurements. Changes made here should
be propagated to the css3.0 schema definition of segtype as well.
LIBRARY
$(TRLIBS)
SEE ALSO
trsave_wf(3)
trsplice(3)
orb2db(1)
autodrm_net(3)
BUGS AND CAVEATS
PFPATH can be used to override the default location of this file.
AUTHOR
Daniel Quinlan