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,
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 merge under the same grouping and tolerance rules.
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 stating that limit in the coordinate’s own units (eg 1 * s). Samemeaning 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. |
| 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, so it reports their gaps like any other patch’s.
See Also
get_gap_edges finds the gaps inside one patch’s coordinate, which is a different question: this method reads the index and never loads data.