Canonicalize AFNI output for caching, drop unused scale_bold

AFNI tools write a NIfTI extension with a wall-clock HISTORY_NOTE, a
random IDCODE_STRING, and an IDCODE_DATE timestamp into every output
file. Those fields blow up content-hash based caching: any downstream
tool sees different bytes each run even when the logical content is
identical, and the whole cache chain cascade-misses.

deoblique_and_reorient mutates via 3drefit (mutable=True) which
styxcache 0.2.0 doesn't replay on hits, compounding the issue. Bypass
the 3drefit call so it always runs, then strip the volatile AFNI
extension before the downstream cached 3dresample sees the file.
Warm-run speedup on tests/integration/functional/test_truncate.py::
test_truncate_trs drops from 33.8s to 10.5s locally.

strip_afni_volatile_metadata in rbc.core.nifti removes the full AFNI
extension (code 4). sform/qform survive so AFNI geometry is preserved;
the rest of the extension is audit metadata AFNI tools recompute.

scale_bold was dead code (no callers in src/ or tests/) and had the
same 3drefit hazard. Delete it rather than carry the workaround.

Author: nx10

src/rbc/core/common.py

@@ -7,18 +7,28 @@
 
 from __future__ import annotations
 
+import contextlib
 from typing import TYPE_CHECKING
 
 import nibabel as nib
 from niwrap import afni
 
 if TYPE_CHECKING:
-    from collections.abc import Sequence
+    from collections.abc import Iterator, Sequence
     from pathlib import Path
 
 from rbc.core.fileops import file_tmp_copy
+from rbc.core.nifti import strip_afni_volatile_metadata
 from rbc.core.niwrap import generate_exec_folder
 
+try:
+    from styxcache import bypass as _styxcache_bypass
+except ImportError:  # styxcache is optional — only used on CI
+
+    @contextlib.contextmanager
+    def _styxcache_bypass() -> Iterator[None]:
+        yield
+
 __all__ = ["deoblique_and_reorient", "merge_3d_to_4d", "split_4d"]
 
 
@@ -41,7 +51,13 @@ def deoblique_and_reorient(
         AFNI 3dresample outputs (use ``.out_file`` for the reoriented image).
     """
     with file_tmp_copy(in_file) as tmp_file:
-        afni.v_3drefit(in_file=tmp_file, deoblique=True)
+        # 3drefit mutates in place, and styxcache 0.2.0 does not replay
+        # mutable-input mutations on cache hits. Bypass it so it always runs,
+        # then strip AFNI's non-deterministic extension (timestamps + random
+        # UUID) so the downstream cached 3dresample call keys on stable bytes.
+        with _styxcache_bypass():
+            afni.v_3drefit(in_file=tmp_file, deoblique=True)
+        strip_afni_volatile_metadata(tmp_file)
         return afni.v_3dresample(
             in_file=tmp_file, prefix=output_fname, orientation="RPI"
         )

src/rbc/core/functional/__init__.py

@@ -20,7 +20,7 @@
     is_valid_pe_direction,
 )
 from .erosion import erode_mask_by_distance, erode_mask_to_proportion
-from .initialization import scale_bold, truncate_trs
+from .initialization import truncate_trs
 from .masking import bold_masking
 from .motion import extract_motion_reference, fsl_motion_correction
 from .nuisance import (
@@ -69,7 +69,6 @@
     "is_valid_pe_direction",
     "nuisance_regression",
     "resample_bold_to_template",
-    "scale_bold",
     "slice_timing_correction",
     "truncate_trs",
     "write_regressor_file",

src/rbc/core/functional/initialization.py

@@ -1,12 +1,9 @@
 """BOLD initialization steps.
 
-After reorientation (handled in ``rbc.core.common``), BOLD data undergoes
-two initialization steps before motion correction:
-
-1. **TR truncation** -- discard the first *N* volumes (default 2) to allow
-   the scanner signal to reach steady state.
-2. **Voxel scaling** -- rescale voxel dimensions (divide by 10) to match
-   the coordinate conventions expected downstream.
+After reorientation (handled in ``rbc.core.common``), BOLD data undergoes an
+initialization step before motion correction: TR truncation -- discard the
+first *N* volumes (default 2) to allow the scanner signal to reach steady
+state.
 """
 
 from __future__ import annotations
@@ -41,26 +38,3 @@ def truncate_trs(in_file: Path, start_tr: int) -> Path:
     )
     assert result.output_file is not None  # noqa: S101
     return result.output_file
-
-
-def scale_bold(in_file: Path, scale_factor: float = 0.1) -> afni.V3drefitOutputs:
-    """Rescale BOLD voxel dimensions via ``3drefit -xyzscale``.
-
-    Some pipelines store BOLD data with inflated voxel sizes. This step
-    multiplies all voxel dimensions by *scale_factor* (default 0.1, i.e.
-    divide by 10) to bring them into the expected coordinate range.
-
-    Note:
-        This modifies the NIfTI header in-place; the voxel data are unchanged.
-
-    Args:
-        in_file: BOLD timeseries whose header should be updated.
-        scale_factor: Multiplier for voxel dimensions (default 0.1).
-
-    Returns:
-        AFNI 3drefit outputs.
-    """
-    return afni.v_3drefit(
-        in_file=in_file,
-        xyzscale=scale_factor,
-    )

src/rbc/core/nifti.py

@@ -26,8 +26,15 @@
     "Volume",
     "nifti_num_slices",
     "nifti_num_volumes",
+    "strip_afni_volatile_metadata",
 ]
 
+# AFNI embeds a NIfTI extension (code 4) with an XML payload that contains
+# wall-clock timestamps and a random per-invocation UUID. Those poison
+# content-hash based caching for any tool downstream. Drop the extension
+# entirely; AFNI tools fall back to sform/qform (untouched) for geometry.
+_AFNI_EXTENSION_CODE = 4
+
 
 # NIfTI spatial unit codes (nibabel xyzt_units bits 0-2)
 _NIB_UNIT_TO_UNITS: dict[int, Units] = {}  # populated after Units definition
@@ -524,3 +531,22 @@ def nifti_num_slices(in_file: str | Path) -> int:
         return img.shape[slice_axis]
 
     return img.shape[2] if len(img.shape) >= 3 else 1
+
+
+def strip_afni_volatile_metadata(path: str | Path) -> None:
+    """Rewrite a NIfTI file with AFNI's non-deterministic extension removed.
+
+    AFNI tools embed a NIfTI extension carrying wall-clock timestamps and a
+    random per-invocation UUID, which breaks content-hash based caching for
+    any downstream consumer. We drop the whole AFNI extension; the standard
+    NIfTI sform/qform are untouched so downstream tools still get correct
+    geometry.
+    """
+    img = nib.nifti1.load(path)
+    ext_list = img.header.extensions
+    kept = [e for e in ext_list if e.get_code() != _AFNI_EXTENSION_CODE]
+    if len(kept) == len(ext_list):
+        return
+    ext_list.clear()
+    ext_list.extend(kept)
+    nib.save(img, path)