DASDAE Inventory

The following describes the DASDAE Inventory, which captures the observing system around generated DFOS data. Importantly, it matches the same abstraction layering as StationXML.

Inventory Tree

DASDAE Inventory
Legend
  • MetadataTop-level metadata document or overview.
  • ContainerOrganizational grouping for monitoring entities.
  • Monitoring regionDurable observing target or monitoring identity.
  • Instrument-specificInstrument stream, response, or acquisition-specific metadata.
  • Shareable resourceStable resource-id object reused across inventory context.

Inventory is the main object which manages the other objects, as well as an IO and update interface.

References is a mapping of shareable resources, with a resource identifier as a key and the shareable object as the value. Objects that can be shared across the tree use stable resource_id values and live here. Examples include interrogators, cables, enclosures, external documents, etc.

CRS is the coordinate reference system. It governs the semantics of all coordinate values contained in the inventory. It should default to a standard global coordinate reference system already used by StationXML (e.g., EPSG:4979), so if it is not defined it will behave how users expect. However, it can be overridden for exceptional deployment conditions (e.g., laboratory, underground mines, etc.).

A Network is a coded container for monitoring regions.

Station represents a point-like monitoring domain. It is essentially the same as in StationXML, but with broader coordinate system support.

FiberArray represents a distributed, fiber-based monitoring domain. It has a sequence of OpticalPaths, which can vary over time, and a sequence of Acquisition objects.

The granularity rule: a fiber array groups similar, co-located fiber routes, and each route is a location code carrying one optical path at a time. Two fibers sharing one cable are naturally one array with two location codes — nearly the same geometry, one deployment identity. Dissimilar routes — the arms of a multi-arm deployment radiating in different directions — are separate FiberArrays, each with its own acquisitions (see the NORFOX example). Within a path, geometry segments and annotations subdivide space; path epochs subdivide time.

The OpticalPath, described in more detail in the next section, tracks the optical components, coupling conditions, geometry, and annotations.

Acquisition is a coded object that describes the instrument configuration that produced observations on the FiberArray. Any number of Acquisitions can be associated with a single FiberArray. Multiple acquisitions would be used when one interrogator simultaneously records data with several gauge lengths, or raw time-series data plus derived products such as frequency-band-extracted or decimated time-series data. A new Acquisition might also represent another interrogator plugged into the same optical path later on, or a change in interrogator configuration. Acquisition contains the location_code parameter, which names the optical path lineage the acquisition interrogates — acquisitions sharing a location share a path, the way SEED location codes distinguish co-located instruments at one station. The optional interrogator_port records which instrument connector fed the acquisition on multiplexed interrogators; it is descriptive only.

Each acquisition also carries the map from its channel-like coordinate onto the path’s optical distance axis. The path axis is the shared reference frame — established however works best, such as OTDR traces, build sheets, or tap tests — and every acquisition calibrates onto it independently, since different interrogators on the same fiber disagree about channel positions (internal fiber, patch cords, refractive-index settings, decimation). That calibration is a DistanceMap of control points, and it is the only mechanism: a single point states an origin — taking the nominal spatial_interval as its slope on the channel axis, and one meter of path per interrogator meter on the instrument-distance axis — while further points describe a measured, bending relationship. A map may state its points in both input coordinates at once, so one acquisition serves patches whose axes differ, and the patch’s own coordinate decides which is read. Fiber upstream of the path origin (interrogator internals, patch cords, lead cables) is outside the model; its only observable effect is the acquisition’s channel map.

The acquisition code is similar to the channel code from StationXML. The model constrains only its syntax (per the Model Constraints below), not its semantics, and enforces no length limit. For miniSEED2/SDS export the classic fixed widths apply — network ≤ 2, station or fiber array ≤ 5, location ≤ 2, channel ≤ 3 characters; longer codes remain legal and convert to FDSN Source Identifiers, which have no such limits (the DAS example network exceeds this). For data that will flow to FDSN systems, we recommend SEED-style three-character codes such as HSF or FSF depending on sampling rate, following the GEOFON DAS guidelines. (GEOFON’s station-per-sampling-point construction does not apply here; in this model FiberArray plays the station role and spatial channels are a coordinate.) Codes outside SEED semantics (e.g., RAW) or longer descriptive codes are explicitly permitted for what SEED channel codes cannot express, such as multiple simultaneous products from one interrogator.

Linking Patches to Acquisitions

Patches (time-series data) do not directly embed the inventory. They carry a acquisition_key composed of:

network.fiber_array.location.acquisition

That identifier resolves to the relevant FiberArray and Acquisition for a patch time. Likewise, channels in StationXML are resolved using network.station.location.channel. This makes a patch portable and keeps large or revised inventory context outside the patch until a user explicitly asks to add it.

acquisition_key records provenance, not identity. It names the observing configuration that produced the samples and is never unique to a patch: every window, selection, or split from the same acquisition shares one. No patch operation modifies acquisition_key; it is only set when resolved from an archive layout or explicitly assigned by the user. Combining patches with different acquisition_keys yields a patch with no single ancestor, so the field is cleared rather than silently inheriting one value.

Codes plus time are the only resolution mechanism, mirroring how SEED/FDSN identifiers resolve against StationXML epochs: the same acquisition_key legitimately spans many acquisition epochs, and a time selects among them. Patches whose time axis is no longer physical (e.g., correlations with lag time) resolve by passing an explicit time argument to resolution methods. The model stores no surrogate epoch identifier; one is derivable as codes plus epoch start time (DAS.L001.01.RAW@2024-05-01T000000, ISO basic — filename- and hive-safe). The name follows the FDSN Source Identifier vocabulary. It is a _key rather than an _id because it is a structured lookup path resolved against the inventory, not an opaque token: names ending in _id are left free to hold one, as ProdML’s acquisition_id does.

Epochs and corrections are distinct operations with distinct rules. Epochs record changes in the world — an instrument swap, a configuration change, a fiber break — and are additive: close one epoch, open the next. Corrections record changes in our knowledge — a re-tap-test revealing the channel map was always wrong, a re-survey improving coordinates — and are in-place edits to the inventory document, applying retroactively to all data the epoch covers. This mirrors StationXML practice, where a wrong sensitivity is fixed by republishing metadata, not by minting a new channel epoch.

A finer-grained processing lineage — for example, an identifier updated with a fingerprint or hash of each operation applied to a patch — may be added in a future revision. The current model intentionally tracks only the physical ancestor.

These do not need to be added to native DAS files directly but can be encoded in hive-style archive directory names as discussed in the Spool API section.

Model Constraints

  • No more than one OpticalPath per (FiberArray, location_code) is valid for a given time.
  • All validity and coverage intervals are half-open, [start, end): an instant exactly on an epoch boundary belongs to the newer epoch, and a distance exactly on an interval edge belongs to the following interval. The outermost endpoint of a coverage domain — where no further interval follows — is included. An unset (None) end time means the interval is open — ongoing.
  • All times in the model are UTC.
  • Within a Network, Station and FiberArray codes are disjoint for overlapping time ranges.
  • Station codes must be unique within a Network for overlapping time ranges; Channel (location_code, code) pairs must be unique within a Station for overlapping time ranges and resolve to exactly one Channel at any instant.
  • Resource IDs must be unique across shareable resources. Resource IDs are a separate namespace from codes and may use _.
  • All codes used in acquisition_key are restricted to letters, digits, and -; . is reserved as the separator and _ is excluded (it is the FDSN Source Identifier separator).
  • Codes are non-empty, except location_code, which may be blank as in FDSN; a blank location appears as an empty token in dotted identifiers (DAS.L001..RAW).
  • acquisition_key parts must resolve to exactly one Network, FiberArray, OpticalPath (selected by the location code), and Acquisition at any given instant; a patch is resolvable as a whole only when every instant it spans resolves to the same acquisition.
  • Acquisition (location_code, code) pairs must be unique within a FiberArray for overlapping time ranges.
  • A distance_map states at least one input axis, and every axis it states has one value per control point: they are the same points in different coordinates. A patch carrying more than one of those coordinates must agree with the map about all of them, or it contradicts the map about its own channels.
  • No recorded file spans an acquisition epoch boundary: a configuration change stops and restarts the acquisition. A straddling file indicates an incorrect epoch time, and the file boundary is the ground truth for correcting it. Optical-path epochs carry no such guarantee — a fiber can break mid-recording.