brkraw 0.5.2__tar.gz → 0.5.3__tar.gz

{brkraw-0.5.2 → brkraw-0.5.3}/.github/workflows/release_on_merge.yml

@@ -29,11 +29,10 @@ jobs:
           import re
           from pathlib import Path
 
-          text = Path("src/brkraw/__init__.py").read_text(encoding="utf-8")
+          text = Path("src/brkraw/__init__.py").read_text(encoding="utf-8").lstrip("\\ufeff")
           match = re.search(
-              r"^\\s*__version__(?:\\s*:\\s*[^=]+)?\\s*=\\s*['\\\"]([^'\\\"]+)['\\\"]",
+              r"__version__(?:\s*:\s*[^=]+)?\s*=\s*['\"]([^'\"]+)['\"]",
               text,
-              re.M,
           )
           if not match:
               raise SystemExit("No __version__ found in src/brkraw/__init__.py")

{brkraw-0.5.2 → brkraw-0.5.3}/CITATION.cff

@@ -34,4 +34,4 @@ keywords:
   - BIDS
   - neuroimaging
 
-version: "0.5.2"
+version: "0.5.3"

{brkraw-0.5.2 → brkraw-0.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brkraw
-Version: 0.5.2
+Version: 0.5.3
 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
@@ -48,7 +49,7 @@ Description-Content-Type: text/markdown
 
 A modular toolkit for Bruker MRI raw-data handling.
 
-BrkRaw (v0.5.2) converts raw data into standardized, neuroimaging-ready
+BrkRaw (v0.5.3) 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.2},
   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 -->

{brkraw-0.5.2 → brkraw-0.5.3}/README.md

@@ -10,7 +10,7 @@
 
 A modular toolkit for Bruker MRI raw-data handling.
 
-BrkRaw (v0.5.2) converts raw data into standardized, neuroimaging-ready
+BrkRaw (v0.5.3) converts raw data into standardized, neuroimaging-ready
 datasets, with extensible rules/specs and plugin hooks.
 
 - Documentation: [brkraw.github.io](https://brkraw.github.io/)
@@ -28,16 +28,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.2},
   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 -->

brkraw-0.5.3/RELEASE_NOTES.md

@@ -0,0 +1,13 @@
+# Release v0.5.3
+
+Date: 2026-01-21
+Changes since 0.5.2
+
+- fix: avoid gh pr graphql in release_pr (6311e09)
+- docs: release notes for v0.5.3 (2e427de)
+- chore: prepare release v0.5.3 (15e1158)
+- docs: update contributors (83d68bf)
+- Add debug logging for converter hooks (db8943d)
+- refactor: drop flip_x from nifti header (14e5304)
+- refactor: route hook kwargs by signature and drop format option (4c3f4d6)
+- readme.md biblatex update (b39e11d)

{brkraw-0.5.2 → brkraw-0.5.3}/brkraw/__init__.py

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

{brkraw-0.5.2 → brkraw-0.5.3}/brkraw/apps/loader/core.py

@@ -163,6 +163,7 @@ class BrukerLoader:
             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(
@@ -259,9 +260,8 @@ class BrukerLoader:
             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_func = None
 
     def get_scan(self, scan_id: int) -> "ScanLoader":
         """Return scan by id.
@@ -349,7 +349,6 @@ class BrukerLoader:
                         override_header: Optional[Nifti1HeaderContents] = None,
                         override_subject_type: Optional[SubjectType] = None,
                         override_subject_pose: Optional[SubjectPose] = None,
-                        flip_x: bool = False, 
                         flatten_fg: bool = False,
                         xyz_units: XYZUNIT = 'mm', 
                         t_units: TUNIT = 'sec'):
@@ -362,7 +361,6 @@ class BrukerLoader:
             override_header: Optional header values to apply.
             override_subject_type: Subject type override for subject view.
             override_subject_pose: Subject pose override for subject view.
-            flip_x: If True, set NIfTI header x-flip flag.
             xyz_units: Spatial units for NIfTI header.
             t_units: Temporal units for NIfTI header.
 
@@ -372,12 +370,10 @@ class BrukerLoader:
         scan = self.get_scan(scan_id)
         return scan.convert(
             reco_id,
-            format="nifti",
             space=space,
             override_header=override_header,
             override_subject_type=override_subject_type,
             override_subject_pose=override_subject_pose,
-            flip_x=flip_x,
             flatten_fg=flatten_fg,
             xyz_units=xyz_units,
             t_units=t_units,
@@ -388,27 +384,23 @@ class BrukerLoader:
         scan_id: int,
         reco_id: Optional[int] = None,
         *,
-        format: Literal["nifti", "nifti1"] = "nifti",
         space: AffineSpace = 'subject_ras',
         override_header: Optional[Nifti1HeaderContents] = None,
         override_subject_type: Optional[SubjectType] = None,
         override_subject_pose: Optional[SubjectPose] = None,
-        flip_x: bool = False,
         flatten_fg: bool = False,
         xyz_units: XYZUNIT = "mm",
         t_units: TUNIT = "sec",
         hook_args_by_name: Optional[Mapping[str, Mapping[str, Any]]] = None,
     ):
-        """Convert a scan/reco to the requested output format."""
+        """Convert a scan/reco to output object(s) supporting to_filename()."""
         scan = self.get_scan(scan_id)
         return scan.convert(
             reco_id,
-            format=format,
             space=space,
             override_header=override_header,
             override_subject_type=override_subject_type,
             override_subject_pose=override_subject_pose,
-            flip_x=flip_x,
             flatten_fg=flatten_fg,
             xyz_units=xyz_units,
             t_units=t_units,

{brkraw-0.5.2 → brkraw-0.5.3}/brkraw/apps/loader/helper.py

@@ -21,7 +21,7 @@ from ...core.parameters import Parameters
 from ...specs.remapper import load_spec, map_parameters, load_context_map, apply_context_map
 from ...specs.rules import load_rules, select_rule_use
 from ...dataclasses import Reco, Scan, Study
-from .types import ScanLoader
+from .types import ScanLoader, ToFilename, ConvertType, GetDataobjType, GetAffineType
 from ...specs import hook as converter_core
 from ...resolver import affine as affine_resolver
 from ...resolver import image as image_resolver
@@ -472,6 +472,54 @@ def _apply_affine_post_transform(affines: AffineReturn, *, kwargs: Mapping[str,
 
 
 def get_nifti1image(
+    self: Union["Scan", "ScanLoader"],
+    reco_id: int,
+    dataobjs: Tuple[np.ndarray, ...],
+    affines: Tuple[np.ndarray, ...],
+    *,
+    xyz_units: XYZUNIT = "mm",
+    t_units: TUNIT = "sec",
+    override_header: Optional[Nifti1HeaderContents] = None,
+) -> Optional[Union[Tuple["Nifti1Image", ...], "Nifti1Image"]]:
+    """Return NIfTI image(s) for a reco.
+
+    Args:
+        self: Scan or ScanLoader instance.
+        reco_id: Reco identifier to read (defaults to the first available).
+        xyz_units: Spatial units for NIfTI header.
+        t_units: Temporal units for NIfTI header.
+        override_header: Optional header values to apply.
+
+    Returns:
+        Output object(s) supporting to_filename(). Returns None when required
+        metadata is unavailable.
+    """
+    self = cast(ScanLoader, self)
+    
+    image_info = self.image_info.get(reco_id)
+    if dataobjs is None or affines is None or image_info is None:
+        return None
+
+    niiobjs = []
+    for i, dataobj in enumerate(dataobjs):
+        affine = affines[i]
+        niiobj = Nifti1Image(dataobj, affine)
+        nifti1header_contents = nifti_resolver.resolve(
+            image_info, xyz_units=xyz_units, t_units=t_units
+        )
+        if override_header:
+            for key, value in override_header.items():
+                if value is not None:
+                    nifti1header_contents[key] = value
+        niiobj = nifti_resolver.update(niiobj, nifti1header_contents)
+        niiobjs.append(niiobj)
+
+    if len(niiobjs) == 1:
+        return niiobjs[0]
+    return tuple(niiobjs)
+
+
+def convert(
     self: Union["Scan", "ScanLoader"],
     reco_id: Optional[int] = None,
     *,
@@ -479,30 +527,30 @@ def get_nifti1image(
     override_header: Optional[Nifti1HeaderContents] = None,
     override_subject_type: Optional[SubjectType] = None,
     override_subject_pose: Optional[SubjectPose] = None,
-    flip_x: bool = False,
     flatten_fg: bool = False,
     xyz_units: XYZUNIT = "mm",
     t_units: TUNIT = "sec",
     hook_args_by_name: Optional[Mapping[str, Mapping[str, Any]]] = None,
-) -> Optional[Union[Tuple["Nifti1Image", ...], "Nifti1Image"]]:
-    """Return NIfTI image(s) for a reco.
-
+    **kwargs: Any,
+) -> Optional[Union["ToFilename", Tuple["ToFilename", ...]]]:
+    """Convert a reco to output object(s).
+    
     Args:
-        self: Scan or ScanLoader instance.
-        reco_id: Reco identifier to read (defaults to the first available).
         space: Output affine space ("raw", "scanner", "subject_ras").
         override_header: Optional header values to apply.
         override_subject_type: Subject type override for subject-view wrapping.
         override_subject_pose: Subject pose override for subject-view wrapping.
-        flip_x: If True, set NIfTI header x-flip flag.
+        flatten_fg: If True, flatten foreground dimensions.
+        xyz_units: Spatial units for NIfTI header.
+        t_units: Temporal units for NIfTI header.
+        hook_args_by_name: Optional hook args mapping (split per helper signature).
+        flatten_fg: If True, flatten foreground dimensions.
         xyz_units: Spatial units for NIfTI header.
         t_units: Temporal units for NIfTI header.
-
     Returns:
         Single NIfTI image when one slice pack exists; otherwise a tuple of
         images. Returns None when required metadata is unavailable.
     """
-
     if not all(
         hasattr(self, attr) for attr in ["image_info", "affine_info", "get_dataobj", "get_affine"]
     ):
@@ -512,14 +560,57 @@ def get_nifti1image(
     resolved_reco_id = _resolve_reco_id(self, reco_id)
     if resolved_reco_id is None:
         return None
+
+    hook_name = getattr(self, "_converter_hook_name", None)
+    if isinstance(hook_name, str) and hook_name:
+        logger.debug(
+            "Convert starting for scan %s reco %s with hook %s",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+            hook_name,
+        )
+    else:
+        logger.debug(
+            "Convert starting for scan %s reco %s (no hook)",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+        )
+    
     hook_kwargs = _resolve_hook_kwargs(self, hook_args_by_name)
     data_kwargs = _filter_hook_kwargs(self.get_dataobj, hook_kwargs)
+    convert_kwargs = {
+        key: value
+        for key, value in hook_kwargs.items()
+        if key not in data_kwargs
+    }
     if data_kwargs:
+        logger.debug(
+            "Calling get_dataobj for scan %s reco %s with args %s",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+            data_kwargs,
+        )
         dataobjs = self.get_dataobj(resolved_reco_id, **data_kwargs)
     else:
+        logger.debug(
+            "Calling get_dataobj for scan %s reco %s (no args)",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+        )
         dataobjs = self.get_dataobj(resolved_reco_id)
     affine_kwargs = _filter_hook_kwargs(self.get_affine, hook_kwargs)
+    convert_kwargs = {
+        key: value
+        for key, value in convert_kwargs.items()
+        if key not in affine_kwargs
+    }
     if affine_kwargs:
+        logger.debug(
+            "Calling get_affine for scan %s reco %s with args %s",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+            affine_kwargs,
+        )
         affines = self.get_affine(
             resolved_reco_id,
             space=space,
@@ -528,77 +619,64 @@ def get_nifti1image(
             **affine_kwargs,
         )
     else:
+        logger.debug(
+            "Calling get_affine for scan %s reco %s (no args)",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+        )
         affines = self.get_affine(
             resolved_reco_id,
             space=space,
             override_subject_type=override_subject_type,
             override_subject_pose=override_subject_pose,
         )
-    image_info = self.image_info.get(resolved_reco_id)
-
-    if dataobjs is None or affines is None or image_info is None:
+    
+    if dataobjs is None or affines is None:
         return None
-
-    if not isinstance(dataobjs, tuple) and not isinstance(affines, tuple):
+    
+    if not isinstance(dataobjs, tuple):
         dataobjs = (dataobjs,)
+    if not isinstance(affines, tuple):
         affines = (affines,)
-
-    niiobjs = []
+    
+    dataobjs = list(dataobjs)
     for i, dataobj in enumerate(dataobjs):
         if flatten_fg and dataobj.ndim > 4:
             spatial_shape = dataobj.shape[:3]
             flattened = int(np.prod(dataobj.shape[3:]))
-            dataobj = dataobj.reshape((*spatial_shape, flattened), order="A")
-        affine = affines[i]
-        niiobj = Nifti1Image(dataobj, affine)
-        nifti1header_contents = nifti_resolver.resolve(
-            image_info, flip_x=flip_x, xyz_units=xyz_units, t_units=t_units
+            dataobjs[i] = dataobj.reshape((*spatial_shape, flattened), order="A")
+    dataobjs = tuple(dataobjs)
+     
+    converter_func = getattr(self, "converter_func", None)
+    if isinstance(converter_func, ConvertType):
+        hook_call_kwargs = _filter_hook_kwargs(converter_func, convert_kwargs)
+        logger.debug(
+            "Calling converter hook for scan %s reco %s with args %s",
+            getattr(self, "scan_id", "?"),
+            resolved_reco_id,
+            hook_call_kwargs,
+        )
+        return converter_func(
+            dataobj=dataobjs,
+            affine=affines,
+            **hook_call_kwargs,
         )
-        if override_header:
-            for key, value in override_header.items():
-                if value is not None:
-                    nifti1header_contents[key] = value
-        niiobj = nifti_resolver.update(niiobj, nifti1header_contents)
-        niiobjs.append(niiobj)
-
-    if len(niiobjs) == 1:
-        return niiobjs[0]
-    return tuple(niiobjs)
-
 
-def convert(
-    self: Union["Scan", "ScanLoader"],
-    reco_id: Optional[int] = None,
-    *,
-    format: Literal["nifti", "nifti1"] = "nifti",
-    space: AffineSpace = "subject_ras",
-    override_header: Optional[Nifti1HeaderContents] = None,
-    override_subject_type: Optional[SubjectType] = None,
-    override_subject_pose: Optional[SubjectPose] = None,
-    flip_x: bool = False,
-    flatten_fg: bool = False,
-    xyz_units: XYZUNIT = "mm",
-    t_units: TUNIT = "sec",
-    hook_args_by_name: Optional[Mapping[str, Mapping[str, Any]]] = None,
-) -> Optional[Union[Tuple["Nifti1Image", ...], "Nifti1Image"]]:
-    """Convert a reco to a selected output format."""
-    if format not in {"nifti", "nifti1"}:
-        raise ValueError(f"Unsupported format: {format}")
+    nifti1image_kwargs = {
+        "xyz_units": xyz_units,
+        "t_units": t_units,
+        "override_header": override_header,
+        **kwargs,
+    }
+    nifti1image_kwargs = _filter_hook_kwargs(get_nifti1image, nifti1image_kwargs)
     return get_nifti1image(
         self,
-        reco_id,
-        space=space,
-        override_header=override_header,
-        override_subject_type=override_subject_type,
-        override_subject_pose=override_subject_pose,
-        flip_x=flip_x,
-        flatten_fg=flatten_fg,
-        xyz_units=xyz_units,
-        t_units=t_units,
-        hook_args_by_name=hook_args_by_name,
+        reco_id=resolved_reco_id,
+        dataobjs=dataobjs,
+        affines=affines,
+        **nifti1image_kwargs,
     )
 
-
 def _resolve_hook_kwargs(
     scan: Union["Scan", "ScanLoader"],
     hook_args_by_name: Optional[Mapping[str, Mapping[str, Any]]],
@@ -608,6 +686,12 @@ def _resolve_hook_kwargs(
     hook_name = getattr(scan, "_converter_hook_name", None)
     if not isinstance(hook_name, str) or not hook_name:
         return {}
+    logger.debug(
+        "Resolving hook args for scan %s hook %s (available: %s)",
+        getattr(scan, "scan_id", "?"),
+        hook_name,
+        sorted(hook_args_by_name.keys()),
+    )
     values = hook_args_by_name.get(hook_name)
     if values is None:
         seen: set[str] = set()
@@ -643,7 +727,12 @@ def _resolve_hook_kwargs(
                 )
                 values = candidate_values
                 break
-    return dict(values) if isinstance(values, Mapping) else {}
+    resolved = dict(values) if isinstance(values, Mapping) else {}
+    if resolved:
+        logger.debug("Resolved hook args for %s: %s", hook_name, resolved)
+    else:
+        logger.debug("No hook args resolved for %s.", hook_name)
+    return resolved
 
 
 def _filter_hook_kwargs(func: Any, hook_kwargs: Mapping[str, Any]) -> Dict[str, Any]:
@@ -785,6 +874,17 @@ def apply_converter_hook(
     """Override scan conversion helpers using a converter hook."""
     converter_core.validate_hook(converter_hook)
     plugin = dict(converter_hook)
+    logger.debug(
+        "Binding converter hook for scan %s: %s",
+        getattr(scan, "scan_id", "?"),
+        sorted(plugin.keys()),
+    )
+    if "get_dataobj" in plugin and not isinstance(plugin["get_dataobj"], GetDataobjType):
+        raise TypeError("Converter hook 'get_dataobj' must match GetDataobjType.")
+    if "get_affine" in plugin and not isinstance(plugin["get_affine"], GetAffineType):
+        raise TypeError("Converter hook 'get_affine' must match GetAffineType.")
+    if "convert" in plugin and not isinstance(plugin["convert"], ConvertType):
+        raise TypeError("Converter hook 'convert' must match ConvertType.")
     scan._converter_hook = plugin
     if "get_dataobj" in plugin:
         scan.get_dataobj = MethodType(plugin["get_dataobj"], scan)
@@ -794,4 +894,11 @@ def apply_converter_hook(
             get_affine = partial(get_affine, decimals=affine_decimals)
         scan.get_affine = MethodType(get_affine, scan)
     if "convert" in plugin:
-        scan.convert = MethodType(plugin["convert"], scan)
+        scan.converter_func = MethodType(plugin["convert"], scan)
+    else:
+        scan.converter_func = None
+    logger.debug(
+        "Converter hook bound for scan %s (hook=%s)",
+        getattr(scan, "scan_id", "?"),
+        getattr(scan, "_converter_hook_name", None),
+    )

{brkraw-0.5.2 → brkraw-0.5.3}/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, Callable, List, TYPE_CHECKING, runtime_checkable
 if TYPE_CHECKING:
     from typing_extensions import ParamSpec, TypeAlias
 else:
@@ -35,6 +35,7 @@ AffineSpace = Literal["raw", "scanner", "subject_ras"]
 P = ParamSpec("P")
 
 
+@runtime_checkable
 class GetDataobjType(Protocol[P]):
     """Callable signature for get_dataobj overrides."""
     def __call__(
@@ -47,6 +48,7 @@ class GetDataobjType(Protocol[P]):
         ...
 
 
+@runtime_checkable
 class GetAffineType(Protocol):
     """Callable signature for get_affine overrides."""
     def __call__(
@@ -63,44 +65,21 @@ class GetAffineType(Protocol):
         ...
 
 
-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"]]:
-        ...
-
-
+@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"]]:
+    ) -> Optional[Union["ToFilename", Tuple["ToFilename", ...]]]:
+        ...
+
+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 +105,11 @@ 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]
-
+    
+    
     def get_fid(self, 
                 buffer_start: Optional[int], 
                 buffer_size: Optional[int], 
@@ -155,15 +136,12 @@ class ScanLoader(Scan, BaseLoader):
         ...
 
     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"]]:
@@ -173,17 +151,16 @@ class ScanLoader(Scan, BaseLoader):
             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"]]:
+            **kwargs: Any,
+            ) -> Optional[Union["ToFilename", Tuple["ToFilename", ...]]]:
         ...
 
     def get_metadata(
@@ -201,15 +178,15 @@ 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',