annotation_loader

module of dascore.core

source

Read annotation sets from storage.

A set is stored either as a directory naming what it holds – always annotations.csv, one row per annotation; attrs where it states its own dimensions and provenance; vertices.csv where any path or polygon needs one – or as a bare table whose dimensions the caller states.

A directory of those directories is a collection, and reads as one set whose set column names which of them each row came from: one return type, so nothing downstream has to ask which layout it was handed. What a set declares only for itself – its dimensions, its provenance, its documented columns – is kept under attrs.sets, and a row’s identity is still the id it already had, so an id two sets share is refused rather than qualified by the set it came from.

A table may declare the dimensions it is stated in itself, in a # dims: distance, time comment above its header, and a directory of data carries the annotations made on it under the hidden name .annotations, as it carries its inventory under .inventory.

A column whose header begins with an underscore is the author’s own – a crew’s notes on how something was deployed, say – and is read by nothing: the set does not carry it, so it stays in the file it was written in.

CSV has no types, so this module decides what each column holds before the models see it: a basis cell is the JSON document its curve dumps, and every other cell is read the way it was written. A dimension column is read by the set’s own reader, so a stored table and a frame in memory are typed alike. Tables are read strictly, through read_table, and the neutral errors that raises are named as annotation errors here, at the one boundary which knows the format.

Functions

Name	Description
annotations	Load annotations from whatever holds them.
find_annotations	Return what a directory of data carries its annotations under, or None.