A simple subnetwork file

Fundamentals of an information file

Under the folder which will contain all your information files, create a folder called network. Network information files can be part of or referenced by a campaign information file, but since we are not dealing with campaigns in obsinfo we will start with a network file.

Use your favourite text editor to create a network information file. Select as filename something meaningful, for example, single period OBS from INSU-IPGP would be SPOBS.INSU-IPGP. Then add the type of information file, network and the type of format, yaml:

SPOBS.INSU-IPGP.subnetwork.yaml

The file should start with the three dashes; the next line must specify the obsinfo version (required to know how to process the file). There are several optional fields which we will omit in this first exercise. It’s a good idea, though, to include a revision with a date and an author.

---
format_version: "0.111"
revision:
   authors:
       - names: ["Wayne Crawford"]
         agencies: ["IPGP", "CNRS"]
         emails: ["crawford@ipgp.fr"]
         phones: ["+33 01 83 95 76 63"]
   date: "2017-10-04"

Note the dash in a lonely line which indicates authors is a list. Alternatively, since the author is probably an information that will be repeated several times, this information can be stored in another file. Let’s say we create a folder named persons at the same level as network and then create a file inside that folder named Wayne_Crawford.person.yaml. We put the three fields previously under the authors key in that file, so the file will look like:

---
format_version: "0.111"
person:
    names: ["Wayne Crawford"]
    agencies: ["IPGP", "CNRS"]
    emails: ["crawford@ipgp.fr"]
    phones: ["+33 01 83 95 76 63"]

And then we reference the file with a $ref field in the original network file:

---
format_version: "0.110"
revision:
   authors:
       - $ref: 'persons/Wayne_Crawford.person.yaml'
   date: "2017-10-04"

The effect of this, from the point of view of obsinfo, is to insert said part of the Wayne_Crawford.person.yaml file instead of the $ref line. If you do this all of the contents will be inserted. This is undesirable as it will cause a syntax error; the system expects to see the fields names, emails, agencies and phones, not the three dashes, the version, etc. The solution is using an anchor or fragment, which will only insert the contents of the field referenced by the anchor. In this case, the anchor should be the field person, and so the final syntax is the following:

---
format_version: "0.111"
revision:
   authors:
       - $ref: 'persons/Wayne_Crawford.person.yaml#person'
   date: "2017-10-04"

File discovery

Finding the information files is one of the most important features in obsinfo. Notice that the pathnames in the examples above are not absolute (i.e. they don’t start at the base of the filesystem). In regular POSIX practice it is assumed that non-absolute paths are added to the directory where the application is executed (called the current working directory, or cwd). To allow the user to store instrumentation files in one standard spot, obsinfo will try to discover the file in one of several directories specified by the variable obsinfo_datapath, which is set by the obsinfo-setup application and found in the configuration file ~/.obsinforc (~ is your home directory). This works much in the same way that executables are found in Linux, MacOS or Windows using the variable PATH.

Whenever a file in a $ref is specified without an absolute path, obsinfo will sequentally look for the file in all the directories specified in obsinfo_datapath. A special keyword, GITLAB, specifies a remote Gitlab repository. Here’s an example:

obsinfo_datapath, as specified above, will always look in a local directory where the current examples are installed (via pip or conda) and then, if not found, in the remote repository. This gives the user great flexibility, as (s)he can override an existing remote information file with a local one, change the order of discovery, etc.

In the end, you will create your own information files in a directory selected by you. Then you will have to edit the obsinfo_datapath variable to reflect the directory from which you want to access your information files.

It is possible, although not recommended, to use absolute paths.

Use of slashes (/) instead of Windows backslashes () is recommended for uniformity, so a file can be used on different operation systems. However, if you use backslashes, obsinfo will understand them.

subnetwork

The next field key, subnetwork, starts the actual information. You may specify several sub-elements which are listed in Subnetwork, but let’s stick to the fundamentals:

subnetwork:
   network:
       code: "4G" # Either an FDSN provided network code or "XX" if no such code exists.
       name: "Short period OBSs" # Use the FDSN name if applicable
       start_date: "2007-07-01"
       end_date: "2025-12-31"
       description: "Short period OBS network example"
       operators: [{$ref: "operators/EMSO-AZORES.operator.yaml#operator"}]
   operators:
       -   {$ref: "operators/INSU-IPGP.operator.yaml#operator"}

The network section describes the network, of which the subnetwork is a subset.

If the network has been declared to FDSN, the information in network should correspond to the values on the FDSN site. For information on how to request a network code or use a temporary code, see this link .

stations

Stations belonging to the network are specified next. They could, of coursem be put in a different file, but it is a best practice to put the station information, so that one file contains all of the essential deployment information.

The following attribute is, therefore, stations. One can specify as many stations as you want, but in this example we will only specify one. Stations are identified by a one to five character code. This code acts like a key, but be careful to surround it by quotes: otherwise it will be flagged as an error by the JSON syntax validator. The start_date and end_date should correspond to data start and end. The site is described as a text field, and a location code is specified too. More on locations later.

stations:
     "LSVW":
         site: "Lucky Strike Volcano West"
         start_date: "2015-04-22T12:00:00Z"
         end_date: "2016-05-28T21:01:00Z"
         location_code: "00"
         instrumentation:

             ...

instrumentation

Stations must have an instrumentation, which specifies the entire data recording system, from the sensor(s) to the datalogger. The best practice is to specify these in a separate file, as the same instrumentation (with different serial numbers and possibly different configurations) may be used at several stations and/or for several experiments . The way to reference an instrumentation is the following:

instrumentation:
    base: {$ref: "instrumentations/SPOBS2.instrumentation_base.yaml#instrumentation_base"}
    datalogger_configuration: "250 sps"

$ref is a different file in a folder called instrumentation. It is possible to specify several instrumentations in list format:

instrumentations:
        - {base: {$ref: "instrumentations/SPOBS2.instrumentation_base.yaml#instrumentation_base"}}
        - {$ref: {"instrumentations/BBOBS1_2012+.instrumentation_base.yaml#instrumentation_base"}}

Instrumentations can be configured in several ways. One almost always provides a datalogger_configuration, to specify the sample rate and possibly digital filters and/or gains. Here is an example using all the possible keys:

instrumentation:
    base: {$ref: "instrumentations/SPOBS2.instrumentation_base.yaml#instrumentation_base"}
    serial_number: "01"
    configuration: "low power"
    modifications:
        ...
    channel_modifications:
        ...

The serial_number key lets you specify the instrumentation’s serial number The configuration key lets you select a configuration that has been pre-defined for the instrumentation. The modifications and channel_modifications keys let you modify individual elements within the instrumentation: we will discuss them later.

Locations

There must be at least one location in the file. This is the position in geographical coordinates of the station, usually referred as location “00”. Locations are specified as follows:

locations:
    "00":
        base: {$ref: 'location_bases/INSU-IPGP.location_base.yaml#location_base'}
        configuration: "ACOUSTIC_SURVEY"
        position: {lon: -32.32504, lat: 37.29744, elev: -2030}

There is a base, which is again a referenced file in a different folder (as best practice). Again, there is a configuration, which lets us chose which method was used to locate the station (a default value is chosen if configuration is not provided).

Observe the difference between a list and a dictionary. List items are separated by dashes, dictionaries need a key/value pair. authors is a list. locations is a dictionary.

However, there can be several locations. That’s the reason we have a location_code to specify the location corresponding to the station itself. Other locations can be used if different channels have different positions or if two channels have the same FDSN channel code, as will be seen shortly.

Channel modifications

channel_modifications allow you to apply modifications to certain channels in the instrumentation. For example, a change in an instrument_component configuration (more about this in the Next page, Building a simple instrumentation file). Higher-level specifications take priority, so if channel_modifications are specified both in the subnetwork file and in the instrumentation file, the one in the subnetwork file takes precedence.

Channel modifications are what makes obsinfo so flexible. We can specify several different configurations for the same components, and then select one of them. We can also directly change other attributes in the instrumentation. This allows components to be regarded almost as virtual descriptions which, when a particular configuration is selected, are instantiated into a specific, actual component. Thus instrumentation files can be authentic libraries with little changes, while the changes of configuration are specified for each station in a network in a specific campaign.

Furthermore, these libraries can reside in a central GitLab repository, which is updated by authorized users and, being public, is available for reuse by all users. A user can even clone the repository in the regular GitLab way (see here) in order to work offline with the latest version of the repository.

Complete example

You can skip this section in a first reading.

This is an actual subnetwork information file with the above information and some optional fields which we have not yet described. Note the additions:

A second station
Use of yaml_anchors to avoid repeating information in the same file
Comments field in network
a processing field in a station. For more information on this, see Processing

— format_version: “0.111” revision:

authors:

{$ref: “persons/Wayne_Crawford.person.yaml#person”}

date: “2019-12-19”

subnetwork:

network:

$ref: “networks/EMSO-AZORES.network.yaml#network”

operators:

{$ref: “operators/INSU-IPGP.operator.yaml#operator”}

stations:

“BB_1”:

site: “My favorite site” start_date: “2011-04-23T10:00:00” end_date: “2011-05-28T15:37:00” location_code: “00” locations:

“00”:
base: {$ref: ‘location_bases/INSU-IPGP.location_base.yaml#location_base’} configuration: “BUC_DROP” position: {lon: -32.234, lat: 37.2806, elev: -1950}

instrumentation:

base: {$ref: “instrumentations/BBOBS1_pre2012.instrumentation_base.yaml#instrumentation_base”} configuration: “SN07” modifications:

datalogger: {configuration: “62.5sps”}

processing:

clock_correction_linear:
base: {$ref: “timing_bases/Seascan_GNSS.timing_base.yaml#timing_base”} start_sync_reference: “2015-04-23T11:20:00” end_sync_reference: “2016-05-27T14:00:00.2450” end_sync_instrument: “2016-05-27T14:00:00”

“BB_2”:

site: “My other favorite site” start_date: “2015-04-23T10:00:00Z” end_date: “2016-05-28T15:37:00Z” location_code: “00” notes: [“example of deploying with a different sphere”] instrumentation:

base: {$ref: “instrumentations/BBOBS1_2012+.instrumentation_base.yaml#instrumentation_base”} serial_number: “06” modifications:

datalogger: {configuration: “62.5sps”, equipment: {serial_number: “26”}} preamplifier: {equipment: {serial_number: “26”}}

channel_modifications:
“1-”: {sensor: {configuration: “Sphere08”}} “2-”: {sensor: {configuration: “Sphere08”}} “Z-”: {sensor: {configuration: “Sphere08”}} “H-”: {sensor: {configuration: “5004”}}

locations:

“00”:: base: {$ref: ‘location_bases/INSU-IPGP.location_base.yaml#location_base’} configuration: “BUC_DROP” position: {lon: -32.29756, lat: 37.26049, elev: -1887}

processing:

clock_correction_linear:
base: {$ref: “timing_bases/Seascan_GNSS.timing_base.yaml#timing_base”} start_sync_reference: “2015-04-22T12:24:00” end_sync_reference: “2016-05-28T15:35:00.3660” end_sync_instrument: “2016-05-28T15:35:02”

In all obsinfo information files, you can add notes as a list of strings. Notes are not put into the StationXML file, they only serve documentation purposes within the information file.

comments, on the other hand, comments are added to StationXML files, and can only be placed at levels which correspond to the levels in a StationXML file with a Comment field.

extras are key:value pairs for information that you wish to document/process but do not correspond to existing obsinfo elements. They are added as comments to the output StationXML file.