aind-metadata-reader 0.2.0__py3-none-any.whl

aind_metadata_reader/readers.py

@@ -0,0 +1,541 @@
+"""Partial semantic views never require metadata to satisfy an upstream schema."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from aind_metadata_reader._wire import canonical
+from aind_metadata_reader.components import ArtifactReference, CodeView, references
+from aind_metadata_reader.diagnostics import Diagnostic, FieldState, MetadataError
+from aind_metadata_reader.document import Document, Field
+from aind_metadata_reader.formats import ReaderSelection, select_reader
+from aind_metadata_reader.inspection import (
+    ReadStatus,
+    ReadValue,
+    as_string,
+    children,
+    diagnostics,
+    issue,
+    object_view,
+    observe,
+    unavailable,
+)
+from aind_metadata_reader.validation import ValidationReport, validate
+
+
+def _core(document: Document, name: str) -> ReadValue[Document]:
+    field = document.field("/" + name)
+    return object_view(document.field("") if field.state == FieldState.ABSENT else field)
+
+
+def _context(
+    document: Document, core: Literal["processing", "acquisition"], hint: str | None
+) -> ReadValue[ReaderSelection]:
+    try:
+        return ReadValue(document.field(""), ReadStatus.AVAILABLE, select_reader(document, core, hint))
+    except (ValueError, TypeError) as error:
+        diagnostic = (
+            error.diagnostic
+            if isinstance(error, MetadataError)
+            else issue(document.field(""), "unsupported_format", str(error))
+        )
+        return ReadValue(document.field(""), ReadStatus.UNSUPPORTED, diagnostics=(diagnostic,))
+
+
+_DIRECTIONS = {
+    "lefttoright": "R",
+    "leftright": "R",
+    "righttoleft": "L",
+    "rightleft": "L",
+    "anteriortoposterior": "P",
+    "anteriorposterior": "P",
+    "posteriortoanterior": "A",
+    "posterioranterior": "A",
+    "superiortoinferior": "I",
+    "superiorinferior": "I",
+    "inferiortosuperior": "S",
+    "inferiorsuperior": "S",
+}
+
+
+@dataclass(frozen=True)
+class Axis:
+    """An inspected axis can retain incomplete or unfamiliar recorded meanings."""
+
+    document: Document
+    name: str | None
+    position: int
+    direction: str | None
+    unit: str | None
+    dimension: int | None = None
+    field: Field | None = None
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+    @property
+    def anatomical_direction(self) -> str | None:
+        """Return recognized ITK direction letters; unfamiliar terms remain in direction."""
+        return _DIRECTIONS.get(re.sub(r"[^a-z]", "", (self.direction or "").lower()))
+
+
+@dataclass(frozen=True)
+class CoordinateFrame:
+    """One recorded frame and independent interpretations of its axes and orientation."""
+
+    document: Document
+    scope: Literal["legacy", "local", "global"]
+    name: str | None
+    axes: tuple[Axis, ...]
+    configuration: Document | None = None
+    axes_read: ReadValue[tuple[Axis, ...]] | None = None
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+    @property
+    def orientation(self) -> ReadValue[str]:
+        """Explain when recorded axes cannot establish a cardinal 3D orientation."""
+        letters = "".join(axis.anatomical_direction or "?" for axis in self.axes)
+        if len(letters) == 3 and all(sum(letter in pair for letter in letters) == 1 for pair in ("LR", "AP", "SI")):
+            return ReadValue(self.document.field("/axes"), ReadStatus.AVAILABLE, letters)
+        return unavailable(
+            self.document.field("/axes"),
+            ReadStatus.UNSUPPORTED,
+            "Axes do not establish a cardinal 3D orientation",
+            "unsupported_geometry",
+        )
+
+    @property
+    def anatomical_orientation(self) -> str | None:
+        """Inspect orientation without making a valid cardinal frame a reading prerequisite."""
+        return self.orientation.value
+
+
+def _dimension(value: Any) -> int:
+    if isinstance(value, bool) or not (
+        isinstance(value, int) or isinstance(value, str) and value.isascii() and value.isdigit()
+    ):
+        raise MetadataError("Array dimension must be a nonnegative integer")
+    number = int(value)
+    if number < 0:
+        raise MetadataError("Array dimension must be nonnegative")
+    return number
+
+
+def _axes(document: Document, legacy: bool) -> ReadValue[tuple[Axis, ...]]:
+    entries = children(document, "/axes")
+    if entries.status != ReadStatus.AVAILABLE:
+        return ReadValue(entries.field, entries.status, diagnostics=entries.diagnostics)
+    axes = []
+    issues = list(entries.diagnostics)
+    for i, entry in enumerate(entries.value or ()):
+        if entry.value is None:
+            axes.append(Axis(document, None, i, None, None, field=entry.field, diagnostics=entry.diagnostics))
+            continue
+        axis = entry.value
+        name = observe(axis.field("/name"), as_string)
+        direction = observe(axis.field("/direction"), as_string)
+        unit = observe(axis.field("/unit") if legacy else document.field("/axis_unit"), as_string)
+        dimension = (
+            observe(axis.field("/dimension"), _dimension)
+            if legacy
+            else ReadValue(axis.field("/dimension"), ReadStatus.UNSUPPORTED)
+        )
+        local = diagnostics(name, direction, unit, dimension)
+        if direction.value is not None and re.sub(r"[^a-z]", "", direction.value.lower()) not in _DIRECTIONS:
+            local += (issue(direction.field, "unsupported_direction", "Unfamiliar anatomical direction retained"),)
+        axes.append(
+            Axis(
+                axis,
+                name.value.lower() if name.value is not None else None,
+                i,
+                direction.value,
+                unit.value,
+                dimension.value,
+                entry.field,
+                local,
+            )
+        )
+        issues.extend(local)
+    if not axes:
+        issues.append(issue(entries.field, "absent", "No axes recorded"))
+    if len({axis.name for axis in axes}) != len(axes):
+        issues.append(issue(entries.field, "ambiguous", "Axis names do not identify unique coordinates"))
+    return ReadValue(entries.field, ReadStatus.AVAILABLE, tuple(axes), tuple(issues))
+
+
+def _frame_entries(
+    document: Document, names: tuple[str, ...], scope: Literal["local", "global"], configuration: Document | None = None
+) -> tuple[ReadValue[CoordinateFrame], ...]:
+    fields = [document.field("/" + name) for name in names]
+    present = [f for f in fields if f.state == FieldState.PRESENT]
+    if not present:
+        return tuple(ReadValue(f, ReadStatus.NULL) for f in fields if f.state == FieldState.NULL)
+    conflict = len(present) > 1 and any(canonical(f.value) != canonical(present[0].value) for f in present[1:])
+    # Equal aliases identify one recorded frame; conflicting aliases remain separate.
+    selected = present if conflict else present[:1]
+    results: list[ReadValue[CoordinateFrame]] = []
+    for source in selected:
+        frame = object_view(source)
+        if frame.value is None:
+            results.append(ReadValue(source, frame.status, diagnostics=frame.diagnostics))
+            continue
+        axes = _axes(frame.value, False)
+        frame_issues = axes.diagnostics
+        if conflict:
+            frame_issues += (issue(source, "ambiguous", "Conflicting deprecated and replacement coordinate systems"),)
+        view = CoordinateFrame(
+            frame.value,
+            scope,
+            observe(frame.value.field("/name"), as_string).value,
+            axes.value or (),
+            configuration,
+            axes,
+            frame_issues,
+        )
+        results.append(ReadValue(source, ReadStatus.AVAILABLE, view, frame_issues))
+    return tuple(results)
+
+
+@dataclass(frozen=True)
+class Acquisition:
+    """Inspection preserves a core even when some or all imaging capabilities are unavailable."""
+
+    document: Document
+    reader: ReaderSelection | None
+    frames: tuple[CoordinateFrame, ...]
+    frame_scope: str | None = None
+    diagnostics: tuple[Diagnostic, ...] = ()
+    frame_entries: ReadValue[tuple[ReadValue[CoordinateFrame], ...]] | None = None
+    source: Field | None = None
+
+    @property
+    def raw(self) -> Any:
+        """Retain the selected core even when it is not an object."""
+        return self.source.value if self.source is not None else self.document.raw
+
+    @property
+    def validation(self) -> ValidationReport:
+        """Reading makes no schema-validation claim."""
+        return validate(self.source if self.source is not None else self.document)
+
+    def select_frame(self, *, pointer: str | None = None, scope: str | None = None) -> ReadValue[CoordinateFrame]:
+        """Return an inspectable selection instead of requiring an unambiguous frame."""
+        scope = self.frame_scope if scope is None else scope
+        frames = tuple(
+            f
+            for f in self.frames
+            if (scope is None or f.scope == scope) and (pointer is None or f.document.pointer == pointer)
+        )
+        if len(frames) == 1:
+            return ReadValue(frames[0].document.field(""), ReadStatus.AVAILABLE, frames[0])
+        return unavailable(
+            self.document.field(""),
+            ReadStatus.AMBIGUOUS if frames else ReadStatus.ABSENT,
+            f"Expected one coordinate frame, found {len(frames)}; select a frame pointer or scope",
+        )
+
+    def one_frame(self, *, pointer: str | None = None, scope: str | None = None) -> CoordinateFrame:
+        """Explicitly require one frame; ordinary inspection uses select_frame()."""
+        return self.select_frame(pointer=pointer, scope=scope).require()
+
+    @property
+    def axes(self) -> tuple[Axis, ...]:
+        """Inspect available axes; selection diagnostics remain in select_frame()."""
+        frame = self.select_frame().value
+        return () if frame is None else frame.axes
+
+    @property
+    def array_mapping(self) -> ReadValue[tuple[Axis, ...]]:
+        """Expose whether explicit dimensions establish a usable array mapping."""
+        frame = self.select_frame()
+        if frame.value is None:
+            return ReadValue(frame.field, frame.status, diagnostics=frame.diagnostics)
+        axes = frame.value.axes
+        if not axes or any(a.dimension is None for a in axes):
+            return unavailable(
+                frame.field, ReadStatus.UNSUPPORTED, "Array dimensions are not established", "unsupported_capability"
+            )
+        if len({a.dimension for a in axes}) != len(axes):
+            return unavailable(frame.field, ReadStatus.INVALID, "Array dimensions are not unique")
+        return ReadValue(frame.field, ReadStatus.AVAILABLE, tuple(sorted(axes, key=lambda a: a.dimension or 0)))
+
+    @property
+    def array_axes(self) -> tuple[Axis, ...]:
+        """Return available array axes; array_mapping explains unavailable interpretations."""
+        return self.array_mapping.value or ()
+
+
+def read_acquisition(
+    document: Document,
+    *,
+    device_name: str | None = None,
+    stream_index: int | None = None,
+    frame_scope: Literal["legacy", "local", "global"] | None = None,
+    format_hint: str | None = None,
+) -> Acquisition:
+    """Inspect recognized components without requiring valid metadata or guessing unknown layouts."""
+    core = _core(document, "acquisition")
+    if core.value is None:
+        missing: ReadValue[tuple[ReadValue[CoordinateFrame], ...]] = ReadValue(
+            core.field, core.status, diagnostics=core.diagnostics
+        )
+        return Acquisition(document, None, (), frame_scope, core.diagnostics, missing, core.field)
+    document = core.value
+    context = _context(document, "acquisition", format_hint)
+    if context.value is None:
+        unavailable_entries: ReadValue[tuple[ReadValue[CoordinateFrame], ...]] = ReadValue(
+            document.field(""), ReadStatus.UNSUPPORTED, diagnostics=context.diagnostics
+        )
+        return Acquisition(document, None, (), frame_scope, context.diagnostics, unavailable_entries, core.field)
+    reader = context.value
+    if reader.format.layout == "legacy":
+        axes = _axes(document, True)
+        frame = CoordinateFrame(
+            document, "legacy", None, axes.value or (), axes_read=axes, diagnostics=axes.diagnostics
+        )
+        issues = axes.diagnostics
+        if device_name is not None or stream_index is not None:
+            issues += (
+                issue(core.field, "unsupported_selection", "Legacy acquisition has no device/stream selection mapping"),
+            )
+            selected: ReadValue[tuple[ReadValue[CoordinateFrame], ...]] = ReadValue(
+                core.field, ReadStatus.UNSUPPORTED, diagnostics=issues
+            )
+            return Acquisition(document, reader, (), frame_scope, issues, selected, core.field)
+        entries: ReadValue[tuple[ReadValue[CoordinateFrame], ...]] = ReadValue(
+            core.field, ReadStatus.AVAILABLE, (ReadValue(core.field, ReadStatus.AVAILABLE, frame, issues),), issues
+        )
+        return Acquisition(document, reader, (frame,), frame_scope, issues, entries, core.field)
+    return _configured_acquisition(document, reader, device_name, stream_index, frame_scope)
+
+
+def _configured_acquisition(
+    document: Document, reader: ReaderSelection, device: str | None, stream: int | None, scope: str | None
+) -> Acquisition:
+    biodata = reader.format.family == "biodata"
+    global_names = ("global_coordinate_system",) if biodata else ("global_coordinate_system", "coordinate_system")
+    local_names = ("local_coordinate_system",) if biodata else ("local_coordinate_system", "coordinate_system")
+    entries = list(_frame_entries(document, global_names, "global"))
+    streams = children(document, "/data_streams")
+    issues = list(streams.diagnostics)
+    selected = 0
+    for i, entry in enumerate(streams.value or ()):
+        if stream is not None and stream != i or entry.value is None:
+            continue
+        configs = children(entry.value, "/configurations")
+        issues.extend(configs.diagnostics)
+        for config in configs.value or ():
+            if config.value is None:
+                continue
+            doc = config.value
+            if doc.field("/object_type").value != "Imaging config":
+                continue
+            if device is not None and doc.field("/device_name").value != device:
+                continue
+            selected += 1
+            entries.extend(_frame_entries(doc, local_names, "local", doc))
+    if (device is not None and not selected) or (stream is not None and not 0 <= stream < len(streams.value or ())):
+        issues.append(issue(document.field(""), "absent", "No imaging configuration matches the requested selection"))
+        entries = []
+    issues.extend(d for entry in entries for d in entry.diagnostics)
+    frames = tuple(entry.value for entry in entries if entry.value is not None)
+    result = ReadValue(document.field(""), ReadStatus.AVAILABLE, tuple(entries), tuple(issues))
+    return Acquisition(document, reader, frames, scope, tuple(issues), result, document.field(""))
+
+
+@dataclass(frozen=True)
+class Process:
+    """A process remains inspectable when code, inputs, or pipeline relationships are incomplete."""
+
+    document: Document
+    legacy: bool
+    process_type: str | None
+    name: str | None
+    code_version: str | None
+    code_url: str | None
+    pipeline_name: str | None
+    pipeline_version: str | None
+    input_location: str | None
+    output_location: str | None
+    pipeline: Document | None = None
+    reader: ReaderSelection | None = None
+    code: CodeView | None = None
+    outputs: ReadValue[tuple[ArtifactReference, ...]] | None = None
+    diagnostics: tuple[Diagnostic, ...] = ()
+
+    @property
+    def parameters_field(self) -> Field:
+        """Retain the actual parameters field, including malformed code parents."""
+        return self.code.parameters.field if self.code is not None else self.document.field("/parameters")
+
+    @property
+    def parameters(self) -> dict[str, Any] | None:
+        """Return available parameters; code.parameters explains any limitation."""
+        return None if self.code is None else self.code.parameters.value
+
+    @property
+    def inputs(self) -> ReadValue[tuple[ArtifactReference, ...]]:
+        """Keep file, asset, and grouped-asset references distinct."""
+        return (
+            self.code.inputs
+            if self.code is not None
+            else unavailable(self.document.field(""), ReadStatus.UNSUPPORTED, "Code view unavailable")
+        )
+
+    @property
+    def input_data(self) -> list[dict[str, Any]] | None:
+        """Compatibility access to recorded nested asset objects without guessing file paths."""
+        value = self.document.field("/code/input_data").value
+        return value if isinstance(value, list) and all(isinstance(v, dict) for v in value) else None
+
+
+@dataclass(frozen=True)
+class Processing:
+    """Ordered partial processes and every original entry, including uninterpretable nodes."""
+
+    document: Document
+    reader: ReaderSelection | None
+    processes: tuple[Process, ...]
+    diagnostics: tuple[Diagnostic, ...] = ()
+    process_entries: ReadValue[tuple[ReadValue[Process], ...]] | None = None
+    source: Field | None = None
+
+    @property
+    def raw(self) -> Any:
+        """Retain malformed or unsupported cores without interpreting them as empty data."""
+        return self.source.value if self.source is not None else self.document.raw
+
+    @property
+    def validation(self) -> ValidationReport:
+        """Interpretation availability makes no upstream-schema validity claim."""
+        return validate(self.source if self.source is not None else self.document)
+
+    def find(self, process_type: str) -> tuple[Process, ...]:
+        """Match recorded vocabulary values without a closed enumeration of allowed nouns."""
+        return tuple(p for p in self.processes if p.process_type == process_type)
+
+    def select(self, process_type: str) -> ReadValue[Process]:
+        """Inspect an ambiguous or unavailable selection without raising."""
+        matches = self.find(process_type)
+        if len(matches) == 1:
+            return ReadValue(matches[0].document.field(""), ReadStatus.AVAILABLE, matches[0])
+        return unavailable(
+            self.document.field(""),
+            ReadStatus.AMBIGUOUS if matches else ReadStatus.ABSENT,
+            f"Expected one {process_type!r} process, found {len(matches)}",
+        )
+
+    def one(self, process_type: str) -> Process:
+        """Explicitly require one matching process; use select() for ordinary inspection."""
+        return self.select(process_type).require()
+
+
+def _process(item: Document, reader: ReaderSelection, container: Document, pipelines: tuple[Document, ...]) -> Process:
+    legacy = reader.format.layout == "legacy"
+    code = CodeView(item.field("") if legacy else item.field("/code"), "legacy" if legacy else "nested")
+    process_type = observe(item.field("/name" if legacy else "/process_type"), as_string)
+    name = observe(item.field("/name"), as_string)
+    in_legacy_pipeline = legacy and item.pointer.startswith(container.pointer + "/data_processes/")
+    pipeline_name = observe(
+        container.field("/pipeline_name") if in_legacy_pipeline else item.field("/pipeline_name"), as_string
+    )
+    matches = (
+        (container,)
+        if in_legacy_pipeline
+        else tuple(
+            p for p in pipelines if pipeline_name.value is not None and p.field("/name").value == pipeline_name.value
+        )
+    )
+    pipeline = matches[0] if len(matches) == 1 else None
+    pv = (
+        observe(pipeline.field("/pipeline_version" if legacy else "/version"), as_string)
+        if pipeline is not None
+        else None
+    )
+    output = references(item.field("/output_location" if legacy else "/output_path"), "paths")
+    singleton = output.value[0].location.value if output.value is not None and len(output.value) == 1 else None
+    input_path = observe(item.field("/input_location"), as_string).value if legacy else None
+    issues = diagnostics(
+        process_type, name, pipeline_name, code.version, code.url, code.parameters, code.inputs, output
+    )
+    if pv is not None:
+        issues += pv.diagnostics
+    if pipeline_name.value is not None and len(matches) != 1:
+        issues += (
+            issue(
+                pipeline_name.field,
+                "unresolved_reference" if not matches else "ambiguous",
+                "Pipeline reference does not identify one recorded pipeline",
+            ),
+        )
+    return Process(
+        item,
+        legacy,
+        process_type.value,
+        name.value,
+        code.version.value,
+        code.url.value,
+        pipeline_name.value,
+        None if pv is None else pv.value,
+        input_path,
+        singleton,
+        pipeline,
+        reader,
+        code,
+        output,
+        issues,
+    )
+
+
+def read_processing(document: Document, *, format_hint: str | None = None) -> Processing:
+    """Inspect known parts independently; preserve unknown versions and invalid entries with diagnostics."""
+    core = _core(document, "processing")
+    if core.value is None:
+        missing: ReadValue[tuple[ReadValue[Process], ...]] = ReadValue(
+            core.field, core.status, diagnostics=core.diagnostics
+        )
+        return Processing(document, None, (), core.diagnostics, missing, core.field)
+    document = core.value
+    context = _context(document, "processing", format_hint)
+    if context.value is None:
+        unavailable_entries: ReadValue[tuple[ReadValue[Process], ...]] = ReadValue(
+            core.field, ReadStatus.UNSUPPORTED, diagnostics=context.diagnostics
+        )
+        return Processing(document, None, (), context.diagnostics, unavailable_entries, core.field)
+    reader = context.value
+    legacy = reader.format.layout == "legacy"
+    container = object_view(document.field("/processing_pipeline")) if legacy else object_view(core.field)
+    pipeline_entries = children(document, "/pipelines") if not legacy else None
+    pipelines = (
+        tuple(entry.value for entry in pipeline_entries.value or () if entry.value is not None)
+        if pipeline_entries is not None
+        else ()
+    )
+    collections = [children(container.value, "/data_processes")] if container.value is not None else []
+    if legacy:
+        collections.append(children(document, "/analyses"))
+    entries: list[ReadValue[Process]] = []
+    issues = list(container.diagnostics) + ([] if pipeline_entries is None else list(pipeline_entries.diagnostics))
+    for collection in collections:
+        issues.extend(collection.diagnostics)
+        for entry in collection.value or ():
+            if entry.value is None:
+                entries.append(ReadValue(entry.field, entry.status, diagnostics=entry.diagnostics))
+                continue
+            view = _process(entry.value, reader, container.value or document, pipelines)
+            entries.append(ReadValue(entry.field, ReadStatus.AVAILABLE, view, view.diagnostics))
+            issues.extend(view.diagnostics)
+    processes = tuple(entry.value for entry in entries if entry.value is not None)
+    status = _collection_status(collections, container)
+    inspected = ReadValue(core.field, status, tuple(entries) if status == ReadStatus.AVAILABLE else None, tuple(issues))
+    return Processing(document, reader, processes, tuple(issues), inspected, core.field)
+
+
+def _collection_status(
+    collections: list[ReadValue[tuple[ReadValue[Document], ...]]], container: ReadValue[Document]
+) -> ReadStatus:
+    if any(c.status == ReadStatus.AVAILABLE for c in collections):
+        return ReadStatus.AVAILABLE
+    if container.status != ReadStatus.AVAILABLE:
+        return container.status
+    return next((c.status for c in collections if c.status != ReadStatus.ABSENT), ReadStatus.ABSENT)