MCFLIRT → AFNI 3dVolreg feature swap

[oesteban]

Objective

With the expansion mechanism (nipreps/agentic-files#9) in place, synthesize an fMRIPrep variant that replaces FSL MCFLIRT with AFNI 3dVolreg for head-motion correction — first proposed in #1535 back in March 2019 — as a diff against the fMRIPrep-preference path over the neutral HMC operation (nipreps/fmri-preprocessing-llm-wiki#3). The point of this issue is that, once #9 exists, this swap is nearly free: because 3dVolreg and MCFLIRT are methodologically equivalent but not numerically identical, the variant is validated on semantic substitutability (expert sign-off in nipreps/fmriprep-equivalence#7), not numerical identity.

Rationale

This is the concrete payoff of the whole architecture, and it is deliberately anchored on resolving the expansion mechanism (nipreps/agentic-files#9): if #9 works, producing this variant should be almost trivial — and that near-zero effort is the result we want to demonstrate. It also turns a seven-year-old feature request into a real, wanted change: the original motivations recorded in #1535 still hold — 3dVolreg is consistent with the estimator already used in MRIQC, faster than MCFLIRT, and reported to be more accurate (Oakes et al., 2005) — so the swap is worth making on its merits, not only as a demonstration.

Important

This is the non-memorizable demonstration: the MCFLIRT→3dVolreg variant is not in fMRIPrep, so it cannot be recalled from training and must be reasoned from the KB. If it works and validates, grounding is doing real work — and whether the model memorized fMRIPrep is beside the point.

Methodological approach

1. Synthesize. Apply the expansion mechanism (nipreps/agentic-files#9) to the HMC operation (nipreps/fmri-preprocessing-llm-wiki#3): select 3dVolreg from the neutral method space and re-synthesize the affected part of the pipeline, producing the variant.
2. Check the contract. The automatic functional-contract check confirms the 3dVolreg node's outputs (realignment parameters, resampled series) satisfy the downstream interface, so the rest of the pipeline runs and yields valid derivatives.
3. Expert validation. A domain expert signs off on semantic/methodological substitutability (nipreps/fmriprep-equivalence#7) — the substitution preserves the step's function despite differing numerically.
4. Ship. Make the validated variant available to users end-to-end, resolving Replace mcflirt with 3dVolreg #1535.

Outcomes/impact

1. A working, expert-validated MCFLIRT→3dVolreg fMRIPrep variant, available to users — closing the long-standing request in Replace mcflirt with 3dVolreg #1535.

This is the flagship demonstration that grounded node substitution lowers the cost of new features (measured against the effort a hand implementation would take), and the non-memorizable evidence that the agent reasons from the KB rather than recalling fMRIPrep.

Direct upstream issues

(issues this one depends on / builds upon)

• Replace mcflirt with 3dVolreg #1535
• Expansion mechanism — synthesize a methodologically-valid alternative processing choice agentic-files#9
• Formalize fMRI head-motion estimation & correction fmri-preprocessing-llm-wiki#3

Direct downstream issues

(issues that depend on this one)

• First multiverse expansion: brain extraction fmri-preprocessing-llm-wiki#7
• Validate MCFLIRT→3dVolreg swap fmriprep-equivalence#7