OpticalPath

OpticalPath is the ordered optical-distance model used to project physical metadata onto DAS data. It is linked from a FiberArray, carries time validity, and can be operated on directly before being placed back into an Inventory.

Path Operations

from dascore.core.inventory import OpticalPath

path = fiber_array.optical_paths[0]

short_path = path.select(distance=(100.0, 500.0))
left, right = path.split_at(250.0)
reversed_path = path.reverse()
joined_path = left + right

path.check()

select(distance=(start, stop)) clips optical components, geometries, coupling conditions, and annotations to the requested optical-distance interval. Open bounds can use None. Selections and splits preserve absolute optical distances — pieces are never rebased to zero.

split_at(distance) returns the two selected path pieces on either side of the split distance.

reverse() reverses ordered tracks and rewrites every distance-bearing track — geometry arrays, coupling intervals, and annotations — against the reversed path.

path_a + path_b concatenates two paths when their CRS definitions match, rewriting the second path’s tracks onto the combined axis.

check() checks that geometry, coupling, and annotation tracks stay within path bounds. Component tiling is not among its checks: the cumulative layout makes it inherent, since each component begins where the previous one ended. Geometry and coupling coverage may be partial; uncovered intervals are undefined rather than invalid. Overlapping geometry segments or coupling conditions raise; annotations may overlap freely.

Patch Projection

Patch.enrich resolves the valid optical path from the patch acquisition_key and patch time, mapping channels to optical distance internally (via the acquisition’s distance_map) before projecting the path tracks:

patch = patch.enrich(
    inventory,
    coords=("distance", "rock_type", "x", "y", "z", "optical_components.name"),
    on_missing="null",
)

Coordinate requests can include optical distance itself; geometry axes such as x, y, z, latitude, longitude, and elevation; any annotation group by name; and interval metadata from qualified tracks such as optical_components.name, geometry.name, or coupling.coupling_type. Qualified names match the model attributes (and the authoring CSV stems) exactly.

Annotation groups enrich according to their value type: a membership group becomes a boolean coordinate (false where uncovered), while categorical and numeric groups become single-valued coordinates carrying missing values where uncovered. Because single-valued groups may not overlap, no coordinate request is ambiguous — the model rejects the ambiguity long before enrichment sees it.

Design Rule

OpticalPath is not the raw channel table: the acquisition maps channels into optical distance; the path maps optical distance into geometry, annotations, coupling, and optical-component context.