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

aind_metadata_reader/smartspim.py

@@ -0,0 +1,214 @@
+"""Conservative SmartSPIM metadata interpretations, selected explicitly by callers."""
+
+from __future__ import annotations
+
+import math
+from pathlib import PurePosixPath
+from typing import Any
+from urllib.parse import urlsplit
+
+from aind_metadata_reader.applicability import Applicability, RuleEvaluation
+from aind_metadata_reader.components import ArtifactReference, references
+from aind_metadata_reader.document import Document
+from aind_metadata_reader.inspection import ReadStatus, ReadValue, unavailable
+from aind_metadata_reader.interpretation import Change
+from aind_metadata_reader.readers import Process
+
+_RULE = "smartspim.LS-17"
+_REVISION = "1"
+# Exact component versions observed in retained production captures. No known fix
+# boundary exists: neither pipeline nor registration versions substitute for these.
+_OBSERVED_FUSION_VERSIONS = frozenset(("0.0.2", "0.0.4"))
+
+
+def _vector(value: Any, size: int, *, positive: bool = False) -> list[float]:
+    if not isinstance(value, list) or len(value) != size:
+        raise ValueError("Transform vector has the wrong dimensionality")
+    if any(type(v) not in (int, float) or not math.isfinite(v) or (positive and v <= 0) for v in value):
+        raise ValueError("Transform vector must contain finite numbers with valid signs")
+    return [float(v) for v in value]
+
+
+def _transforms(value: Any, size: int) -> tuple[list[float], list[float], bool]:
+    if not isinstance(value, list) or not 1 <= len(value) <= 2:
+        raise ValueError("Expected a scale followed by an optional translation")
+    scale = value[0]
+    if not isinstance(scale, dict) or set(scale) != {"type", "scale"} or scale["type"] != "scale":
+        raise ValueError("Unsupported transform composition")
+    spacing = _vector(scale["scale"], size, positive=True)
+    if len(value) == 1:
+        return spacing, [0.0] * size, False
+    translation = value[1]
+    if (
+        not isinstance(translation, dict)
+        or set(translation) != {"type", "translation"}
+        or translation["type"] != "translation"
+    ):
+        raise ValueError("Unsupported transform composition")
+    return spacing, _vector(translation["translation"], size), True
+
+
+def _close(left: list[float], right: list[float]) -> bool:
+    return all(math.isclose(a, b, rel_tol=1e-10, abs_tol=1e-12) for a, b in zip(left, right, strict=True))
+
+
+def _geometry(attributes: Document) -> tuple[list[dict[str, Any]], list[list[dict[str, Any]]]]:
+    """Recognize only the observed NGFF 0.4, dyadic block-mean geometry."""
+    multiscales = attributes.raw.get("multiscales")
+    if not isinstance(multiscales, list) or len(multiscales) != 1 or not isinstance(multiscales[0], dict):
+        raise ValueError("Expected one multiscale image")
+    image = multiscales[0]
+    if image.get("version") != "0.4":
+        raise ValueError("Only the observed NGFF 0.4 representation is supported")
+    axes = image.get("axes")
+    if not isinstance(axes, list) or any(not isinstance(axis, dict) for axis in axes):
+        raise ValueError("Expected explicit axis objects")
+    names = [axis.get("name") for axis in axes]
+    if len(names) != len(set(names)) or set(names) != {"t", "c", "z", "y", "x"}:
+        raise ValueError("Expected distinct t, c, z, y, x axes")
+    spatial = [i for i, axis in enumerate(axes) if axis.get("type") == "space"]
+    if {names[i] for i in spatial} != {"x", "y", "z"} or any(axes[i].get("unit") != "micrometer" for i in spatial):
+        raise ValueError("Expected three spatial axes in micrometers")
+    global_transforms = image.get("coordinateTransformations")
+    if global_transforms is not None:
+        global_scale, _, global_translation = _transforms(global_transforms, len(axes))
+        if global_translation or global_scale != [1.0] * len(axes):
+            raise ValueError("Nonidentity image-level transforms need a different rule")
+    datasets = image.get("datasets")
+    if not isinstance(datasets, list) or not datasets or any(not isinstance(d, dict) for d in datasets):
+        raise ValueError("Expected nonempty pyramid datasets")
+    if [d.get("path") for d in datasets] != [str(i) for i in range(len(datasets))]:
+        raise ValueError("Expected the observed contiguous level paths starting at zero")
+    vectors = [_transforms(d.get("coordinateTransformations"), len(axes)) for d in datasets]
+    base_scale, origin, _ = vectors[0]
+    replacements = []
+    for level, (scale, translation, has_translation) in enumerate(vectors):
+        ratio = 2**level
+        expected_scale = [s * ratio if i in spatial else s for i, s in enumerate(base_scale)]
+        if not _close(scale, expected_scale):
+            raise ValueError("Pyramid scales do not match the observed dyadic spatial reduction")
+        offset = (ratio - 1) / 2
+        physical = [o + offset * base_scale[i] if i in spatial else o for i, o in enumerate(origin)]
+        voxel_counts = [o + offset if i in spatial else o for i, o in enumerate(origin)]
+        if not _close(translation, physical):
+            missing = not has_translation and _close(origin, [0.0] * len(axes))
+            if not missing and not (has_translation and _close(translation, voxel_counts)):
+                raise ValueError("Stored translations match neither corrected geometry nor an observed LS-17 signature")
+        replacements.append([{"type": "scale", "scale": scale}, {"type": "translation", "translation": physical}])
+    return datasets, replacements
+
+
+def evaluate_ls17(
+    attributes: Document,
+    producer: Process,
+    *,
+    author: str,
+    association_evidence: tuple[str, ...] = (),
+    averaging_evidence: tuple[str, ...] = (),
+) -> RuleEvaluation:
+    """Propose physical translations only for evidenced, known-buggy fused outputs.
+
+    Callers must attest that the selected process produced this artifact and that
+    its pyramid uses block averaging. A matching channel basename is an additional
+    check, not proof of association. Evaluation performs no IO or application.
+    """
+    evidence = (
+        f"artifact {attributes.snapshot.content_digest}{attributes.pointer}",
+        f"producer {producer.document.snapshot.content_digest}{producer.document.pointer}",
+        *association_evidence,
+        *averaging_evidence,
+    )
+    inputs = (attributes.reference(), producer.document.reference())
+    readers = () if producer.reader is None else (producer.reader.record_for(producer.document),)
+    implementation = "aind_metadata_reader.smartspim.evaluate_ls17/1"
+
+    def decision(outcome: Applicability, reason: str, changes: tuple[Change, ...] = ()) -> RuleEvaluation:
+        return RuleEvaluation(_RULE, _REVISION, outcome, reason, evidence, changes, inputs, readers, implementation)
+
+    if producer.process_type != "Image tile fusing":
+        return decision(Applicability.UNKNOWN, "The selected process does not identify the fusion producer")
+    if producer.code_version not in _OBSERVED_FUSION_VERSIONS:
+        return decision(Applicability.UNKNOWN, "Fusion component version is missing or outside the observed buggy set")
+    if (
+        not association_evidence
+        or not averaging_evidence
+        or any(not isinstance(e, str) or not e.strip() for e in (*association_evidence, *averaging_evidence))
+    ):
+        return decision(Applicability.UNKNOWN, "Artifact association and block-averaging evidence are required")
+    locator = attributes.snapshot.source.locator
+    output = producer.output_location
+    if not locator or not output:
+        return decision(Applicability.UNKNOWN, "Artifact locator and producer output path are required")
+    try:
+        artifact_path = PurePosixPath(urlsplit(locator).path)
+        channel = PurePosixPath(urlsplit(output).path).name
+    except ValueError:
+        return decision(Applicability.UNKNOWN, "Artifact or producer output locator is malformed")
+    if artifact_path.name != ".zattrs" or artifact_path.parent.name != channel or not channel.endswith(".zarr"):
+        return decision(Applicability.UNKNOWN, "Artifact channel and producer output path disagree")
+    try:
+        datasets, replacements = _geometry(attributes)
+    except (ValueError, TypeError, OverflowError) as error:
+        return decision(Applicability.UNKNOWN, str(error))
+    changes = []
+    # Level zero establishes the origin. It must never acquire a centering offset.
+    for level, (dataset, replacement) in enumerate(zip(datasets, replacements, strict=True)):
+        if level == 0:
+            continue
+        _, recorded, _ = _transforms(dataset["coordinateTransformations"], len(replacement[0]["scale"]))
+        if _close(recorded, replacement[1]["translation"]):
+            continue
+        changes.append(
+            Change.propose(
+                attributes,
+                f"/multiscales/0/datasets/{level}/coordinateTransformations",
+                replacement,
+                operation_id=f"{_RULE}/{_REVISION}/level-{level}",
+                rule_id=_RULE,
+                rule_revision=_REVISION,
+                implementation=implementation,
+                kind="correction",
+                author=author,
+                reason="Place block-averaged voxel centers in the declared physical units",
+                evidence=evidence,
+                scope=f"Physical geometry of fused pyramid level {level}; not a historical registration frame",
+                references=inputs,
+                readers=readers,
+            )
+        )
+    if not changes:
+        return decision(
+            Applicability.NOT_APPLICABLE, "Stored translations already match the block-averaged physical geometry"
+        )
+    return decision(
+        Applicability.APPLICABLE,
+        "Known fusion version and observed LS-17 signature with explicit evidence",
+        tuple(changes),
+    )
+
+
+def registration_input(process: Process) -> ReadValue[tuple[ArtifactReference, ...]]:
+    """Inspect evidenced file inputs to the SmartSPIM registration import step.
+
+    Version 0.0.37 records this input in output_parameters.input_location.
+    This observed convention is not extrapolated to unverified producer versions
+    or interpreted as a generic Code input_data asset-to-file conversion.
+    """
+    if process.process_type != "Image importing":
+        return unavailable(
+            process.document.field(""), ReadStatus.UNSUPPORTED, "Process is not a registration import step"
+        )
+    inputs = process.inputs
+    if inputs.status == ReadStatus.AVAILABLE and inputs.value and all(r.kind == "file" for r in inputs.value):
+        return inputs
+    repository = (process.code_url or "").rstrip("/").removesuffix(".git")
+    if (
+        process.code_version == "0.0.37"
+        and repository == "https://github.com/AllenNeuralDynamics/aind-smartspim-ccf-registration"
+    ):
+        return references(process.document.field("/output_parameters/input_location"), "paths")
+    return unavailable(
+        process.document.field(""),
+        ReadStatus.UNSUPPORTED,
+        "Producer evidence does not establish a file-level registration input",
+    )

aind_metadata_reader/validation.py

@@ -0,0 +1,89 @@
+"""Optional validation reports never gate inspection or alter historical metadata."""
+
+from dataclasses import dataclass
+from importlib import import_module
+from importlib.metadata import version
+from typing import Literal, NoReturn
+
+from aind_metadata_reader.diagnostics import Diagnostic, FieldState
+from aind_metadata_reader.document import Document, Field, SnapshotReference, encode_segment
+
+
+@dataclass(frozen=True)
+class ValidationReport:
+    """A scoped JSON Schema result, not an upstream-model or scientific validity claim."""
+
+    document: SnapshotReference
+    status: Literal["not_checked", "valid", "invalid", "unavailable"]
+    schema: SnapshotReference | None = None
+    validator: str | None = None
+    diagnostics: tuple[Diagnostic, ...] = ()
+    dialect: str | None = None
+
+
+def _no_remote(uri: str) -> NoReturn:
+    raise LookupError(f"External schema reference is not supplied: {uri}")
+
+
+def validate(
+    document: Document | Field, schema: Document | None = None, *, dialect: str | None = None
+) -> ValidationReport:
+    """Check a supplied historical JSON Schema without fetching, filling defaults, or coercing.
+
+    No schema means not checked. Missing validator support, an unusable schema,
+    or unresolved references mean unavailable, not invalid metadata. Custom
+    Pydantic model validators and scientific correctness are outside this report.
+    """
+    reference = SnapshotReference(
+        document.snapshot.snapshot_id,
+        document.snapshot.content_digest,
+        document.snapshot.original_digest,
+        document.snapshot.source,
+        document.pointer,
+    )
+    if schema is None:
+        return ValidationReport(reference, "not_checked")
+    try:
+        if isinstance(document, Field) and document.state == FieldState.ABSENT:
+            raise ValueError("An absent field is not a serialized instance to validate")
+        package = import_module("jsonschema")
+        referencing = import_module("referencing")
+        declared = schema.raw.get("$schema")
+        if dialect is not None and declared is not None and dialect != declared:
+            raise ValueError("Supplied dialect conflicts with the schema's declaration")
+        selected = declared or dialect
+        checker = package.validators.validator_for({"$schema": selected}, default=None) if selected else None
+        if checker is None:
+            # Upstream exported schemas can omit $schema. Their caller must select
+            # a dialect explicitly rather than inheriting the installed latest.
+            raise ValueError("Schema must declare a supported $schema dialect")
+        checker.check_schema(schema.raw)
+        validator = checker(schema.raw, registry=referencing.Registry(retrieve=_no_remote))
+        errors = tuple(validator.iter_errors(document.raw if isinstance(document, Document) else document.value))
+        issues = tuple(
+            Diagnostic(
+                "schema_validation",
+                error.message,
+                document.pointer + "".join("/" + encode_segment(str(p)) for p in error.absolute_path),
+                document.snapshot.snapshot_id,
+            )
+            for error in errors
+        )
+        return ValidationReport(
+            reference,
+            "invalid" if issues else "valid",
+            schema.reference(),
+            f"jsonschema/{version('jsonschema')}; assertions only; formats not checked",
+            issues,
+            selected,
+        )
+    except Exception as error:  # noqa: BLE001 - optional validator failures are reported, never reading gates
+        return ValidationReport(
+            reference,
+            "unavailable",
+            schema.reference(),
+            diagnostics=(
+                Diagnostic("validation_unavailable", str(error), schema.pointer, schema.snapshot.snapshot_id),
+            ),
+            dialect=dialect,
+        )