dbbuild tables - description of sensor and data logger parameter files for dbbuild
dbbuild(1) uses parameter file descriptions of data loggers
and sensors to help interactively build a database from
scratch. The user must provide installation information
like station (and perhaps channel) names, station location,
sensor orientation, and sensor and data logger serial numbers.
The user must also choose the data logger and sensor models from the
list supported by dbbuild. When a particular model is not already
supported, the user must first construct files which
describe the data logger and/or sensor, and install these files
in the proper directories.
Because the names of these files are saved into the calibration database
table, the parameter file names must be less than 32 characters (not
counting the .pf suffix).
This document describes the format of the data logger and sensor
parameter files.
Sensor description files must provide the following information:
-
description
description (up to 50 characters)
-
dfile
(short) suggestion for response file name
-
info
more info for a popup balloon about this sensor
-
rsptype
response type (eg, A, V or D)
-
orientations
a list of orientation names (Z,N,E) with corresponding hang, vang values
-
band
eg, b for broadband
-
gtype
description, such as sensor, seismometer
-
sensitivity
nominal calibration constant in ounits/iunits
-
iunits
input units (in waveforms * calib) of fundamental quantity being measured,
eg nm/s for a velocity instrument using CSS3.0 conventions
-
ounits
output units for this instrument, often V (volts)
-
orientations
This is a list of the channels for this sensor,
each line contains three fields: a distinctive name (usually Z, N, and E for
a 3-component instrument), and the corresponding values of hang and vang
(see the sitechan table for more information about these).
-
response
sensor response (usually, poles and zeros), in a single stage -- ie,
there may not be multiple sets of poles and zeros, only one set.
-
sensor_type_code
The second letter (designating sensor type) in a 3-character SEED channel code.
-
short_period_sensor
May be yes or no; indicates whether the corner period is less than or
more than 10 seconds, following the SEED channel naming guidelines in
Appendix A of the SEED reference manual for the BAND code (first character in
SEED channel code). Together with the sample
rate, this determines the first character of the SEED channel name for
sample rates about 10 hertz.
Data logger description files provide the following information:
-
dfile
(short) suggestion for response file name
-
description
longer description
-
info
more info for a popup balloon about this data logger
-
streams
a single line consisting of the various possible output data streams.
This is typically just a list of output sample rates, but some
data loggers may get the same output sample rate but using different
stacks of filters. Each such distinct stack (that may be used) should be named in this list.
-
soh
a single line list of the various (1d) state of health streams generated by this
data logger; state of health channels are added for each element of this list
Each state of health channel then has its own array which is named
after and describes the channel, with the following elements:
stages |
list of stages for the channel (no samprate) |
sensitivity |
gnom for this sensor |
gains |
a/d gain(s) for this datalogger |
iunits |
natural units for this sensor |
samprate |
input sample rate for this sensor |
-
possible_streams
For certain data loggers, choosing one stream rules out other possible streams,
so that only certain subsets of the streams defined are allowed. The optional
possible_streams entry is a perl subroutine which given a list of currently elected
streams returns a list of allowable streams. dbbuild eliminates from this
returned list any already chosen streams.
-
stream definitions
Each stream mentioned in the streams line has a defining line in the parameter file.
For example, if 100sps is a stream, then there is an entry in the parameter file
which has the key 100sps. The corresponding value is a list of names of filter stages
which make up that stream.
-
specify_filters
For some data loggers, the filter stack for any particular sample rate
can depends on the other selected sample rates. Ie, the filter stack
for a particular sample rate can only be determined when all the sample
rates are known.
This perl function from the parameter file takes as input the list of selected
sample rates, and returns a flag and an array reference. The flag is zero
if there is no difficulty, 1 if it's not possible to accommodate all the
selected sample rates.
The array is indexed by sample rate, and the values are a blank separated
list of corresponding filters which make up the stack for that sample rate.
-
stage definitions
Like the streams, each filter stage has a definition in the parameter file, which
defines the stage.
The contents of a filter stage array are:
-
gtype
description, such as FIR_decimator
-
sensitivity
nominal sensitivity (in ounits/iunits) for sensor
-
gains
nominal gain (in counts/iunits) for a datalogger
-
iunits
input units,
eg V (volts) for an a/d converter
-
ounits
output units for this stage,
eg counts for an a/d converter
-
response
A single response stage, eg, a fir filter.
-
decifac
Only for a fir filter, this is the decimation factor for the stage
-
izero
Index within fir coefficients corresponding to the 0th
sample. This is needed for asymmetric FIR filters, or
filters that are causal.
-
leadfac
If you put it in, it is put into the database, but ask Frank what it is.
There is a special stage named a/d for the analog to digital converter.
-
samprate
Normally, the input sample rate for the a/d stage is specified in the a/d
stage. However, in some circumstances, the sample rate may instead be
specified in the first digital stage, eg for composite stages
for the Q330, or for the initial fir filter in RefTek data loggers which
may be configured to have various a/d sample rates.
-
sn
The serial number for the associated equipment.
This may be specified as "datalogger".
Some equipment comes with more precise gain information for
each instrument. These gains may be used to replace
the nominal gains in the instrument parameter files by creating
separate parameter file named:
$ANTELOPE/data/instruments/sn/<dfile>/<serial-number>.pf
The dfile portion of the filename comes from a parameter in the default
instrument parameter file; the serial number is the manufacturer's serial
number for the equipment.
For sensors, this additional parameter file contains one array named
sensitivity which has the sensitivity for each sensor output, indexed by the
default axis labels in the standard sensor parameter file.
For 3-component sensors, this is typically "Z", "N", and "E", so the
serial number specific parameter file might be named
$ANTELOPE/data/instruments/sn/sts2/sn.pf, and might
look something like this:
sensitivity &Arr{
E 17e-7
N 16e-7
Z 15e-7
}
For dataloggers, the additional parameter file is similar, containing an array
named gains which has the gain for each datalogger input,
indexed by the names of the leads. You must set up the scheme
for identifying the leads. If the leads were named
ch1,
ch2 and
ch3, then the serial number specific datalogger file might be named
$ANTELOPE/data/instruments/sn/q730/sn.pf, and might
look like:
gains &Arr{
ch1 500
ch2 600
ch3 700
}
This is an example of a sensor parameter file. The
response file is contained in the file $ANTELOPE/data/responses/example.
category Imaginary Sensors
configuration Neverland Standard
description a non-existent sensor
dfile imaginary
rsptype V # velocity instrument
band b # broad band
gtype sensor
sensitivity 15e-7 # equivalent to 1500 V/m/sec sensor
iunits nm/s
ounits V
orientations &Tbl{
Z 0 0
N 0 90
E 90 90
}
response &datafile(responses/sts2)
Here's an example of a data logger parameter file which contains
a possible_streams subroutine.
category Imaginary Dataloggers
configuration Neverland Standard
description some non-existent data logger
dfile imaginary
streams 200sps 100sps 40sps 20sps 10sps 5sps 1sps
# definitions of streams
200sps 200 cf1 cf2 cf2 cf2 cf2 cf2 cf3
100sps 100 cf1 cf2 cf2 cf2 cf2 cf2 cf3 RT72A_2_f
40sps 40 cf1 cf2 cf2 cf2 cf2 cf2 cf3 RT72A_5_f
20sps 20 cf1 cf2 cf2 cf2 cf2 cf2 cf3 RT72A_5_f RT72A_2_f
10sps 10 cf1 cf2 cf2 cf2 cf2 cf2 cf3 RT72A_5_f RT72A_2_f RT72A_2_f
5sps 5 cf1 cf2 cf2 cf2 cf2 cf2 cf3 RT72A_5_f RT72A_2_f RT72A_2_f RT72A_2_f
1sps 1 cf1 cf2 cf2 cf2 cf2 cf2 cf3 RT72A_5_f RT72A_2_f RT72A_2_f RT72A_2_f RT72A_5_f
possible_streams &Literal{
my @chosen = @_ ;
my @ok = () ;
my %chosen ;
foreach (@chosen) {
$chosen{$_} = 1 ;
}
if ( defined $chosen{"200sps"}
|| defined $chosen{"40sps"}
|| defined $chosen{"20sps"} ) {
@ok = qw(200sps 40sps 20sps) ;
} elsif ( defined $chosen{"100sps"}
|| defined $chosen{"10sps"}
|| defined $chosen{"5sps"}
|| defined $chosen{"1sps"} ) {
@ok = qw(100sps 10sps 5sps 1sps) ;
} else {
@ok = qw(200sps 100sps 40sps 20sps 10sps 5sps 1sps) ;
}
return (@ok) ;
}
gains 526315 # in units of counts/volt
# Stages
a/d &Arr{
samprate 102400
gtype digitizer
iunits V
ounits counts
}
cf1 &Arr{
gtype FIR_decimator
decifac 8
response &datafile(responses/cf1)
}
cf2 &Arr{
gtype FIR_decimator
decifac 2
response &datafile(responses/cf2)
}
cf3 &Arr{
gtype FIR_decimator
decifac 2
response &datafile(responses/cf3)
}
RT72A_5_f &Arr{
gtype FIR_decimator
decifac 5
response &datafile(responses/RT72A_5_f)
}
RT72A_2_f &Arr{
gtype FIR_decimator
decifac 2
response &datafile(responses/RT72A_2_f)
}
dbbuild(1)
dbbuild_batch(5)
If the manufacturer puts blanks in the serial number, this causes
odd file names for instrument specific files.
Daniel Quinlan
Table of Contents
Antelope Release 4.7 Darwin 7.9.0 2005-07-19
Boulder Real Time Technologies, Inc
For more information, contact support@brtt.com