spacr.metadata_resolution

Recover missing spaCR metadata columns without silent identity guesses.

The resolver is UI-independent. A Qt dialog can be supplied as prompt; headless callers receive one actionable exception instead of blocking on a window no one is watching. Known aliases are canonicalised before any human choice is requested.

Exceptions

MetadataResolutionRequired

A headless caller must provide an explicit metadata mapping.

Classes

MetadataDecision	One all-at-once answer returned by a UI or a saved setting.
MetadataRequest	All unresolved targets and evidence shown to one prompt.
ResolutionResult	Resolved frame plus the auditable decisions that changed it.

Functions

build_metadata_request(→ MetadataRequest)	Build the single request a GUI displays for every missing column.
clear_run_metadata_decisions(→ None)	Clear remembered prompt answers (primarily for tests/new runs).
resolve_metadata_columns(→ ResolutionResult)	Resolve every required metadata column in one deterministic pass.

Module Contents

exception spacr.metadata_resolution.MetadataResolutionRequired(missing: Sequence[str], available: Sequence[str])

Bases: ValueError

A headless caller must provide an explicit metadata mapping.

Parameters:

• missing – canonical metadata columns that could not be resolved.

• available – source columns that were available for explicit mapping.

Retain the unresolved and available columns for programmatic repair.

class spacr.metadata_resolution.MetadataDecision

One all-at-once answer returned by a UI or a saved setting.

Parameters:

• column_map – mapping from each canonical target name to an existing source column, applied collision-safely before identity derivation.

• well_column – optional source column whose values are parsed strictly as well labels to supply missing rowID and columnID values.

• pseudo_source – optional source column whose distinct typed values receive pseudo row and column coordinates when real well metadata is unavailable.

• allow_pseudo – explicit permission to synthesize coordinates from pseudo_source; the source alone never changes the frame.

• save_path – optional JSON audit destination written after successful resolution with the decision and generated pseudo-well assignments.

• remember – whether a prompted decision is cached under a supplied cache_key for the remainder of the current process.

class spacr.metadata_resolution.MetadataRequest

All unresolved targets and evidence shown to one prompt.

Parameters:

• missing – canonical columns that still require a decision.

• available – source columns available for mapping.

• examples – representative string values for each source column.

• guesses – best-effort source-column suggestion for each target.

class spacr.metadata_resolution.ResolutionResult

Resolved frame plus the auditable decisions that changed it.

Parameters:

• frame – normalized frame containing every required metadata column.

• column_map – explicit canonical-target to source-column mappings used.

• derived_from_well – well column used to derive row and column IDs, if derivation was necessary.

• pseudo_map – audited source identities and their generated pseudo well coordinates.

spacr.metadata_resolution.build_metadata_request(frame: pandas.DataFrame, required: Iterable[str]) → MetadataRequest

Build the single request a GUI displays for every missing column.

Parameters:

• frame – metadata frame whose current columns and examples are shown.

• required – canonical columns that the calling workflow requires.

spacr.metadata_resolution.clear_run_metadata_decisions() → None

Clear remembered prompt answers (primarily for tests/new runs).

spacr.metadata_resolution.resolve_metadata_columns(frame: pandas.DataFrame, required: Iterable[str], *, column_map: Mapping[str, str] | None = None, well_column: str | None = None, pseudo_source: str | None = None, allow_pseudo: bool = False, prompt: Callable[[MetadataRequest], MetadataDecision] | None = None, cache_key: str | None = None, save_path: str | None = None) → ResolutionResult

Resolve every required metadata column in one deterministic pass.

Parameters:

• frame – source metadata frame to normalize and resolve.

• required – canonical columns that must be present in the result.

column_map is {canonical_target: actual_source}. A prompt, when supplied, is called at most once and receives all unresolved columns. Without one, missing columns raise MetadataResolutionRequired with the non-interactive settings needed to proceed.

Nested helpers

build_metadata_request.comparable(value: str) → str

Reduce a metadata name to case-insensitive alphanumeric text.

Parameters:

value – canonical or source column name to compare.

Returns:

case-folded name with punctuation and whitespace removed.

spacr/metadata_resolution.py:141

build_metadata_request.guess_score(source: str, target_key: str = target_key, target_root: str = target_root) → float

Score one available column against the current missing target.

Parameters:

• source – available source-column name to rank.

• target_key – normalized current target, bound when the scorer is created so the surrounding loop cannot change it.

• target_root – target without an id or label suffix, likewise bound for this scorer.

Returns:

sequence similarity plus a root-name bonus when the target without an id or label suffix occurs in the normalized source name.

spacr/metadata_resolution.py:154