annotations

module of dascore.core source

DASCore annotations: labelled locations over the dimensions of patch data.

An annotation set describes data – picks, events, noisy hours, vehicle tracks – in the frame of the patches it was made on. Facts about the fiber itself belong to the inventory instead, in optical distance; see dascore.core.inventory.

A set holds three parts:

  • annotations: one row per located thing. For each declared dimension a row states a value (<dim>), a half-open range (<dim>_min and <dim>_max), or nothing, in which case it spans the whole dimension. Every row states at least one dimension, and a dimension holds one kind of coordinate: numbers, times or durations.
  • features: what annotations compose. Every annotation belongs to one feature, named by its feature_id; a blank feature_id makes the row its own feature, and a feature_id naming no features row creates one. A feature is a group (blank geometry), a path ordered by seq within part, or a polygon ordered by seq within (part, ring), ring 0 being the outer boundary. Features hold no coordinates.
  • bases: keyed curves (Line, Moveout) a path may be drawn from, so a path may exist as a curve alone.

Provenance (acquisition_key, data_id) is a feature’s own, else its child set’s (by set label), else the set’s. A member inherits it, states none, and its own label does not change it; a lone row is its own feature.

Any other column is an extra carried untouched, except a column whose name begins with an underscore: that is the author’s own, and a set never holds it.

Functions

Name Description
annotation_set_to_csv Return the annotations table as CSV text, optionally writing it to a path.
annotation_set_to_parquet Write the annotations table as one parquet file.
read_dimension Read a dimension column as the numbers or times its cells state.
read_ordinal Read an order column (seq, part or ring) as the numbers it states.
save_annotation_set Write the set to a directory, creating it if needed.

Classes

Name Description
AnnotationBasis Base for the curves a path may be drawn from.
AnnotationColumn What a set says about one of its columns.
AnnotationSet An immutable set of annotations, the features they compose, and bases.
AnnotationSetAttrs The attributes of an annotation set: what it describes and how.
Feature One feature of an AnnotationSet.
Group The unordered members of a group feature, one region each.
Line A straight line between two points.
Moveout The arrival time of a wavefront along the fiber, as a function of distance.
Path An open sequence of vertices, e.g. a vehicle track.
Polygon Closed rings of vertices bounding an area.
Region Per-dimension bounds: where one annotation row is.