brkraw 0.3.11__py3-none-any.whl → 0.5.0__py3-none-any.whl

brkraw/apps/loader/info/__init__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from .study import resolve as study
+from .scan import resolve as scan
+
+__all__ = [
+    'study',
+    'scan'
+]
+
+__dir__ = __all__

brkraw/apps/loader/info/scan.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import Any, cast, TYPE_CHECKING, Dict, Optional, Union
+from pathlib import Path
+import logging
+from ....specs.remapper import load_spec, map_parameters
+from ....specs.remapper.validator import validate_spec
+
+
+if TYPE_CHECKING:
+    from ..types import ScanLoader, RecoLoader
+
+logger = logging.getLogger("brkraw")
+
+
+def resolve(
+    scan: "ScanLoader",
+    *,
+    spec: Optional[Dict[str, Any]] = None,
+    transforms: Optional[Dict[str, Any]] = None,
+    spec_source: Optional[Union[str, Path]] = None,
+    spec_filename: Optional[str] = None,
+    validate: bool = True,
+) -> Dict[str, Any]:
+    """Resolve scan-level metadata using a remapper spec.
+
+    The spec/transform sources are resolved in the following priority order:
+    1) ``spec``/``transforms`` mappings passed directly.
+    2) ``spec_source``.
+    3) Package default ``scan.yaml``, optionally overridden by ``spec_filename``.
+
+    Args:
+        scan: ScanLoader instance to resolve metadata from.
+        spec: Spec mapping to use directly (highest priority).
+        transforms: Transform mapping to use with ``spec``.
+        spec_source: Path for a YAML spec.
+        spec_filename: Package-relative spec filename (default ``scan.yaml``).
+        validate: When True, validate the spec before mapping.
+
+    Returns:
+        A dictionary of resolved scan metadata.
+    """
+    scan = cast("ScanLoader", scan)
+
+    if spec is not None:
+        spec_data = spec
+        transforms_data = transforms or {}
+        if validate:
+            validate_spec(spec_data)
+    elif spec_source is not None:
+        spec_data, transforms_data = load_spec(
+            spec_source,
+            validate=validate,
+        )
+    else:
+        spec_file = Path(__file__).with_name(spec_filename or "scan.yaml")
+        spec_data, transforms_data = load_spec(
+            spec_file,
+            validate=validate,
+        )
+    results = map_parameters(scan, spec_data, transforms_data)
+    if len(scan.avail):
+        results['Reco(s)'] = {}
+        for reco_id in scan.avail.keys():
+            reco_spec = {
+                "Type": {
+                    "sources": [
+                        {
+                            "file": "visu_pars",
+                            "key": "VisuCoreFrameType",
+                            "reco_id": reco_id,
+                        }
+                    ]
+                }
+            }
+            try:
+                results["Reco(s)"][reco_id] = map_parameters(scan, reco_spec)
+            except (FileNotFoundError, AttributeError) as exc:
+                logger.warning(
+                    "visu_pars missing for scan %s reco %s; skipping reco entry: %s",
+                    getattr(scan, "scan_id", "unknown"),
+                    reco_id,
+                    exc,
+                )
+    return results

brkraw/apps/loader/info/scan.yaml

@@ -0,0 +1,90 @@
+__meta__:
+  name: "scan_info"
+  version: "1.0.0"
+  description: "Scan-level info mapping for Bruker datasets."
+  category: "info_spec"
+  transforms_source: "transform.py"
+
+Method:
+  sources:
+    - file: acqp
+      key: ACQ_method
+  transform: strip_jcamp_string
+Protocol:
+  sources:
+    - file: acqp
+      key: ACQ_protocol_name
+  transform: strip_jcamp_string
+Dim:
+  sources:
+    - file: acqp
+      key: ACQ_dim
+DimDesc:
+  sources:
+    - file: acqp
+      key: ACQ_dim_desc
+  transform: convert_to_list
+NumEchoes:
+  sources:
+    - file: acqp
+      key: NECHOES
+TE (ms):
+  sources:
+    - file: method
+      key: PVM_EchoTime
+    - file: acqp
+      key: ACQ_echo_time
+  transform: convert_to_list
+TR (ms):
+  sources:
+    - file: method
+      key: PVM_RepetitionTime
+    - file: acqp
+      key: ACQ_repetition_time
+  transform: convert_to_list
+FlipAngle (degree):
+  sources:
+    - file: acqp
+      key: ACQ_flip_angle
+Shape:
+  sources:
+    - file: method
+      key: PVM_Matrix
+  transform: convert_to_list
+FOV (mm):
+  sources:
+    - file: method
+      key: PVM_Fov
+  transform: convert_to_list
+NumSlicePack:
+  sources:
+    - file: method
+      key: PVM_NSPacks
+SliceOrient:
+  sources:
+    - file: method
+      key: PVM_SPackArrSliceOrient
+  transform: convert_to_list
+ReadOrient:
+  sources:
+    - file: method
+      key: PVM_SPackArrReadOrient
+  transform: convert_to_list
+SliceDistance (mm):
+  sources:
+    - file: method
+      key: PVM_SPackArrSliceDistance
+  transform: convert_to_list
+SliceGap (mm):
+  sources:
+    - file: method
+      key: PVM_SPackArrSliceGap
+  transform: convert_to_list
+NumAverage:
+  sources:
+    - file: method
+      key: PVM_NAverages
+NumRepeat:
+  sources:
+    - file: method
+      key: PVM_NRepetitions

brkraw/apps/loader/info/study.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+"""Resolve study-level metadata using remapping rules.
+
+This module maps Paravision JCAMP parameters into a normalized dictionary.
+It prefers subject-level parameters when available, and falls back to scan-level
+visu_pars data when subject metadata is missing. Scan fallback selects the
+first scan that contains a reco with a readable visu_pars object.
+"""
+
+from typing import Any, cast, TYPE_CHECKING, Dict, Optional
+from pathlib import Path
+from ....core.parameters import Parameters
+from ....specs.remapper import load_spec, map_parameters
+from ....specs.remapper.validator import validate_spec
+
+
+if TYPE_CHECKING:
+    from .. import BrukerLoader
+    from ..types import StudyLoader
+
+
+def resolve(loader: "BrukerLoader") -> Dict[str, Any]:
+    """Resolve study/subject metadata into a normalized mapping.
+
+    Args:
+        loader: BrukerLoader instance providing access to Study/Scan/Reco nodes.
+
+    Returns:
+        A dictionary containing study and subject metadata fields.
+
+    Raises:
+        ValueError: If no scans are available or no scan has a readable
+            visu_pars when subject metadata is missing.
+    """
+    def _resolve_section_transforms_path(section: Dict[str, Any]) -> Optional[Path]:
+        meta = section.get("__meta__")
+        if not isinstance(meta, dict) or not meta.get("transforms_source"):
+            return None
+        path = Path(meta["transforms_source"])
+        if not path.is_absolute():
+            path = (spec_path.parent / path).resolve()
+        return path
+
+    spec_path = Path(__file__).with_name("study.yaml")
+    spec, transforms = load_spec(
+        spec_path,
+        validate=False,
+    )
+    validate_spec(spec["study"], transforms_source=_resolve_section_transforms_path(spec["study"]))
+    validate_spec(spec["scan"], transforms_source=_resolve_section_transforms_path(spec["scan"]))
+    study = cast("StudyLoader", loader._study)
+    if study.has_subject:
+        return map_parameters(study, spec["study"], transforms=transforms, validate=True)
+    else:
+        if not study.avail:
+            raise ValueError("No scans available to resolve study info from visu_pars.")
+        scan_with_visu = None
+        for scan in study.avail.values():
+            for reco in scan.avail.values():
+                visu = getattr(reco, "visu_pars", None)
+                if isinstance(visu, Parameters):
+                    scan_with_visu = scan
+                    break
+            if scan_with_visu is not None:
+                break
+        if scan_with_visu is None:
+            raise ValueError("No scan contains a reco with readable visu_pars for study info.")
+        return map_parameters(scan_with_visu, spec["scan"], transforms=transforms)

brkraw/apps/loader/info/study.yaml

@@ -0,0 +1,156 @@
+study:
+  __meta__:
+    name: "study_info"
+    version: "1.0.0"
+    description: "Study-level info mapping for Bruker datasets."
+    category: "info_spec"
+    transforms_source: "transform.py"
+  Study.Opperator:
+    sources:
+      - file: subject
+        key: SUBJECT_referral
+      - file: subject
+        key: SUBJECT_study_operator
+    transform: strip_jcamp_string
+  Study.Date:
+    sources:
+      - file: subject
+        key: SUBJECT_abs_date
+      - file: subject
+        key: SUBJECT_study_date
+    transform:
+      - unixtime_to_datetime
+  Study.ID:
+    sources:
+      - file: subject
+        key: SUBJECT_study_name
+    transform: strip_jcamp_string
+  Study.Number:
+    sources:
+      - file: subject
+        key: SUBJECT_study_nr
+    transform: strip_jcamp_string
+  Study.InstanceUID:
+    sources:
+      - file: subject
+        key: SUBJECT_study_instance_uid
+    transform: strip_jcamp_string
+  Subject.ID:
+    sources:
+      - file: subject
+        key: SUBJECT_id
+    transform: strip_jcamp_string
+  Subject.Name:
+    sources:
+      - file: subject
+        key: SUBJECT_name_string
+    transform: strip_jcamp_string
+  Subject.Type:
+    sources:
+      - file: subject
+        key: SUBJECT_type
+  Subject.Sex:
+    sources:
+      - file: subject
+        key: SUBJECT_sex
+      - file: subject
+        key: SUBJECT_gender
+    transform: strip_jcamp_string
+  Subject.DateOfBirth:
+    sources:
+      - file: subject
+        key: SUBJECT_dbirth
+    transform:
+      - strip_jcamp_string
+      - stringtime_to_datetime
+  Subject.Weight:
+    sources:
+      - file: subject
+        key: SUBJECT_weight
+    transform: strip_jcamp_string
+  Subject.Position:
+    sources:
+      - file: subject
+        key: SUBJECT_study_instrument_position
+      - inputs:
+          entry:
+            sources:
+              - file: subject
+                key: SUBJECT_entry
+          position:
+            sources:
+              - file: subject
+                key: SUBJECT_position
+        transform: merge_entry_and_position
+    transform: strip_jcamp_string
+
+scan:
+  __meta__:
+    name: "scan_info_fallback"
+    version: "1.0.0"
+    description: "Scan-level fallback info mapping for Bruker datasets."
+    category: "info_spec"
+    transforms_source: "transform.py"
+  Study.Opperator:
+    sources:
+      - file: visu_pars
+        key: VisuStudyReferringPhysician
+    transform: strip_jcamp_string
+  Study.Date:
+    sources:
+      - file: visu_pars
+        key: VisuStudyDate
+    transform:
+      - strip_jcamp_string
+      - stringtime_to_datetime
+  Study.ID:
+    sources:
+      - file: visu_pars
+        key: VisuStudyId
+    transform: strip_jcamp_string
+  Study.Number:
+    sources:
+      - file: visu_pars
+        key: VisuStudyNumber
+    transform: strip_jcamp_string
+  Study.InstanceUID:
+    sources:
+      - file: visu_pars
+        key: VisuStudyUid
+    transform: strip_jcamp_string
+  Subject.ID:
+    sources:
+      - file: visu_pars
+        key: VisuSubjectId
+    transform: strip_jcamp_string
+  Subject.Name:
+    sources:
+      - file: visu_pars
+        key: VisuSubjectName
+    transform: strip_jcamp_string
+  Subject.Type:
+    sources:
+      - file: visu_pars
+        key: VisuSubjectType
+    transform: strip_jcamp_string
+  Subject.Sex:
+    sources:
+      - file: visu_pars
+        key: VisuSubjectSex
+    transform: strip_jcamp_string
+  Subject.DateOfBirth:
+    sources:
+      - file: visu_pars
+        key: VisuSubjectBirthDate
+    transform:
+      - strip_jcamp_string
+      - stringtime_to_datetime
+  Subject.Weight:
+    sources:
+      - file: visu_pars
+        key: VisuSubjectWeight
+    transform: strip_jcamp_string
+  Subject.Position:
+    sources:
+      - file: visu_pars
+        key: VisuSubjectPosition

brkraw/apps/loader/info/transform.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Union, Optional, Tuple, List, Any, cast
+from datetime import datetime, timezone, timedelta
+import numpy as np
+import re
+
+def strip_jcamp_string(value: Optional[str]) -> str:
+    if value is None:
+        return "Unknown"
+    text = str(value).strip()
+    if text.startswith("<") and text.endswith(">"):
+        text = text[1:-1]
+    text = re.sub(r"\^+", " ", text)
+    return " ".join(text.split())
+
+
+def unixtime_to_datetime(value: Union[int, float, Tuple[Union[int, float], ...]]) -> datetime:
+    """Convert unix time value to timezone-aware datetime.
+
+    Accepts:
+      - int/float: epoch seconds (local timezone)
+      - tuple: (sec,), (sec, ms), or (sec, ms, offset_min)
+
+    If offset_min is missing, local timezone is used.
+    """
+    local_tz = datetime.now().astimezone().tzinfo
+
+    if isinstance(value, (int, float)):
+        return datetime.fromtimestamp(value, tz=local_tz)
+
+    if not isinstance(value, tuple) or not value:
+        raise TypeError(f"Unsupported value: {value!r}")
+
+    sec = value[0]
+    ms = value[1] if len(value) > 1 else 0
+    offset_min = value[2] if len(value) > 2 else None
+
+    tz = timezone(timedelta(minutes=offset_min)) if offset_min is not None else local_tz
+    return datetime.fromtimestamp(sec, tz=tz).replace(microsecond=int(ms) * 1000)
+
+
+def stringtime_to_datetime(value: str) -> Union[datetime, str]:
+    """Parse PV time strings into datetime.
+
+    Supported formats:
+      - 2026-01-01T12:00:00,873-0500
+      - 12:00:00 1 Jan 2026
+      - 1 Jan 2026
+      - 20260101
+    """
+    _FORMATS = (
+        "%Y-%m-%dT%H:%M:%S,%f%z",
+        "%H:%M:%S %d %b %Y",
+        "%d %b %Y",
+        "%Y%m%d",
+    )
+    
+    value = value.strip()
+    if len(value) == 0:
+        return "Unknown"
+    for fmt in _FORMATS:
+        try:
+            return datetime.strptime(value, fmt)
+        except ValueError:
+            continue
+    raise ValueError(f"Unsupported time format: {value!r}")
+
+
+def merge_entry_and_position(entry: str, position: str):
+    entry = entry.split('_')[-1].replace("First", "")
+    position = position.split('_')[-1]
+    return f'{entry}_{position}'
+
+
+def convert_to_list(value: Any) -> List[Any]:
+    if value is None:
+        return []
+    if hasattr(value, "tolist"):
+        return cast(Any, value).tolist()
+    if isinstance(value, (list, tuple)):
+        return list(value)
+    return [value]
+    
+
+__all__ = [
+    'strip_jcamp_string',
+    'unixtime_to_datetime',
+    'stringtime_to_datetime',
+    'merge_entry_and_position',
+    'convert_to_list'
+]