Inventory Reference

WarningExperimental

This page covers an experimental part of DASCore: its API and file formats may change in any minor release without a deprecation period. See what experimental means.

This page lists where each part of an inventory lives in an authoring directory, how the objects refer to one another, and every field of every model. The field tables are generated from the models in dascore.core.inventory, so they match the installed version.

How the files fit together

Each file holds one object, and its name states that object’s identity:

inventory.yaml                          Inventory: CRS, creation info (optional)
resources/<resource_id>.yaml            Interrogator, Cable, Enclosure,
                                        OpticalMeasurement, ExternalResource
networks/<network>.yaml                 Network (optional)
stations/<network>.<code>.yaml          Station, with its channels
fiber_arrays/<network>.<code>/
    attrs.yaml                          FiberArray
    path[.<location_code>][@<start>]/   one OpticalPath epoch
        attrs.yaml                      OpticalPath
        optical_components.csv          components, one per row
        geometry.csv                    geometry control points, one per row
        coupling.csv                    coupling intervals, one per row
        labels.csv                      label intervals, one per row
acquisitions/<network>.<fiber_array>.<location_code>.<code>.yaml
                                        Acquisition, with its distance_map

Acquisitions are tied to their fiber array and optical path by name, not by nesting: acquisitions/XT.TUN1.00.DAS.yaml belongs to fiber array TUN1 of network XT, and interrogates the optical path in fiber_arrays/XT.TUN1/path.00/, because both state location code 00. Its distance_map places its channels on that path’s optical distance.

Resources are stated once under resources/ and referred to by resource_id, which is the file name without its suffix:

Field Refers to
Acquisition.interrogator Interrogator
FiberSegment.container Cable
container of a Connector, Splice, Terminator, or Amplifier Enclosure
Cable.container Enclosure or Cable
a component’s loss_measurement and reflectance_measurement OpticalMeasurement
OpticalPath.measurements OpticalMeasurement
Cable.specification, Enclosure.specification, OpticalMeasurement.data ExternalResource

An OpticalMeasurement is the record of one test (method, wavelength, time, the trace or report file), not a value. A component cites one from loss_measurement or reflectance_measurement to say where its loss_db or reflectance_db came from. OpticalPath.measurements lists the tests of the path as a whole, such as an end-to-end OTDR trace, which no single component owns. Both are provenance: neither becomes a patch attribute or coordinate.

Why distances repeat

The four tracks of an optical path are separate tables along the same optical distance, and none refers to another’s rows. Where a label, a geometry segment, and a component describe the same stretch of fiber, each table states that stretch’s distances. This keeps each track free to cover only what is known and to be split differently: a label can span many components, and geometry needs a control point wherever the fiber bends. The cost is that a change in distance, such as a repair, must be applied to every table; generating the tables from one description avoids editing them by hand.

Some repetition is avoidable. A component’s name and a geometry segment’s name are coordinates already, so select(optical_components="spool") or select(geometry="spool") works without a label stating the same interval. A distance map’s optical_distance values are where the interrogator’s axis was calibrated, not track boundaries, so they need not match any table.

Fields

Every model also has description (free text) and extra_fields (other metadata, as a mapping). Models with epochs (Network, Station, Channel, FiberArray, Acquisition, OpticalPath) have time_min and time_max, unbounded by default; an @<start> suffix on a file or directory name sets time_min, and an optical-path epoch ends where the next one at its location begins. Object files also state object_type, the model’s name.

Where In the files is blank, the field is a key of the same name in the model’s file or a column of the same name in its table.

Envelope, networks, and acquisitions

Inventory

inventory.yaml.

Field Required Default In the files Description
schema_version no 1 Version of the inventory manifest envelope.
resource_id no '' Identifier for the inventory manifest.
creation_info no CreationInfo() QuakeML-style creation and update metadata.
resources no {} the resources/ directory Shareable resources keyed by resource_id.
coordinate_reference_system no CoordinateReferenceSystem() Inventory-wide CRS used by all coordinate-bearing metadata.
networks no () the networks/, stations/, fiber_arrays/ and acquisitions/ directories Network containers in the inventory.

CoordinateReferenceSystem

coordinate_reference_system in inventory.yaml.

Field Required Default In the files Description
authority no 'EPSG' CRS authority.
code no '4979' Authority code for this CRS.
name no 'WGS 84 3D' Human-readable CRS name.
coordinate_labels no ('longitude', 'latitude', 'elevation') Meaning of the canonical (x, y, z) axes, in order. Labels come from the controlled coordinate vocabulary.
units no ('degree', 'degree', 'meter') Units of the canonical axes, in order; same length as coordinate_labels.
vertical_datum no '' Vertical datum or reference surface, if known.
wkt no '' WKT2 definition for frames an authority code cannot describe (local, derived, or compound CRSs); empty for registry CRSs.

CreationInfo

creation_info in inventory.yaml.

Field Required Default In the files Description
agency_id no '' Responsible agency.
author no '' Author or process.
creation_time no unset Time this inventory was originally created (UTC).
update_time no unset Time the content was last updated (UTC); by convention set alongside a version bump when a correction is made.
version no '' Content version of the document.

Network

networks/<code>.yaml; optional, since any address naming the network creates it.

Field Required Default In the files Description
code yes the file name Network code.
name no '' Human-readable network name.
identifiers no () Scheme-prefixed identifier URIs naming this object, e.g. ‘doi:10.7914/SN/XX’.
fiber_arrays no () fiber_arrays/<code>.* Fiber arrays in this network.
stations no () stations/<code>.* Stations in this network.

FiberArray

fiber_arrays/<network>.<code>/attrs.yaml.

Field Required Default In the files Description
code yes the directory name, after <network>. Station-like fiber array code.
name no '' Human-readable fiber array name.
identifiers no () Scheme-prefixed identifier URIs naming this object, e.g. ‘doi:10.7914/SN/XX’.
acquisitions no () acquisitions/<network>.<code>.* Acquisitions associated with this fiber array.
optical_paths no () its path* directories Optical paths associated with this fiber array.

Acquisition

acquisitions/<network>.<fiber_array>.<location_code>.<code>.yaml, or acquisitions/<network>.<fiber_array>.<location_code>.<code>/attrs.yaml.

Field Required Default In the files Description
code yes the file name Channel-like acquisition code.
location_code no '' the file name FDSN-style location code naming the optical path lineage this acquisition interrogates; may be blank, as in FDSN.
data_type no '' Quantity measured or produced.
data_category no '' Acquisition family such as DAS, DTS, or DSS.
data_units no None Units of data produced.
interrogator no None a resource_id Interrogator used for this acquisition; an object or a resource_id reference.
interrogator_port no None Instrument connector or launch port that fed this acquisition, for multiplexed interrogators. Descriptive only.
firmware_version no '' Interrogator firmware version during this acquisition.
software_version no '' Acquisition software version during this acquisition.
gauge_length no None Gauge length in meters.
pulse_rate no None Pulse repetition rate in Hz.
pulse_width no None Pulse width in seconds.
sample_rate no None FDSN-style acquisition sample rate in Hz.
spatial_interval no None Nominal spatial sampling interval between channels in meters. Participates in channel resolution only as the slope of a single-point distance_map read on the channel axis.
distance_map no None inline, or distance_map.csv Map from interrogator-reported channels or distances onto optical path distance.
closed_fiber_loop no None True when the interrogator is attached to both path ends.

DistanceMap

distance_map in the acquisition file, or distance_map.csv beside its attrs.yaml with one row per control point.

Field Required Default In the files Description
channel at least one of channel and acquisition_distance None Interrogator-reported channel numbers; strictly increasing.
acquisition_distance at least one of channel and acquisition_distance None Interrogator-reported nominal distances; strictly increasing.
optical_distance yes Optical path distances at the control points; strictly increasing.

Optical path

OpticalPath

fiber_arrays/<network>.<fiber_array>/path[.<location_code>][@<start>]/attrs.yaml.

Field Required Default In the files Description
name no '' Human-readable optical path name.
location_code no '' the directory suffix after path. FDSN-style location code naming this path lineage within its fiber array; blank by default.
optical_components no () optical_components.csv in the path directory, or inline Optical components on this path, held in distance order whatever order they were stated in.
geometry no () geometry.csv in the path directory, or inline Piecewise geometry segments on this path.
coupling no () coupling.csv in the path directory, or inline Coupling conditions on this path.
labels no () labels.csv in the path directory, or inline Labels on this path.
measurements no () a list of resource_ids OTDR and other optical measurements of this whole path.

FiberSegment

A row of the path’s optical_components.csv with object_type FiberSegment.

Field Required Default In the files Description
distance_min yes Lower optical distance of this interval in meters.
distance_max yes Upper optical distance of this interval in meters; equal to distance_min for a point marker.
name no '' Human-readable component name.
loss_db no None One-way transmission loss across this component in dB.
loss_measurement no None a resource_id Measurement record(s) the loss value(s) came from.
reflectance_db no None Return loss (reflectance) of this component in dB.
reflectance_measurement no None a resource_id Measurement record(s) the reflectance value(s) came from.
container no None a resource_id Cable containing this fiber.
fiber_number no None Fiber position within the parent cable.
fiber_color no None Fiber color code.
fiber_type no '' Fiber type, such as single_mode or multi_mode.
fiber_standard no '' Fiber standard or grade, such as ITU-T G.652.D.
refractive_index no None Effective group index used to convert optical time of flight to distance; the OTDR group index setting.
buffer_type no '' Controlled buffer category; empty when not stated.

Connector

A row of the path’s optical_components.csv with object_type Connector.

Field Required Default In the files Description
distance_min yes Lower optical distance of this interval in meters.
distance_max no blank, for a point; it takes distance_min Upper optical distance of this interval in meters; equal to distance_min for a point marker.
name no '' Human-readable component name.
loss_db no None One-way transmission loss across this component in dB.
loss_measurement no None a resource_id Measurement record(s) the loss value(s) came from.
reflectance_db no None Return loss (reflectance) of this component in dB.
reflectance_measurement no None a resource_id Measurement record(s) the reflectance value(s) came from.
container no None a resource_id Enclosure housing this connector.
connector_type no '' Connector type.

Splice

A row of the path’s optical_components.csv with object_type Splice.

Field Required Default In the files Description
distance_min yes Lower optical distance of this interval in meters.
distance_max no blank, for a point; it takes distance_min Upper optical distance of this interval in meters; equal to distance_min for a point marker.
name no '' Human-readable component name.
loss_db no None One-way transmission loss across this component in dB.
loss_measurement no None a resource_id Measurement record(s) the loss value(s) came from.
reflectance_db no None Return loss (reflectance) of this component in dB.
reflectance_measurement no None a resource_id Measurement record(s) the reflectance value(s) came from.
container no None a resource_id Enclosure housing this splice.
splice_type no '' Splice type, such as fusion.

Terminator

A row of the path’s optical_components.csv with object_type Terminator.

Field Required Default In the files Description
distance_min yes Lower optical distance of this interval in meters.
distance_max no blank, for a point; it takes distance_min Upper optical distance of this interval in meters; equal to distance_min for a point marker.
name no '' Human-readable component name.
loss_db no None One-way transmission loss across this component in dB.
loss_measurement no None a resource_id Measurement record(s) the loss value(s) came from.
reflectance_db no None Return loss (reflectance) of this component in dB.
reflectance_measurement no None a resource_id Measurement record(s) the reflectance value(s) came from.
container no None a resource_id Enclosure housing this terminator.
termination_type no '' Termination type, such as open, capped, or angled.

Amplifier

A row of the path’s optical_components.csv with object_type Amplifier.

Field Required Default In the files Description
distance_min yes Lower optical distance of this interval in meters.
distance_max no blank, for a point; it takes distance_min Upper optical distance of this interval in meters; equal to distance_min for a point marker.
name no '' Human-readable component name.
loss_db no None One-way transmission loss across this component in dB.
loss_measurement no None a resource_id Measurement record(s) the loss value(s) came from.
reflectance_db no None Return loss (reflectance) of this component in dB.
reflectance_measurement no None a resource_id Measurement record(s) the reflectance value(s) came from.
container no None a resource_id Enclosure housing this amplifier.
amplifier_type no '' Amplifier type, such as edfa or raman.

Geometry

Rows of the path’s geometry.csv, one per control point.

Field Required Default In the files Description
name yes, in geometry.csv '' the name column; rows sharing it form one segment Human-readable geometry name.
optical_distance yes Optical distances paired to values; at least two strictly increasing values whose span is the segment’s coverage.
columns yes every other column, keyed by its header Columns measured along this segment, keyed by name; each holds one value per distance.
units no {} a header suffix, such as chainage (m) Units of the columns which are not position axes.

CouplingCondition

A row of the path’s coupling.csv.

Field Required Default In the files Description
distance_min yes Lower optical distance of this interval in meters.
distance_max yes Upper optical distance of this interval in meters; equal to distance_min for a point marker.
coupling_type yes Controlled coupling category.
medium no '' Surrounding medium.
attachment no '' Attachment method.
depth no None Depth in meters, positive down, relative to the local surface, when relevant.

OpticalPathLabel

A row of the path’s labels.csv.

Field Required Default In the files Description
distance_min yes Lower optical distance of this interval in meters.
distance_max yes Upper optical distance of this interval in meters; equal to distance_min for a point marker.
group yes Name of the labelled variable.
value no None Value of the variable over this interval; unset for a label which states membership.

Resources

Interrogator

resources/<resource_id>.yaml.

Field Required Default In the files Description
resource_id no '' the file name Stable identifier for this shareable inventory resource; hashed from its content when unstated.
name no '' Human-readable resource name.
manufacturer no '' Manufacturer name.
model no '' Model number.
serial_number no '' Serial number.
instrument_type no '' General instrument category.

Cable

resources/<resource_id>.yaml.

Field Required Default In the files Description
resource_id no '' the file name Stable identifier for this shareable inventory resource; hashed from its content when unstated.
name no '' Human-readable resource name.
manufacturer no '' Manufacturer name.
model no '' Model name.
diameter no None Outer cable diameter in meters.
specification no None a resource_id External specification or datasheet.
container no None a resource_id Optional containing physical asset.
fiber_count no None Number of fibers contained in the cable.

Enclosure

resources/<resource_id>.yaml.

Field Required Default In the files Description
resource_id no '' the file name Stable identifier for this shareable inventory resource; hashed from its content when unstated.
name no '' Human-readable resource name.
enclosure_type no '' Functional enclosure type, such as splice_box, junction_box, coupler, turnaround, protective_housing, conduit, pipe, duct, casing, borehole, or tray.
material no '' Material of the enclosure.
manufacturer no '' Manufacturer name.
model no '' Model name.
inner_diameter no None Inner diameter in meters.
specification no None a resource_id External specification or datasheet.

OpticalMeasurement

resources/<resource_id>.yaml.

Field Required Default In the files Description
resource_id no '' the file name Stable identifier for this shareable inventory resource; hashed from its content when unstated.
name no '' Human-readable measurement name.
method no '' How the values were obtained: otdr, power_meter, splicer_estimate, datasheet, or other.
time no unset Time of the measurement (UTC).
wavelength no None Measurement wavelength in nm.
pulse_width no None OTDR pulse width in seconds.
direction no '' Measurement direction: forward or reverse.
data no None a resource_id The trace or report file, as a resource.

ExternalResource

resources/<resource_id>.yaml.

Field Required Default In the files Description
resource_id no '' the file name Stable identifier for this shareable inventory resource; hashed from its content when unstated.
uri no '' URI or identifier for the resource.
name no '' Human-readable resource name.

Stations

Stations describe point sensors beside fiber arrays.

Station

stations/<network>.<code>.yaml.

Field Required Default In the files Description
code yes the file name Station code used in data source identifiers.
name no '' Human-readable station name.
identifiers no () Scheme-prefixed identifier URIs naming this object, e.g. ‘doi:10.7914/SN/XX’.
coordinates no None Coordinates on the canonical (x, y, z) axes; the inventory CRS coordinate_labels declare their meaning.
channels no () Channels associated with this station.

Channel

An entry of channels in its station’s file.

Field Required Default In the files Description
code yes Channel code used in data source identifiers.
location_code no '' FDSN-style location code; may be blank.
coordinates no None Coordinates on the canonical (x, y, z) axes; the inventory CRS coordinate_labels declare their meaning.
sample_rate no None Sample rate in Hz.
azimuth no None Sensor component azimuth in degrees clockwise from north, [0, 360).
dip no None Sensor component dip in degrees down from horizontal, [-90, 90].
depth no None Sensor depth in meters below the local surface; positive down.
data_type no '' Quantity measured or produced.
data_units no None Units of data produced.
response no None Optional response metadata.

Response

response in a channel.

Field Required Default In the files Description
sensitivity no None Overall channel sensitivity.
input_units no None Physical units before conversion.
output_units no None Physical units after conversion.