Add per-regressor regression to longitudinal functional workflow

FunctionalLongOutputs gains regressed_bold and cleaned_bold dicts
keyed by regressor strategy.  longitudinal_process now accepts
regressor_files (raw .1D from cross-sectional) and re-runs
apply_regression + apply_regression_bandpass on the warped BOLD.
No regressor recomputation -- same matrix, different target space.

bold_mask is now mandatory (was Path | None).

BIDS export writes per-regressor desc-regressed and desc-preproc BOLD
with reg-<strategy> entity.  resolve_longitudinal_func resolves the
raw regressor files per strategy.

CLI gains --regressor with the same choices as cross-sectional
(36-parameter, aCompCor).

Port of the longitudinal regression logic from #282.

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

Author: nx10

src/rbc/bids/longitudinal/functional.py

@@ -7,6 +7,7 @@
 from rbc.bids import Suffix, bids_safe_label
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
     from pathlib import Path
 
     import polars as pl
@@ -22,7 +23,8 @@ def resolve_longitudinal_func(
     tpl_df: pl.DataFrame,
     *,
     ses: str,
-) -> dict[str, Path | None]:
+    regressors: Sequence[str] = ("36-parameter",),
+) -> dict[str, Path | dict[str, Path]]:
     """Resolve inputs for longitudinal functional processing.
 
     Args:
@@ -31,10 +33,23 @@ def resolve_longitudinal_func(
         func_df: DataFrame of functional derivatives.
         tpl_df: DataFrame of longitudinal template files.
         ses: Session label (used for template xfm lookup).
+        regressors: Regressor strategy names to resolve raw regressor
+            files for.
 
     Returns:
-        Dict with keys matching ``longitudinal_process`` parameters.
+        Dict with keys matching ``longitudinal_process`` parameters,
+        including ``regressor_files`` keyed by strategy name.
     """
+    regressor_files: dict[str, Path] = {}
+    for reg in regressors:
+        regressor_files[reg] = func_q.expect(
+            func_df,
+            suffix="regressors",
+            desc=bids_safe_label(reg),
+            extension=".1D",
+            without=["space"],
+        )
+
     return {
         "template": tpl_q.expect(tpl_df, suffix="T1w"),
         "anat_to_template_xfm": tpl_q.expect(
@@ -54,18 +69,25 @@ def resolve_longitudinal_func(
         "bold": func_q.expect(
             func_df, suffix=Suffix.BOLD, desc="preproc", without=["space"]
         ),
-        "bold_mask": func_q.find(
+        "bold_mask": func_q.expect(
             func_df, suffix=Suffix.MASK, desc="brain", without=["space"]
         ),
+        "regressor_files": regressor_files,
     }
 
 
-def export_longitudinal_func(fex: Bids, outputs: FunctionalLongOutputs) -> None:
+def export_longitudinal_func(
+    fex: Bids,
+    outputs: FunctionalLongOutputs,
+    *,
+    regressors: Sequence[str],
+) -> None:
     """Export longitudinal functional outputs.
 
     Args:
         fex: Bids builder with ``space="longitudinal"`` and identity entities.
         outputs: Results from the longitudinal functional workflow.
+        regressors: Regressor strategy names that were applied.
     """
     fex.save(outputs.sbref, suffix=Suffix.SBREF)
     fex.save(outputs.bold, suffix=Suffix.BOLD, desc="preproc")
@@ -75,5 +97,18 @@ def export_longitudinal_func(fex: Bids, outputs: FunctionalLongOutputs) -> None:
         desc="composite",
         extra={"from": "bold", "to": "longitudinal", "mode": "image"},
     )
-    if outputs.bold_mask:
-        fex.save(outputs.bold_mask, suffix=Suffix.MASK, desc="brain")
+    fex.save(outputs.bold_mask, suffix=Suffix.MASK, desc="brain")
+
+    for reg in regressors:
+        fex.save(
+            outputs.regressed_bold[reg],
+            suffix=Suffix.BOLD,
+            desc="regressed",
+            extra={"reg": bids_safe_label(reg)},
+        )
+        fex.save(
+            outputs.cleaned_bold[reg],
+            suffix=Suffix.BOLD,
+            desc="preproc",
+            extra={"reg": bids_safe_label(reg)},
+        )

src/rbc/cli/longitudinal/functional.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
 from rbc.cli.base import _validate_task
 from rbc.cli.longitudinal._base import LongitudinalBaseArgs, add_fs_license_argument
@@ -20,6 +20,7 @@ class FunctionalLongArgs(LongitudinalBaseArgs):
     """Arguments for ``rbc longitudinal functional``."""
 
     task: str | None
+    regressor: Sequence[Literal["36-parameter", "aCompCor"]]
 
     @classmethod
     def validate_namespace(cls, ns: argparse.Namespace) -> FunctionalLongArgs:
@@ -28,6 +29,7 @@ def validate_namespace(cls, ns: argparse.Namespace) -> FunctionalLongArgs:
         return cls(
             **LongitudinalBaseArgs.validate_namespace(ns).__dict__,
             task=ns.task,
+            regressor=ns.regressor,
         )
 
 
@@ -41,6 +43,7 @@ def main(args: FunctionalLongArgs) -> int:
             session_label=args.session_label,
             task=args.task,
         ),
+        regressors=args.regressor,
         runner_config=RunnerConfig(
             runner=args.runner,
             verbose=bool(args.verbose),
@@ -61,7 +64,7 @@ def register_command(
         parents=parents,
         description=(
             "Warp preprocessed BOLD derivatives into each subject's "
-            "longitudinal template space."
+            "longitudinal template space and re-run nuisance regression."
         ),
         help="Longitudinal functional stage",
         usage=(
@@ -75,6 +78,13 @@ def register_command(
         default=None,
         help="Task label to filter BOLD runs (without 'task-' prefix).",
     )
+    parser.add_argument(
+        "--regressor",
+        nargs="+",
+        choices=["36-parameter", "aCompCor"],
+        default=["36-parameter"],
+        help="Space-delimited nuisance regression method(s) to apply.",
+    )
 
     parser.set_defaults(
         func=lambda args: main(FunctionalLongArgs.validate_namespace(args))

src/rbc/orchestration/longitudinal/functional.py

@@ -20,6 +20,7 @@
 if TYPE_CHECKING:
     from collections.abc import Sequence
     from pathlib import Path
+    from typing import Literal
 
     import polars as pl
 
@@ -34,13 +35,16 @@ def process_func(
     pipe_ctx: RunContext,
     func_df: pl.DataFrame,
     tpl_df: pl.DataFrame,
+    *,
+    regressors: Sequence[Literal["36-parameter", "aCompCor"]] = ("36-parameter",),
 ) -> None:
     """Handle functional longitudinal processing for one BOLD run.
 
     Args:
         pipe_ctx: RunContext bound to this subject/session.
         func_df: Functional derivative DataFrame for this run.
         tpl_df: Longitudinal template DataFrame.
+        regressors: Regressor strategies to apply in longitudinal space.
     """
     row = func_df.filter(suffix=Suffix.BOLD).row(0, named=True)
     ents = extract_entities(row, ["task", "run"])
@@ -54,17 +58,22 @@ def process_func(
         func_df,
         tpl_df,
         ses=pipe_ctx.ses,  # type: ignore[arg-type]
+        regressors=regressors,
+    )
+    func_outputs = functional_longitudinal(
+        **resolved,  # type: ignore[arg-type]
+        regressor_set=regressors,
     )
-    func_outputs = functional_longitudinal(**resolved)  # type: ignore[arg-type]
     fex = func_q.derive(space="longitudinal")
-    export_longitudinal_func(fex, func_outputs)
+    export_longitudinal_func(fex, func_outputs, regressors=regressors)
 
 
 def run(
     input_dirs: Sequence[Path],
     output_dir: Path,
     *,
     filters: Filters,
+    regressors: Sequence[Literal["36-parameter", "aCompCor"]] = ("36-parameter",),
     runner_config: RunnerConfig | None = None,
 ) -> None:
     """Run longitudinal functional processing for all matching subjects/sessions.
@@ -75,6 +84,7 @@ def run(
             and longitudinal templates).
         output_dir: Output directory for derivatives.
         filters: Participant/session/task filters applied before grouping.
+        regressors: Regressor strategies to apply in longitudinal space.
         runner_config: Execution backend configuration.
     """
     config = runner_config or RunnerConfig()
@@ -91,7 +101,12 @@ def run(
         input_dirs, output_dir, filters=filters, verbose=verbose
     ):
         for func_df, _ in iter_session_files(session, groupby=FUNC_GROUP_ENTITIES):
-            process_func(pipe_ctx=pipe_ctx, func_df=func_df, tpl_df=tpl_df)
+            process_func(
+                pipe_ctx=pipe_ctx,
+                func_df=func_df,
+                tpl_df=tpl_df,
+                regressors=regressors,
+            )
         pipe_ctx.ensure_dataset_description()
 
     _logger.info("RBC longitudinal functional workflow complete")

src/rbc/workflows/longitudinal/functional.py

@@ -1,22 +1,29 @@
 """Longitudinal functional processing workflow.
 
 Transforms preprocessed functional outputs to a pre-computed longitudinal
-template space and returns all output paths as a
+template space, then re-runs nuisance regression on the warped BOLD using
+raw regressors from the cross-sectional run.  Returns all output paths as a
 :class:`FunctionalLongOutputs` named tuple.
 """
 
 from __future__ import annotations
 
+import logging
 from typing import TYPE_CHECKING, NamedTuple
 
+from rbc.core.functional import apply_regression, apply_regression_bandpass
 from rbc.core.longitudinal.transform import (
     compose_transform,
     func_transform,
     mask_transform,
 )
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
     from pathlib import Path
+    from typing import Literal
+
+_logger = logging.getLogger("rbc")
 
 
 class FunctionalLongOutputs(NamedTuple):
@@ -26,14 +33,19 @@ class FunctionalLongOutputs(NamedTuple):
         bold_to_long_xfm: BOLD-to-longitudinal-template composite warp.
         sbref: Motion reference volume warped to longitudinal template space.
         bold: Preprocessed BOLD warped to longitudinal template space.
-        bold_mask: Brain mask warped to longitudinal template space,
-            or *None* if no mask was provided.
+        bold_mask: Brain mask warped to longitudinal template space.
+        regressed_bold: Per-regressor nuisance-regressed BOLD (no bandpass)
+            in longitudinal template space, keyed by strategy name.
+        cleaned_bold: Per-regressor nuisance-regressed + bandpass-filtered
+            BOLD in longitudinal template space, keyed by strategy name.
     """
 
     bold_to_long_xfm: Path
     sbref: Path
     bold: Path
-    bold_mask: Path | None = None
+    bold_mask: Path
+    regressed_bold: dict[str, Path]
+    cleaned_bold: dict[str, Path]
 
 
 def longitudinal_process(
@@ -43,41 +55,70 @@ def longitudinal_process(
     bold_to_anat_itk: Path,
     sbref: Path,
     bold: Path,
-    bold_mask: Path | None,
+    bold_mask: Path,
+    regressor_files: dict[str, Path],
+    regressor_set: Sequence[Literal["36-parameter", "aCompCor"]] = ("36-parameter",),
 ) -> FunctionalLongOutputs:
     """Transform preprocessed functional outputs to longitudinal template space.
 
-    Assumes a longitudinal template has been generated, the subject-to-template
-    composite warp is available, and anatomical data has already been processed
-    to longitudinal template space.
+    After warping the BOLD timeseries, re-runs nuisance regression using the
+    raw (unfiltered) regressors produced by the cross-sectional pipeline.
+    No regressor recomputation is performed: the same regressor matrix is
+    applied in the new target space.
 
     Args:
         template: Longitudinal template image.
         anat_to_template_xfm: T1w-to-longitudinal-template composite warp.
         bold_to_anat_itk: BOLD-to-T1w affine in ITK format.
         sbref: Motion reference (single-band reference) volume.
         bold: Preprocessed bold image.
-        bold_mask: Bold brain mask, if available.
+        bold_mask: Bold brain mask.
+        regressor_files: Raw (unfiltered) regressor ``.1D`` files from
+            the cross-sectional run, keyed by strategy name.
+        regressor_set: Which regressor strategies to apply.  Must be a
+            subset of the keys in *regressor_files*.
 
     Returns:
-        :class:`FunctionalLongOutputs` with all non-null inputs transformed to template
-            space.
+        :class:`FunctionalLongOutputs` with all inputs transformed to
+        longitudinal template space and per-regressor regression outputs.
     """
     bold_to_tpl_xfm = compose_transform(
         ref=template,
         bold_to_anat_itk=bold_to_anat_itk,
         anat_to_tpl_xfm=anat_to_template_xfm,
     )
 
+    long_sbref = func_transform(
+        in_file=sbref, template=template, xfm=bold_to_tpl_xfm, strategy="single"
+    )
+    long_bold = func_transform(
+        in_file=bold, template=template, xfm=bold_to_tpl_xfm, strategy="chunked"
+    )
+    long_mask = mask_transform(mask=bold_mask, template=template, xfm=bold_to_tpl_xfm)
+
+    regressed: dict[str, Path] = {}
+    cleaned: dict[str, Path] = {}
+    for reg in regressor_set:
+        reg_file = regressor_files[reg]
+        _logger.info("Longitudinal %s nuisance regression (no bandpass)", reg)
+        regressed[reg] = apply_regression(
+            bold_file=long_bold,
+            brain_mask_file=long_mask,
+            regressor_file=reg_file,
+        ).regressed_bold
+
+        _logger.info("Longitudinal %s nuisance regression + bandpass filtering", reg)
+        cleaned[reg] = apply_regression_bandpass(
+            bold_file=long_bold,
+            brain_mask_file=long_mask,
+            regressor_file=reg_file,
+        ).regressed_bold
+
     return FunctionalLongOutputs(
-        sbref=func_transform(  # 3D volume
-            in_file=sbref, template=template, xfm=bold_to_tpl_xfm, strategy="single"
-        ),
-        bold=func_transform(
-            in_file=bold, template=template, xfm=bold_to_tpl_xfm, strategy="chunked"
-        ),
-        bold_mask=mask_transform(mask=bold_mask, template=template, xfm=bold_to_tpl_xfm)
-        if bold_mask
-        else None,
         bold_to_long_xfm=bold_to_tpl_xfm,
+        sbref=long_sbref,
+        bold=long_bold,
+        bold_mask=long_mask,
+        regressed_bold=regressed,
+        cleaned_bold=cleaned,
     )

tests/unit/cli/test_longitudinal.py

@@ -80,15 +80,24 @@ class TestFunctionalLongArgs:
     def test_valid_task(self, base_ns: argparse.Namespace) -> None:
         """Alphanumeric task labels pass validation."""
         base_ns.task = "rest"
+        base_ns.regressor = ["36-parameter"]
         args = FunctionalLongArgs.validate_namespace(base_ns)
         assert args.task == "rest"
 
     def test_invalid_task_rejected(self, base_ns: argparse.Namespace) -> None:
         """Task labels with special characters are rejected."""
         base_ns.task = "rest/invalid"
+        base_ns.regressor = ["36-parameter"]
         with pytest.raises(ValueError, match="Task"):
             FunctionalLongArgs.validate_namespace(base_ns)
 
+    def test_regressor_preserved(self, base_ns: argparse.Namespace) -> None:
+        """Regressor choices round-trip through validation."""
+        base_ns.task = None
+        base_ns.regressor = ["36-parameter", "aCompCor"]
+        args = FunctionalLongArgs.validate_namespace(base_ns)
+        assert list(args.regressor) == ["36-parameter", "aCompCor"]
+
 
 class TestMetricsLongArgs:
     """Tests for the metrics longitudinal subcommand validator."""