| function of dascore.core.annotations | source |
save_annotation_set(
annotations: AnnotationSet ,
path: str | pathlib._local.Path[str, Path] ,
format: str = csv,
)-> ‘pathlib.Path’
Write the set to a directory, creating it if needed.
Reached as annotation_set.io.save.
The directory states the set in three parts: what it is and which dimensions it holds, its annotations, and – where any path or polygon needs them – its vertices. It reads back through dascore.annotations.
The attributes are written as JSON rather than as YAML, so storing a set needs nothing beyond the standard library; a set authored by hand may spell them in YAML, which reads back the same.
Sets which were loaded together write one table rather than a directory each: the set column already says which set every row belongs to, and what each of them states for itself travels in the attributes, so the flat spelling loses nothing.
The tables are CSV unless another encoding is asked for. Parquet writes the same parts under the same names, with its own suffix, and keeps a column’s type rather than its spelling wherever it has one for it; it needs pyarrow, where CSV needs nothing.
Writing states the whole directory, so a part this set does not have is removed rather than left behind. A stale vertices table, the YAML the attributes used to be spelled in, or the CSV a set was written as before it was written as parquet, would otherwise sit beside what was written and leave a directory which loaded before the save refusing to load after it.
| Parameter | Description |
|---|---|
| annotations | The set to write. |
| path | The directory to write into. |
| format |
The encoding the tables are written in: csv or parquet.
|
The directory written to, so a save reads straight back.
import pandas as pd
import dascore as dc
frame = pd.DataFrame(
{"group": ["event"], "distance_start": [10.0], "distance_end": [80.0]}
)
annotations = dc.AnnotationSet(frame, dims=("time", "distance"))
directory = annotations.io.save("picks") # doctest: +SKIP
dc.annotations(directory) == annotations # doctest: +SKIPTrue