The instrumentation database
The instrumentation database contains the instrumentations belonging to an OBS facility, as well as all of that instrumentation’s components:
channels
, composed ofinstruments
andorientations
instruments
, which are composed of adatalogger
, asensor
and possibly apreamplifier
dataloggers
,sensors
andpreamplifiers
, composed ofstages
stages
, each containing afilter
This document briefly describes these elements and their
relations. It also briefly describes how to set up configurations
. More
detailed descriptions can be found in the Tutorial sections on
header elements
Every obsinfo file should have top-level format_version
and revision
elements.
The can also have a notes
element, to write down information that will
NOT be put in the StationXML file. There may also a top-level field called
yaml_anchors
. In previous versions of obsinfo this was a convenient place to store
repeating elements, but with the current JSONRef system there is less
and less use for this.
We have kept it in case others find it useful.
In most information file examples, we have removed the format_version
and
revision
elements to save space, but they should always be there.
instrumentation_base files:
See also Building a simple instrumentation file with channels
instrumentation_base
files specify complete instrumentations (ocean bottom
seismometers or hydrophomes, water-column hydrophones, etc.).
A typical file (without configurations) looks like:
instrumentation_base:
equipment:
model: "SPOBS2"
type: "Short Period Ocean Bottom Seismometer"
description: "LCHEAPO 2000 SPOBS, 4 channels, L-28 3C geophone"
manufacturer: "Scripps Inst. Oceanography"
vendor: "Scripps Inst. Oceanography"
channels:
default:
datalogger: {base: {$ref: "dataloggers/LC2000.datalogger_base.yaml#datalogger_base"}}
preamplifier: {base: {$ref: "preamplifiers/LCHEAPO_GEOPHONE.preamplifier_base.yaml#preamplifier_base"},
configuration: "128x gain"}
sensor: {base: {$ref: "sensors/SERCEL_L28.sensor_base.yaml#sensor_base"}}
"1":
orientation : {"H": {azimuth.deg: {value: 0}, dip.deg: {value: 90}}}
^preamplifier: {base: {$ref: "preamplifiers/LCHEAPO_HYDRO.preamplifier_base.yaml#preamplifier_base"},
configuration: "16x gain"}
^sensor: {base: {$ref: "sensors/HITECH_HTI90U.sensor_base.yaml#sensor_base"}}
"2": {orientation: {"2": {azimuth.deg: {value: 90, uncertainty: 180}}}}
"3": {orientation: {"1": {azimuth.deg: {value: 0, uncertainty: 180}}}}
"4": {orientation: {"3": {dip.deg: {value: 90}}}}
Whereas a file with configurations looks like:
instrumentation_base:
equipment:
model: "BBOBS1"
type: "Broadband Ocean Bottom Seismometer"
description: "LCHEAPO 2000 BBOBS 2012-present"
manufacturer: "Scripps Inst. Oceanography - INSU"
vendor: "Scripps Inst. Oceanography - INSU"
channels:
default:
datalogger: {base: {$ref: "dataloggers/LC2000.datalogger_base.yaml#datalogger_base"}}
preamplifier: {base: {$ref: "preamplifiers/LCHEAPO_BBOBS.preamplifier_base.yaml#preamplifier_base"},
configuration: "0.225x gain"}
sensor: {base: {$ref: "sensors/NANOMETRICS_T240__theoretical.sensor_base.yaml#sensor_base"},
configuration: "SN1-399, single-sided"}
"1":
orientation: {"2": {azimuth.deg: {value: 90, uncertainty: 180}}}
"2":
orientation: {"1": {azimuth.deg: {value: 90, uncertainty: 180}}}
"3":
orientation: {"Z": {azimuth.deg: {value: 0}, dip.deg: {value: -90}}}
preamplifier: {configuration: "1x gain"}
"4":
orientation : {"H": {azimuth.deg: {value: 0}, dip.deg: {value: 90}}}
^preamplifier: {base: {$ref: "preamplifiers/LCHEAPO_DPG.preamplifier_base.yaml#preamplifier_base"}}
^sensor: {base: {$ref: "sensors/SIO_DPG.sensor_base.yaml#sensor_base"}}
extras:
DBIRD_response_type : "CALIBRATED"
configurations:
"SN01":
equipment: {serial_number: '01'}
channels:
default: {sensor: {configuration: "Sphere01"}}
"4": {sensor: {configuration: "generic"}}
"SN02":
equipment: {serial_number: '02'}
channels:
default: {sensor: {configuration: "Sphere02"}}
"4": {sensor: {configuration: "generic"}}
"SN03":
equipment: {serial_number: '03'}
channels:
default: {sensor: {configuration: "Sphere03"}}
"4": {sensor: {configuration: "generic"}}
instrumentation-level configurations are useful when each instrumentation has
specific sensors mounted on them by default.
Note that in the above example there is no configuration_default
,
meaning that this instrumentation
must always be specified with a configuration
Instrument_Component files
See also Building instrument component files with response stages: sensors and preamplifiers
The next level down from instrumentation_base
files are
datalogger_base
, sensor_base
and preamplifier_base
files,
collectively refered to as instrument_components
.
Thre three types of instrument_components
have several common elements,
most notably stages
.
datalogger
and sensor
have a couple of specific elements.
datalogger_base files
See also Building a datalogger information file
- Specific elements
sample_rate
andcorrection
.
datalogger_base:
equipment:
model: "CS5321/22"
type: "delta-sigma A/D converter + digital filter"
description: "CS5321/22 delta-sigma A/D converter + FIR digital filter"
manufacturer: "Cirrus Logic"
vendor: "various"
stages:
- {base: {$ref: "dataloggers/stages/CS5321_FIR1.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR3.stage_base.yaml#stage_base"}}
sample_rate: 125
correction: 0.232
configuration_default: "125sps"
configurations:
"62.5sps":
configuration_description: "62.5 sps"
sample_rate: 62.5
correction: 0.464
stages:
- {base: {$ref: "dataloggers/stages/CS5321_FIR1.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR3.stage_base.yaml#stage_base"}}
"500sps":
configuration_description: "500 sps"
sample_rate: 500
correction: 0.058
stages:
- {base: {$ref: "dataloggers/stages/CS5321_FIR1.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR3.stage_base.yaml#stage_base"}}
"1000sps":
configuration_description: "1000 sps"
sample_rate: 1000
correction: 0.029
stages:
- {base: {$ref: "dataloggers/stages/CS5321_FIR1.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR2.stage_base.yaml#stage_base"}}
- {base: {$ref: "dataloggers/stages/CS5322_FIR3.stage_base.yaml#stage_base"}}
This file sets configuration_default: "125 sps"
so, if configuration
is not specified, “125 sps” will be used.
sensor_base files
- Specific element
seed_codes
sensor_base:
equipment:
model: "Trillium T240"
type: "Broadband seismometer"
description: "Trillium T240 seismometer, negative shorted to ground"
manufacturer: "Nanometrics, Inc"
vendor: "Nanometrics, Inc"
seed_codes:
band_base: "B"
instrument: "H"
configuration_default: "SN1-399, single-sided"
stages:
- {base: {$ref: "sensors/stages/Trillium_T240__theoretical.stage_base.yaml#stage_base"}}
configurations:
"Sphere01":
equipment: {serial_number: "133"}
stage_modifications:
'*': {configuration: "SN1-399, single-sided"}
"Sphere02":
equipment: {serial_number: "132"}
stage_modifications:
'*': {configuration: "SN1-399, single-sided"}
"Sphere03":
equipment: {serial_number: "134"}
stage_modifications:
'*': {configuration: "SN1-399, single-sided"}
"Sphere06":
equipment: {serial_number: "830"}
stage_modifications:
'*': {configuration: "SN400+, single-sided"}
The configurations specify the sensor serial number and seismometer response for each seismometer sphere.
preamplifier_base files
- specific elements
None
preamplifier_base:
equipment:
model: "BBOBS-GAIN"
type: "Analog gain card"
description: "INSU BBOBS gain card"
manufacturer: "SIO or IPGP"
vendor: "LCHEAPO"
stages:
- {base: {$ref: "preamplifiers/stages/INSU_BBOBS_theoretical.stage_base.yaml#stage_base"}}
configuration_default: "1x gain"
configurations:
"0.225x gain":
stage_modifications:
'*': {configuration: "0.225x"}
"1x gain":
stage_modifications:
'*': {configuration: "1.0x"}
Preamplifiers are optional. The configurations specify the analog gain between the sensor and the datalogger.
stage_base files
See also Building a stage information file with different filters
stage_base:
description : "SENSOR - TRILLIUM 240 SN1-399 (SINGLE-SIDED)"
input_units : {name: "m/s", description: "VELOCITY"}
output_units : {name: "V", description: "VOLTS"}
gain :
value: 598.45
frequency: 1.
filter:
$ref: "sensors/stages/filters/Trillium_T240_SN1-399_generic.filter.yaml#filter"
configuration_default: "SN1-399, single-sided"
configurations:
"SN1-399, single-sided":
filter:
$ref: "sensors/stages/filters/Trillium_T240_SN1-399_generic.filter.yaml#filter"
gain: {value: 598.45, frequency: 1.}
"SN400+, single-sided":
gain: {value: 594.5, frequency: 1.}
filter:
$ref: "sensors/stages/filters/Trillium_T240_SN400-_generic.filter.yaml#filter"
"SN1-399, differential":
filter:
$ref: "sensors/stages/filters/Trillium_T240_SN1-399_generic.filter.yaml#filter"
gain: {value: 1196.9, frequency: 1.}
"SN400+, differential":
gain: {value: 1189., frequency: 1.}
filter:
$ref: "sensors/stages/filters/Trillium_T240_SN400-_generic.filter.yaml#filter"
The configurations specify different instrument responses depending on the seismometer serial number and the connection (single-sided or differential)
filter files:
See also Building a filter information file for different filters
The 5 StationXML filter types can be specified:
PoleZeros
, FIR
, Coefficients
, ResponseList
and
Polynomial
.
obsinfo also allows 3 other types for simplicity:
Analog
An analog gain stage with no filtering (translated to StationXML PoleZero with no poles or zeros)
ADConversion
Like the Analog stage, plus information about input voltage and output count limits
Digital
A digital stage with no filtering (translated to StationXML Coefficients stage with numerator = [1] and denominator = [])
Below is an example pole-zero file.
filter:
type: "PolesZeros"
transfer_function_type: "LAPLACE (RADIANS/SECOND)"
zeros:
- '0.0 + 0.0j'
- '0.0 + 0.0j'
poles:
- '19.99 + 19.99j'
- '19.99 - 19.99j'
delay and correction
obsinfo differs slightly from StationXML is in its handling of delays in digital filters. StationXML (and RESP) have three parameters in each stage, relating to the time delay created by the stage, in each Stage’s Decimation section:
- Offset
Sample offset chosen for use. If the first sample is used, set this field to zero. If the second sample, set it to 1, and so forth.
- Delay
The estimated pure delay for the stage (in seconds). This value will almost always be positive to indicate a delayed signal.
- Correction
The time shift, if any, applied to correct for the delay at this stage. The sign convention used is opposite the <Delay> value; a positive sign here indicates that the trace was corrected to an earlier time to cancel the delay caused by the stage and indicated in the <Delay> element.
A digital filter’s true delay is in samples, not seconds, meaning that the delay will depend on the sampling rate.
obsinfo’s atomic philosphy does not permit a variable delay (in
seconds) when the delay is constant (in samples).
obsinfo therefore provides the elements delay.samples
for digital filters
and delay.seconds
for analog filters.
obsinfo converts delay.samples
to Delay
(in seconds)
in the output StationXML file.
obsinfo does not provide an offset
element because it was not clear to
what it represents, compared to delay.
offset
is in samples rather than in seconds and at first we thought that it
was the right way to express digital filter delays, but the StationXML documentation
states that offset
should be between 0 and the decimation factor.