enrich

enrich(
    self ,
    on_unresolved: Literal[‘warn’, ‘raise’, ‘ignore’] = warn,
    **kwargs ,
)-> ‘Self’

Enrich each patch this spool yields from an inventory.

The work happens as each patch is extracted, not now, so this is cheap on a large spool and costs one Patch.enrich per patch which actually comes out. Enrichment survives select, sort, chunk and friends; Spool.remove_inventory undoes it.

Enriching never removes a patch: one the inventory does not describe comes out unchanged rather than missing, so an inventory covering part of an archive needs no pruning first. Deciding membership is conform_to_inventory’s job, and leaving it there is what keeps this lazy — nothing resolves until a patch is pulled.

The inventory is the one attach_inventory put on the spool, which is the only way a spool gets one.

Parameters

Parameter	Description
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.
**kwargs	Held and passed to `Patch.enrich` for each extracted patch. The names accepted are read from its signature, so the two cannot disagree, and only the names are checked at this point — the values each patch’s own enrichment checks as it is extracted. Calling `enrich` again replaces these rather than adding to them. They are:

Other Parameters

Parameter	Description
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 excludes `data_type`, `data_category`, and `data_units`, which describe the data as it now stands, and `sample_rate` and `spatial_interval`, which the patch’s own coordinates already state; naming one restores the as-acquired value.
coords	True (the default) to add the geometry axes and annotation groups of the resolved optical path, a tuple of names to add exactly those, or False to add none. Names may be `distance` for optical distance, a coordinate label the inventory’s CRS defines, an annotation group, 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. Blanket requests copy what is applicable and never trigger it, and per-channel coverage gaps are always missing values rather than errors.
conflict	Indicates how to handle conflicts in attributes other than those indicated by dim (eg tag, history, acquisition_key, etc). If “drop” simply drop conflicting attributes, or attributes not shared by all models. If “raise” raise an [AttributeMergeError](`dascore.exceptions.AttributeMergeError`] when issues are encountered. If “keep_first”, just keep the first value for each attribute. Enrichment combines the inventory’s values with the patch’s own, so the default `keep_first` lets the inventory win and re-enriching is a refresh. `raise` is the misresolution guard: a header disagreeing with the resolved acquisition usually means the `acquisition_key` resolved to the wrong place.

Examples

import dascore as dc
from dascore.examples import inventory_patch_pair

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

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