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

brkraw/dataclasses/__init__.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from .study import Study
+from .scan import Scan
+from .reco import Reco
+from .node import DatasetNode
+
+
+__all__ = [
+    'Study', 
+    'Scan', 
+    'Reco', 
+    'DatasetNode'
+]

brkraw/dataclasses/node.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import io
+from typing import Any, List, Union, Optional, TYPE_CHECKING, cast, Dict
+
+
+from ..core.fs import DatasetFS
+from ..core.parameters import Parameters
+
+if TYPE_CHECKING:
+    from ..core.fs import DatasetFile
+    from ..core.zip import ZippedFile
+
+def _is_probably_text(data: bytes) -> bool:
+    """Heuristic to decide if data should be treated as text."""
+    if not data:
+        return True
+    sample = data[:1024]
+    if b"\x00" in sample:
+        return False
+
+    text_chars = set(range(0x20, 0x7F)) | {0x09, 0x0A, 0x0D, 0x08, 0x0C, 0x1B}
+    nontext = sum(b not in text_chars for b in sample)
+    return (nontext / len(sample)) < 0.30
+
+
+class DatasetNode:
+    """Shared utilities for dataset-backed nodes (Study, Scan, Reco)."""
+
+    fs: "DatasetFS"
+    relroot: str
+    _cache: Dict[str, Any]
+
+    def _full_path(self, name: str) -> str:
+        relroot = self.relroot.strip("/")
+        name = name.strip("/")
+        return f"{relroot}/{name}" if relroot else name
+
+    def _candidates(self, name: str) -> List[str]:
+        """Generate possible dataset entry names for an attribute-like token."""
+        if not name:
+            return []
+        candidates = [name]
+
+        def add(candidate: str) -> None:
+            if candidate and candidate not in candidates:
+                candidates.append(candidate)
+
+        stripped = name[5:] if name.startswith("file_") else None
+        add(stripped or "")
+
+        dotted = name.replace("_", ".")
+        add(dotted if dotted != name else "")
+
+        if stripped:
+            dotted_stripped = stripped.replace("_", ".")
+            add(dotted_stripped)
+
+        return candidates
+
+    def _resolve_entry(self, relpath: str) -> Optional[Union["ZippedFile", "DatasetFile"]]:
+        """Return the file-like entry object for a dataset-relative path."""
+        relpath = relpath.strip("/")
+        parent, _, leaf = relpath.rpartition("/")
+        dirpath = parent
+        entries = self.fs.iterdir(dirpath)
+        for entry in entries:
+            if entry.name == leaf and entry.is_file():
+                return cast(Union["ZippedFile", "DatasetFile"], entry)
+        return None
+
+    def open(self, name: str):
+        """Open a dataset-relative entry with best-effort typing.
+
+        Attempts to parse JCAMP parameters first; falls back to text or binary
+        buffers when parsing fails.
+        """
+        if name.startswith("_"):
+            raise FileNotFoundError(name)
+
+        for candidate in self._candidates(name):
+            path = self._full_path(candidate)
+            cache_key = f"{path}"
+            cached = self._cache.get(cache_key)
+            if cached is not None:
+                return cached
+
+            entry = self._resolve_entry(path)
+            if entry is None:
+                continue
+
+            data = entry.read()
+
+            param = None
+            if Parameters._looks_like_jcamp(data):
+                try:
+                    param = Parameters(data)
+                except Exception:
+                    param = None
+            if param is not None:
+                self._cache[cache_key] = param
+                return param
+
+            if _is_probably_text(data):
+                try:
+                    text = data.decode("utf-8")
+                    obj = io.StringIO(text)
+                except UnicodeDecodeError:
+                    obj = io.BytesIO(data)
+            else:
+                obj = io.BytesIO(data)
+
+            self._cache[cache_key] = obj
+            return obj
+
+        raise FileNotFoundError(name)
+
+    def __getattr__(self, name: str):
+        if name.startswith("_"):
+            raise AttributeError(name)
+        try:
+            return self.open(name)
+        except FileNotFoundError as exc:
+            raise AttributeError(name) from exc
+
+    def __getitem__(self, key: str):
+        """Dictionary-style access to files (supports names not valid as attributes)."""
+        return self.open(str(key))
+
+    def listdir(self, relpath: str = "") -> List[str]:
+        """List entries under this node (dirs first, then files)."""
+        target = self._full_path(relpath)
+        return self.fs.listdir(target)
+
+    def iterdir(self, relpath: str = ""):
+        """Iterate over entries under this node as objects (dirs first, then files)."""
+        target = self._full_path(relpath)
+        for entry in self.fs.iterdir(target):
+            yield entry

brkraw/dataclasses/reco.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+
+from ..core.fs import DatasetFS
+from .node import DatasetNode
+from typing import TYPE_CHECKING, Dict
+if TYPE_CHECKING:
+    from .scan import Scan
+
+
+@dataclass
+class Reco(DatasetNode):
+    fs: DatasetFS
+    scan_id: int
+    reco_id: int
+    relroot: str          # e.g.: "3/pdata/1"
+    _cache: Dict[str, object] = field(default_factory=dict, init=False, repr=False)
+
+    @classmethod
+    def from_fs(cls, fs: DatasetFS, scan: "Scan", reco_id: int, relroot: str) -> "Reco":
+        return cls(fs=fs, scan_id=scan.scan_id, reco_id=reco_id, relroot=relroot)
+
+    def __repr__(self) -> str:
+        image_type = None
+        try:
+            reco_obj = getattr(self, "reco")
+            image_type = getattr(reco_obj, "RECO_image_type", None)
+        except Exception:
+            image_type = None
+        type_part = f" type={image_type!r}" if image_type is not None else ""
+        return f"Reco(scan_id={self.scan_id} id={self.reco_id} rel='/{self.relroot}'{type_part})"
+
+__all__ = ['Reco']

brkraw/dataclasses/scan.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Dict, Optional, Mapping
+
+from ..core.fs import DatasetFS
+from .node import DatasetNode
+from .reco import Reco
+
+
+@dataclass
+class Scan(DatasetNode):
+    fs: DatasetFS
+    scan_id: int
+    relroot: str
+    recos: Dict[int, Reco] = field(default_factory=dict)
+    _cache: Dict[str, object] = field(default_factory=dict, init=False, repr=False)
+
+    @classmethod
+    def from_fs(cls, fs: DatasetFS, scan_id: int, relroot: str) -> "Scan":
+        scan = cls(fs, scan_id, relroot)
+        scan._index_recos(top=relroot)
+        return scan
+
+    def _index_recos(self, top: Optional[str] = None) -> None:
+        """Find pdata/<reco_id> dirs under this scan and attach PVReco."""
+        import re
+        pdata_prefix = f"{self.relroot}/pdata"
+
+        for dirpath, dirnames, filenames in self.fs.walk(top=top or ""):
+            rel = self.fs.strip_anchor(dirpath)
+            if not rel.startswith(pdata_prefix):
+                continue
+            m = re.fullmatch(rf"{self.relroot}/pdata/(\d+)", rel)
+            if not m:
+                continue
+            reco_id = int(m.group(1))
+            self.recos[reco_id] = Reco.from_fs(
+                fs=self.fs,
+                scan=self,
+                reco_id=reco_id,
+                relroot=rel,
+            )
+
+    def get_reco(self, reco_id: int) -> Reco:
+        return self.recos[reco_id]
+
+    @property
+    def avail(self) -> Mapping[int, Reco]:
+        return {k: self.recos[k] for k in sorted(self.recos)}
+
+    def __repr__(self) -> str:
+        method_val = None
+        try:
+            method_obj = getattr(self, "method")
+            method_val = getattr(method_obj, "Method", None)
+        except Exception:
+            method_val = None
+        method_part = f" Method={method_val!r}" if method_val is not None else ""
+        return f"Scan(id={self.scan_id} rel='/{self.relroot}'{method_part})"
+
+    __all__ = ['Scan']

brkraw/dataclasses/study.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, Mapping, Union, TYPE_CHECKING, List
+
+from ..core.fs import DatasetFS
+from .node import DatasetNode
+from .scan import Scan
+
+if TYPE_CHECKING:
+    from ..apps.loader.types import ScanLoader
+
+
+@dataclass
+class Study(DatasetNode):
+    fs: DatasetFS
+    relroot: str = ""
+    scans: Dict[int, Scan] = field(default_factory=dict)
+    _cache: Dict[str, object] = field(default_factory=dict, init=False, repr=False)
+
+    @classmethod
+    def from_path(cls, path: Union[str, Path]) -> "Study":
+        """Load a study rooted at path, preferring bottom-up discovery."""
+        fs = DatasetFS.from_path(path)
+        found = cls.discover(fs)
+        if not found:
+            raise ValueError(f"No Paravision study found under {path}")
+
+        anchor = fs.anchor
+        if anchor:
+            for study in found:
+                if study.relroot == anchor:
+                    return study
+
+        if len(found) == 1:
+            return found[0]
+
+        raise ValueError(
+            f"Multiple studies found under {path}; "
+            f"cannot choose automatically ({[s.relroot for s in found]})"
+        )
+
+    @classmethod
+    def discover(cls, fs: DatasetFS) -> List["Study"]:
+        """Bottom-up discovery using reco markers (2dseq + visu_pars)."""
+        reco_dirs: List[str] = []
+        for dirpath, dirnames, filenames in fs.walk():
+            rel = fs.strip_anchor(dirpath)
+            names = set(filenames)
+            if "2dseq" in names and "visu_pars" in names:
+                reco_dirs.append(rel)
+
+        studies: Dict[str, Study] = {}
+        for reco_dir in reco_dirs:
+            parts = [p for p in reco_dir.split("/") if p]
+            if "pdata" not in parts:
+                continue
+            pdata_idx = parts.index("pdata")
+            if pdata_idx < 1 or pdata_idx + 1 >= len(parts):
+                continue
+
+            scan_id_part = parts[pdata_idx - 1]
+            if not scan_id_part.isdigit():
+                continue
+            scan_id = int(scan_id_part)
+
+            reco_id_part = parts[pdata_idx + 1]
+            if not reco_id_part.isdigit():
+                continue
+
+            scan_root = "/".join(parts[:pdata_idx])
+            study_root = "/".join(parts[:pdata_idx - 1])
+            
+            if not (
+                fs.exists(f"{scan_root}/method")
+                and fs.exists(f"{scan_root}/acqp")
+                and fs.exists(f"{reco_dir}/reco")
+            ):
+                continue
+
+            study = studies.get(study_root)
+            if study is None:
+                study = cls(fs=fs, relroot=study_root, scans={})
+                studies[study_root] = study
+
+            if scan_id not in study.scans:
+                study.scans[scan_id] = Scan.from_fs(fs, scan_id, scan_root)
+
+        return [studies[k] for k in sorted(studies.keys())]
+
+    @property
+    def avail(self) -> Mapping[int, Union[Scan, "ScanLoader"]]:
+        return {k: self.scans[k] for k in sorted(self.scans)}
+
+    def get_scan(self, scan_id: int) -> Scan:
+        return self.scans[scan_id]
+
+    @property
+    def has_subject(self) -> bool:
+        target = f"{self.relroot}/subject" if self.relroot else "subject"
+        return self.fs.exists(target)
+
+    def __repr__(self) -> str:
+        root_label = self.relroot or self.fs.root.name
+        mode = getattr(self.fs, "_mode", "dir")
+
+        subject_part = ""
+        try:
+            subj = getattr(self, "subject")
+            from ..core.parameters import Parameters  # local import to avoid cycle
+
+            if isinstance(subj, Parameters):
+                sid = getattr(subj, "SUBJECT_id", None)
+                name = getattr(subj, "SUBJECT_name_string", None)
+                study_name = getattr(subj, "SUBJECT_study_name", None)
+                study_nr = getattr(subj, "SUBJECT_study_nr", None)
+                bits = []
+                if name is not None:
+                    bits.append(f"name={name!r}")
+                if sid is not None:
+                    bits.append(f"id={sid}")
+                if study_name is not None:
+                    bits.append(f"study={study_name!r}")
+                if study_nr is not None:
+                    bits.append(f"nr={study_nr}")
+                if bits:
+                    subject_part = " subject(" + " ".join(bits) + ")"
+        except Exception:
+            subject_part = ""
+
+        return f"Study(root='{root_label}' mode={mode}{subject_part})"

brkraw/default/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__all__ = []

brkraw/default/pruner_specs/deid4share.yaml

@@ -0,0 +1,42 @@
+__meta__:
+  name: "deid4share"
+  version: "0.2.0"
+  description: >
+    De-identification prune spec for Bruker ParaVision datasets. Drops the
+    subject file and redacts potential PII from JCAMP-DX parameters. Supports
+    template variables: $subject_id, $subject_name, $study_id.
+  category: "pruner_spec"
+
+mode: "keep"
+
+files:
+  - "method"
+  - "acqp"
+  - "reco"
+  - "visu_pars"
+  - "2dseq"
+
+update_params:
+  acqp:
+    ACQ_operator: ""
+    ACQ_institution: ""
+    ACQ_station: ""
+    ACQ_time: "<00:00:00 01 Jan 2000>"
+    ACQ_abs_time: "0"
+
+  visu_pars:
+    VisuInstitution: ""
+    VisuSubjectId: "$subject_id"
+    VisuSubjectName: "$subject_name"
+    VisuStudyId: "$study_id"
+    VisuStudyDate: "<00:00:00 01 Jan 2000>"
+    VisuStudyUid: "<1.2.3.4.5>"
+    VisuSeriesUid: "<1.2.3.4.5.1>"
+    VisuFrameUid: "<1.2.3.4.5.2>"
+    VisuSystemOrderNumber: "<>"
+    VisuInstitution: "<>"
+
+  reco:
+    RECO_base_image_uid: "<1.2.3.4.5.6>"
+
+add_root: true

brkraw/default/rules/00_default.yaml

@@ -0,0 +1,4 @@
+metadata_spec:
+  - name: "metadata-dicom"
+    description: "Default metadata mapping for Bruker scans."
+    use: "specs/metadata_dicom.yaml"

brkraw/default/specs/metadata_dicom.yaml

@@ -0,0 +1,236 @@
+__meta__:
+  name: "metadata_dicom"
+  version: "0.0.1"
+  description: "DICOM metadata mapping for Bruker PvDataset."
+  category: "metadata_spec"
+  transforms_source: "metadata_transforms.py"
+
+ImageType:
+  sources:
+    - file: visu_pars
+      key: VisuSeriesTypeId
+  transform: strip_jcamp_string
+
+AcquisitionDateTime:
+  sources:
+    - file: visu_pars
+      key: VisuAcqDate
+  transform: strip_jcamp_string
+
+MagneticFieldStrength:
+  sources:
+    - file: visu_pars
+      key: VisuMagneticFieldStrength
+
+ScanningSequence:
+  sources:
+    - file: visu_pars
+      key: VisuAcqSequenceName
+  transform: strip_jcamp_string
+
+SequenceVariant:
+  sources:
+    - file: visu_pars
+      key: VisuAcqSequenceName
+  transform: strip_jcamp_string
+
+ScanOptions:
+  sources:
+    - file: visu_pars
+      key: VisuAcqSpectralSuppression
+  transform: strip_jcamp_string
+
+RepetitionTime:
+  sources:
+    - file: visu_pars
+      key: VisuAcqRepetitionTime
+
+EchoTime:
+  sources:
+    - file: visu_pars
+      key: VisuAcqEchoTime
+
+InversionTime:
+  sources:
+    - file: visu_pars
+      key: VisuAcqInversionTime
+
+FlipAngle:
+  sources:
+    - file: visu_pars
+      key: VisuAcqFlipAngle
+
+SliceThickness:
+  sources:
+    - file: visu_pars
+      key: VisuCoreSliceThickness
+
+PixelBandwidth:
+  sources:
+    - file: visu_pars
+      key: VisuAcqPixelBandwidth
+
+InPlanePhaseEncodingDirection:
+  sources:
+    - file: visu_pars
+      key: VisuAcqGradEncoding
+
+PercentSampling:
+  sources:
+    - file: visu_pars
+      key: VisuAcqPartialFourier
+
+PercentPhaseFieldOfView:
+  sources:
+    - file: visu_pars
+      key: VisuCoreExtent
+
+PixelSpacing:
+  inputs:
+    extent:
+      sources:
+        - file: visu_pars
+          key: VisuCoreExtent
+    size:
+      sources:
+        - file: visu_pars
+          key: VisuCoreSize
+  transform: pixel_spacing_from_extent
+
+SliceThickness_FG:
+  sources:
+    - file: visu_pars
+      key: VisuCoreSliceThickness
+
+ImagePositionPatient:
+  sources:
+    - file: visu_pars
+      key: VisuCorePosition
+  transform: as_list
+
+ImageOrientationPatient:
+  sources:
+    - file: visu_pars
+      key: VisuCoreOrientation
+  transform: as_list
+
+RescaleSlope_FG:
+  sources:
+    - file: visu_pars
+      key: VisuCoreDataSlope
+
+RescaleIntercept_FG:
+  sources:
+    - file: visu_pars
+      key: VisuCoreDataOffs
+
+RepetitionTime_FG:
+  sources:
+    - file: visu_pars
+      key: VisuAcqRepetitionTime
+
+EchoTime_FG:
+  sources:
+    - file: visu_pars
+      key: VisuAcqEchoTime
+
+FlipAngle_FG:
+  sources:
+    - file: visu_pars
+      key: VisuAcqFlipAngle
+
+EchoTrainLength:
+  sources:
+    - file: visu_pars
+      key: VisuAcqEchoTrainLength
+
+NumberOfAverages:
+  sources:
+    - file: visu_pars
+      key: VisuAcqNAverages
+
+PartialFourier:
+  sources:
+    - file: visu_pars
+      key: VisuAcqPartialFourier
+
+PhaseEncodingDirectionPositive:
+  sources:
+    - file: visu_pars
+      key: VisuAcqGradEncoding
+
+DiffusionBValue_FG:
+  sources:
+    - file: visu_pars
+      key: VisuAcqDiffusionBMatrix
+
+DiffusionGradientOrientation_FG:
+  sources:
+    - file: visu_pars
+      key: VisuAcqDiffusionGradOrient
+  transform: as_list
+
+MRSpectroscopyAcquisitionType:
+  sources:
+    - file: visu_pars
+      key: VisuMrsAcquisitionType
+  transform: strip_jcamp_string
+
+ResonantNucleus:
+  sources:
+    - file: visu_pars
+      key: VisuMrsResonantNuclei
+  transform: strip_jcamp_string
+
+SpectralWidth_MRS:
+  sources:
+    - file: visu_pars
+      key: VisuMrsSpectralWidth
+
+TransmitterFrequency_MRS:
+  sources:
+    - file: visu_pars
+      key: VisuMrsTransmitterFreq
+
+ChemicalShiftReference:
+  sources:
+    - file: visu_pars
+      key: VisuMrsChemicalShiftRef
+
+NumberOfZeroFills:
+  sources:
+    - file: visu_pars
+      key: VisuMrsZeroFill
+
+KSpaceFiltering:
+  sources:
+    - file: visu_pars
+      key: VisuAcqKSpaceFiltering
+
+PulseSequenceName_MRS:
+  sources:
+    - file: visu_pars
+      key: VisuAcqSequenceName
+  transform: strip_jcamp_string
+
+EchoTime_MRS:
+  sources:
+    - file: visu_pars
+      key: VisuAcqEchoTime
+
+RepetitionTime_MRS:
+  sources:
+    - file: visu_pars
+      key: VisuAcqRepetitionTime
+
+WaterSuppression:
+  sources:
+    - file: visu_pars
+      key: VisuAcqSpectralSuppression
+  transform: strip_jcamp_string
+
+VolumeLocalizationTechnique:
+  sources:
+    - file: visu_pars
+      key: VisuMrsLocalizationTechnique
+  transform: strip_jcamp_string