enrich

enrich(
    self ,
    inventory: dascore.core.inventory.Inventory | str | os.PathLike | None[Inventory, str, PathLike, None] = None,
    attrs: bool | tuple[bool, tuple[str, …]] = True,
    coords: bool | tuple[bool, tuple[str, …]] = True,
    acquisition_key: str | None[str, None] = None,
    time = None,
    on_missing: Literal[‘warn’, ‘raise’, ‘ignore’, ‘null’] = raise,
    conflict: Literal[‘drop’, ‘raise’, ‘keep_first’, ‘keep_last’] = raise,
    on_unresolved: Literal[‘warn’, ‘raise’, ‘ignore’] = warn,
)-> ‘Self’

Enrich each patch this spool yields from an inventory.

Enrichment runs lazily as patches are extracted and survives subsequent spool operations. It never removes patches: on_unresolved controls warnings or errors for unresolved patches. Use conform_to_inventory to restrict membership.

The arguments other than inventory and on_unresolved are passed to Patch.enrich for each extracted patch. The policies, a None attrs or coords, and the shape of acquisition_key are checked now; everything else is checked as each patch is extracted. Calling enrich again replaces these arguments rather than adding to them.

Parameters

Parameter	Description
inventory	The inventory to enrich from, or its path, which is attached with `attach_inventory`. None uses the inventory already attached and raises if there is none.
attrs	True (the default) to copy the observing-system facts the inventory is authoritative for, a tuple of names to copy exactly those, or False to copy none. The blanket form is every scalar field of the resolved acquisition (and of its interrogator) except `data_type` and `data_units`, which describe the data as it now stands rather than the system, and `sample_rate` and `spatial_interval`, which the patch’s own coordinates already state and a decimated patch would contradict. Naming one of those four asks for the as-acquired value; whether it lands over one the patch already states is `conflict`’s business, as it is for every other name.
coords	True (the default) to add the geometry axes and label groups of the resolved optical path, a tuple of names to add exactly those, or False to add none. The blanket form adds the geometry axes, named as the inventory’s CRS names them (`x`, `y`, `z` when the inventory keeps the default CRS), the label groups, and `coupling`, whose values are the coupling type of each channel. Names may be `distance` for optical distance, one of the axes the inventory’s CRS names, a label group, a typed track (`coupling`, `geometry`, `optical_components`), or a qualified track field such as `coupling.medium`.
acquisition_key	The inventory identity to resolve, for patches which do not carry one. Given both, each patch and this argument must agree.
time	The instant to resolve at, for patches whose time axis is not physical. A patch with a real time coordinate resolves at its own time and passing this raises.
on_missing	What to do when an explicitly requested name is one the inventory does not define: “raise” (the default), “warn” to say so and leave it off, “ignore” to leave it off silently, or “null” to fill the dtype-appropriate missing marker so the name is present either way; the marker never replaces a value the patch already states. Blanket requests copy what is applicable and never trigger it, and per-channel coverage gaps are always missing values rather than errors.
conflict	What to do when an attr the patch states disagrees with the inventory. An attr either side leaves unset (None, NaN, ““) never conflicts: the patch’s is filled and the inventory’s is ignored, under every policy. Numbers equal up to float rounding agree. ”raise” (default) raises a PatchError, since a disagreement usually means the `acquisition_key` resolved to the wrong place. “keep_first” keeps the patch’s value, “keep_last” takes the inventory’s to correct the file, and “drop” removes the attr.
on_unresolved	What to do with a patch the inventory does not describe — one naming no entry, or naming one the inventory does not resolve to exactly one of. “warn” (the default) leaves it un-enriched and says so, “ignore” leaves it silently, and “raise” fails. A patch which straddles two epochs is described twice rather than not at all, and raises regardless: it needs subdividing.

Examples

import dascore as dc
from dascore.examples import inventory_patch_pair

patch, inventory = inventory_patch_pair()
spool = dc.spool(patch).enrich(inventory)
assert spool[0].attrs.gauge_length == 10.0

# Or name what is wanted, as with Patch.enrich.
spool = dc.spool(patch).enrich(inventory, coords=False)