enrich

enrich(
    patch: Patch ,
    inventory: Inventory ,
    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’] = keep_first,
)-> ‘PatchType’

Copy inventory metadata onto a patch.

The patch resolves its inventory context from its acquisition_key and its time, then the acquisition’s channel map places each channel on the optical path so the path’s tracks can be projected onto it. The patch keeps no reference to the inventory afterwards.

Parameters

Parameter	Description
patch	The patch to enrich.
inventory	The inventory to resolve against.
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, 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 a patch which does not carry one. Given both, the patch and this argument must agree.
time	The instant to resolve at, for a patch 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 attributes which hold conflicting values across the patches being combined (eg data_type, data_units, custom attrs). A missing value (None, NaN, ““) is a value like any other: it equals another missing one and nothing else, so a patch which never stated an attribute conflicts with one which did. History and the ids are never compared. If”raise” (default) raise an AttributeMergeError for conflicting values. If “drop”, omit the conflicting attributes from the output. If “keep_first”, keep the first patch’s value of each. Enrichment combines the inventory’s values with the patch’s own rather than a sequence of patches, so it also accepts `keep_last`, which is the inventory correcting the file. The default `keep_first` keeps what the patch already stated: an attr a reader read out of the file header was there first. Either way an attr the patch leaves unset is filled, which is most of what enrichment does. `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()
# Copy everything applicable.
enriched = patch.enrich(inventory)
# Or name what is wanted.
enriched = patch.enrich(
    inventory, attrs=("gauge_length",), coords=("x", "y", "z"),
)