longitudinal func outputs

Author: jpillai00

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="regressorsBPF",
+            desc=bids_safe_label(reg),
+            extension=".1D",
+        )
 
     mni = func.derive(space=TemplateSpace.MNI152NLIN6ASYM)
     for reg in regressors:

src/rbc/bids/longitudinal.py

@@ -4,9 +4,10 @@
 
 from typing import TYPE_CHECKING
 
-from rbc.bids import Suffix
+from rbc.bids import Suffix, bids_safe_label
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
     from pathlib import Path
 
     import polars as pl
@@ -106,7 +107,8 @@ def resolve_longitudinal_func(
     tpl_df: pl.DataFrame,
     *,
     ses: str,
-) -> dict[str, Path | None]:
+    regressors: Sequence[str],
+) -> dict[str, Path | None | dict[str, Path]]:
     """Resolve inputs for longitudinal functional processing.
 
     Args:
@@ -115,6 +117,7 @@ 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 names (e.g. ``["36-parameter"]``).
 
     Returns:
         Dict with keys matching ``longitudinal_process`` parameters.
@@ -138,9 +141,15 @@ 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": {
+            reg: func_q.expect(
+                func_df, suffix="regressors", desc=bids_safe_label(reg), extension=".1D"
+            )
+            for reg in regressors
+        },
     }
 
 
@@ -159,5 +168,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, path in outputs.regressed_bold.items():
+        fex.save(
+            path,
+            suffix=Suffix.BOLD,
+            desc="regressed",
+            extra={"reg": bids_safe_label(reg)},
+        )
+    for reg, path in outputs.cleaned_bold.items():
+        fex.save(
+            path,
+            suffix=Suffix.BOLD,
+            desc="preproc",
+            extra={"reg": bids_safe_label(reg)},
+        )

src/rbc/cli/longitudinal.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 BaseArgs, _or_default, _validate_nifti_path
 from rbc.orchestration import Filters, RunnerConfig
@@ -23,6 +23,7 @@ class LongitudinalArgs(BaseArgs):
     anatomical: bool
     functional: bool
     registration_template: Path
+    regressor: Sequence[Literal["36-parameter", "aCompCor"]]
 
     @classmethod
     def validate_namespace(cls, ns: argparse.Namespace) -> LongitudinalArgs:
@@ -38,6 +39,7 @@ def validate_namespace(cls, ns: argparse.Namespace) -> LongitudinalArgs:
             registration_template=_or_default(
                 ns.anat_template, REGISTRATION_TEMPLATES.brain_1mm
             ),
+            regressor=ns.regressor,
         )
 
 
@@ -53,6 +55,7 @@ def main(args: LongitudinalArgs) -> int:
         anatomical=args.anatomical,
         functional=args.functional,
         registration_template=args.registration_template,
+        regressors=args.regressor,
         runner_config=RunnerConfig(
             runner=args.runner,
             verbose=bool(args.verbose),
@@ -85,6 +88,13 @@ def register_command(
         action="store_true",
         help="Use functional longitudinal pipeline for processing",
     )
+    parser.add_argument(
+        "--regressor",
+        nargs="+",
+        choices=["36-parameter", "aCompCor"],
+        default=["36-parameter"],
+        help="Space-delimited nuisance regression method(s) to apply.",
+    )
 
     templates = parser.add_argument_group("template overrides")
     templates.add_argument(

src/rbc/orchestration/longitudinal.py

@@ -75,13 +75,15 @@ def process_func(
     pipe_ctx: RunContext,
     func_df: pl.DataFrame,
     tpl_df: pl.DataFrame,
+    regressors: Sequence[str],
 ) -> 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 names (e.g. ``["36-parameter"]``).
     """
     row = func_df.filter(suffix=Suffix.BOLD).row(0, named=True)
     ents = extract_entities(row, ["task", "run"])
@@ -95,6 +97,7 @@ 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]
     fex = func_q.derive(space="longitudinal")
@@ -109,6 +112,7 @@ def run(
     anatomical: bool = True,
     functional: bool = True,
     registration_template: Path = REGISTRATION_TEMPLATES.brain_1mm,
+    regressors: Sequence[str] = ("36-parameter",),
     runner_config: RunnerConfig | None = None,
 ) -> None:
     """Run the longitudinal pipeline for all matching subjects/sessions.
@@ -120,6 +124,7 @@ def run(
         anatomical: Run anatomical longitudinal processing.
         functional: Run functional longitudinal processing.
         registration_template: Brain template for ANTs registration.
+        regressors: Nuisance regressor strategies to apply (e.g. ``["36-parameter"]``).
         runner_config: Execution backend configuration.
     """
     config = runner_config or RunnerConfig()
@@ -173,7 +178,12 @@ def run(
 
         if functional:
             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()
 

src/rbc/workflows/functional.py

@@ -81,7 +81,8 @@ 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: Nuisance regressor ``.1D`` files.
+        bpf_regressor_file: Bandpass-filtered nuisance regressor ``.1D`` files.
         template_brain_mask: Brain mask warped to template space.
     """
 
@@ -105,6 +106,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
 
 
@@ -378,7 +380,8 @@ 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={r: regressors[r].regressor_file for r in regressor_set},
+        bpf_regressor_file=filtered_regressors,
         template_brain_mask=tmpl_brain,
     )
 
@@ -392,12 +395,18 @@ class FunctionalLongOutputs(NamedTuple):
         bold: Preprocessed BOLD warped to longitudinal template space.
         bold_mask: Brain mask warped to longitudinal template space,
             or *None* if no mask was provided.
+        regressed_bold: Nuisance-regressed (non-bandpassed) BOLD in longitudinal
+            template space. Suitable for ALFF/fALFF.
+        cleaned_bold: Nuisance-regressed + bandpass-filtered BOLD in longitudinal
+            template space (Hallquist 2013).
     """
 
     forward_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(
@@ -407,41 +416,83 @@ def longitudinal_process(
     bold_to_anat_itk: Path,
     sbref: Path,
     bold: Path,
-    bold_mask: Path | None,
+    bold_mask: Path,
+    regressor_files: dict[str, Path],
 ) -> 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.
 
+    Regressors are computed once during cross-sectional preprocessing and passed
+    in via ``regressor_files``. Only the regression steps are re-run against the
+    longitudinal space BOLD.
+
+    Steps:
+    1. Compose BOLD-to-anatomical + anatomical-to-longitudinal-template transforms.
+    2. Warp sbref (3D) and preproc BOLD (4D) to longitudinal template space.
+    3. Warp brain mask to longitudinal template space.
+    4. Nuisance regression without bandpass on longitudinal-space BOLD
+       (for ALFF/fALFF).
+    5. Nuisance regression with simultaneous bandpass filtering on longitudinal-space
+        BOLD (Hallquist 2013).
+
     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 in native space.
+        regressor_files: Per-regressor nuisance regressor ``.1D`` files.
+
 
     Returns:
         :class:`FunctionalLongOutputs` with all non-null inputs transformed to template
             space.
     """
+    # 1. Compose full BOLD -> longitudinal template transform
     bold_to_tpl_xfm = compose_transform(
         ref=template,
         bold_to_anat_itk=bold_to_anat_itk,
         anat_to_tpl_xfm=anat_to_template_xfm,
     )
 
+    # 2. Warp sbref & bold to longitudinal space
+    warped_sbref = func_transform(
+        in_file=sbref, template=template, xfm=bold_to_tpl_xfm, strategy="single"
+    )
+    warped_bold = func_transform(
+        in_file=bold, template=template, xfm=bold_to_tpl_xfm, strategy="chunked"
+    )
+
+    # 3. Warp bold mask to longitudinal space
+    warped_mask = mask_transform(mask=bold_mask, template=template, xfm=bold_to_tpl_xfm)
+
+    regression: dict[str, ApplyRegressionOutputs] = {}
+    cleaned: dict[str, ApplyRegressionOutputs] = {}
+    for reg, reg_file in regressor_files.items():
+        # 4. Nuisance regression without bandpass
+        _logger.info("%s nuisance regression (no bandpass)", reg)
+        regression[reg] = apply_regression(
+            bold_file=warped_bold,
+            brain_mask_file=warped_mask,
+            regressor_file=reg_file,
+        )
+        # 5. Simultaneous regression + bandpass filtering (Hallquist 2013)
+        _logger.info("%s nuisance regression + bandpass filtering", reg)
+        cleaned[reg] = apply_regression_bandpass(
+            bold_file=warped_bold,
+            brain_mask_file=warped_mask,
+            regressor_file=reg_file,
+        )
+
     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,
         forward_xfm=bold_to_tpl_xfm,
+        sbref=warped_sbref,
+        bold=warped_bold,
+        bold_mask=warped_mask,
+        regressed_bold={r: regression[r].regressed_bold for r in regressor_files},
+        cleaned_bold={r: cleaned[r].regressed_bold for r in regressor_files},
     )

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"bpf_regressors_{r}.1D") for r in regressors},
         template_brain_mask=_dummy(w, "template_mask.nii.gz"),
     )