stored_coord

stored_coord(
    labels ,
    snap: bool | str | collections.abc.Collection[bool, str, collections.abc.Collection[str]] ,
    name: str ,
    where: Any = ““,
    decode: collections.abc.Callable[collections.abc.Callable[ndarray, ndarray], None] = None,
    start = None,
    step = None,
    count: int | None[int, None] = None,
    units = None,
)-> ‘BaseCoord’

Return a coordinate a file stores as labels, on a grid if snap names it.

Every reader builds its snapped grids here (rule 3 of the coordinate guidelines, notes/coordinates.qmd). The grid comes from the start and step the file states when both are given, such as a start time and its acquisition rate; otherwise it spans the first and last labels in their count, so labels from a clock unlocked from sampling still come back evenly sampled. A spanning step is a whole number of ticks where that keeps the last label within its stored precision, else an exact fraction of one. The grid is checked against the end labels, and a grid spanning them against the quartile labels too. Where one sits further than dascore.config.max_shift steps from it, beyond what its stored precision resolves (a hole, or a clock running apart), the labels are returned as stored with a SnapWarning naming the file, as they are when they end in missing values or do not advance. Only the checked labels are read unless they are kept. A coordinate snap does not name, or which is not numeric or time-like, comes back exactly as stored.

Parameters

Parameter	Description
labels	The stored labels: an array, or anything indexed like one, such as an HDF5 dataset.
snap	The reader’s `snap` option; see `should_snap`.
name	The coordinate’s name.
where	The file, or the open resource, named in the warning.
decode	Turns stored labels into coordinate values, such as `dascore.to_datetime64` for epoch seconds.
start	The first label the file states, as a coordinate value.
step	The step the file states, such as `step_from_rate(rate)`.
count	How many leading labels are samples; all of them if None.
units	The coordinate’s units.

Examples

import numpy as np
from dascore.io.utils import stored_coord
# distances stored with a little noise
labels = np.arange(10.0) + np.array([0, 1, -1, 0, 2, 0, -2, 1, 0, 0]) / 100
exact = stored_coord(labels, False, name="distance")
grid = stored_coord(labels, ("distance",), name="distance")
assert grid.evenly_sampled and not exact.evenly_sampled