import dascore as dc
from dascore.examples import inventory_patch_pair
patch, inventory = inventory_patch_pair()
spool = dc.spool(patch).attach_inventory(inventory)
# The example path annotates two zones along the fiber.
zones = spool.expand_by("zone")
assert len(zones) == 2
assert set(zones.get_contents()["zone"]) == {"north", "south"}
# Which can be narrowed by a glob over the values.
assert len(spool.expand_by("zone", include="nor*")) == 1expand_by
expand_by(
self ,
name: str ,
include: str | collections.abc.Sequence[str, collections.abc.Sequence[str], None] = None,
exclude: str | collections.abc.Sequence[str, collections.abc.Sequence[str], None] = None,
stamp: bool = True,
)-> ‘Self’
Expand the spool into one patch per value of an inventory coordinate.
Each distinct categorical, membership, or numeric value produces the channels carrying that value. The outputs partition the fiber, so a patch containing several values may produce several patches.
A patch no single inventory context describes – one straddling an acquisition or optical-path change, reaching outside every optical-path epoch, or not described at all – produces nothing, and one warning per call counts such patches. Run conform_to_inventory first to split patches at optical-path changes so the described parts can be expanded; it refuses a patch spanning an acquisition change, which must be split by time instead.
Parameters
| Parameter | Description |
|---|---|
| name | The inventory-derived coordinate to expand by. |
| include, exclude |
Glob patterns matched against each value written as a string, which is what lets one spelling cover all three kinds of group: "hole_*" reads a categorical one, "Tru*"a membership one, and "1.*" a numeric one. Selecting on thestamp afterwards compares typed values instead, so the two are not interchangeable. With include, only values matchingone of them are kept; exclude drops the values it matches,and wins where both match. |
| stamp |
Whether to record the value on each output patch as an attr named after the coordinate, so overlapping siblings stay distinguishable and later operations can select on it. Pass False for a nested expansion, where the second should not overwrite the first. |