bone-imaging-derivatives 0.1.0__tar.gz

bone_imaging_derivatives-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bone Imaging Tools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bone_imaging_derivatives-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: bone-imaging-derivatives
+Version: 0.1.0
+Summary: Dependency-light contracts for bone imaging derivative datasets
+Author: Bone Imaging Tools
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# bone-imaging-derivatives
+
+Small, standard-library-only models and helpers for interoperable bone-imaging derivative manifests.

bone_imaging_derivatives-0.1.0/README.md

@@ -0,0 +1,3 @@
+# bone-imaging-derivatives
+
+Small, standard-library-only models and helpers for interoperable bone-imaging derivative manifests.

bone_imaging_derivatives-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bone-imaging-derivatives"
+version = "0.1.0"
+description = "Dependency-light contracts for bone imaging derivative datasets"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Bone Imaging Tools"}]
+dependencies = []
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

bone_imaging_derivatives-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives/__init__.py

@@ -0,0 +1,19 @@
+"""Public contract API for bone-imaging derivative datasets."""
+
+from .compatibility import (
+    discover_legacy_registered_microarchitecture_records, discover_legacy_timelapsed_records,
+    write_compatibility_manifest,
+)
+from .discovery import discover_manifests, find_records
+from .manifest import DerivativeManifest, read_manifest, write_manifest
+from .planning import WorkflowPlan, WorkflowRequirement, resolve_workflow_plan
+from .progress import DerivativeProgressEvent, format_progress_event, parse_progress_event
+from .records import DerivativeRecord
+
+__all__ = [
+    "DerivativeManifest", "DerivativeProgressEvent", "DerivativeRecord", "WorkflowPlan",
+    "WorkflowRequirement", "discover_legacy_registered_microarchitecture_records",
+    "discover_legacy_timelapsed_records", "discover_manifests", "find_records",
+    "format_progress_event", "parse_progress_event", "read_manifest", "resolve_workflow_plan",
+    "write_compatibility_manifest", "write_manifest",
+]

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives/compatibility.py

@@ -0,0 +1,73 @@
+"""Best-effort readers for pre-manifest derivative layouts."""
+
+from pathlib import Path
+
+from .layout import manifest_path
+from .manifest import DerivativeManifest, write_manifest
+from .records import DerivativeRecord
+
+
+def _context(path: Path) -> tuple[str, str, str | None]:
+    subject = next((part[4:] for part in path.parts if part.startswith("sub-")), "legacy")
+    site = next((part[5:] for part in path.parts if part.startswith("site-")), "unknown")
+    session = next((part[4:] for part in path.parts if part.startswith("ses-")), None)
+    return subject, site, session
+
+
+def _space(path: Path) -> str:
+    name = str(path).lower()
+    return "reference" if "reference" in name or "registered" in name else "native"
+
+
+def discover_legacy_timelapsed_records(dataset_root: Path) -> list[DerivativeRecord]:
+    """Discover recognizable artifacts below the historical TimelapsedHRpQCT tree."""
+    root = Path(dataset_root)
+    legacy = root / "derivatives" / "TimelapsedHRpQCT"
+    if not legacy.exists():
+        return []
+    artifact_patterns = (
+        ("formation", "Timelapsed", "formation_mask"),
+        ("resorption", "Timelapsed", "resorption_mask"),
+        ("stable", "Timelapsed", "stable_mask"),
+        ("remodelling", "Timelapsed", "remodelling_pairwise_table"),
+        ("transform", "Registration", "transform_to_reference"),
+        ("common", "CommonRegion", "scan_region_native_common"),
+        ("region", "CommonRegion", "scan_region_native_common"),
+    )
+    records: list[DerivativeRecord] = []
+    for path in sorted(item for item in legacy.rglob("*") if item.is_file()):
+        name = path.name.lower()
+        artifact = next(((family, role) for key, family, role in artifact_patterns if key in name), None)
+        if artifact is None:
+            continue
+        subject, site, session = _context(path)
+        family, role = artifact
+        records.append(DerivativeRecord(family, role, subject, site, session, None,
+                                        _space(path), path, "legacy"))
+    return records
+
+
+def discover_legacy_registered_microarchitecture_records(dataset_root: Path) -> list[DerivativeRecord]:
+    """Discover registered microarchitecture CSV tables not yet recorded in a manifest."""
+    root = Path(dataset_root)
+    base = root / "derivatives" / "Microarchitecture"
+    if not base.exists():
+        return []
+    records: list[DerivativeRecord] = []
+    for path in sorted(base.rglob("*.csv")):
+        if "registered" not in str(path).lower():
+            continue
+        subject, site, session = _context(path)
+        records.append(DerivativeRecord("Microarchitecture", "measurements_table", subject, site,
+                                        session, None, "table", path, "legacy", content_type="table"))
+    return records
+
+
+def write_compatibility_manifest(dataset_root: Path) -> Path:
+    """Write a manifest that explicitly exposes all currently recognized legacy files."""
+    root = Path(dataset_root)
+    records = tuple(discover_legacy_timelapsed_records(root) + discover_legacy_registered_microarchitecture_records(root))
+    output = manifest_path(root, "Compatibility")
+    manifest = DerivativeManifest.create("Compatibility", root, {"name": "bone-imaging-derivatives", "version": "0.1.0"}, records)
+    write_manifest(manifest, output)
+    return output

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives/discovery.py

@@ -0,0 +1,41 @@
+"""Manifest discovery and record filtering."""
+
+from pathlib import Path
+from typing import Sequence
+
+from .manifest import DerivativeManifest, read_manifest
+from .records import DerivativeRecord
+
+
+def discover_manifests(dataset_root: Path, *, strict: bool = False) -> list[DerivativeManifest]:
+    """Return readable manifests below ``derivatives`` in deterministic path order.
+
+    By default, malformed or incomplete manifests are skipped so an interrupted
+    write in one family does not hide completed derivatives in another. Set
+    ``strict`` to surface the first read error to validation callers.
+    """
+    root = Path(dataset_root)
+    derivatives = root / "derivatives"
+    if not derivatives.exists():
+        return []
+    manifests: list[DerivativeManifest] = []
+    for path in sorted(derivatives.rglob("manifest.json")):
+        try:
+            manifests.append(read_manifest(path))
+        except (OSError, TypeError, ValueError):
+            if strict:
+                raise
+    return manifests
+
+
+def find_records(manifests: Sequence[DerivativeManifest], *, derivative: str | None = None,
+                 role: str | None = None, subject_id: str | None = None, site: str | None = None,
+                 session_id: str | None = None, stack_index: int | None = None,
+                 space: str | None = None) -> list[DerivativeRecord]:
+    """Filter records using only specified attributes."""
+    expected = {key: value for key, value in {
+        "derivative": derivative, "role": role, "subject_id": subject_id, "site": site,
+        "session_id": session_id, "stack_index": stack_index, "space": space,
+    }.items() if value is not None}
+    return [record for manifest in manifests for record in manifest.records
+            if all(getattr(record, key) == value for key, value in expected.items())]

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives/families.py

@@ -0,0 +1,25 @@
+"""Standard derivative-family vocabulary."""
+
+REGISTRATION = "Registration"
+COMMON_REGION = "CommonRegion"
+SEGMENTATION = "Segmentation"
+MICROARCHITECTURE = "Microarchitecture"
+PLATE_ROD_MORPHOMETRY = "PlateRodMorphometry"
+TIMELAPSED = "Timelapsed"
+FEA = "FEA"
+MECHANOREGULATION = "Mechanoregulation"
+VOID_SPACE = "VoidSpace"
+COMPATIBILITY = "Compatibility"
+
+DERIVATIVE_FAMILIES = frozenset({
+    REGISTRATION, COMMON_REGION, SEGMENTATION, MICROARCHITECTURE,
+    PLATE_ROD_MORPHOMETRY, TIMELAPSED, FEA, MECHANOREGULATION, VOID_SPACE,
+    COMPATIBILITY,
+})
+
+
+def validate_derivative_family(value: str) -> str:
+    """Return a recognized derivative family or raise a useful error."""
+    if value not in DERIVATIVE_FAMILIES:
+        raise ValueError(f"Unknown derivative family: {value!r}")
+    return value

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives/layout.py

@@ -0,0 +1,24 @@
+"""Helpers for the standard derivatives directory layout."""
+
+from pathlib import Path
+
+from .families import validate_derivative_family
+
+
+def derivative_family_root(dataset_root: Path, derivative_family: str) -> Path:
+    validate_derivative_family(derivative_family)
+    return Path(dataset_root) / "derivatives" / derivative_family
+
+
+def manifest_path(dataset_root: Path, derivative_family: str) -> Path:
+    return derivative_family_root(dataset_root, derivative_family) / "manifest.json"
+
+
+def record_output_path(dataset_root: Path, derivative_family: str, subject_id: str, site: str,
+                       *parts: str) -> Path:
+    """Build a standard subject/site derivative artifact path."""
+    if not subject_id or subject_id.startswith("sub-"):
+        raise ValueError("subject_id must omit the 'sub-' prefix")
+    if not site:
+        raise ValueError("site must be non-empty")
+    return derivative_family_root(dataset_root, derivative_family) / f"sub-{subject_id}" / f"site-{site}" / Path(*parts)

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives/manifest.py

@@ -0,0 +1,135 @@
+"""JSON serialization for derivative manifests."""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+from .families import validate_derivative_family
+from .records import DerivativeRecord
+
+SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class DerivativeManifest:
+    schema_version: int
+    derivative_family: str
+    dataset_root: Path
+    records: tuple[DerivativeRecord, ...]
+    software: Mapping[str, str]
+    created_at: str
+
+    def __post_init__(self) -> None:
+        if self.schema_version != SCHEMA_VERSION:
+            raise ValueError(f"Unsupported schema_version: {self.schema_version}")
+        validate_derivative_family(self.derivative_family)
+        if not self.software.get("name") or not self.software.get("version"):
+            raise ValueError("software must include name and version")
+        object.__setattr__(self, "dataset_root", Path(self.dataset_root))
+        object.__setattr__(self, "records", tuple(self.records))
+        object.__setattr__(self, "software", dict(self.software))
+
+    @classmethod
+    def create(cls, derivative_family: str, dataset_root: Path, software: Mapping[str, str],
+               records: tuple[DerivativeRecord, ...] = (), created_at: str | None = None) -> "DerivativeManifest":
+        return cls(SCHEMA_VERSION, derivative_family, Path(dataset_root), tuple(records), dict(software),
+                   created_at or datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"))
+
+
+def _portable_path(path: Path, root: Path) -> str:
+    try:
+        return str(path.relative_to(root))
+    except ValueError:
+        return str(path)
+
+
+def _record_payload(record: DerivativeRecord, root: Path) -> dict[str, Any]:
+    data: dict[str, Any] = {
+        "derivative": record.derivative, "role": record.role, "subject_id": record.subject_id,
+        "site": record.site, "session_id": record.session_id, "stack_index": record.stack_index,
+        "space": record.space, "path": _portable_path(record.path, root), "source": record.source,
+        "inputs": list(record.inputs), "metadata": dict(record.metadata), "record_id": record.record_id,
+    }
+    for key in ("content_type", "coordinate_reference", "settings_hash", "software"):
+        value = getattr(record, key)
+        if value is not None:
+            data[key] = value
+    return data
+
+
+def write_manifest(manifest: DerivativeManifest, path: Path) -> None:
+    """Write an indented, portable schema-v1 JSON manifest."""
+    path = Path(path)
+    root = manifest.dataset_root.resolve()
+    manifest_location = path.resolve()
+    dataset_root = "." if _manifest_is_within_dataset(manifest_location, root) else str(root)
+    payload = {
+        "schema_version": manifest.schema_version, "derivative_family": manifest.derivative_family,
+        "software": dict(manifest.software), "dataset_root": dataset_root, "created_at": manifest.created_at,
+        "records": [_record_payload(record, root) for record in manifest.records],
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _manifest_is_within_dataset(path: Path, dataset_root: Path) -> bool:
+    try:
+        path.relative_to(dataset_root)
+    except ValueError:
+        return False
+    return True
+
+
+def _dataset_root_from_manifest(path: Path, raw_root: Path) -> Path:
+    """Resolve a portable ``'.'`` root from the standard derivatives layout."""
+    if raw_root != Path("."):
+        return (path.parent / raw_root).resolve()
+    for parent in path.parents:
+        if parent.name == "derivatives":
+            return parent.parent.resolve()
+    return path.parent.resolve()
+
+
+def _required(data: Mapping[str, Any], key: str) -> Any:
+    if key not in data:
+        raise ValueError(f"Manifest record is missing required field: {key}")
+    return data[key]
+
+
+def _read_record(data: Mapping[str, Any], root: Path) -> DerivativeRecord:
+    raw_path = Path(_required(data, "path"))
+    path = raw_path if raw_path.is_absolute() else root / raw_path
+    return DerivativeRecord(
+        derivative=_required(data, "derivative"), role=_required(data, "role"),
+        subject_id=_required(data, "subject_id"), site=_required(data, "site"),
+        session_id=_required(data, "session_id"), stack_index=_required(data, "stack_index"),
+        space=_required(data, "space"), path=path, source=_required(data, "source"),
+        inputs=tuple(_required(data, "inputs")), metadata=_required(data, "metadata"),
+        record_id=data.get("record_id"), content_type=data.get("content_type"),
+        coordinate_reference=data.get("coordinate_reference"), settings_hash=data.get("settings_hash"),
+        software=data.get("software"),
+    )
+
+
+def read_manifest(path: Path) -> DerivativeManifest:
+    """Read a schema-v1 manifest and resolve relative records from its dataset root."""
+    path = Path(path)
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid manifest JSON: {path}") from exc
+    if not isinstance(payload, dict):
+        raise ValueError("Manifest must be a JSON object")
+    version = _required(payload, "schema_version")
+    if version != SCHEMA_VERSION:
+        raise ValueError(f"Unsupported schema_version: {version}")
+    raw_root = Path(_required(payload, "dataset_root"))
+    root = raw_root if raw_root.is_absolute() else _dataset_root_from_manifest(path, raw_root)
+    records_data = _required(payload, "records")
+    if not isinstance(records_data, list):
+        raise ValueError("records must be a list")
+    return DerivativeManifest(version, _required(payload, "derivative_family"), root,
+                              tuple(_read_record(record, root) for record in records_data),
+                              _required(payload, "software"), _required(payload, "created_at"))

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives/planning.py

@@ -0,0 +1,77 @@
+"""Small prerequisite planner shared by package batch workflows."""
+
+from dataclasses import dataclass
+from typing import Sequence
+
+from .discovery import find_records
+from .manifest import DerivativeManifest
+from .records import DerivativeRecord
+
+
+@dataclass(frozen=True)
+class WorkflowRequirement:
+    derivative: str
+    roles: tuple[str, ...]
+    required: bool = True
+
+
+@dataclass(frozen=True)
+class WorkflowPlan:
+    workflow: str
+    available: tuple[DerivativeRecord, ...]
+    missing: tuple[WorkflowRequirement, ...]
+    steps: tuple[str, ...]
+    blocked: bool
+
+
+_REQUIREMENTS = {
+    "CommonRegion": (WorkflowRequirement("Registration", ("transform_to_reference",)),),
+    "Microarchitecture": (WorkflowRequirement("CommonRegion", ("scan_region_native_common",), False),),
+    "PlateRodMorphometry": (WorkflowRequirement("CommonRegion", ("scan_region_native_common",), False),),
+    "Timelapsed": (
+        WorkflowRequirement("Registration", ("transform_to_reference",)),
+        WorkflowRequirement("CommonRegion", ("scan_region_native_common",), False),
+    ),
+    "FEA": (WorkflowRequirement("CommonRegion", ("scan_region_native_common",), False),),
+    "Mechanoregulation": (
+        WorkflowRequirement("Timelapsed", ("remodelling_pairwise_table",)),
+        WorkflowRequirement("FEA", ("solver_output",)),
+    ),
+}
+
+
+def resolve_workflow_plan(workflow: str, *, manifests: Sequence[DerivativeManifest], subject_id: str,
+                          site: str, sessions: Sequence[str], generate_missing: bool) -> WorkflowPlan:
+    """Resolve prerequisites for every selected session.
+
+    The first selected session is the registration reference, so it does not
+    require a ``transform_to_reference`` record. All other requirements are
+    checked at each requested session.
+    """
+    if workflow not in _REQUIREMENTS:
+        raise ValueError(f"Unknown workflow: {workflow!r}")
+    available = tuple(find_records(manifests, subject_id=subject_id, site=site))
+    missing: list[WorkflowRequirement] = []
+    steps: list[str] = []
+    for requirement in _REQUIREMENTS[workflow]:
+        required_sessions = tuple(str(session) for session in sessions)
+        if requirement.derivative == "Registration" and "transform_to_reference" in requirement.roles:
+            required_sessions = required_sessions[1:]
+        missing_sessions = tuple(
+            session for session in required_sessions
+            if not all(any(record.derivative == requirement.derivative and record.role == role
+                           and record.session_id == session for record in available)
+                       for role in requirement.roles)
+        )
+        has_all_roles = not missing_sessions
+        session_note = f" for sessions: {', '.join(missing_sessions)}" if missing_sessions else ""
+        if has_all_roles:
+            steps.append(f"Reuse {requirement.derivative} {'/'.join(requirement.roles)}")
+        else:
+            missing.append(requirement)
+            if generate_missing:
+                steps.append(f"Generate {requirement.derivative} {'/'.join(requirement.roles)}{session_note}")
+            elif requirement.required:
+                steps.append(f"Missing {requirement.derivative} {'/'.join(requirement.roles)}{session_note}")
+    blocked = any(requirement.required for requirement in missing) and not generate_missing
+    return WorkflowPlan(workflow, available, tuple(missing), tuple(steps), blocked)

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives/progress.py

@@ -0,0 +1,46 @@
+"""Line-oriented JSON progress protocol for background processes."""
+
+from dataclasses import dataclass
+import json
+from pathlib import Path
+
+_PREFIX = "BONE_DERIVATIVES_PROGRESS "
+
+
+@dataclass(frozen=True)
+class DerivativeProgressEvent:
+    family: str
+    subject_id: str | None
+    site: str | None
+    session_id: str | None
+    step: str
+    status: str
+    message: str
+    path: Path | None = None
+
+    def __post_init__(self) -> None:
+        if not self.family or not self.step or not self.status:
+            raise ValueError("family, step, and status must be non-empty")
+        if self.path is not None:
+            object.__setattr__(self, "path", Path(self.path))
+
+
+def format_progress_event(event: DerivativeProgressEvent) -> str:
+    """Format one parseable progress line without printing it."""
+    data = {"family": event.family, "subject_id": event.subject_id, "site": event.site,
+            "session_id": event.session_id, "step": event.step, "status": event.status,
+            "message": event.message, "path": str(event.path) if event.path is not None else None}
+    return _PREFIX + json.dumps(data, sort_keys=True)
+
+
+def parse_progress_event(line: str) -> DerivativeProgressEvent | None:
+    """Parse a progress line, returning ``None`` for normal process output."""
+    if not line.startswith(_PREFIX):
+        return None
+    try:
+        data = json.loads(line[len(_PREFIX):])
+        return DerivativeProgressEvent(data["family"], data.get("subject_id"), data.get("site"),
+                                       data.get("session_id"), data["step"], data["status"],
+                                       data.get("message", ""), Path(data["path"]) if data.get("path") else None)
+    except (TypeError, KeyError, ValueError, json.JSONDecodeError):
+        return None

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives/records.py

@@ -0,0 +1,62 @@
+"""Immutable records describing one derivative artifact."""
+
+from dataclasses import dataclass, field
+from hashlib import sha256
+from pathlib import Path
+from typing import Any, Mapping
+
+from .families import validate_derivative_family
+from .roles import validate_role
+
+_SPACES = frozenset({"native", "reference", "moving", "fixed", "model", "table"})
+_SOURCES = frozenset({"generated", "provided", "derived", "legacy"})
+
+
+@dataclass(frozen=True)
+class DerivativeRecord:
+    derivative: str
+    role: str
+    subject_id: str
+    site: str
+    session_id: str | None
+    stack_index: int | None
+    space: str
+    path: Path
+    source: str
+    inputs: tuple[str, ...] = ()
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+    record_id: str | None = None
+    content_type: str | None = None
+    coordinate_reference: Mapping[str, Any] | None = None
+    settings_hash: str | None = None
+    software: Mapping[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        validate_derivative_family(self.derivative)
+        validate_role(self.role)
+        if not self.subject_id or self.subject_id.startswith("sub-"):
+            raise ValueError("subject_id must be non-empty and omit the 'sub-' prefix")
+        if not self.site or "/" in self.site:
+            raise ValueError("site must be a non-empty normalized identifier")
+        if self.session_id is not None and not self.session_id:
+            raise ValueError("session_id must be non-empty when provided")
+        if self.stack_index is not None and not isinstance(self.stack_index, int):
+            raise ValueError("stack_index must be an integer or None")
+        if self.space not in _SPACES:
+            raise ValueError(f"Unknown coordinate space: {self.space!r}")
+        if self.source not in _SOURCES:
+            raise ValueError(f"Unknown record source: {self.source!r}")
+        object.__setattr__(self, "path", Path(self.path))
+        object.__setattr__(self, "inputs", tuple(self.inputs))
+        object.__setattr__(self, "metadata", dict(self.metadata))
+        if self.coordinate_reference is not None:
+            object.__setattr__(self, "coordinate_reference", dict(self.coordinate_reference))
+        if self.software is not None:
+            object.__setattr__(self, "software", dict(self.software))
+        if self.record_id is None:
+            object.__setattr__(self, "record_id", self._default_record_id())
+
+    def _default_record_id(self) -> str:
+        parts = (self.derivative, self.role, self.subject_id, self.site,
+                 self.session_id or "", str(self.stack_index), self.space, str(self.path))
+        return sha256("\x1f".join(parts).encode()).hexdigest()[:20]

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives/roles.py

@@ -0,0 +1,27 @@
+"""Stable semantic roles used by derivative records."""
+
+DERIVATIVE_ROLES = frozenset({
+    "transform_pairwise", "transform_to_reference", "transform_from_reference",
+    "registration_mask", "registration_qc", "scan_region_native",
+    "scan_region_reference", "scan_region_common_reference",
+    "scan_region_native_common", "bone_segmentation", "periosteal_mask",
+    "endosteal_mask", "trabecular_mask", "cortical_mask", "scan_region_mask",
+    "void_mask", "measurements_table", "trabecular_thickness_map",
+    "trabecular_spacing_map", "trabecular_number_map", "cortical_thickness_map",
+    "cortical_porosity_map", "plate_rod_label_map", "plate_rod_measurements_table",
+    "plate_local_thickness_map", "rod_local_thickness_map", "skeleton_map",
+    "remodelling_pairwise_table", "remodelling_trajectory_table", "formation_mask",
+    "resorption_mask", "stable_mask", "transformed_image", "filled_image",
+    "qc_report", "mesh", "material_map", "boundary_conditions", "solver_input",
+    "solver_output", "strain_map", "stress_map", "load_transfer_table",
+    "mechanoregulation_table", "mechanical_signal_map", "formation_mechanics_map",
+    "resorption_mechanics_map", "adaptation_classification_map",
+    "void_measurements_table", "void_distance_map", "void_connectivity_map",
+})
+
+
+def validate_role(value: str) -> str:
+    """Return a recognized record role or raise a useful error."""
+    if value not in DERIVATIVE_ROLES:
+        raise ValueError(f"Unknown derivative role: {value!r}")
+    return value

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives.egg-info/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: bone-imaging-derivatives
+Version: 0.1.0
+Summary: Dependency-light contracts for bone imaging derivative datasets
+Author: Bone Imaging Tools
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# bone-imaging-derivatives
+
+Small, standard-library-only models and helpers for interoperable bone-imaging derivative manifests.

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+LICENSE
+README.md
+pyproject.toml
+src/bone_imaging_derivatives/__init__.py
+src/bone_imaging_derivatives/compatibility.py
+src/bone_imaging_derivatives/discovery.py
+src/bone_imaging_derivatives/families.py
+src/bone_imaging_derivatives/layout.py
+src/bone_imaging_derivatives/manifest.py
+src/bone_imaging_derivatives/planning.py
+src/bone_imaging_derivatives/progress.py
+src/bone_imaging_derivatives/records.py
+src/bone_imaging_derivatives/roles.py
+src/bone_imaging_derivatives.egg-info/PKG-INFO
+src/bone_imaging_derivatives.egg-info/SOURCES.txt
+src/bone_imaging_derivatives.egg-info/dependency_links.txt
+src/bone_imaging_derivatives.egg-info/top_level.txt
+tests/test_compatibility.py
+tests/test_discovery.py
+tests/test_layout_and_validation.py
+tests/test_manifest.py
+tests/test_planning.py
+tests/test_progress.py

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bone_imaging_derivatives-0.1.0/src/bone_imaging_derivatives.egg-info/top_level.txt

@@ -0,0 +1 @@
+bone_imaging_derivatives

bone_imaging_derivatives-0.1.0/tests/test_compatibility.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+
+from bone_imaging_derivatives import (
+    DerivativeManifest,
+    discover_legacy_registered_microarchitecture_records,
+    discover_legacy_timelapsed_records,
+    read_manifest,
+    resolve_workflow_plan,
+    write_compatibility_manifest,
+)
+
+
+def test_legacy_discovery_and_compatibility_manifest_cover_existing_outputs(tmp_path: Path) -> None:
+    """Legacy folders must remain available while packages migrate to manifests."""
+    root = tmp_path / "dataset"
+    (root / "derivatives" / "TimelapsedHRpQCT" / "sub-S01" / "site-tibia" / "ses-1").mkdir(parents=True)
+    (root / "derivatives" / "TimelapsedHRpQCT" / "sub-S01" / "site-tibia" / "ses-1" / "formation_mask.nii.gz").touch()
+    micro_path = root / "derivatives" / "Microarchitecture" / "sub-S01" / "site-tibia" / "registered" / "measurements.csv"
+    micro_path.parent.mkdir(parents=True, exist_ok=True)
+    micro_path.touch()
+
+    timelapsed = discover_legacy_timelapsed_records(root)
+    microarchitecture = discover_legacy_registered_microarchitecture_records(root)
+    manifest_path = write_compatibility_manifest(root)
+
+    assert timelapsed[0].role == "formation_mask"
+    assert timelapsed[0].source == "legacy"
+    assert microarchitecture[0].role == "measurements_table"
+    assert len(read_manifest(manifest_path).records) == 2
+
+
+def test_legacy_transform_is_registration_and_satisfies_common_region_planning(tmp_path: Path) -> None:
+    """Misclassifying a legacy transform would falsely block common-region migration."""
+    root = tmp_path / "dataset"
+    transform = root / "derivatives" / "TimelapsedHRpQCT" / "sub-S01" / "site-tibia" / "ses-2" / "transform_to_reference.tfm"
+    transform.parent.mkdir(parents=True)
+    transform.touch()
+
+    records = discover_legacy_timelapsed_records(root)
+    manifest = DerivativeManifest.create("Compatibility", root, {"name": "test", "version": "1"}, tuple(records))
+    plan = resolve_workflow_plan("CommonRegion", manifests=(manifest,), subject_id="S01", site="tibia",
+                                 sessions=("1", "2"), generate_missing=False)
+
+    assert [(record.derivative, record.role) for record in records] == [("Registration", "transform_to_reference")]
+    assert plan.blocked is False

bone_imaging_derivatives-0.1.0/tests/test_discovery.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+
+from bone_imaging_derivatives import (
+    DerivativeManifest, DerivativeRecord, discover_manifests, find_records, write_manifest,
+)
+
+
+def _manifest(root: Path, family: str, record: DerivativeRecord) -> DerivativeManifest:
+    return DerivativeManifest.create(
+        derivative_family=family, dataset_root=root, software={"name": "test", "version": "1"},
+        records=(record,), created_at="2026-08-29T00:00:00Z",
+    )
+
+
+def test_discovery_and_filtering_return_only_matching_records(tmp_path: Path) -> None:
+    """Ignoring filter fields would feed a workflow records from another session."""
+    root = tmp_path / "dataset"
+    registration = DerivativeRecord("Registration", "transform_to_reference", "S01", "tibia", "1", 1, "native", root / "a.tfm", "generated")
+    common = DerivativeRecord("CommonRegion", "scan_region_native_common", "S01", "tibia", "2", 1, "native", root / "b.nii.gz", "generated")
+    write_manifest(_manifest(root, "Registration", registration), root / "derivatives" / "Registration" / "manifest.json")
+    write_manifest(_manifest(root, "CommonRegion", common), root / "derivatives" / "CommonRegion" / "manifest.json")
+
+    manifests = discover_manifests(root)
+    found = find_records(manifests, derivative="CommonRegion", subject_id="S01", session_id="2", space="native")
+
+    assert [record.path for record in found] == [root / "b.nii.gz"]
+
+
+def test_discovery_skips_a_malformed_manifest_when_valid_manifests_exist(tmp_path: Path) -> None:
+    """One interrupted write must not hide records from other completed families."""
+    root = tmp_path / "dataset"
+    record = DerivativeRecord("Registration", "transform_to_reference", "S01", "tibia", "1", 1,
+                              "native", root / "transform.tfm", "generated")
+    write_manifest(_manifest(root, "Registration", record), root / "derivatives" / "Registration" / "manifest.json")
+    malformed = root / "derivatives" / "CommonRegion" / "manifest.json"
+    malformed.parent.mkdir(parents=True)
+    malformed.write_text("{not valid JSON")
+
+    manifests = discover_manifests(root)
+
+    assert [manifest.derivative_family for manifest in manifests] == ["Registration"]

bone_imaging_derivatives-0.1.0/tests/test_layout_and_validation.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+import pytest
+
+from bone_imaging_derivatives import DerivativeRecord
+from bone_imaging_derivatives.families import validate_derivative_family
+from bone_imaging_derivatives.layout import derivative_family_root, record_output_path
+from bone_imaging_derivatives.roles import validate_role
+
+
+def test_layout_helpers_build_the_standard_subject_site_layout(tmp_path: Path) -> None:
+    """A changed layout would make independently produced derivatives undiscoverable."""
+    root = tmp_path / "dataset"
+    assert derivative_family_root(root, "CommonRegion") == root / "derivatives" / "CommonRegion"
+    assert record_output_path(root, "CommonRegion", "S01", "tibia", "native_space", "ses-1", "masks", "mask.nii.gz") == (
+        root / "derivatives" / "CommonRegion" / "sub-S01" / "site-tibia" / "native_space" / "ses-1" / "masks" / "mask.nii.gz"
+    )
+
+
+def test_family_role_and_record_validation_reject_unknown_contract_values(tmp_path: Path) -> None:
+    """Unknown family or role strings would create non-interoperable records."""
+    assert validate_derivative_family("CommonRegion") == "CommonRegion"
+    assert validate_role("scan_region_native_common") == "scan_region_native_common"
+    with pytest.raises(ValueError, match="Unknown derivative family"):
+        validate_derivative_family("Unknown")
+    with pytest.raises(ValueError, match="Unknown derivative role"):
+        validate_role("not-a-role")
+    with pytest.raises(ValueError, match="Unknown derivative role"):
+        DerivativeRecord("CommonRegion", "not-a-role", "S01", "tibia", "1", None, "native", tmp_path / "x", "generated")

bone_imaging_derivatives-0.1.0/tests/test_manifest.py

@@ -0,0 +1,62 @@
+from pathlib import Path
+import shutil
+
+from bone_imaging_derivatives import DerivativeManifest, DerivativeRecord, read_manifest, write_manifest
+
+
+def test_manifest_round_trip_stores_dataset_relative_paths(tmp_path: Path) -> None:
+    """Changing the dataset root would break portable manifest records."""
+    dataset_root = tmp_path / "dataset"
+    output = dataset_root / "derivatives" / "CommonRegion" / "manifest.json"
+    record_path = dataset_root / "derivatives" / "CommonRegion" / "sub-S01" / "mask.nii.gz"
+    manifest = DerivativeManifest.create(
+        derivative_family="CommonRegion",
+        dataset_root=dataset_root,
+        software={"name": "timelapsed-hrpqct", "version": "2.0"},
+        records=(
+            DerivativeRecord(
+                derivative="CommonRegion", role="scan_region_native_common", subject_id="S01",
+                site="tibia", session_id="1", stack_index=1, space="native", path=record_path,
+                source="generated", inputs=("input-1",), metadata={"method": "overlap"},
+            ),
+        ),
+        created_at="2026-08-29T00:00:00Z",
+    )
+
+    write_manifest(manifest, output)
+    loaded = read_manifest(output)
+
+    assert loaded == manifest
+    assert '"path": "derivatives/CommonRegion/sub-S01/mask.nii.gz"' in output.read_text()
+
+
+def test_manifest_rejects_unsupported_schema_version(tmp_path: Path) -> None:
+    """Accepting a future schema could silently misinterpret a record."""
+    path = tmp_path / "manifest.json"
+    path.write_text('{"schema_version": 2}')
+
+    import pytest
+
+    with pytest.raises(ValueError, match="schema_version"):
+        read_manifest(path)
+
+
+def test_manifest_relative_records_follow_a_copied_dataset_root(tmp_path: Path) -> None:
+    """An absolute serialized root would make copied datasets point at stale artifacts."""
+    original = tmp_path / "original"
+    original_record = original / "derivatives" / "Registration" / "sub-S01" / "transform.tfm"
+    manifest_path = original / "derivatives" / "Registration" / "manifest.json"
+    manifest = DerivativeManifest.create(
+        "Registration", original, {"name": "timelapsed-hrpqct", "version": "2.0"},
+        (DerivativeRecord("Registration", "transform_to_reference", "S01", "tibia", "1", None,
+                          "native", original_record, "generated"),),
+        "2026-08-29T00:00:00Z",
+    )
+    write_manifest(manifest, manifest_path)
+    copied = tmp_path / "copied"
+    shutil.copytree(original, copied)
+
+    loaded = read_manifest(copied / "derivatives" / "Registration" / "manifest.json")
+
+    assert loaded.dataset_root == copied.resolve()
+    assert loaded.records[0].path == copied / "derivatives" / "Registration" / "sub-S01" / "transform.tfm"

bone_imaging_derivatives-0.1.0/tests/test_planning.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+
+from bone_imaging_derivatives import DerivativeManifest, DerivativeRecord, WorkflowRequirement, resolve_workflow_plan
+
+
+def test_planner_blocks_common_region_without_registration_when_generation_disabled(tmp_path: Path) -> None:
+    """Missing required transforms must block a common-region run when generation is disabled."""
+    manifest = DerivativeManifest.create("Registration", tmp_path, {"name": "test", "version": "1"}, (), "2026-08-29T00:00:00Z")
+
+    plan = resolve_workflow_plan("CommonRegion", manifests=(manifest,), subject_id="S01", site="tibia", sessions=("1", "2"), generate_missing=False)
+
+    assert plan.blocked is True
+    assert plan.missing[0].derivative == "Registration"
+    assert plan.missing[0].roles == ("transform_to_reference",)
+
+
+def test_planner_allows_missing_prerequisite_generation(tmp_path: Path) -> None:
+    """The generation option should turn a satisfiable prerequisite into an executable step."""
+    plan = resolve_workflow_plan("Timelapsed", manifests=(), subject_id="S01", site="tibia", sessions=("1", "2"), generate_missing=True)
+
+    assert plan.blocked is False
+    assert any("Generate Registration" in step for step in plan.steps)
+
+
+def test_planner_requires_transform_for_every_non_reference_session(tmp_path: Path) -> None:
+    """Treating one session's transform as all sessions' input would start incomplete work."""
+    first_session_transform = DerivativeRecord(
+        "Registration", "transform_to_reference", "S01", "tibia", "1", None,
+        "native", tmp_path / "ses-1.tfm", "generated",
+    )
+    manifest = DerivativeManifest.create(
+        "Registration", tmp_path, {"name": "test", "version": "1"},
+        (first_session_transform,), "2026-08-29T00:00:00Z",
+    )
+
+    plan = resolve_workflow_plan("CommonRegion", manifests=(manifest,), subject_id="S01", site="tibia",
+                                 sessions=("1", "2"), generate_missing=False)
+
+    assert plan.blocked is True
+    assert plan.missing == (WorkflowRequirement("Registration", ("transform_to_reference",)),)
+    assert any("sessions: 2" in step for step in plan.steps)

bone_imaging_derivatives-0.1.0/tests/test_progress.py

@@ -0,0 +1,13 @@
+from pathlib import Path
+
+from bone_imaging_derivatives import DerivativeProgressEvent, format_progress_event, parse_progress_event
+
+
+def test_progress_events_round_trip_and_ignore_unrelated_output(tmp_path: Path) -> None:
+    """A progress parser must recover job state without treating arbitrary logs as events."""
+    event = DerivativeProgressEvent("CommonRegion", "S01", "tibia", "1", "write", "completed", "Saved mask", tmp_path / "mask.nii.gz")
+
+    line = format_progress_event(event)
+
+    assert parse_progress_event(line) == event
+    assert parse_progress_event("ordinary application log") is None