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

brkraw/apps/loader/info/scan.py

@@ -8,9 +8,9 @@ from ....specs.remapper.validator import validate_spec
 
 
 if TYPE_CHECKING:
-    from ..types import ScanLoader, RecoLoader
+    from ..types import ScanLoader
 
-logger = logging.getLogger("brkraw")
+logger = logging.getLogger(__name__)
 
 
 def resolve(

brkraw/apps/loader/info/transform.py

@@ -2,7 +2,6 @@ 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:

brkraw/apps/loader/types.py

@@ -5,7 +5,7 @@ Last updated: 2025-12-30
 
 from __future__ import annotations
 
-from typing import Any, Union, Tuple, Dict, Optional, Protocol, Literal, Mapping, Callable, List, TYPE_CHECKING
+from typing import Any, Union, Tuple, Dict, Optional, Protocol, Literal, Mapping, List, TYPE_CHECKING, runtime_checkable
 if TYPE_CHECKING:
     from typing_extensions import ParamSpec, TypeAlias
 else:
@@ -16,37 +16,46 @@ else:
 from ...dataclasses.study import Study
 from ...dataclasses.scan import Scan
 from ...dataclasses.reco import Reco
+from ...resolver.affine import SubjectType, SubjectPose
 import numpy as np
+from numpy.typing import NDArray
 
 if TYPE_CHECKING:
     from pathlib import Path
     from ...core.parameters import Parameters
     from ...resolver.image import ResolvedImage
-    from ...resolver.affine import ResolvedAffine, SubjectType, SubjectPose
+    from ...resolver.affine import ResolvedAffine
     from ...resolver.nifti import Nifti1HeaderContents, XYZUNIT, TUNIT
-    from nibabel.nifti1 import Nifti1Image
-    
 
 
 InfoScope = Literal['full', 'study', 'scan']
-AffineReturn = Optional[Union[np.ndarray, Tuple[np.ndarray, ...]]]
+Dataobjs = Optional[Union[NDArray, Tuple[NDArray, ...]]]
+Affines = Optional[Union[NDArray, Tuple[NDArray, ...]]]
 AffineSpace = Literal["raw", "scanner", "subject_ras"]
+ConvertedObj = Optional[Union["ToFilename", Tuple["ToFilename", ...]]]
+Metadata = Optional[Union[Dict, Tuple[Optional[Dict], ...]]]
+HookArgs = Optional[Mapping[str, Mapping[str, Any]]]
+
 
 P = ParamSpec("P")
 
 
+@runtime_checkable
 class GetDataobjType(Protocol[P]):
     """Callable signature for get_dataobj overrides."""
     def __call__(
         self,
         scan: "Scan",
         reco_id: Optional[int],
+        cycle_index: Optional[int],
+        cycle_count: Optional[int],
         *args: P.args,
         **kwargs: P.kwargs
-    ) -> Optional[Union[Tuple["np.ndarray", ...], "np.ndarray"]]:
+    ) -> Dataobjs:
         ...
 
 
+@runtime_checkable
 class GetAffineType(Protocol):
     """Callable signature for get_affine overrides."""
     def __call__(
@@ -59,48 +68,25 @@ class GetAffineType(Protocol):
         override_subject_pose: Optional[SubjectPose],
         decimals: Optional[int] = None,
         **kwargs: Any
-    ) -> Optional[Union[Tuple["np.ndarray", ...], "np.ndarray"]]:
-        ...
-
-
-class GetNifti1ImageType(Protocol):
-    """Callable signature for get_nifti1image overrides."""
-    def __call__(
-        self,
-        scan: "Scan",
-        reco_id: Optional[int] = None,
-        *,
-        override_header: Optional[Union[dict, "Nifti1HeaderContents"]],
-        space: AffineSpace,
-        override_subject_type: Optional[SubjectType],
-        override_subject_pose: Optional[SubjectPose],
-        flip_x: bool,
-        flatten_fg: bool,
-        xyz_units: XYZUNIT,
-        t_units: TUNIT,
-        **kwargs: Any,
-    ) -> Optional[Union[Tuple["Nifti1Image", ...], "Nifti1Image"]]:
+    ) -> Affines:
         ...
 
 
+@runtime_checkable
 class ConvertType(Protocol):
     """Callable signature for convert overrides."""
     def __call__(
         self,
         scan: "Scan",
-        reco_id: Optional[int] = None,
-        *,
-        format: Union[Literal["nifti", "nifti1"], str],
-        override_header: Optional[Union[dict, "Nifti1HeaderContents"]],
-        space: AffineSpace,
-        override_subject_type: Optional[SubjectType],
-        override_subject_pose: Optional[SubjectPose],
-        flip_x: bool,
-        flatten_fg: bool,
-        xyz_units: XYZUNIT,
-        t_units: TUNIT,
+        dataobj: Union[Tuple["np.ndarray", ...], "np.ndarray"],
+        affine: Union[Tuple["np.ndarray", ...], "np.ndarray"],
         **kwargs: Any,
-    ) -> Optional[Union[Tuple["Nifti1Image", ...], "Nifti1Image"]]:
+    ) -> ConvertedObj:
+        ...
+
+class ToFilename(Protocol):
+    """Result object that can be written to disk."""
+    def to_filename(self, filename: Union[str, "Path"], *args: Any, **kwargs: Any) -> Any:
         ...
 
 
@@ -126,9 +112,12 @@ class ScanLoader(Scan, BaseLoader):
 
     image_info: Dict[int, Optional["ResolvedImage"]]
     affine_info: Dict[int, Optional["ResolvedAffine"]]
+    converter_func: Optional[ConvertType]
     _converter_hook: Optional[ConverterHook]
     _converter_hook_name: Optional[str]
-
+    _hook_resolved: bool = False
+    
+    
     def get_fid(self, 
                 buffer_start: Optional[int], 
                 buffer_size: Optional[int], 
@@ -138,8 +127,12 @@ class ScanLoader(Scan, BaseLoader):
 
     def get_dataobj(
             self, 
-            reco_id: Optional[int] = None
-            ) -> Optional[Union[Tuple["np.ndarray", ...], "np.ndarray"]]: 
+            reco_id: Optional[int] = None,
+            *,
+            cycle_index: Optional[int] = None,
+            cycle_count: Optional[int] = None,
+            **kwargs: Any
+            ) -> Dataobjs: 
         ...
 
     def get_affine(
@@ -151,39 +144,35 @@ class ScanLoader(Scan, BaseLoader):
             override_subject_pose: Optional[SubjectPose],
             decimals: Optional[int] = None,
             **kwargs: Any,
-            ) -> Optional[Union[Tuple["np.ndarray", ...], "np.ndarray"]]:
+            ) -> Affines:
         ...
 
     def get_nifti1image(
-            self, 
-            reco_id: Optional[int] = None, 
+            self,
+            reco_id: int, 
+            dataobjs: Tuple["np.ndarray", ...],
+            affines: Tuple["np.ndarray", ...],
             *, 
             override_header: Optional[Union[dict, "Nifti1HeaderContents"]],
-            space: AffineSpace = "subject_ras",
-            override_subject_type: Optional[SubjectType],
-            override_subject_pose: Optional[SubjectPose],
-            flip_x: bool, 
-            flatten_fg: bool,
             xyz_units: XYZUNIT, 
             t_units: TUNIT
-            ) -> Optional[Union[Tuple["Nifti1Image", ...], "Nifti1Image"]]:
+            ) -> ConvertedObj:
         ...
 
     def convert(
             self,
             reco_id: Optional[int] = None,
             *,
-            format: Literal["nifti", "nifti1"],
-            override_header: Optional[Union[dict, "Nifti1HeaderContents"]],
             space: AffineSpace = "subject_ras",
+            override_header: Optional[Union[dict, "Nifti1HeaderContents"]],
             override_subject_type: Optional[SubjectType],
             override_subject_pose: Optional[SubjectPose],
-            flip_x: bool,
             flatten_fg: bool,
             xyz_units: XYZUNIT,
             t_units: TUNIT,
-            hook_args_by_name: Optional[Mapping[str, Mapping[str, Any]]] = None,
-            ) -> Optional[Union[Tuple["Nifti1Image", ...], "Nifti1Image"]]:
+            hook_args_by_name: HookArgs = None,
+            **kwargs: Any,
+            ) -> ConvertedObj:
         ...
 
     def get_metadata(
@@ -192,7 +181,7 @@ class ScanLoader(Scan, BaseLoader):
             spec: Optional[Union[Mapping[str, Any], str, "Path"]] = None,
             context_map: Optional[Union[str, "Path"]] = None,
             return_spec: bool = False,
-            ) -> Optional[Union[dict, Tuple[Optional[dict], Optional[dict]]]]:
+            ) -> Metadata:
         ...
 
 
@@ -201,19 +190,27 @@ class RecoLoader(Reco, BaseLoader):
     ...
 
 
-ConverterHook: TypeAlias = Mapping[str, Union[GetDataobjType[Any], GetAffineType, GetNifti1ImageType, ConvertType]]
+ConverterHook: TypeAlias = Mapping[str, Union[GetDataobjType[Any], GetAffineType, ConvertType]]
 """Mapping of converter hook keys to override callables."""
 
 
 __all__ = [
     'GetDataobjType',
     'GetAffineType',
-    'GetNifti1ImageType',
     'ConvertType',
+    'ToFilename',
     'ConverterHook',
     'StudyLoader',
     'ScanLoader',
     'RecoLoader',
+    'SubjectType',
+    'SubjectPose',
+    'Affines',
+    'Dataobjs',
+    'Metadata',
+    'ConvertedObj',
+    'HookArgs',
+    'AffineSpace',
 ]
 
 def __dir__() -> List[str]:

brkraw/cli/commands/addon.py

@@ -10,7 +10,7 @@ from brkraw.core import config as config_core
 from brkraw.core import formatter
 from brkraw.apps import addon as addon_app
 
-logger = logging.getLogger("brkraw")
+logger = logging.getLogger(__name__)
 
 
 def cmd_addon(args: argparse.Namespace) -> int:

brkraw/cli/commands/cache.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import argparse
+import logging
+from typing import Optional
+
+from ...core import cache
+
+logger = logging.getLogger(__name__)
+
+
+def cmd_cache(args: argparse.Namespace) -> int:
+    handler = getattr(args, "cache_func", None)
+    if handler is None:
+        args.parser.print_help()
+        return 2
+    return handler(args)
+
+
+def cmd_info(args: argparse.Namespace) -> int:
+    info = cache.get_info(root=args.root)
+    path = info["path"]
+    size = info["size"]
+    count = info["count"]
+
+    # Format size
+    unit = "B"
+    size_f = float(size)
+    for u in ["B", "KB", "MB", "GB", "TB"]:
+        unit = u
+        if size_f < 1024:
+            break
+        size_f /= 1024
+
+    print(f"Path:  {path}")
+    print(f"Size:  {size_f:.2f} {unit}")
+    print(f"Files: {count}")
+    return 0
+
+
+def cmd_clear(args: argparse.Namespace) -> int:
+    if not args.yes:
+        info = cache.get_info(root=args.root)
+        if info["count"] == 0:
+            print("Cache is already empty.")
+            return 0
+        path = info["path"]
+        prompt = f"Clear {info['count']} files from {path}? [y/N]: "
+        try:
+            reply = input(prompt).strip().lower()
+        except EOFError:
+            reply = ""
+        if reply not in {"y", "yes"}:
+            return 1
+    
+    cache.clear(root=args.root)
+    print("Cache cleared.")
+    return 0
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[name-defined]
+    cache_parser = subparsers.add_parser(
+        "cache",
+        help="Manage brkraw cache.",
+    )
+    cache_parser.add_argument(
+        "--root",
+        help="Override config root directory (default: BRKRAW_CONFIG_HOME or ~/.brkraw).",
+    )
+    cache_parser.set_defaults(func=cmd_cache, parser=cache_parser)
+    cache_sub = cache_parser.add_subparsers(dest="cache_command")
+
+    info_parser = cache_sub.add_parser("info", help="Show cache information.")
+    info_parser.set_defaults(cache_func=cmd_info)
+
+    clear_parser = cache_sub.add_parser("clear", help="Clear cache contents.")
+    clear_parser.add_argument(
+        "--yes", "-y",
+        action="store_true",
+        help="Do not prompt for confirmation.",
+    )
+    clear_parser.set_defaults(cache_func=cmd_clear)

brkraw/cli/commands/config.py

@@ -11,7 +11,7 @@ import subprocess
 
 from brkraw.core import config as config_core
 
-logger = logging.getLogger("brkraw")
+logger = logging.getLogger(__name__)
 
 
 def cmd_config(args: argparse.Namespace) -> int:
@@ -179,7 +179,7 @@ def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[na
     path_parser = config_sub.add_parser("path", help="Print a specific config path.")
     path_parser.add_argument(
         "name",
-        choices=["root", "config", "rules", "specs", "transforms"],
+        choices=["root", "config", "rules", "specs", "transforms", "cache"],
         help="Path key to print.",
     )
     path_parser.set_defaults(config_func=cmd_path)

brkraw/cli/commands/convert.py

@@ -11,9 +11,8 @@ import json
 import logging
 import os
 import re
-import sys
 from pathlib import Path
-from typing import Any, Mapping, Optional, Dict, List, Tuple, Literal, cast, get_args
+from typing import Any, Mapping, Optional, Dict, List, Tuple, cast, get_args
 
 import numpy as np
 from brkraw.cli.utils import load
@@ -27,7 +26,7 @@ from brkraw.resolver.affine import SubjectPose, SubjectType
 from brkraw.apps.loader.types import AffineSpace
 
 
-logger = logging.getLogger("brkraw")
+logger = logging.getLogger(__name__)
 
 _INVALID_CHARS = re.compile(r"[^A-Za-z0-9._-]+")
 
@@ -84,10 +83,30 @@ def cmd_convert(args: argparse.Namespace) -> int:
     if args.no_convert and not args.sidecar:
         logger.error("--no-convert requires --sidecar.")
         return 2
-    if not args.flip_x:
-        args.flip_x = _env_flag("BRKRAW_CONVERT_FLIP_X")
     if not args.flatten_fg:
         args.flatten_fg = _env_flag("BRKRAW_CONVERT_FLATTEN_FG")
+
+    # resolve cycle_index/cycle_count from env
+    if args.cycle_index is None:
+        value = os.environ.get("BRKRAW_CONVERT_CYCLE_INDEX")
+        if value:
+            try:
+                args.cycle_index = int(value)
+            except ValueError:
+                logger.error("Invalid BRKRAW_CONVERT_CYCLE_INDEX: %s", value)
+                return 2
+    if args.cycle_count is None:
+        value = os.environ.get("BRKRAW_CONVERT_CYCLE_COUNT")
+        if value:
+            try:
+                args.cycle_count = int(value)
+            except ValueError:
+                logger.error("Invalid BRKRAW_CONVERT_CYCLE_COUNT: %s", value)
+                return 2
+    # if cycle_count is set but cycle_index is not, default cycle_index to 0
+    if args.cycle_index is None and args.cycle_count is not None:
+        args.cycle_index = 0
+
     if args.space is None:
         args.space = os.environ.get("BRKRAW_CONVERT_SPACE")
     if args.override_subject_type is None:
@@ -119,7 +138,6 @@ def cmd_convert(args: argparse.Namespace) -> int:
     if args.space is None:
         args.space = "subject_ras"
     for attr, env_key in (
-        ("format", "BRKRAW_CONVERT_FORMAT"),
         ("header", "BRKRAW_CONVERT_HEADER"),
         ("context_map", "BRKRAW_CONVERT_CONTEXT_MAP"),
     ):
@@ -139,13 +157,6 @@ def cmd_convert(args: argparse.Namespace) -> int:
             logger.error("Cannot use --prefix when --output is a file path.")
             return 2
 
-    args.format = _coerce_choice(
-        "BRKRAW_CONVERT_FORMAT",
-        args.format or "nifti",
-        ("nifti", "nifti1"),
-        default="nifti",
-    )
-
     try:
         render_layout_supports_counter = "counter" in inspect.signature(layout_core.render_layout).parameters
     except (TypeError, ValueError):
@@ -179,6 +190,7 @@ def cmd_convert(args: argparse.Namespace) -> int:
     hook_args_by_name = merge_hook_args(hook_args_by_name, hook_args_cli)
 
     loader = load(args.path, prefix="Loading")
+    logger.debug("Dataset: %s loaded", args.path)
     try:
         override_header = nifti_resolver.load_header_overrides(args.header)
     except ValueError:
@@ -234,7 +246,9 @@ def cmd_convert(args: argparse.Namespace) -> int:
         if scan_id is None:
             continue
         scan = loader.get_scan(scan_id)
+        logger.debug("Processing scan %s.", scan_id)
         reco_ids = [args.reco_id] if args.reco_id is not None else list(scan.avail.keys())
+        logger.debug("Recos: %s", reco_ids or "None")
         if not reco_ids:
             if getattr(scan, "_converter_hook", None):
                 reco_ids = [None]
@@ -262,20 +276,26 @@ def cmd_convert(args: argparse.Namespace) -> int:
                 nii_list: List[Any] = []
                 output_count = 1
             else:
-                nii = loader.convert(
-                    scan_id,
-                    reco_id=reco_id,
-                    format=cast(Literal["nifti", "nifti1"], args.format),
-                    space=cast(AffineSpace, args.space),
-                    override_header=cast(Nifti1HeaderContents, override_header) if override_header else None,
-                    override_subject_type=cast(Optional[SubjectType], args.override_subject_type),
-                    override_subject_pose=cast(Optional[SubjectPose], args.override_subject_pose),
-                    flip_x=args.flip_x,
-                    flatten_fg=args.flatten_fg,
-                    xyz_units=cast(XYZUNIT, args.xyz_units),
-                    t_units=cast(TUNIT, args.t_units),
-                    hook_args_by_name=hook_args_by_name,
-                )
+                try:
+                    nii = loader.convert(
+                        scan_id,
+                        reco_id=reco_id,
+                        space=cast(AffineSpace, args.space),
+                        override_header=cast(Nifti1HeaderContents, override_header) if override_header else None,
+                        override_subject_type=cast(Optional[SubjectType], args.override_subject_type),
+                        override_subject_pose=cast(Optional[SubjectPose], args.override_subject_pose),
+                        flatten_fg=args.flatten_fg,
+                        xyz_units=cast(XYZUNIT, args.xyz_units),
+                        t_units=cast(TUNIT, args.t_units),
+                        hook_args_by_name=hook_args_by_name,
+                        cycle_index=args.cycle_index,
+                        cycle_count=args.cycle_count,
+                    )
+                except Exception as exc:
+                    logger.error("Conversion failed for scan %s reco %s: %s", scan_id, reco_id, exc)
+                    if not batch_all and args.reco_id is not None:
+                        return 2
+                    continue
                 if nii is None:
                     if not batch_all and args.reco_id is not None:
                         logger.error("No NIfTI output generated for scan %s reco %s.", scan_id, reco_id)
@@ -686,7 +706,10 @@ def _parse_hook_args(values: List[str]) -> Dict[str, Dict[str, Any]]:
         key = key.strip()
         if not hook_name or not key:
             raise ValueError("Hook args must include hook name and key.")
-        parsed.setdefault(hook_name, {})[key] = _coerce_scalar(value.strip())
+        coerced_value = _coerce_scalar(value.strip())
+        logger.debug("Parsed hook arg %s:%s=%s", hook_name, key, coerced_value)
+        parsed.setdefault(hook_name, {})[key] = coerced_value
+    logger.debug("Parsed hook args: %s", parsed)
     return parsed
 
 
@@ -781,11 +804,6 @@ def _add_convert_args(
             type=int,
             help="Reco id to convert (defaults to all recos when omitted).",
         )
-    parser.add_argument(
-        "--flip-x",
-        action="store_true",
-        help="Flip x-axis in NIfTI header.",
-    )
     parser.add_argument(
         "--xyz-units",
         choices=list(get_args(XYZUNIT)),
@@ -854,16 +872,21 @@ def _add_convert_args(
         choices=list(get_args(SubjectPose)),
         help="Override subject pose for subject-view affines (space=subject_ras).",
     )
-    parser.add_argument(
-        "--format",
-        choices=["nifti", "nifti1"],
-        help="Output format (default: nifti).",
-    )
     parser.add_argument(
         "--flatten-fg",
         action="store_true",
         help="Flatten frame-group dimensions to 4D when data is 5D or higher.",
     )
+    parser.add_argument(
+        "--cycle-index",
+        type=int,
+        help="Start cycle index (last axis). When set, read only a subset of cycles.",
+    )
+    parser.add_argument(
+        "--cycle-count",
+        type=int,
+        help="Number of cycles to read starting at --cycle-index. When omitted, reads to the end.",
+    )
     parser.add_argument(
         "--no-compress",
         dest="compress",

brkraw/cli/commands/hook.py

@@ -15,7 +15,7 @@ from brkraw.core import formatter
 from brkraw.specs import hook as converter_core
 import yaml
 
-logger = logging.getLogger("brkraw")
+logger = logging.getLogger(__name__)
 
 
 def cmd_hook(args: argparse.Namespace) -> int:
@@ -178,12 +178,10 @@ _PRESET_IGNORE_PARAMS = frozenset(
         "scan",
         "scan_id",
         "reco_id",
-        "format",
         "space",
         "override_header",
         "override_subject_type",
         "override_subject_pose",
-        "flip_x",
         "xyz_units",
         "t_units",
         "decimals",

brkraw/cli/commands/info.py

@@ -7,7 +7,7 @@ from pathlib import Path
 from brkraw.core import config as config_core
 from brkraw.cli.utils import load
 
-logger = logging.getLogger("brkraw")
+logger = logging.getLogger(__name__)
 
 
 def cmd_info(args: argparse.Namespace) -> int:

brkraw/cli/commands/init.py

@@ -13,7 +13,7 @@ import yaml
 from brkraw.core import config as config_core
 from brkraw.apps import addon as addon_app
 
-logger = logging.getLogger("brkraw")
+logger = logging.getLogger(__name__)
 
 
 def cmd_init(args: argparse.Namespace) -> int:

brkraw/cli/commands/params.py

@@ -14,7 +14,7 @@ import numpy as np
 
 from brkraw.cli.utils import load
 
-logger = logging.getLogger("brkraw")
+logger = logging.getLogger(__name__)
 
 
 def cmd_params(args: argparse.Namespace) -> int:

brkraw/cli/commands/prune.py

@@ -6,7 +6,7 @@ import argparse
 import logging
 from datetime import datetime
 from pathlib import Path
-from typing import Optional, Union
+from typing import Optional
 
 import yaml
 
@@ -14,7 +14,7 @@ from brkraw.cli.utils import spinner
 from brkraw.core import config as config_core
 from brkraw.specs.pruner import prune_dataset_to_zip_from_spec
 
-logger = logging.getLogger("brkraw")
+logger = logging.getLogger(__name__)
 
 
 def cmd_prune(args: argparse.Namespace) -> int: