changes

Author: jpillai00

src/rbc/bids/functional.py

@@ -17,6 +17,22 @@
     from rbc.workflows.functional import FunctionalOutputs
 
 
+def _smooth_label(fwhm: float, precision: int | None = None) -> str:
+    """Format FWHM as a BIDS-safe label (e.g. 6.0 -> 'sm6', 0.1 -> 'sm0p1').
+
+    Trailing zeros are stripped and '.' is replaced with 'p' for BIDS compliance.
+
+    Args:
+        fwhm: Smoothing kernel FWHM in mm.
+        precision: Optional number of decimal places to format to before stripping.
+
+    Returns:
+        BIDS-safe label string (e.g. 'sm6', 'sm0p1').
+    """
+    s = f"{fwhm:.{precision}f}" if precision is not None else str(fwhm)
+    return "sm" + s.rstrip("0").rstrip(".").replace(".", "p")
+
+
 class FunctionalRun(NamedTuple):
     """A single functional run discovered from a BIDS session.
 
@@ -186,7 +202,7 @@ def export_functional(
             mni.save(
                 outputs.cleaned_bold_smooth[reg],
                 suffix=Suffix.BOLD,
-                desc=f"sm{int(smooth)}preproc",
+                desc=f"{_smooth_label(smooth)}preproc",
                 extra={"reg": bids_safe_label(reg)},
             )
     mni.save(outputs.template_bold, suffix=Suffix.BOLD, desc="preproc")

src/rbc/bids/metrics.py

@@ -16,6 +16,22 @@
     from rbc.workflows.metrics import MetricsOutputs
 
 
+def _smooth_label(fwhm: float, precision: int | None = None) -> str:
+    """Format FWHM as a BIDS-safe label (e.g. 6.0 -> 'sm6', 0.1 -> 'sm0p1').
+
+    Trailing zeros are stripped and '.' is replaced with 'p' for BIDS compliance.
+
+    Args:
+        fwhm: Smoothing kernel FWHM in mm.
+        precision: Optional number of decimal places to format to before stripping.
+
+    Returns:
+        BIDS-safe label string (e.g. 'sm6', 'sm0p1').
+    """
+    s = f"{fwhm:.{precision}f}" if precision is not None else str(fwhm)
+    return "sm" + s.rstrip("0").rstrip(".").replace(".", "p")
+
+
 class MetricsInputs(TypedDict):
     """Resolved functional inputs for the metrics workflow."""
 
@@ -70,7 +86,7 @@ def export_metrics(
 
     Raw and z-scored raw maps are always exported. Smoothed and
     z-scored smoothed variants are exported only when the corresponding
-    fields are not None (i.e. when ``smooth=True`` was passed to
+    fields are not None (i.e. when ``smooth`` is not ``None`` in
     ``single_session_metrics``).
 
     Args:
@@ -96,7 +112,7 @@ def export_metrics(
 
     # Smoothed + z-scored smoothed
     if smooth is not None:
-        sm_desc = f"sm{int(smooth)}"
+        sm_desc = _smooth_label(smooth)
         if outputs.alff_smooth is not None:
             mex.save(outputs.alff_smooth, suffix="alff", desc=sm_desc)
             assert outputs.alff_smooth_zscored is not None  # noqa: S101

src/rbc/core/common.py

@@ -1,8 +1,9 @@
-"""Processing steps shared across anatomical and functional streams.
+"""Processing steps shared across anatomical, functional, and metrics streams.
 
 Currently provides:
 - Deobliquing and RPI reorientation (initial preprocessing for T1w and BOLD).
 - 4D NIfTI splitting and merging utilities.
+- Spatially smooth a 3D map or 4D timeseries to a target FWHM.
 """
 
 from __future__ import annotations
@@ -21,7 +22,7 @@
 from rbc.core.nifti import strip_afni_volatile_metadata
 from rbc.core.niwrap import generate_exec_folder
 
-__all__ = ["deoblique_and_reorient", "merge_3d_to_4d", "split_4d"]
+__all__ = ["deoblique_and_reorient", "merge_3d_to_4d", "smooth", "split_4d"]
 
 
 def deoblique_and_reorient(
@@ -92,3 +93,33 @@ def merge_3d_to_4d(volumes: Sequence[Path], output: Path) -> Path:
     merged = nib.funcs.concat_images(imgs, axis=None)
     nib.save(merged, output)
     return output
+
+
+def smooth(
+    in_file: Path,
+    mask_file: Path,
+    fwhm: float = 6.0,
+) -> Path:
+    """Spatially smooth a 3D map or 4D timeseries to a target FWHM.
+
+    Uses AFNI ``3dBlurToFWHM`` to iteratively blur the input until the
+    estimated smoothness reaches the requested FWHM within the brain mask.
+    Supports both 3D derivative maps (ALFF, fALFF, ReHo) and 4D BOLD
+    timeseries.
+
+    Args:
+        in_file: NIfTI image to smooth (3-D map or 4-D timeseries).
+        mask_file: Binary brain mask; voxels outside are set to zero.
+        fwhm: Target full-width at half-maximum in mm.
+
+    Returns:
+        Path to the smoothed image.
+    """
+    result = afni.v_3d_blur_to_fwhm(
+        in_file=in_file,
+        mask=mask_file,
+        fwhm=fwhm,
+        prefix="smoothed.nii.gz",
+    )
+    assert result.out_file is not None  # noqa: S101
+    return result.out_file

src/rbc/core/metrics/smoothing.py

@@ -14,6 +14,7 @@
 from niwrap import ants
 
 from rbc.core.common import deoblique_and_reorient
+from rbc.core.common import smooth as apply_smooth
 from rbc.core.fsl2itk import mat_to_itk
 from rbc.core.functional import (
     PEPolarFieldmap,
@@ -34,7 +35,6 @@
     slice_timing_correction,
     truncate_trs,
 )
-from rbc.core.metrics.smoothing import smooth as apply_smooth
 from rbc.core.niwrap import generate_exec_folder
 from rbc_resources import REGISTRATION_TEMPLATES
 
@@ -84,7 +84,7 @@ class FunctionalOutputs(NamedTuple):
             file, matching what ``3dTproject -bandpass`` actually applied.
             For BIDS export only.
         cleaned_bold_smooth: Spatially smoothed nuisance-regressed
-            & bandpass-filtered BOLD, or *None* is no smoothing requested.
+            & bandpass-filtered BOLD, or *None* if no smoothing requested.
         regressor_file: Bandpass-filtered nuisance regressor ``.1D`` file.
         template_brain_mask: Brain mask warped to template space.
     """

src/rbc/workflows/functional.py

@@ -12,9 +12,9 @@
 import logging
 from typing import TYPE_CHECKING, NamedTuple
 
+from rbc.core.common import smooth as apply_smooth
 from rbc.core.metrics.alff import compute_alff
 from rbc.core.metrics.reho import compute_reho
-from rbc.core.metrics.smoothing import smooth as apply_smooth
 from rbc.core.metrics.standardization import compute_zscore
 from rbc.core.metrics.timeseries import compute_timeseries
 from rbc.core.niwrap import generate_exec_folder

src/rbc/workflows/metrics.py

@@ -7,8 +7,7 @@
 import nibabel as nib
 import pytest
 
-from rbc.core.common import deoblique_and_reorient
-from rbc.core.metrics.smoothing import smooth
+from rbc.core.common import deoblique_and_reorient, smooth
 
 if TYPE_CHECKING:
     from conftest import TestSubjectData

tests/integration/metrics/test_smoothing.py

@@ -13,7 +13,7 @@
 
 from rbc.bids.anatomical import export_anatomical
 from rbc.bids.functional import export_functional
-from rbc.bids.metrics import export_metrics
+from rbc.bids.metrics import _smooth_label, export_metrics
 from rbc.bids.qc import export_qc
 from rbc.context import RunContext
 from rbc.workflows.anatomical import AnatomicalOutputs
@@ -364,6 +364,10 @@ def test_smooth_maps_have_correct_desc(
         assert len(sm_only) == 3
         assert len(sm_zstd) == 3
 
+    def test_smooth_label_non_integer(self) -> None:
+        """Non-integer FWHM values are formatted with 'p' instead of '.'."""
+        assert _smooth_label(0.1) == "sm0p1"
+
 
 # ---------------------------------------------------------------------------
 # QC exports