import numpy as np
from dascore.examples import random_spool
spool = random_spool(time_gap=np.timedelta64(1, "s"), length=3)
gaps = spool.get_gaps()
assert len(gaps) == 2
# A contiguous spool has none.
assert random_spool().get_gaps().emptyget_gaps
get_gaps(
self ,
dim: str = time,
tolerance: float | pint.registry.Quantity | numpy.timedelta64[float, Quantity, timedelta64] = 1.5,
group: str | collections.abc.Sequence[str, collections.abc.Sequence[str], None] = None,
on_missing_dim: Literal[‘raise’, ‘drop’] = drop,
)-> ‘pd.DataFrame’
Return a dataframe with one row per gap along a dimension.
Each row is a boundary that chunk would refuse to fill under the same grouping and tolerance rules. A patch with holes enters a spool as its contiguous pieces, so its holes are gaps like any other. A gap a larger tolerance hides is still a chunk break unless fill_value is given.
Parameters
| Parameter | Description |
|---|---|
| dim | The dimension to look for gaps along. |
| tolerance |
The maximum number of samples patches can be spaced and still count as contiguous, or a quantity or timedelta bounding the excess over one sample in the coordinate’s own units (eg 1 * s). Same meaning as chunk’s tolerance.
|
| group |
Attributes which separate patches into unrelated groups; a gap is never reported between two groups. Defaults to the config option patch_kind_attrs. Sampling rate and coordinatestructure split groups too, exactly as they do for chunk,so one attribute value can span several groups. A value nobody recorded is a value of its own, so a patch which never stated the attribute is not grouped with one which did. |
| on_missing_dim |
What to do with patches lacking dim: “drop” (the default)excludes them, “raise” refuses. Chunk defaults to “raise” because it must produce those patches; a report need not. |
Note
{dim}_min is the last sample before the gap and {dim}_max the first sample after it, so gap_size is their difference — one step wider than the missing extent. Subtract the magnitude of the returned {dim}_step for the extent itself; the step keeps the coordinate’s sign, which is negative for a descending one.
group_id names the group each gap belongs to, and is the column to join against get_coverage.
Overlapping and fully-nested patches never open a gap: each boundary is measured against the furthest point reached so far, not the previous row.
A sample-count tolerance scales the step, so patches whose step is unknown report no gaps. An absolute tolerance needs no step (an unknown one counts as nothing), so it reports their gaps like any other patch’s.
See Also
get_gap_edges finds the gaps in the values of a coordinate already loaded; this method reads only the index and never loads data.