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

brkraw/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = '0.5.3'
+__version__ = '0.5.6'
 from .apps.loader import BrukerLoader
 
 

brkraw/api/__init__.py

@@ -0,0 +1,122 @@
+"""Public API surface for BrkRaw.
+
+This module intentionally re-exports a curated set of symbols for external use.
+To keep import-time fast and reduce side effects, most symbols are lazily
+imported on first access (PEP 562: module `__getattr__`).
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any, Dict, Tuple
+
+# Public API -----------------------------------------------------------------
+
+__all__ = [
+    "formatter",
+    "BrukerLoader",
+    "loader",
+    "hook",
+    "hook_manager",
+    "hook_resolver",
+    "pruner",
+    "rules",
+    "addon",
+    "addon_manager",
+    "validate_meta",
+    "transform",
+    "info_resolver",
+    "affine_resolver",
+    "shape_resolver",
+    "image_resolver",
+    "fid_resolver",
+    "nifti_resolver",
+    "types",
+    "config",
+]
+
+# Lazy import map: name -> (module_path, attribute_name or None)
+# If attribute_name is None, the module itself is returned.
+_LAZY: Dict[str, Tuple[str, str | None]] = {
+    # core
+    "formatter": ("brkraw.core", "formatter"),
+
+    # apps
+    "BrukerLoader": ("brkraw.apps.loader", "BrukerLoader"),
+    "loader": ("brkraw.apps", "loader"),
+    "hook_manager": ("brkraw.apps", "hook"),
+    "addon_manager": ("brkraw.apps", "addon"),
+    "hook_resolver": ("brkraw.apps.loader.helper", "resolve_converter_hook"),
+    "config": ("brkraw.core", "config"),
+
+    # apps.loader.info resolvers
+    "info_resolver": ("brkraw.apps.loader", "info"),
+    "transform": ("brkraw.apps.loader.info", "transform"),
+
+    # resolvers
+    "affine_resolver": ("brkraw.resolver", "affine"),
+    "shape_resolver": ("brkraw.resolver", "shape"),
+    "image_resolver": ("brkraw.resolver", "image"),
+    "fid_resolver": ("brkraw.resolver", "fid"),
+    "nifti_resolver": ("brkraw.resolver", "nifti"),
+
+    # specs
+    "hook": ("brkraw.specs", "hook"),
+    "pruner": ("brkraw.specs", "pruner"),
+    "rules": ("brkraw.specs", "rules"),
+    "addon": ("brkraw.specs", "remapper"),
+
+    # meta
+    "validate_meta": ("brkraw.specs.meta", "validate_meta"),
+
+    # local
+    "types": ("brkraw.api", "types"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily import and return public symbols.
+
+    This keeps import-time minimal while preserving the convenient
+    `brkraw.api.<symbol>` access pattern.
+    """
+
+    try:
+        mod_path, attr = _LAZY[name]
+    except KeyError as e:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from e
+
+    mod = import_module(mod_path)
+    obj = mod if attr is None else getattr(mod, attr)
+
+    # Cache the resolved object on the module for fast subsequent access.
+    globals()[name] = obj
+    return obj
+
+
+def __dir__() -> list[str]:
+    # Expose the curated public surface in interactive environments.
+    return sorted(set(__all__))
+
+
+# Type-checking / IDE support -------------------------------------------------
+# Importing these only for type-checking keeps runtime imports lazy.
+if TYPE_CHECKING:
+    from brkraw.core import formatter as formatter
+    from brkraw.core import config as config
+    from brkraw.apps.loader import BrukerLoader as BrukerLoader
+    from brkraw.apps.loader import info as info_resolver
+    from brkraw.apps.loader.info import transform as transform
+    from brkraw.apps.loader.helper import resolve_converter_hook as hook_resolver
+    from brkraw.apps import addon as addon_manager, hook as hook_manager, loader as loader
+    from brkraw.resolver import (
+        affine as affine_resolver,
+        fid as fid_resolver,
+        image as image_resolver,
+        nifti as nifti_resolver,
+        shape as shape_resolver,
+    )
+    from brkraw.specs import hook as hook, pruner as pruner, rules as rules
+    from brkraw.specs import remapper as addon
+    from brkraw.specs.meta import validate_meta as validate_meta
+    from brkraw.api import types as types

brkraw/api/types.py

@@ -0,0 +1,39 @@
+from ..apps.loader.types import (
+    StudyLoader, 
+    ScanLoader, 
+    RecoLoader
+)
+from ..apps.loader.types import (
+    GetAffineType,
+    GetDataobjType,
+    ConvertType,
+    ConverterHook,
+    SubjectType, 
+    SubjectPose, 
+    AffineSpace,
+    Affines,
+    Dataobjs,
+    Metadata,
+    ConvertedObj,
+    HookArgs
+)
+from ..core.parameters import Parameters
+
+__all__ = [
+    "GetAffineType",
+    "GetDataobjType",
+    "ConvertType",
+    "ConverterHook",
+    "StudyLoader",
+    "ScanLoader",
+    "RecoLoader",
+    "SubjectType",
+    "SubjectPose",
+    "AffineSpace",
+    "Affines",
+    "Dataobjs",
+    "Metadata",
+    "ConvertedObj",
+    "HookArgs",
+    "Parameters"
+]

brkraw/apps/loader/__init__.py

@@ -1,10 +1,7 @@
-"""BrkRaw loader package entrypoint.
-
-Last updated: 2025-12-30
-"""
 from __future__ import annotations
 
-
 from .core import BrukerLoader
 
-__all__ = ["BrukerLoader"]
+__all__ = [
+    "BrukerLoader"
+]

brkraw/apps/loader/core.py

@@ -3,8 +3,6 @@
 This module binds helper methods onto Scan/Reco objects so callers can fetch
 reconstructed data, affines, NIfTI images, metadata, and parameter search
 results with a simple API.
-
-Last updated: 2025-12-30
 """
 
 from __future__ import annotations
@@ -14,19 +12,26 @@ import re
 import logging
 import sys
 from functools import partial
-from typing import TYPE_CHECKING, Optional, Tuple, Union, Any, Mapping, Callable, cast, List, Dict, Iterable, Literal
+from typing import (
+    TYPE_CHECKING, cast, 
+    Optional, Union, 
+    Any, Iterable,
+    Tuple, List, Mapping, Dict, Literal,
+)
 from pathlib import Path
 
 from ...core import config as config_core
 from ...core.config import resolve_root
-from ...specs import hook as converter_core
 from ...specs.pruner import prune_dataset_to_zip
 from ...specs.rules import load_rules, select_rule_use
-from ...dataclasses import Scan, Study
-from .types import StudyLoader, ScanLoader, RecoLoader
+from ...dataclasses import Study
+from .types import (
+    StudyLoader, 
+    ScanLoader, 
+    RecoLoader,
+)
 from .formatter import format_info_tables
 
-logger = logging.getLogger("brkraw")
 from . import info as info_resolver
 from .helper import (
     make_dir,
@@ -35,24 +40,39 @@ from .helper import (
     get_dataobj as _get_dataobj,
     get_metadata as _get_metadata,
     get_nifti1image as _get_nifti1image,
+    resolve_reco_id as _resolve_reco_id,
     search_parameters as _search_parameters,
     apply_converter_hook as _apply_converter_hook,
+    resolve_converter_hook as _resolve_converter_hook,
     resolve_data_and_affine as _resolve_data_and_affine,
 )
 
 if TYPE_CHECKING:
     import numpy as np
     from pathlib import Path
+    from .types import (
+        XYZUNIT, 
+        TUNIT, 
+        SubjectType, 
+        SubjectPose, 
+        InfoScope, 
+        AffineSpace,
+        Dataobjs,
+        Affines,
+        ConvertedObj,
+        Metadata,
+    )
     from ...resolver.nifti import Nifti1HeaderContents
-    from .types import XYZUNIT, TUNIT, SubjectType, SubjectPose, InfoScope, AffineSpace
     
+logger = logging.getLogger(__name__)
 
 
 class BrukerLoader:
     """High-level entrypoint that resolves scans and exposes handy accessors."""
 
     def __init__(self, 
-                 path: Union[str, Path], 
+                 path: Union[str, Path],
+                 disable_hook: bool = False,
                  affine_decimals: Optional[int] = None):
         """
         Create a loader for a Bruker study rooted at `path`.
@@ -68,8 +88,11 @@ class BrukerLoader:
         self._study: Union["Study", "StudyLoader"] = Study.from_path(path)
         if affine_decimals is None:
             affine_decimals = config_core.float_decimals(root=resolve_root(None))
+        self._base = resolve_root(None)
+        self._scans = {}
         self._affine_decimals = affine_decimals
         self._sw_version: Optional[str] = self._parse_sw_version()
+        self._hook_disabled = disable_hook
         self._attach_helpers()
 
     def _parse_sw_version(self) -> Optional[str]:
@@ -139,75 +162,52 @@ class BrukerLoader:
 
     def _attach_helpers(self):
         """Resolve per-scan metadata and bind helper methods."""
+        logger.debug("Attaching helpers to study %s", getattr(self._study.fs, "root", "?"))
         self._study = cast(StudyLoader, self._study)
         self._study.search_params = MethodType(_search_parameters, self._study)
-        base = resolve_root(None)
-        try:
-            rules = load_rules(root=base, validate=False)
-        except Exception:
-            rules = {}
-        for scan in self._study.avail.values():
+
+        for lazy_scan in self._study.avail.values():
+            scan = lazy_scan.materialize()
             _resolve_data_and_affine(
                 scan, 
                 affine_decimals=self._affine_decimals
                 )
-            scan = cast(ScanLoader, scan)
-
-            # bind helper functions as methods on the scan instance
-            scan.get_dataobj = MethodType(_get_dataobj, scan)
-            scan.get_affine = MethodType(
-                partial(_get_affine, decimals=self._affine_decimals),
-                scan,
-            )
-            scan.get_nifti1image = MethodType(_get_nifti1image, scan)
-            scan.convert = MethodType(_convert, scan)
-            scan._converter_hook = None
-            scan._converter_hook_name = None
-            scan.converter_func = None
-            if rules:
-                try:
-                    hook_name = select_rule_use(
-                        scan,
-                        rules.get("converter_hook", []),
-                        base=base,
-                        resolve_paths=False,
-                    )
-                except Exception as exc:
-                    logger.debug(
-                        "Converter hook rule selection failed for scan %s: %s",
-                        getattr(scan, "scan_id", "?"),
-                        exc,
-                        exc_info=True,
-                    )
-                    hook_name = None
-                if isinstance(hook_name, str):
-                    try:
-                        entry = converter_core.resolve_hook(hook_name)
-                    except Exception as exc:
-                        logger.warning(
-                            "Converter hook %r not available: %s",
-                            hook_name,
-                            exc,
-                        )
-                        entry = None
-                    if entry:
-                        logger.debug("Applying converter hook: %s", hook_name)
-                        scan._converter_hook_name = hook_name
-                        _apply_converter_hook(
-                            scan,
-                            entry,
-                            affine_decimals=self._affine_decimals,
-                        )
-                    else:
-                        logger.debug("Converter hook %r resolved to no entry.", hook_name)
-                else:
-                    logger.debug("No converter hook selected for scan %s.", getattr(scan, "scan_id", "?"))
+            scan = cast(ScanLoader, lazy_scan.materialize())
+            self.reset_converter(scan)
             scan.get_metadata = MethodType(_get_metadata, scan)
             scan.search_params = MethodType(_search_parameters, scan)
+            scan._hook_resolved = False
+
             for reco in scan.avail.values():
                 reco = cast(RecoLoader, reco)
                 reco.search_params = MethodType(_search_parameters, reco)
     
+    def _prep_scan(self, scan_id: int, reco_id: Optional[int] = None, **kwargs: Any) -> ScanLoader:
+        scan = self.get_scan(scan_id)
+
+        enable_hook = kwargs.get("enable_hook") # force enable
+        if enable_hook is not None:
+            del kwargs["enable_hook"]
+        else:
+            enable_hook = False
+
+        hook_is_enabled = enable_hook or not self._hook_disabled 
+
+        if hook_is_enabled:
+            if enable_hook:
+                logger.debug("hook enabled by optional argument for get_dataobj()")
+            if scan._hook_resolved is False:  # prevent multiple execution
+                _resolve_converter_hook(scan, self._base, affine_decimals=self._affine_decimals)
+
+        logger.debug(
+            "scan=%s reco=%s hook_enabled=%s hook=%s",
+            scan_id,
+            reco_id,
+            hook_is_enabled,
+            getattr(scan, "_converter_hook_name", None),
+        )
+        return scan
+
     def search_params(self, key: str, 
                       *, 
                       file: Optional[Union[str, List[str]]] = None, 
@@ -227,40 +227,22 @@ class BrukerLoader:
         self._study = cast(StudyLoader, self._study)
         return self._study.search_params(key, file=file, scan_id=scan_id, reco_id=reco_id)
 
-    def override_converter(
-        self,
-        scan_id: int,
-        converter_hook: Mapping[str, Callable[..., Any]],
-    ) -> None:
-        """Override scan conversion methods with a converter hook.
-
-        Args:
-            scan_id: Scan identifier.
-            converter_hook: Mapping of method names to callables. Only
-                provided keys are overridden.
-        """
-        scan = self.avail[scan_id]
-        scan = cast(ScanLoader, scan)
-        _apply_converter_hook(
-            scan,
-            converter_hook,
-            affine_decimals=self._affine_decimals,
-        )
-
-    def restore_converter(self, scan_id: int) -> None:
+    def reset_converter(self, scan: ScanLoader) -> None:
         """Restore default conversion methods for a scan.
 
         Args:
             scan_id: Scan identifier.
         """
-        scan = self.avail[scan_id]
-        scan = cast(ScanLoader, scan)
+        logger.debug("Initializing converter for scan %s", getattr(scan, "scan_id", "?"))
         scan.get_dataobj = MethodType(_get_dataobj, scan)
         scan.get_affine = MethodType(
             partial(_get_affine, decimals=self._affine_decimals),
             scan,
         )
+        scan.get_nifti1image = MethodType(_get_nifti1image, scan)
+        scan.convert = MethodType(_convert, scan)
         scan._converter_hook = None
+        scan._converter_hook_name = None
         scan.converter_func = None
 
     def get_scan(self, scan_id: int) -> "ScanLoader":
@@ -272,8 +254,7 @@ class BrukerLoader:
         Returns:
             Scan loader instance.
         """
-        scan = self._study.get_scan(scan_id)
-        scan = cast(ScanLoader, scan)
+        scan = cast(ScanLoader, self._study.get_scan(scan_id))
         return scan
 
     def get_fid(
@@ -298,9 +279,18 @@ class BrukerLoader:
         scan = self.get_scan(scan_id)
         if not hasattr(scan, 'get_fid'):
             return None
-        return scan.get_fid(buffer_start=buffer_start, buffer_size=buffer_size, as_complex=as_complex)
+        return scan.get_fid(
+            buffer_start=buffer_start, 
+            buffer_size=buffer_size, 
+            as_complex=as_complex
+        )
 
-    def get_dataobj(self, scan_id: int, reco_id: Optional[int] = None) -> Optional[Union[Tuple["np.ndarray", ...], "np.ndarray"]]:
+    def get_dataobj(
+            self, 
+            scan_id: int, 
+            reco_id: Optional[int] = None, 
+            **kwargs: Any
+    ) -> Dataobjs:
         """Return reconstructed data for a scan/reco via attached helper.
 
         Args:
@@ -310,18 +300,20 @@ class BrukerLoader:
         Returns:
             Single ndarray when one slice pack exists; otherwise a tuple.
         """
-        scan = self.get_scan(scan_id)
-        return scan.get_dataobj(reco_id)
-
-    def get_affine(self, 
-                   scan_id: int, 
-                   reco_id: Optional[int] = None,
-                   *,
-                   space: AffineSpace = 'subject_ras',
-                   override_subject_type: Optional[SubjectType] = None,
-                   override_subject_pose: Optional[SubjectPose] = None,
-                   decimals: Optional[int] = None
-                   ) -> Optional[Union[Tuple["np.ndarray", ...], "np.ndarray"]]:
+        scan = self._prep_scan(scan_id, reco_id, **kwargs)
+        return scan.get_dataobj(reco_id, **kwargs)
+
+    def get_affine(
+            self, 
+            scan_id: int, 
+            reco_id: Optional[int] = None,
+            *,
+            space: AffineSpace = 'subject_ras',
+            override_subject_type: Optional[SubjectType] = None,
+            override_subject_pose: Optional[SubjectPose] = None,
+            decimals: Optional[int] = None,
+            **kwargs: Any
+    ) -> Affines:
         """Return affine(s) for a scan/reco via attached helper.
 
         Args:
@@ -335,15 +327,16 @@ class BrukerLoader:
         Returns:
             Single affine matrix when one slice pack exists; otherwise a tuple.
         """
-        scan = self.get_scan(scan_id)
+        scan = self._prep_scan(scan_id, reco_id, **kwargs)
         decimals = decimals or self._affine_decimals
         return scan.get_affine(reco_id, 
                                space=space, 
                                override_subject_pose=override_subject_pose, 
                                override_subject_type=override_subject_type,
-                               decimals=decimals)
+                               decimals=decimals, **kwargs)
     
-    def get_nifti1image(self, scan_id: int, reco_id: Optional[int] = None,
+    def get_nifti1image(
+            self, scan_id: int, reco_id: Optional[int] = None,
                         *, 
                         space: AffineSpace = 'subject_ras',
                         override_header: Optional[Nifti1HeaderContents] = None,
@@ -351,7 +344,8 @@ class BrukerLoader:
                         override_subject_pose: Optional[SubjectPose] = None,
                         flatten_fg: bool = False,
                         xyz_units: XYZUNIT = 'mm', 
-                        t_units: TUNIT = 'sec'):
+                        t_units: TUNIT = 'sec'
+    ) -> ConvertedObj:
         """Return NIfTI image(s) for a scan/reco via attached helper.
 
         Args:
@@ -368,13 +362,23 @@ class BrukerLoader:
             Single NIfTI image when one slice pack exists; otherwise a tuple.
         """
         scan = self.get_scan(scan_id)
-        return scan.convert(
-            reco_id,
-            space=space,
+        dataobj = scan.get_dataobj(reco_id)
+        affine = scan.get_affine(reco_id, 
+                                 space=space, 
+                                 decimals=self._affine_decimals,
+                                 override_subject_pose=override_subject_pose,
+                                 override_subject_type=override_subject_type,
+                                 flatten_fg=flatten_fg,
+                                 xyz_units=xyz_units,
+                                 t_units=t_units)
+        resolved_reco_id = _resolve_reco_id(scan, reco_id)
+        if resolved_reco_id is None:
+            return None
+        return scan.get_nifti1image(
+            resolved_reco_id,
+            cast(Tuple[np.ndarray, ...], dataobj),
+            cast(Tuple[np.ndarray, ...], affine),
             override_header=override_header,
-            override_subject_type=override_subject_type,
-            override_subject_pose=override_subject_pose,
-            flatten_fg=flatten_fg,
             xyz_units=xyz_units,
             t_units=t_units,
         )
@@ -389,12 +393,11 @@ class BrukerLoader:
         override_subject_type: Optional[SubjectType] = None,
         override_subject_pose: Optional[SubjectPose] = None,
         flatten_fg: bool = False,
-        xyz_units: XYZUNIT = "mm",
-        t_units: TUNIT = "sec",
         hook_args_by_name: Optional[Mapping[str, Mapping[str, Any]]] = None,
-    ):
+        **kwargs: Any,
+    ) -> ConvertedObj:
         """Convert a scan/reco to output object(s) supporting to_filename()."""
-        scan = self.get_scan(scan_id)
+        scan = self._prep_scan(scan_id, reco_id, **kwargs)
         return scan.convert(
             reco_id,
             space=space,
@@ -402,9 +405,8 @@ class BrukerLoader:
             override_subject_type=override_subject_type,
             override_subject_pose=override_subject_pose,
             flatten_fg=flatten_fg,
-            xyz_units=xyz_units,
-            t_units=t_units,
             hook_args_by_name=hook_args_by_name,
+            **kwargs,
         )
 
     def get_metadata(
@@ -414,7 +416,7 @@ class BrukerLoader:
         spec: Optional[Union[Mapping[str, Any], str, Path]] = None,
         context_map: Optional[Union[str, Path]] = None,
         return_spec: bool = False,
-    ):
+    ) -> Metadata:
         """Return metadata for a scan/reco.
 
         Args:
@@ -472,9 +474,11 @@ class BrukerLoader:
         return BrukerLoader(out_path, affine_decimals=self._affine_decimals)
 
     @property
-    def avail(self) -> Mapping[int, Union["Scan", "ScanLoader"]]:
+    def avail(self) -> Mapping[int, "ScanLoader"]:
         """Available scans keyed by scan id."""
-        return self._study.avail
+        if len(self._scans) != len(self._study.avail):
+            self._scans = {scan_id: cast(ScanLoader, scan.materialize()) for scan_id, scan in self._study.avail.items()}
+        return self._scans
     
     @property
     def subject(self) -> Optional[Dict[str, Any]]:

brkraw/apps/loader/formatter.py

@@ -1,6 +1,4 @@
 """Formatting helpers for loader info output.
-
-Last updated: 2025-12-30
 """
 
 from __future__ import annotations