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

brkraw/core/zip.py

@@ -588,6 +588,8 @@ class ZippedDir:
 def walk(
     zipobj: zipfile.ZipFile,
     top: str = "",
+    *,
+    sort_entries: bool = True,
 ) -> Iterable[Tuple[str, List[ZippedDir], List[ZippedFile]]]:
     """Walk through a ZipFile like os.walk, but with ZippedFile entries.
 
@@ -600,6 +602,9 @@ def walk(
         paths (for example "repo-abc/dir"). When top does not correspond to an
         explicit directory entry, the function still yields a subtree rooted at
         top, and dirpath values are archive paths under that prefix.
+    sort_entries : bool, optional
+        When True, sort directory names and file names for deterministic output.
+        Set to False for faster traversal when ordering does not matter.
 
     Yields
     ------
@@ -613,61 +618,70 @@ def walk(
     """
     tree_map: Dict[str, Dict[str, Any]] = defaultdict(lambda: {"dirs": set(), "files": {}})
 
-    # Normalize and index
-    for arcname in zipobj.namelist():
+    start = top.strip("/")
+    prefix = f"{start}/" if start else ""
+
+    def _is_dir(info: zipfile.ZipInfo) -> bool:
+        # ZipInfo.is_dir() exists on modern Python, but keep a safe fallback.
+        try:
+            return info.is_dir()  # type: ignore[attr-defined]
+        except Exception:
+            return info.filename.endswith("/")
+
+    # Single pass over the archive; restrict to subtree early when top is given.
+    for info in zipobj.infolist():
+        arcname = info.filename
         norm = arcname.rstrip("/")
+        if not norm:
+            continue
+
+        # Restrict to the requested subtree if provided.
+        if start:
+            if norm != start and not norm.startswith(prefix):
+                continue
+
         parts = norm.split("/")
         parent = "/".join(parts[:-1])  # "" at root
         leaf = parts[-1]
 
-        if arcname.endswith("/"):  # a directory entry
+        if _is_dir(info):
             tree_map[parent]["dirs"].add(leaf)
-        else:  # a file entry
-            tree_map[parent]["files"][leaf] = ZippedFile(
-                name=leaf, arcname=norm, zipobj=zipobj
-            )
+        else:
+            tree_map[parent]["files"][leaf] = ZippedFile(name=leaf, arcname=norm, zipobj=zipobj)
 
-        # ensure intermediate directories are known
+        # Ensure intermediate directories are known.
         for i in range(len(parts) - 1):
             up_parent = "/".join(parts[:i])
             up_child = parts[i]
             tree_map[up_parent]["dirs"].add(up_child)
 
-    start = top.rstrip("/")
-
-    # When top does not exist explicitly, build a filtered pseudo-map rooted at top
+    # If the subtree has no entries, return nothing.
     if start and start not in tree_map:
-        pseudo_map: Dict[str, Dict[str, Any]] = defaultdict(lambda: {"dirs": set(), "files": {}})
-        for arcname in zipobj.namelist():
-            if arcname.startswith(start + "/") or arcname.rstrip("/") == start:
-                norm = arcname.rstrip("/")
-                rel = norm[len(start):].lstrip("/")
-                parent = "/".join([start] + ([p for p in rel.split("/")[:-1]] if rel else []))
-                leaf = rel.split("/")[-1] if rel else start.split("/")[-1]
-                if arcname.endswith("/"):
-                    pseudo_map[parent]["dirs"].add(leaf)
-                else:
-                    pseudo_map[parent]["files"][leaf] = ZippedFile(leaf, norm, zipobj)
-                prefix_parts = parent.split("/") if parent else []
-                for i in range(len(prefix_parts)):
-                    up_parent = "/".join(prefix_parts[:i])
-                    up_child = prefix_parts[i]
-                    pseudo_map[up_parent]["dirs"].add(up_child)
-        tree_map = pseudo_map
-        if start and start not in tree_map:
-            return
+        return
 
     built_dirs: Dict[str, ZippedDir] = {}
 
     def _build(path: str) -> ZippedDir:
         if path in built_dirs:
             return built_dirs[path]
-        dirnames = sorted(tree_map[path]["dirs"])
-        files = [tree_map[path]["files"][k] for k in sorted(tree_map[path]["files"].keys())]
+
+        dirset = tree_map[path]["dirs"]
+        files_dict = tree_map[path]["files"]
+
+        if sort_entries:
+            dirnames = sorted(dirset)
+            filekeys = sorted(files_dict.keys())
+        else:
+            # Sets/dicts are already in-memory; avoid sorting for speed.
+            dirnames = list(dirset)
+            filekeys = list(files_dict.keys())
+
+        files = [files_dict[k] for k in filekeys]
         subs: List[ZippedDir] = []
         for name in dirnames:
             sub_path = f"{path}/{name}" if path else name
             subs.append(_build(sub_path))
+
         obj = ZippedDir(
             name=path.rsplit("/", 1)[-1] if path else "",
             path=path,

brkraw/dataclasses/__init__.py

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

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/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.3.dist-info → brkraw-0.5.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brkraw
-Version: 0.5.3
+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>
@@ -45,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.3) 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/)
@@ -70,7 +70,7 @@ If you use BrkRaw in your research, please cite it.
 @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},
-  version = {0.5.2},
+  version = {0.5.5},
   doi = {10.5281/zenodo.3818614},
   url = {https://github.com/BrkRaw/brkraw},
   note = {Documentation: https://brkraw.github.io},