Subnetwork Files

Subnetwork files are as far as most users will delve into obsinfo. They let you specify all of the standard and obs-specific elements of OBS deployments, without going into details about the instrumentation itself.

Here is an typical subnetwork file

---
format_version: "1.0"
revision:
    authors:
        - {$ref: "persons/EXAMPLE.person.yaml"}
    date: "2024-05-19"
subnetwork:
    operators:
        -   {$ref: "operators/EXAMPLE.operator.yaml"}
    network:
        $ref: "networks/EXAMPLE.network.yaml"
        # code: "XX"
        # description: "EXAMPLE HAHA NETWORK"
        # start_date: "2018-01-01"
        # end_date: "2026-12-31"
    stations:
        "LSVN":
            site: "Lucky Strike Volcano, North"
            start_date: "2018-08-16T00:00:00Z"
            end_date: "2019-06-12T22:13:35Z"
            location_code: "00"
            locations:
                "00":
                    base: {$ref: 'location_bases/EXAMPLE.location_base.yaml'}
                    configuration: "BUC_DROP"
                    position: {lon.deg: -32.279, lat.deg: 37.3195, elev.m: -1805}
            instrumentation:
                base: {$ref: "instrumentation_bases/EXAMPLE.instrumentation_base.yaml"}
                serial_number: "03"
                datalogger_configuration: "125sps"
                datalogger_serial_number: "14"
                seismic_sensor_serial_number: "T3506"
                pressure_sensor_serial_number: "IPGP2305"
            processing:
                - clock_correction:
                    drift:
                        base: {$ref: "timing_bases/EXAMPLE.timing_base.yaml"}
                        type: 'piecewise_linear'
                        syncs_instrument_reference:
                            - ["2018-08-15T12:26:00Z", "2018-08-15T12:26:00Z"]
                            - ["2019-06-12T22:10:51Z", "2019-06-12T22:10:50.2615Z"]
        "LSVE":
            site: "Lucky Strike Volcano, East"
            start_date: "2019-02-04T04:53:25Z"
            end_date: "2019-06-14T08:04:35Z"
            location_code: "00"
            locations:
                "00":
                    base: {$ref: 'location_bases/EXAMPLE.location_base.yaml'}
                    configuration: "BUC_DROP"
                    position: {lon.deg: -32.2411, lat.deg: 37.2811, elev.m: -1913}
            instrumentation:
                base: {$ref: "instrumentation_bases/EXAMPLE.instrumentation_base.yaml"}
                serial_number: "04"
                datalogger_configuration: "125sps"
            processing:
                - clock_correction:
                    drift:
                        base: {$ref: "timing_bases/EXAMPLE.timing_base.yaml"}
                        type: 'piecewise_linear'
                        syncs_instrument_reference:
                            - ["2018-08-15T12:26:00Z", "2018-08-15T12:26:00Z"]
                            - ["2019-06-14T04:57:59Z", "2019-06-14T04:58:00.8214Z"]
        "LSVS":
            site: "Lucky Strike Volcano, South"
            start_date: "2018-08-17T00:00:00Z"
            end_date: "2019-06-14T08:00:30Z"
            location_code: "00"
            locations:
                "00":
                    base: {$ref: 'location_bases/EXAMPLE.location_base.yaml'}
                    configuration: "ACOUSTIC_SURVEY"
                    position: {lon.deg: -32.29756, lat.deg: 37.26049, elev.m: -1887}
            instrumentation:
                base: {$ref: "instrumentation_bases/EXAMPLE.instrumentation_base.yaml"} 
                configuration: "SN04_2012+"
                datalogger_configuration: "125sps"
            processing:
               - clock_correction:
                    drift:
                        base: {$ref: "timing_bases/EXAMPLE.timing_base.yaml"}
                        type: 'piecewise_linear'
                        syncs_instrument_reference:
                            - ["2018-08-16T12:24:00Z", "2018-08-16T12:24:00Z"]
                            - ["2019-06-14T08:00:30Z", ~]

Subsections of subnetwork files

Three dashes

---

Specificies that this is a new “data set”

Provenance information

format_version: "1.0"
revision:
    authors:
        - {$ref: "persons/EXAMPLE.person.yaml"}
    date: "2024-05-19"

$ref allows you to import information from another file (see JSON References)

Operators and the FDSN network

subnetwork:
    operators:
        -   {$ref: "operators/EXAMPLE.operator.yaml"}
    network:
        $ref: "networks/EXAMPLE.network.yaml"
        # code: "XX"
        # description: "EXAMPLE HAHA NETWORK"
        # start_date: "2018-01-01"
        # end_date: "2026-12-31"

Stations

This is the biggest and most detailed section. Each station is specified by it’s station code: we focus below on the first station:

        "LSVN":
            site: "Lucky Strike Volcano, North"
            start_date: "2018-08-16T00:00:00Z"
            end_date: "2019-06-12T22:13:35Z"
            location_code: "00"
            locations:
                "00":
                    base: {$ref: 'location_bases/EXAMPLE.location_base.yaml'}
                    configuration: "BUC_DROP"
                    position: {lon.deg: -32.279, lat.deg: 37.3195, elev.m: -1805}
            instrumentation:
                base: {$ref: "instrumentation_bases/EXAMPLE.instrumentation_base.yaml"}
                serial_number: "03"
                datalogger_configuration: "125sps"
                datalogger_serial_number: "14"
                seismic_sensor_serial_number: "T3506"
                pressure_sensor_serial_number: "IPGP2305"
            processing:
                - clock_correction:
                    drift:
                        base: {$ref: "timing_bases/EXAMPLE.timing_base.yaml"}
                        type: 'piecewise_linear'
                        syncs_instrument_reference:
                            - ["2018-08-15T12:26:00Z", "2018-08-15T12:26:00Z"]
                            - ["2019-06-12T22:10:51Z", "2019-06-12T22:10:50.2615Z"]

Many of the values correspond directly to StationXML fields. Exceptions are the processing fields, which are used to specify the clock drift (and any leapseconds), and the datalogger_configuration field.

specifying the clock drift

The processing:clock_correction:drift element allows you to specify the instrument and reference clock times at different moments, and how to interpolate times in between the values. Each row of the syncs_instrument_reference element contains simultaneous values of the instrument time (first element) and the reference time (second element). The first row should be at/before the first data, and the last row should be at/after the last data. Intermediate rows, if any, allow you to specify intermediate values, in case the drift is not purely linear. Interpolation can be piecewise_linear, cubic_spline, or polynomial: for the latter, the polynomial coefficents should be specified and the syncs_instrument_reference are used to verify the resulting values.

Configuration and modification

Fields with a base element can be configured and modified using the configuration and modification fields. configuration allows you to use a pre-defined configuration specified in the base element, modification allows you to specify modifications “on the fly”. Detailed information is available at Base-configuration-modifications. Below is an overview that is specific to subnetwork files.

configuration fields allow you to select one of several configurations defined in the instrumentation_base file, in one of its components (datalogger_base, preamplifier_base or sensor_base, or in one of it’s components’ stages.

The configuration you specify should be defined in the file referenced by the *_base element. You can print a list of the available configurations using the obsinfo configurations subcommand.

If you don’t have an instrumentation_base file, you can simply write a text string after base. In this case obsinfo xml will create a StationXML file without channels, but at least you will have written the metadata needed for future processing. You should still specify any configurations used: just write out the most descriptive text possible (sampling rate, gain, filters…), which will allow you to select the right configuration code once it is defined in a future instrumentation_base file.

The datalogger_configuration field is actually a shortcut for channel_modifications: {'*': {'configuration': }}, because almost every deployment needs to specify the datalogger sampling rate and other options. The example above selects the configuration corresponding to a 125 samples per second rate. Some dataloggers have other options (filter type, gain…): the configuration string should represent all of the options.

The modifications field allows you to modify the base+configuration location or instrumentation. The only instrumentation element available using modifications is equipment: everything else is at the channel level and needs to be specified using the channel_modifications field.

The channel_modifications field is specific to instrumentation and allow you to modify all or individual channels within the instrumentation.

You can use the``stage_modifications`` field within the channel_modifications field, to modify individual stages within a channel. This is fairly rare: for details, see Base-configuration-modifications.

Below is the instrumentation section for an instrumentation for which you want to specify the serial numbers of each instrument component:

instrumentation:
    base: {$ref: "instrumentation_bases/SPOBS2_INSU.instrumentation_base.yaml"}
    serial_number: "03"
    datalogger_configuration: "250sps"
    channel_modifications:
        "*": {sensor: {serial_number: "10"}}
        "H": {equipment: {serial_number: "12"}}

This will set the serial number for all channel’s sensors to “10”, except for the “H” channel, which will be set to “12”

Below is an instrumentation section that specifies custom sensors for each channel:

instrumentation:
    base: {$ref: "instrumentation_bases/SPOBS2_INSU.instrumentation_base.yaml"}
    serial_number: "03"
    datalogger_configuration: "250sps"
    channel_modifications:
        "*": {replace_sensor: {base: {$ref: "sensor_bases/GURALP_CMG3T.sensor_base.yaml"},
                               configuration: "T3669"}}
        "H": {replace_sensor: {base: {$ref: "sensor_bases/HiTech_HTI-04_ULF.sensor_base.yaml"},
                               serial_number: "12345"}}

This will replace the default sensor to a Guralp CMG3T seismometer with configuration “T3669”, and the sensor on channel “H” to a HiTech HTI-04-ULF hydrophone with serial number “12345”. The configuration, which should be specified in the sensor_base file, can specify the instrument response as well as the serial number.

Another common use of configurations is to specify the station position uncertainty, as you can see in every locations element:

instrumentation:
    base: {$ref: "instrumentation_bases/SPOBS2_INSU.instrumentation_base.yaml"}
    serial_number: "03"
    datalogger_configuration: "250sps"
    channel_modifications:
        "*": {replace_sensor: {base: {$ref: "sensor_bases/GURALP_CMG3T.sensor_base.yaml"},
                               configuration: "T3669"}}
        "H": {replace_sensor: {base: {$ref: "sensor_bases/HiTech_HTI-04_ULF.sensor_base.yaml"},
                               serial_number: "12345"}}

This will replace the default sensor to a Guralp CMG3T seismometer with configuration “T3669”, and the sensor on channel “H” to a HiTech HTI-04-ULF hydrophone with serial number “12345”. The configuration, which should be specified in the sensor_base file, can specify the instrument response as well as the serial number.

location_base configurations:

Another common use of configurations is to specify the station position uncertainty, as you can see in each locations element, for example:

locations:
    "00":
        base: {$ref: 'location_bases/EXAMPLE.location_base.yaml'}
        configuration: "BUC_DROP"
        position: {lon.deg:  -32.24117 , lat.deg: 37.28107 , elev.m: -1995}

The configuration “BUC_DROP” is specified in the location_base file:

---
format_version: "1.0"
revision: 
    date: "2022-12-15"
    authors: 
        - $ref: "persons/EXAMPLE.person.yaml"
location_base:
    depth.m: 0
    geology: "unknown"
    vault: "seafloor"
    uncertainties.m: {lon: 200, lat: 200, elev: 20}
    measurement_method: "Sea surface release point"
    configuration_default: "SEA_SURFACE"
    configurations:
        "SEA_SURFACE":
            configuration_description: "Standard sea-surface deployment"
        "ACOUSTIC_SURVEY":
            uncertainties.m: {lon: 5, lat: 5, elev: 10}
            measurement_method: "Acoustic survey"
        "AIRGUN_SURVEY":
            uncertainties.m: {lon: 40, lat: 40, elev: 40}
            measurement_method: "Airgun survey"
            notes: ["Uncertainty will generally be least along-line"]
        "BUC_DIRECT":
            uncertainties.m: {lon: 5, lat: 5, elev: 10}
            measurement_method: "Short baseline transponder, seafloor release"
        "BUC_DROP":
            uncertainties.m: {lon: 20, lat: 20, elev: 20}
            measurement_method: "Short baseline transponder, near-seafloor release"

The configurations element defines the configurations that can be specified in a higher-level file. In this example, the BUC_DROP configuration specifies that the x, y and z uncertainties are 20 meters and it puts text in each position’s measurement_method field. If you wanted to specify that you deployed by BUC DROP but you have a more precise measurement of each uncertainty, you could write:

locations:
    "00":
        base: {$ref: 'location_bases/EXAMPLE.location_base.yaml'}
        configuration: "BUC_DROP"
        position: {lon.deg:  -32.24117 , lat.deg: 37.28107 , elev.m: -1995}
        modifications:
            uncertainties.m: {lon: 10.5, lat: 22.1, elev: 5.6}

or if you wanted to specify both the uncertainty and the measurement method, you could write:

locations:
    "00":
        base: {$ref: 'location_bases/EXAMPLE.location_base.yaml'}
        position: {lon.deg:  -32.24117 , lat.deg: 37.28107 , elev.m: -1995}
        modifications:
            uncertainties.m: {lon: 10.5, lat: 22.1, elev: 5.6}
            measurement_method: "Pifometer"
            geology: "sediments"

(we threw in geology` for fun: you can enter anything that is specified in the locations_base file)

It doesn’t matter if modifications is written above or below configuration: modifications are always applied after the configuration.

instrumentation_base example:

The third station specifies an instrumentation configuration rather than a serial_number:

            site: "Lucky Strike Volcano, South"
            start_date: "2018-08-17T00:00:00Z"
            end_date: "2019-06-14T08:00:30Z"
            location_code: "00"
            locations:
                "00":
                    base: {$ref: 'location_bases/EXAMPLE.location_base.yaml'}
                    configuration: "ACOUSTIC_SURVEY"
                    position: {lon.deg: -32.29756, lat.deg: 37.26049, elev.m: -1887}
            instrumentation:
                base: {$ref: "instrumentation_bases/EXAMPLE.instrumentation_base.yaml"} 
                configuration: "SN04_2012+"
                datalogger_configuration: "125sps"
            processing:
               - clock_correction:
                    drift:
                        base: {$ref: "timing_bases/EXAMPLE.timing_base.yaml"}
                        type: 'piecewise_linear'
                        syncs_instrument_reference:
                            - ["2018-08-16T12:24:00Z", "2018-08-16T12:24:00Z"]
                            - ["2019-06-14T08:00:30Z", ~]

This allows you to pre-specify, for example, different responses for different instrumentations. The serial_number may also be specified in the configuration, saving you having to write it in the subnetwork file. If you also specify serial_number in the subnetwork file, it will overwrite any serial_number value provided in the configuration.

Files read by the subnetwork file

Below are the elements from each file referenced by the subnetwork file, except for the instrumentation_base files, which is described in the Instrumentation Files page.

persons/EXAMPLE.person.yaml

    names: ["Teddy Riner"]
    agencies: ["IPGP", "CNRS"]
    emails: ["riner@cnrs.fr"]
    phones:  ["+33 01 99 88 77 66"]

networks/EXAMPLE.network.yaml

    code: "XX"
    description: "EXAMPLE NETWORK"
    start_date: "2018-01-01"
    end_date: "2026-12-31"
notes: ["The code XX is reserved for test or transient data"]

location_bases/EXAMPLE.location_base.yaml

    depth.m: 0
    geology: "unknown"
    vault: "seafloor"
    uncertainties.m: {lon: 200, lat: 200, elev: 20}
    measurement_method: "Sea surface release point"
    configuration_default: "SEA_SURFACE"
    configurations:
        "SEA_SURFACE":
            configuration_description: "Standard sea-surface deployment"
        "ACOUSTIC_SURVEY":
            uncertainties.m: {lon: 5, lat: 5, elev: 10}
            measurement_method: "Acoustic survey"
        "AIRGUN_SURVEY":
            uncertainties.m: {lon: 40, lat: 40, elev: 40}
            measurement_method: "Airgun survey"
            notes: ["Uncertainty will generally be least along-line"]
        "BUC_DIRECT":
            uncertainties.m: {lon: 5, lat: 5, elev: 10}
            measurement_method: "Short baseline transponder, seafloor release"
        "BUC_DROP":
            uncertainties.m: {lon: 20, lat: 20, elev: 20}
            measurement_method: "Short baseline transponder, near-seafloor release"

timing_bases/EXAMPLE.timing_base.yaml

    instrument: "ACME MCXO timing base"
    instrument_nominal_drift_rate: 1.e-8
    reference: "GNSS"