Inventory

Scope

This chapter describes the concept of inventories.

Overview

In SeisComP the term inventory refers to the meta data of data recording stations. Many SeisComP modules require inventory information to operate correctly and a correct inventory is therefore fundamental to SeisComP.

The inventory will be read from the database by default. To insert or update the inventory in the database, this information needs to be created or downloaded and converted. The following sections will describe the process of populating the database and how applications get access to it.

The format used for inventory is known as SCML. Correct inventory in SCML format can be generated by SMP [22]. Some modules for converting from other formats are listed in section Inventory Format. Tools for processing inventory are listed in section Related Tools.

The inventory shall contain all meta data describing the full recording system and the pre-processing of the raw data stream provided to the data processing modules using the RecordStream. Inventories should be always complete w.r.t the processed data streams, correct and up-to-date. Beside network, station, location and stream information they must include the full sensor and datalogger responses.

Older version used key files to configure available networks and stations. Because the support of response meta-data was very limited, tools were build to add this functionality. Since the release of Seattle the concept of key files for station meta-data has been completely removed from the system. Now SeisComP only handles station meta-data in its own XML format called SCML. The task of supporting old key files, dataless SEED and other formats has been out-sourced to external applications. The inventory synchronization is a two-stage process:

  1. Convert external formats into SCML

  2. Synchronize inventory pool with the database: merged all inventory files and synchronize with the database using scinv snyc.

../../_images/inventory-sync.png

Inventory synchronization as a two-stage process

All station meta-data are stored in etc/inventory and can be organized as needed. Either one file per network, a file containing the complete inventory or one file for all instruments and one file per station. The update script

$ scinv sync

loads the existing inventory from the database and merges each file in etc/inventory. Finally it removes all unreferenced objects and sends all updates to the database.

The SeisComP configuration does not deal with station meta-data anymore. It only configures parameters for modules and module-station associations. The management of the inventory can and should be handled by external tools e.g. SMP [22].

The SeisComP documentation describes the data model including the inventory.

Inventory Format

A typical inventory file in SCML looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<seiscomp xmlns="http://geofon.gfz-potsdam.de/ns/seiscomp-schema/0.11" version="0.11">
  <Inventory>
    <sensor>...
    <datalogger>...
    <network>...
  </Inventory>
</seiscomp>

The version attribute of the seiscomp tag represents the schema version of the SeisComP data model which is consistent with the database schema version and the version of all other representations.

Note

All geographic coordinates (latitudes, longitudes, elevation) are assumed in the World Geodetic System 1984 (WGS84) reference system (National Imagery and Mapping Agency 2000). Latitudes, longitudes are provided in degrees but elevations are given in meters.

Inventories must be provided to SeisComP in XML files in SCML format. A convenient way to generate clean and correct inventory files in SCML format is SMP [22]. Tools are provided to convert between other formats:

Module namespace

Conversion

arclink2inv

Arclink XML to SeisComPML

dlsv2inv

dataless SEED to SeisComPML

inv2dlsv

SeisComPML to dataless SEED

fdsnxml2inv

FDSN StationXML to SeisComPML and back

Adding / Updating Inventory

To add inventory information to the SeisComP database one either has to write directly to the database with custom script (not recommended) or place SCML files in @SYSTEMCONFIGDIR@/inventory. The service to import all data in that directory can be called with

$ seiscomp update-config inventory

This command runs scinv finally. scinv merges all XML files and synchronizes the merged local inventory tree with the database. That is a rather complex process and for more information it is recommended to study the source code of scinv. The bottom line is that inventory data is created from SCML files.

Because nobody will ever create such XML files by hand, tools are necessary. A quite popular tools is the online station management portal (SMP) [22]. SMP will output XML in version of SCML directly.

Another source is the FDSN station webservice (FDSNWS). If the SeisComP implementation of FDSNWS is used, the SeisComP XML format can be requested directly as an extension. Otherwise FDSN StationXML will be provided. Inventory in FDSN StationXML needs to be converted with either fdsnxml2inv or import_inv. The latter is a more versatile application that also supports several import formats.

$ import_inv fdsnxml download-1234.xml

This will automatically place the output XML file in @SYSTEMCONFIGDIR@/inventory. Afterwards call

$ seiscomp update-config inventory

to synchronize the changes with the database. If scconfig is used, then either the Sync button of the Inventory panel or the Update configuration button of the System panel must pressed.

Summary

In order to populate the database with inventory information, the following steps have to be performed:

  1. Convert existing station meta data formats to SCML

  2. Place all SCML files at @SYSTEMCONFIGDIR@/inventory

  3. Synchronize the inventory files and write the meta data to the database. Run

    $ scinv sync

    or

    $ seiscomp update-config inventory

Reading Inventory

Applications usually connect to the database and read the necessary inventory information. An application can decide whether it requires full response information including sensor and data logger response functions or just channel information without instrument descriptions. The latter performs faster and some applications do not require full instrument information.

An application usually does not require special configuration to read inventory information. A database connection is enough and it comes usually along with the handshake message of the messaging server.

If the messaging is not involved, the database can be specified by the command-line option -d:

$ myapp -d [type]://[user]:[password]@[host]:[port]

There are cases when an application should be run without a database connection but requires inventory information, particularly in combination with the --ep command line argument. To direct an application to an inventory XML file (again in SCML format), --inventory-db must be used:

$ myapp --inventory-db inventory.xml

The option --inventory-db will cause the module to completely bypass the database for reading inventory information even if used for event information. The file inventory.xml can be created from the database using scxmldump.