brkraw 0.5.2__py3-none-any.whl → 0.5.5__py3-none-any.whl

brkraw/dataclasses/study.py

@@ -1,21 +1,56 @@
+
 from __future__ import annotations
+
+import logging
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Dict, Mapping, Union, TYPE_CHECKING, List
+from typing import TYPE_CHECKING, Dict, List, Mapping, Optional, Union
 
 from ..core.fs import DatasetFS
 from .node import DatasetNode
 from .scan import Scan
 
-if TYPE_CHECKING:
-    from ..apps.loader.types import ScanLoader
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LazyScan:
+    """Lightweight lazy Scan proxy.
+
+    This defers `Scan.from_fs(...)` until the scan is actually accessed.
+    It implements attribute forwarding so it can be used where a Scan is expected.
+    """
+
+    fs: DatasetFS
+    scan_id: int
+    scan_root: str
+    _scan: Optional[Scan] = field(default=None, init=False, repr=False)
+
+    def materialize(self) -> Scan:
+        if self._scan is None:
+            logger.debug(
+                "Materializing Scan.from_fs for scan_id=%s scan_root=%s",
+                self.scan_id,
+                self.scan_root,
+            )
+            self._scan = Scan.from_fs(self.fs, self.scan_id, self.scan_root)
+        return self._scan
+
+    def __getattr__(self, name: str):
+        # Delegate unknown attributes to the underlying Scan.
+        return getattr(self.materialize(), name)
+
+    def __repr__(self) -> str:
+        if self._scan is None:
+            return f"LazyScan(id={self.scan_id} root='{self.scan_root}')"
+        return repr(self._scan)
 
 
 @dataclass
 class Study(DatasetNode):
     fs: DatasetFS
     relroot: str = ""
-    scans: Dict[int, Scan] = field(default_factory=dict)
+    scans: Dict[int, "LazyScan"] = field(default_factory=dict)
     _cache: Dict[str, object] = field(default_factory=dict, init=False, repr=False)
 
     @classmethod
@@ -42,17 +77,25 @@ class Study(DatasetNode):
 
     @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():
+        """Bottom-up discovery using reco markers (2dseq + visu_pars).
+
+        Notes:
+            Discovery is I/O bound on large studies or slow filesystems.
+            We minimize filesystem calls by:
+            - disabling per-directory sorting in fs.walk
+            - avoiding per-directory set() allocations
+            - caching scan-level existence checks (method/acqp)
+        """
+        studies: Dict[str, "Study"] = {}
+        scan_ok_cache: Dict[str, bool] = {}
+
+        for dirpath, _, filenames in fs.walk(sort_entries=False):
             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 "2dseq" not in filenames or "visu_pars" not in filenames:
+                continue
+
+            parts = [p for p in rel.split("/") if p]
             if "pdata" not in parts:
                 continue
             pdata_idx = parts.index("pdata")
@@ -70,12 +113,18 @@ class Study(DatasetNode):
 
             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")
-            ):
+
+            # Validate scan-level markers once per scan_root.
+            ok = scan_ok_cache.get(scan_root)
+            if ok is None:
+                ok = fs.exists(f"{scan_root}/method") and fs.exists(f"{scan_root}/acqp")
+                scan_ok_cache[scan_root] = ok
+            if not ok:
+                continue
+
+            # Validate reco file. In most PV layouts, `reco` lives in the same pdata/<reco_id> dir.
+            # Prefer checking the listing we already have, fall back to exists() for safety.
+            if "reco" not in filenames and not fs.exists(f"{rel}/reco"):
                 continue
 
             study = studies.get(study_root)
@@ -84,16 +133,17 @@ class Study(DatasetNode):
                 studies[study_root] = study
 
             if scan_id not in study.scans:
-                study.scans[scan_id] = Scan.from_fs(fs, scan_id, scan_root)
+                # Defer Scan.from_fs(...) until the scan is actually accessed.
+                study.scans[scan_id] = LazyScan(fs=fs, scan_id=scan_id, scan_root=scan_root)
 
         return [studies[k] for k in sorted(studies.keys())]
 
     @property
-    def avail(self) -> Mapping[int, Union[Scan, "ScanLoader"]]:
+    def avail(self) -> Mapping[int, "LazyScan"]:
         return {k: self.scans[k] for k in sorted(self.scans)}
 
-    def get_scan(self, scan_id: int) -> Scan:
-        return self.scans[scan_id]
+    def get_scan(self, scan_id: int) -> "Scan":
+        return self.scans[scan_id].materialize()
 
     @property
     def has_subject(self) -> bool:

brkraw/resolver/datatype.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from typing import Union, Optional, TypedDict, cast
 import numpy as np
 from .helpers import get_file
-from ..dataclasses import Scan, Reco
+from ..dataclasses import Scan, Reco, LazyScan
 
 
 WORDTYPE = {
@@ -42,8 +42,16 @@ def _get_dtype(byte_order: str, word_type: str) -> np.dtype:
     return np.dtype(f"{BYTEORDER[byte_order]}{WORDTYPE[word_type]}")
 
 
-def resolve(obj: Union["Scan", "Reco"]) -> Optional[ResolvedDatatype]:
+def resolve(obj: Union["LazyScan", "Scan", "Reco"]) -> Optional[ResolvedDatatype]:
     """Return dtype/slope/offset metadata for a Scan or Reco."""
+    # Accept LazyScan-like proxies by materializing them.
+    if not isinstance(obj, (Scan, Reco)) and hasattr(obj, "materialize"):
+        try:
+            obj = obj.materialize()
+        except Exception as e:
+            raise TypeError(
+                f"resolve() failed to materialize proxy object {type(obj)!r}: {e}"
+            ) from e
     if isinstance(obj, Scan):
         try:
             p = get_file(obj, 'acqp')

brkraw/resolver/image.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 
 
 from typing import TYPE_CHECKING, Optional, Sequence, TypedDict, List, Tuple
+import logging
 from .datatype import resolve as datatype_resolver
 from .shape import resolve as shape_resolver
 from .helpers import get_reco, get_file, swap_element
@@ -22,16 +23,17 @@ if TYPE_CHECKING:
 
 
 class ResolvedImage(TypedDict):
-    dataobj: np.ndarray
+    dataobj: Optional[np.ndarray]
     slope: float
     offset: float
-    shape_desc: List[str]
+    shape_desc: Optional[List[str]]
     sliceorder_scheme: Optional[str]
     num_cycles: int
     time_per_cycle: Optional[float]
 
 
 Z_AXIS_DESCRIPTORS = {'spatial', 'slice', 'without_slice'}
+logger = logging.getLogger("brkraw.resolver.image")
 
 
 def _find_z_axis_candidate(shape_desc: Sequence[str]) -> Optional[int]:
@@ -81,7 +83,10 @@ def ensure_3d_spatial_data(dataobj: np.ndarray, shape_info: "ResolvedShape") ->
         ValueError: When data dimensionality and shape_desc disagree or z-axis
             descriptor is missing.
     """
-    shape = shape_info['shape']
+    # NOTE: `shape_info['shape']` describes the full dataset. When we read only a
+    # subset of cycles (block read), `dataobj.shape` may differ (typically the last
+    # dimension). Use the actual `dataobj.shape` for validation and swapping.
+    shape = list(dataobj.shape)
     shape_desc = list(shape_info['shape_desc'])
 
     if dataobj.ndim != len(shape_desc):
@@ -108,18 +113,102 @@ def ensure_3d_spatial_data(dataobj: np.ndarray, shape_info: "ResolvedShape") ->
     return new_dataobj, normalized_shape_desc
 
 
-def _read_2dseq_data(reco: "Reco", dtype: np.dtype, shape: Sequence[int]) -> np.ndarray:
-    """Read 2dseq file into a Fortran-ordered NumPy array with shape validation."""
-    expected_size = int(np.prod(shape)) * np.dtype(dtype).itemsize
+def _read_2dseq_data(
+        reco: "Reco",
+        dtype: np.dtype,
+        shape: Sequence[int],
+        *,
+        cycle_index: Optional[int] = None,
+        cycle_count: Optional[int] = None,
+        total_cycles: Optional[int] = None,
+    ) -> np.ndarray:
+    """Read 2dseq into a Fortran-ordered NumPy array.
+
+    Default behavior reads the full dataset.
+
+    When `cycle_index` is provided, read a contiguous block of cycles starting at
+    `cycle_index`. Use `cycle_count` to limit how many cycles to read. If
+    `cycle_count` is None, read through the end.
+
+    Notes:
+        This assumes cycles are stored contiguously by cycle in the 2dseq stream.
+        BrkRaw treats the cycle axis as the LAST dimension of `shape`.
+    """
+    itemsize = np.dtype(dtype).itemsize
+
+    # Full read path (default).
+    if cycle_index is None:
+        expected_size = int(np.prod(shape)) * itemsize
+        with get_file(reco, "2dseq") as f:
+            f.seek(0)
+            raw = f.read()
+        if len(raw) != expected_size:
+            raise ValueError(
+                f"2dseq size mismatch: expected {expected_size} bytes for shape {shape}, got {len(raw)}"
+            )
+        try:
+            return np.frombuffer(raw, dtype).reshape(shape, order="F")
+        except ValueError as exc:
+            raise ValueError(f"failed to reshape 2dseq buffer to shape {shape}") from exc
+
+    # Block read path.
+    if total_cycles is None:
+        raise ValueError("total_cycles is required when cycle_index is provided")
+
+    total_cycles = int(total_cycles)
+    if total_cycles < 1:
+        raise ValueError(f"invalid total_cycles={total_cycles}")
+
+    if cycle_index < 0 or cycle_index >= total_cycles:
+        raise ValueError(f"cycle_index {cycle_index} out of range [0, {total_cycles - 1}]")
+
+    if not shape:
+        raise ValueError("shape is empty")
+
+    # BrkRaw convention: cycle axis is the last dimension only when cycles > 1.
+    if total_cycles > 1:
+        if int(shape[-1]) != total_cycles:
+            raise ValueError(
+                f"cycle axis mismatch: expected shape[-1]==total_cycles ({total_cycles}), got shape[-1]={shape[-1]} for shape={shape}"
+            )
+        elems_per_cycle = int(np.prod(shape[:-1])) if len(shape) > 1 else 1
+    else:
+        elems_per_cycle = int(np.prod(shape))
+    bytes_per_cycle = elems_per_cycle * itemsize
+
+    if cycle_count is None:
+        cycle_count = total_cycles - cycle_index
+    cycle_count = int(cycle_count)
+
+    if cycle_count <= 0:
+        raise ValueError(f"cycle_count must be > 0 (got {cycle_count})")
+    if cycle_index + cycle_count > total_cycles:
+        raise ValueError(
+            f"cycle_index+cycle_count exceeds total_cycles: {cycle_index}+{cycle_count} +> {total_cycles}"
+        )
+
+    byte_offset = cycle_index * bytes_per_cycle
+    byte_size = cycle_count * bytes_per_cycle
+
     with get_file(reco, "2dseq") as f:
-        f.seek(0)
-        raw = f.read()
-    if len(raw) != expected_size:
-        raise ValueError(f"2dseq size mismatch: expected {expected_size} bytes for shape {shape}, got {len(raw)}")
+        f.seek(byte_offset)
+        raw = f.read(byte_size)
+
+    if len(raw) != byte_size:
+        raise ValueError(
+            f"2dseq block read size mismatch: expected {byte_size} bytes, got {len(raw)}"
+        )
+
+    # Cycle axis is the last dimension.
+    if len(shape) == 1:
+        block_shape = (cycle_count,)
+    else:
+        block_shape = (*shape[:-1], cycle_count)
+
     try:
-        return np.frombuffer(raw, dtype).reshape(shape, order="F")
+        return np.frombuffer(raw, dtype).reshape(block_shape, order="F")
     except ValueError as exc:
-        raise ValueError(f"failed to reshape 2dseq buffer to shape {shape}") from exc
+        raise ValueError(f"failed to reshape 2dseq block buffer to shape {block_shape}") from exc
 
 
 def _normalize_cycle_info(cycle_info: Optional["ResolvedCycle"]) -> Tuple[int, Optional[float]]:
@@ -129,7 +218,14 @@ def _normalize_cycle_info(cycle_info: Optional["ResolvedCycle"]) -> Tuple[int, O
     return int(cycle_info['num_cycles']), cycle_info.get('time_step')
 
 
-def resolve(scan: "Scan", reco_id: int = 1) -> Optional[ResolvedImage]:
+def resolve(
+    scan: "Scan",
+    reco_id: int = 1,
+    *,
+    load_data: bool = True,
+    cycle_index: Optional[int] = None,
+    cycle_count: Optional[int] = None,
+) -> Optional[ResolvedImage]:
     """Load 2dseq as a NumPy array with associated metadata.
 
     Args:
@@ -161,13 +257,36 @@ def resolve(scan: "Scan", reco_id: int = 1) -> Optional[ResolvedImage]:
         offset = 0.0
     shape = shape_info["shape"]
 
-    try:
-        dataobj = _read_2dseq_data(reco, dtype, shape)
-    except FileNotFoundError:
-        return None
-
-    dataobj, shape_desc = ensure_3d_spatial_data(dataobj, shape_info)
-    num_cycles, time_per_cycle = _normalize_cycle_info(shape_info['objs'].cycle)
+    total_cycles, time_per_cycle = _normalize_cycle_info(shape_info['objs'].cycle)
+
+    dataobj, shape_desc = None, None
+    if load_data:
+        if total_cycles == 1:
+            logger.debug(
+                "Cycle slicing disabled: total_cycles=%s shape=%s",
+                total_cycles,
+                shape,
+            )
+            cycle_index = None
+            cycle_count = None
+        else:
+            logger.debug(
+                "Cycle slicing enabled: total_cycles=%s shape=%s",
+                total_cycles,
+                shape,
+            )
+        try:
+            dataobj = _read_2dseq_data(
+                reco,
+                dtype,
+                shape,
+                cycle_index=cycle_index,
+                cycle_count=cycle_count,
+                total_cycles=total_cycles,
+            )
+        except FileNotFoundError:
+            return None
+        dataobj, shape_desc = ensure_3d_spatial_data(dataobj, shape_info)
 
     result: ResolvedImage = {
         # image
@@ -178,7 +297,7 @@ def resolve(scan: "Scan", reco_id: int = 1) -> Optional[ResolvedImage]:
         'sliceorder_scheme': shape_info['sliceorder_scheme'],
 
         # cycle
-        'num_cycles': num_cycles,
+        'num_cycles': total_cycles,
         'time_per_cycle': time_per_cycle,
     }
     return result

brkraw/resolver/nifti.py

@@ -32,7 +32,6 @@ DimInfo = Tuple[Optional[int], Optional[int], Optional[int]]
 logger = logging.getLogger("brkraw")
 
 class Nifti1HeaderContents(TypedDict, total=False):
-    flip_x: bool
     slice_code: int
     slope_inter: Tuple[float, float]
     time_step: Optional[float]
@@ -57,7 +56,6 @@ class Nifti1HeaderContents(TypedDict, total=False):
 _XYZ_UNITS = set(get_args(XYZUNIT))
 _T_UNITS = set(get_args(TUNIT))
 _HEADER_FIELDS = {
-    "flip_x",
     "slice_code",
     "slope_inter",
     "time_step",
@@ -159,9 +157,7 @@ def _coerce_header_contents(data: Mapping[str, Any]) -> Nifti1HeaderContents:
                 header[key] = None
                 continue
             raise ValueError(f"{key} cannot be null.")
-        if key == "flip_x":
-            header[key] = _coerce_bool(value, name=key)
-        elif key in {"slice_code", "qform_code", "sform_code", "slice_start", "slice_end", "intent_code"}:
+        if key in {"slice_code", "qform_code", "sform_code", "slice_start", "slice_end", "intent_code"}:
             header[key] = int(value)
         elif key in {"time_step", "slice_duration", "cal_min", "cal_max"}:
             header[key] = float(value)
@@ -247,9 +243,8 @@ def _set_dataobj(niiobj: "Nifti1Image", dataobj: np.ndarray) -> None:
 
 
 def resolve(
-    image_info: "ResolvedImage", 
-    flip_x: bool = False, 
-    xyz_units: "XYZUNIT" = 'mm', 
+    image_info: "ResolvedImage",
+    xyz_units: "XYZUNIT" = 'mm',
     t_units: "TUNIT" = 'sec'
 ) -> Nifti1HeaderContents:
     
@@ -273,7 +268,6 @@ def resolve(
     slope = image_info['slope']
     offset = image_info['offset']
     result: Nifti1HeaderContents = {
-        'flip_x': flip_x,
         'slice_code': slice_code,
         'slope_inter': (slope, offset),
         'time_step': time_step,
@@ -295,9 +289,7 @@ def update(
     for c, val in nifti1header_contents.items():
         if val is None or c in ('qform_code', 'sform_code'):
             continue
-        if c == 'flip_x':
-            niiobj.header.default_x_flip = bool(val)
-        elif c == "slice_code":
+        if c == "slice_code":
             if _coerce_int(val, name="slice_code") != 0:
                 niiobj.header['slice_code'] = _coerce_int(val, name="slice_code")
         elif c == "slope_inter":

brkraw/schema/niftiheader.yaml

@@ -4,8 +4,6 @@ title: "BrkRaw NIfTI Header Overrides"
 type: object
 additionalProperties: false
 properties:
-  flip_x:
-    type: boolean
   slice_code:
     type: integer
   slope_inter:

brkraw/specs/meta/validator.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-from pathlib import Path
 from typing import Any, Dict, Iterable, List, Mapping, Optional
 from importlib import resources
 

brkraw/specs/rules/logic.py

@@ -10,7 +10,7 @@ from ..remapper import load_spec, map_parameters
 from .validator import validate_rules
 import logging
 
-logger = logging.getLogger("brkraw")
+logger = logging.getLogger(__name__)
 
 RULE_CATEGORIES = ("info_spec", "metadata_spec", "converter_hook")
 SPEC_CATEGORIES = ("info_spec", "metadata_spec")
@@ -216,8 +216,6 @@ def select_rule_use(
                 logger.debug("Rule %r matched, selected use=%r.", rule.get("name"), selected)
             else:
                 logger.debug("Rule %r matched but has no usable 'use' entry.", rule.get("name"))
-        else:
-            logger.debug("Rule %r did not match.", rule.get("name"))
     logger.debug("Rule selection result: %r", selected)
     return selected
 

{brkraw-0.5.2.dist-info → brkraw-0.5.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brkraw
-Version: 0.5.2
+Version: 0.5.5
 Summary: Toolkit for loading Bruker Paravision datasets, mapping metadata, and exporting NIfTI
 Project-URL: Homepage, https://brkraw.github.io
 Maintainer-email: SungHo Lee <shlee@unc.edu>
@@ -31,6 +31,7 @@ Requires-Dist: mkdocs; extra == 'dev'
 Requires-Dist: mkdocs-material; extra == 'dev'
 Requires-Dist: pymdown-extensions; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: tomli; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: rich; extra == 'docs'
 Provides-Extra: minimal
@@ -44,11 +45,11 @@ Description-Content-Type: text/markdown
 </picture>
 <!-- markdownlint-enable MD041 MD033 MD013 -->
 
-[![DOI](https://zenodo.org/badge/245546149.svg)](https://doi.org/10.5281/zenodo.3818614)
+[![DOI](docs/assets/zenodo_badge.svg)](https://doi.org/10.5281/zenodo.3818614)
 
 A modular toolkit for Bruker MRI raw-data handling.
 
-BrkRaw (v0.5.2) converts raw data into standardized, neuroimaging-ready
+BrkRaw (v0.5.5) converts raw data into standardized, neuroimaging-ready
 datasets, with extensible rules/specs and plugin hooks.
 
 - Documentation: [brkraw.github.io](https://brkraw.github.io/)
@@ -66,16 +67,14 @@ If you use BrkRaw in your research, please cite it.
 
 <!-- BEGIN: brkraw-bibtex -->
 ```biblatex
-@software{brkraw_2026,
-  author = {Lee, Sung-Ho and Devenyi, Gabriel A and Ban, Woomi and Shih, Yen-Yu Ian},
+@software{brkraw,
+  author = {Lee, Sung-Ho and Devenyi, Gabriel A. and Ban, Woomi and Shih, Yen-Yu Ian},
   title = {BrkRaw: A modular toolkit for Bruker MRI raw-data handling},
-  year = {2026},
-  version = {0.5.0},
+  version = {0.5.5},
   doi = {10.5281/zenodo.3818614},
   url = {https://github.com/BrkRaw/brkraw},
   note = {Documentation: https://brkraw.github.io},
-  license = {GPL-3.0-only},
-  date = {2026-01-13}
+  license = {GPL-3.0-only}
 }
 ```
 <!-- END: brkraw-bibtex -->