select

select(
    self ,
    _attrs: collections.abc.Mapping[collections.abc.Mapping[str, Any], str, collections.abc.Iterable[str], None] = None,
    _coords: collections.abc.Mapping[collections.abc.Mapping[str, Any], str, collections.abc.Iterable[str], None] = None,
    samples: bool = False,
    relative: bool = False,
    **kwargs ,
)-> ‘Self’

Sub-select parts of the spool.

Can be used to specify dimension ranges, or glob matches on string attributes, read as SQLite’s GLOB reads them. Bare keyword names resolve against attributes first, then coordinates; unknown names raise.

Parameters

Parameter	Description
_attrs	Attribute selections: a dict of `name -> selector` (the general form — required when a name cannot be a Python keyword) or a name/collection of names tagging bare kwargs as attributes (disambiguates names shared with coordinates).
_coords	Coordinate selections; same forms as `_attrs`, validating names as coordinates only.
samples	If True, selections are coordinate-only and given in sample indices; they never exclude patches, but are applied to each patch as it loads.
relative	If True, coordinate range bounds are relative to each patch: positive from its start, negative from its end. Bounds keep their lower/upper order; crossed bounds select nothing. Patches without the selected coordinate or whose resolved window is empty are excluded using the indexed coordinate envelopes. Exact sample selection occurs when a patch loads.
**kwargs	Specifies query. A coordinate accepts one `(start, stop)` range or an `(n, 2)` array of absolute ranges (`None`, NaN or NaT is open); arrays on several coordinates need equal row counts, row `i` of each forming one box. Rows select independently in input order, so overlaps and duplicates return separate pieces. Array ranges do not support `samples=True` or `relative=True`. Attribute selectors retain their usual meaning.

Note

With an inventory attached, a patch that no single inventory context describes does not match a name the inventory answers for: one straddling an acquisition or optical-path change, reaching outside every optical-path epoch, with no physical time to resolve at, or not described at all. A straddler’s parts could answer differently and the others have no answer, and selection judges whole patches, so such patches are dropped with one warning per call counting them. conform_to_inventory splits patches at optical-path changes first, so the described parts can be selected; a patch spanning an acquisition change must instead be split by time. Patches that resolve but do not match drop silently.

Examples

import dascore as dc
spool = dc.get_example_spool("diverse_das")
# subselect data in a particular time range
time = ('2020-01-03', '2020-01-03T00:00:10')
time_spool = spool.select(time=time)
# subselect based on matching tag parameter
tag_spool = spool.select(tag='some*')
import numpy as np
ranges = np.array([[0, 10], [20, 30]])
pieces = spool.select(distance=ranges)
# one box per row on two dimensions; row two's time end is open
boxes = spool.select(distance=ranges, time=[time, [time[0], None]])