Inventory Reference
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. |