Overview
Information files are the core units of the obsinfo system. We present here the most important concepts, the hierarchy of information files and some examples.
Concepts
The basic hierarchy is subnetwork -> stations -> instrumentation -> channels -> {datalogger, preamplifier, sensor} -> stages -> filter
- datalogger, preamplifier and sensor objects:
are at the same level and all have stages subobjects.
Are refered to collectively as`instrument_compoents`
Their stages are put into StationXML from top (stage N) to bottom (stage N+M). The ordering is sensor -> preamplifier -> datalogger, so the top sensor stage will be the instrument’s stage 0.
preamplifier is optional.
information is generally divided into “atomic” files which are referenced using the $ref: operator (inherited from JSONref).
The paths in the $ref operator are added to the datapath specified in the .obsinforc file (often the current directory, a local instrumentation database and possibly an online database)
- base objects and configuration (Details)
allow partial (pre-configured) customization of station, instrumentation and instrument_component objects
are specified using a base and (optional) config object at each of these levels in the information files.
Use configuration_definitions (and a configuration_default object in case config is not specified) sub-objects specified within the base configurable object
- channel modifications (Details)
allow full customization of all objects
provide a “base” customization for all channels, then a specification/customization of differences between individual channels
The order of evaluation for customization is base < config < channel_modifications. Within channel_modifications, the most specific channel specifiers override the more general ones.
Hierarchy
We will present:
A basic level diagram of the entire structure (missing many sub-fields)
A full decription of each atomic-level object
A full level diagram of the entire structure, including all sub-fields
The definition (JSON Schemas) for the information files are found in obsinfo/data/schemas
1) Basic level diagram
Only required fields are shown, except a few very commonly-used fields, surrounded by “*”s. atomic objects described below are surrounded by <>
subnetwork: <network>
operator:
<operator>
network_info:
<network_info>
stations:
{STATIONNAME1}: <station>
site: string
start_date: string
end_date: string
location_code: string
locations:
{LOCATION_1}: <location>
{LOCATION_2}: <location>
...
instrumentation: <instrumentation>
base:
equipment:
<equipment object>
channels:
default: <channel>
datalogger:
base: <datalogger>
equipment:
<equipment>
sample_rate: number
stages:
-
base: <stage>
input_units: <units>
name: string
description: string
output_units: <units>
gain:
value: float
filter: <filter>
type: string
- base: <stage>
- ...
*preamplifier: <preamplifier>*
base:
equipment:
<equipment>
stages:
- base: <stage>
- base: <stage>
- ...
sensor: <sensor>
base:
equipment:
<equipment>
seed_codes:
band_base: "B" or "S"
instrument: single character
stages:
- base: <stage>
- base: <stage>
- ...
{SPECIFIC-CHANNEL1}: subset of <channel>
{SPECIFIC-CHANNEL2}: subset of <channel>
...
{STATIONNAME2}:
...
2) Atomic level diagram with comments
Starred fields are optional. If you put a level in a separate file, it is good practice to use the following file structure:
format_version: <format_version>
*revision: <revision>*
*notes: list of strings*
level: <level>
Major objects
subnetwork
operator: <operator>
*stations_operator: <operator>*
*restricted_state: {}*
*comments: list of strings*
*extras: <free-form object>*
campaign_ref_name: string
network_info: <network_info>
stations:
<STATIONNAME1>:
<station>
<STATIONNAME2>:
<station>
...
station
site: string
start_date: string
end_date: string
location_code: string
*operator: <operator>*
instrumentation:
base: <instrumentation>
*config: <string>*
*channel_modifications: {}*
*serial_number: string*
locations: object list of <location>
*notes: list of strings*
*comments: list of strings or <stationxml_comment>*
*extras: <free-form object>*
*processing:*
- *clock_correction_linear: {}*
- *clock_correction_leapsecond: {}*
instrumentation
*operator: {}*
equipment: {}
channels:
default:
<channel>
<SPECIFIC-CHANNEL1>:
subset of <channel>
<SPECIFIC-CHANNEL2>:
subset of <channel>
...
*configuration_default: string*
*configuration_definitions:*
{CONFIGURATION_1}: <subset of instrumentation>
{CONFIGURATION_2}: <subset of instrumentation>
...
channel
*orientation_code: string or {}*
datalogger:
base: <datalogger>
*config: string*
*preamplifier:*
base: <preamplifier>
*config: string*
sensor:
base: <sensor>
*config: string*
*location_code: string* # otherwise inherits from station
*comments: list of strings*
*extras: <free-format object>*
datalogger
<GENERIC_COMPONENT>
sample_rate: number
*delay_correction: number*
preamplifier
<GENERIC_COMPONENT>
sensor
<GENERIC_COMPONENT>
seed_codes:
GENERIC_COMPONENT
equipment:
<equipment>
*response_modifications: {}*
*notes: list of strings*
*stages:*
- base: <stage>
*config: string*
- base: <stage>
*config: string*
- ...
*configuration_default: string*
*configuration_definitions:*
{CONFIGURATION_1}: <subset of datalogger, sensor, or preamplifier>
{CONFIGURATION_2}: <subset of datalogger, sensor, or preamplifier>
...
stage
input_units: string
output_units string
gain: float
*name: string*
*description: string*
*decimation_factor: integer*
*delay: number*
*calibration_date: string*
*polarity: '+' or '-'* # default is '+'
*input_sample_rate: number*
*filter:*
<filter>
*configuration_default: string*
*configuration_definitions:*
{CONFIGURATION_1}: <subset of stage>
{CONFIGURATION_2}: <subset of stage>
...
filter
fields depend on type:
type: "PoleZeros"
poles: list
zeros: list
*offset: float*
*transfer_function_type": "LAPLACE (RADIANS/SECOND)", "LAPLACE (HERTZ)", or "DIGITAL (Z-TRANSFORM)"
*normalization_frequency: float*
*normalization_factor: float*
type: "FIR"
symmetry: "EVEN", "ODD" or "NONE"
coefficients: list
offset: float
"coefficient_divisor": float
type: "Coefficients"
numerator_coefficients: list
denominator_coefficients": list
*transfer_function_type: "ANALOG (RADIANS/SECOND)", "ANALOG (HERTZ)" or "DIGITAL"*
*offset: float*
type: "ResponseList"
elements: list
*offset: float*
type: "Polynomial"
# Not implemented, had no examples to verify with
type: "ADConversion"
input_full_scale: float
output_full_scale: float
type: "Analog"
type: "Digital"
Minor objects
author_, operator_, location_base_ and network_info_ are often in separate files, should probably have their own schema file.
equipment_ is widespread enough that it should probably have its own schema file as well
first_name: string
last_name: string"
*institution: string*
*email: string*
*phones: array*
type: string
description: string
manufacturer: string
model: string
*vendor: string*
*serial_number: string*
*installation_date: string, date formatted*
*removal_date: string, date formatted*
*calibration_dates: array of strings, date format*
base:
uncertainties.m:
lat: number (in meters)
lon: number (in meters)
elev: number (in meters)
depth.m: number
geology: string
vault: string
*localisation_method: string*
position:
lat: number (in degrees)
lon: number (in degrees)
elev: number (in meters)
code: string
name: string
start_date: string, date formatted
end_date: string, date formatted
description: string
*comments: list of strings or <stationxml_comment>*
*website: string*
reference_name: string
*full_name: string*
*contact: <author object>*
*phone_number: string*
*email: string*
*website: string*
date: string
authors: list of <author object>
value: string
*begin_effective_time: string, date formatted*
*end_effective_time: string, date formatted*
*authors: list of <author>*
3) Full level diagram
Structural units
A full obsinfo network description consists of the following fields
(starred fields are optional):
format_version: {}
*revision: {}*
*notes: []*
subnetwork:
network_info: {}
operator: {}
*restricted_state: {}*
*comments: []*
*extras: {}*
*ref_names:*
campaign: string
operator: string
stations:
<STATIONNAME1>:
site: string
start_date: string
end_date: string
location_code: string
*serial_number: string*
*operator: {}*
instrumentation:
base:
*operator: {}*
equipment: {}
channels:
default:
*orientation_code: string or {}*
datalogger:
<< GENERIC_COMPONENT
sample_rate: number
*delay_correction: number*
*preamplifier:*
*<< GENERIC_COMPONENT*
sensor:
<< GENERIC_COMPONENT
seed_codes:
*preamplifier_configuration: string*
*sensor_configuration: string*
*datalogger_configuration: string*
*location_code: string* # otherwise inherits from station
*comments: []*
*extras: {}*
<SPECIFIC-CHANNEL1>: {}
<SPECIFIC-CHANNEL2>: {}
...
*channel_modifications: {}*
*serial_number: string*
locations: {}
*notes: []*
*comments: []*
*extras: {}*
*processing:*
- *clock_correction_linear: {}*
- *clock_correction_leapsecond: {}*
<STATIONNAME2>:
...
Where GENERIC_COMPONENT is:
equipment:
<equipment>
*configuration_default: string*
*configuration_definitions: {}*
*response_modifications: {}*
*notes: []*
*stages:*
- stage:
input_units: string
output_units string
gain: float
*name: string*
*description: string*
*decimation_factor: integer*
*delay: number*
*calibration_date: string*
*polarity: '+' or '-'* # default is '+'
*input_sample_rate: number*
*filter:*
<filter>
- stage:
- ...