Split FunctionalOutputs.regressor_file into raw + bandpass-filtered

regressor_file now carries the raw (unfiltered) regressor .1D files as
computed from native-space BOLD.  The new bpf_regressor_file field
holds the bandpass-filtered version that 3dTproject actually applied,
exported with desc-<strategy>Filtered for provenance.

This lets the longitudinal pipeline reuse the raw regressors without
recomputation, matching the cross-sectional principle: one regressor
computation per run, applied in each target space.

Port of the regressor-split idea from #282.

Co-authored-by: Janhavi Pillai <janhavi.pillai@gmail.com>

Author: nx10

docs/data_dictionary.md

@@ -56,7 +56,8 @@ Produced by `rbc functional`. These are functional MRI (BOLD) processing results
 | `*_space-MNI152NLin6Asym_desc-preproc_bold.nii.gz`                 | `bold`       | BOLD timeseries resampled to MNI152NLin6Asym template space in a single interpolation step (before denoising)                             | ANTs resampling                                  | 4D NIfTI                     |
 | `*_space-MNI152NLin6Asym_desc-bold_mask.nii.gz`                    | `mask`       | Brain mask warped to template space at the BOLD resolution                                                                                | ANTs resampling                                  | 3D NIfTI, binary mask        |
 | `*_space-MNI152NLin6Asym_reg-{regressor}_desc-preproc_bold.nii.gz` | `bold`       | Denoised BOLD timeseries in template space after nuisance regression and bandpass filtering. `{regressor}` is `36parameter` or `aCompCor` | Nuisance regression                              | 4D NIfTI                     |
-| `*_desc-{regressor}_regressors.1D`                                 | `regressors` | Nuisance regressor matrix used for denoising. `{regressor}` is `36parameter` or `aCompCor`                                                | Computed from motion parameters and tissue masks | Text, multi-column 1D file   |
+| `*_desc-{regressor}_regressors.1D`                                 | `regressors` | Raw (unfiltered) nuisance regressor matrix. `{regressor}` is `36parameter` or `aCompCor`. Carried forward for longitudinal regression reuse | Computed from motion parameters and tissue masks | Text, multi-column 1D file   |
+| `*_desc-{regressor}Filtered_regressors.1D`                         | `regressors` | Bandpass-filtered nuisance regressor matrix matching what `3dTproject -bandpass` applied. For provenance only | FFT-based bandpass filter | Text, multi-column 1D file   |
 
 ---
 
@@ -133,3 +134,9 @@ Produced by the `rbc longitudinal` subcommand group (`template`, `anatomical`, `
 | `*_space-longitudinal_desc-T1w_mask.nii.gz`        | `mask` | Brain mask in longitudinal template space                                 | ANTs registration to longitudinal template | 3D NIfTI, binary mask        |
 | `*_from-T1w_to-longitudinal_mode-image_xfm.nii.gz` | `xfm`  | Warp field mapping subject anatomy to the longitudinal template           | ANTs registration                          | 3D NIfTI, displacement field |
 | `*_from-longitudinal_to-T1w_mode-image_xfm.nii.gz` | `xfm`  | Inverse warp field mapping longitudinal template back to subject anatomy  | ANTs registration                          | 3D NIfTI, displacement field |
+| `*_space-longitudinal_sbref.nii.gz`                | `sbref` | Motion reference volume warped to longitudinal template space             | ANTs warping (composed BOLD-to-longitudinal) | 3D NIfTI                   |
+| `*_space-longitudinal_desc-preproc_bold.nii.gz`    | `bold` | Preprocessed BOLD warped to longitudinal template space                    | ANTs warping (composed BOLD-to-longitudinal) | 4D NIfTI                   |
+| `*_space-longitudinal_desc-brain_mask.nii.gz`      | `mask` | BOLD brain mask in longitudinal template space                             | ANTs warping (nearest-neighbor)              | 3D NIfTI, binary mask      |
+| `*_from-bold_to-longitudinal_...xfm.nii.gz`       | `xfm`  | Composite BOLD-to-longitudinal-template warp field                         | ANTs compose transforms                      | 3D NIfTI, displacement field |
+| `*_space-longitudinal_desc-regressed_reg-<strategy>_bold.nii.gz` | `bold` | Nuisance-regressed BOLD (no bandpass) in longitudinal space, per regressor strategy | AFNI 3dTproject | 4D NIfTI |
+| `*_space-longitudinal_desc-preproc_reg-<strategy>_bold.nii.gz`   | `bold` | Nuisance-regressed + bandpass-filtered BOLD in longitudinal space, per regressor strategy | AFNI 3dTproject -bandpass | 4D NIfTI |

src/rbc/bids/functional.py

@@ -158,6 +158,12 @@ def export_functional(
             desc=bids_safe_label(reg),
             extension=".1D",
         )
+        func.save(
+            outputs.bpf_regressor_file[reg],
+            suffix="regressors",
+            desc=f"{bids_safe_label(reg)}Filtered",
+            extension=".1D",
+        )
 
     mni = func.derive(space=TemplateSpace.MNI152NLIN6ASYM)
     for reg in regressors:

src/rbc/workflows/functional.py

@@ -76,7 +76,12 @@ class FunctionalOutputs(NamedTuple):
         template_bold: BOLD resampled to template space.
         regressed_bold: Nuisance-regressed & non-bandpassed BOLD.
         cleaned_bold: Nuisance-regressed & bandpass-filtered BOLD.
-        regressor_file: Bandpass-filtered nuisance regressor ``.1D`` file.
+        regressor_file: Raw (unfiltered) nuisance regressor ``.1D`` file,
+            as computed from native-space BOLD.  Carried forward so
+            longitudinal regression can reuse it without recomputation.
+        bpf_regressor_file: Bandpass-filtered nuisance regressor ``.1D``
+            file, matching what ``3dTproject -bandpass`` actually applied.
+            For BIDS export only.
         template_brain_mask: Brain mask warped to template space.
     """
 
@@ -100,6 +105,7 @@ class FunctionalOutputs(NamedTuple):
     regressed_bold: dict[str, Path]
     cleaned_bold: dict[str, Path]
     regressor_file: dict[str, Path]
+    bpf_regressor_file: dict[str, Path]
     template_brain_mask: Path
 
 
@@ -329,6 +335,7 @@ def single_session_preprocess(
 
     regression: dict[str, ApplyRegressionOutputs] = {}
     cleaned: dict[str, ApplyRegressionOutputs] = {}
+    raw_regressors: dict[str, Path] = {}
     filtered_regressors: dict[str, Path] = {}
     for regressor in regressor_set:
         # 15. Nuisance regression without bandpass (pre-bandpass residuals
@@ -350,8 +357,11 @@ def single_session_preprocess(
             regressor_file=regressors[regressor].regressor_file,
         )
 
-        # 17. Export bandpass-filtered regressors (matches what 3dTproject
-        #     actually applied; raw regressors still in compute_regressors output)
+        # 17a. Carry raw (unfiltered) regressors forward for longitudinal reuse
+        raw_regressors[regressor] = regressors[regressor].regressor_file
+
+        # 17b. Export bandpass-filtered regressors (matches what 3dTproject
+        #      actually applied)
         filtered_regressors[regressor] = bandpass_regressor_file(
             regressors[regressor].regressor_file,
             tr=metadata.tr,
@@ -379,6 +389,7 @@ def single_session_preprocess(
         template_bold=template_bold,
         regressed_bold={r: regression[r].regressed_bold for r in regressor_set},
         cleaned_bold={r: cleaned[r].regressed_bold for r in regressor_set},
-        regressor_file=filtered_regressors,
+        regressor_file=raw_regressors,
+        bpf_regressor_file=filtered_regressors,
         template_brain_mask=tmpl_brain,
     )

tests/unit/bids/test_exports.py

@@ -74,6 +74,7 @@ def _make_func_outputs(w: Path, regressors: list[str]) -> FunctionalOutputs:
         regressed_bold={r: _dummy(w, f"regressed_{r}.nii.gz") for r in regressors},
         cleaned_bold={r: _dummy(w, f"cleaned_{r}.nii.gz") for r in regressors},
         regressor_file={r: _dummy(w, f"regressors_{r}.1D") for r in regressors},
+        bpf_regressor_file={r: _dummy(w, f"regressors_bpf_{r}.1D") for r in regressors},
         template_brain_mask=_dummy(w, "template_mask.nii.gz"),
     )
 
@@ -195,26 +196,27 @@ def test_file_count_single_regressor(
     ) -> None:
         """Correct file count with one regressor.
 
-        8 native-space fixed + 1 regressor file + 2 per-regressor MNI
-        + 2 fixed MNI = 13.
+        8 native-space fixed + 2 regressor files (raw + filtered)
+        + 2 per-regressor MNI + 2 fixed MNI = 14.
         """
         outputs = _make_func_outputs(workdir, ["36-parameter"])
         export_functional(func_bids, outputs, regressors=["36-parameter"])
         saved = list(pipe_ctx.output_dir.rglob("*.*"))
-        assert len(saved) == 13
+        assert len(saved) == 14
 
     def test_file_count_two_regressors(
         self, func_bids: Bids, workdir: Path, pipe_ctx: RunContext
     ) -> None:
         """Correct file count with two regressors.
 
-        8 fixed + 2 regressor files + 4 per-regressor MNI + 2 fixed MNI = 16.
+        8 fixed + 4 regressor files (2x raw + 2x filtered)
+        + 4 per-regressor MNI + 2 fixed MNI = 18.
         """
         regs = ["36-parameter", "aCompCor"]
         outputs = _make_func_outputs(workdir, regs)
         export_functional(func_bids, outputs, regressors=regs)
         saved = list(pipe_ctx.output_dir.rglob("*.*"))
-        assert len(saved) == 16
+        assert len(saved) == 18
 
 
 # ---------------------------------------------------------------------------