Longitudinal pipeline: refactor and release readiness (tracker)

[nx10]

Tracking issue for the longitudinal pipeline refactor leading up to release.

Supersedes: #201, #153, #190, #200
Closes on land: #254, #282, #297 (Stage 0)
Follow-ups filed: #302 (noit=True spike), #303 (cross-sectional QC viz), #304 (longitudinal QC viz)

Goal

Restructure the longitudinal pipeline into a clean submodule tree (cli/longitudinal/, workflows/longitudinal/, bids/longitudinal/, orchestration/longitudinal/) mirroring cross-sectional, with a rbc longitudinal <stage> CLI (plus rbc long alias) and full test coverage.

Full working plan in internal docs.

Target CLI

rbc longitudinal template   INPUT_DIR [...] -o OUTPUT_DIR --fs-license PATH
rbc longitudinal anatomical INPUT_DIR [...] -o OUTPUT_DIR
rbc longitudinal functional INPUT_DIR [...] -o OUTPUT_DIR [--regressor ...]
rbc longitudinal metrics    INPUT_DIR [...] -o OUTPUT_DIR [--atlas ... --fwhm ...]
rbc longitudinal qc         INPUT_DIR [...] -o OUTPUT_DIR
rbc longitudinal all        INPUT_DIR [...] -o OUTPUT_DIR

rbc long is a subparser alias. Cross-sectional CLI unchanged.

Stages (each = one PR)

• Stage 0 — Close Refactor longitudinal script #254, Additional outputs to longitudinal functional workflow Fix #190 #282, Longitudinal metrics workflow Fix #200 #297 with attribution notes. File follow-up issues: noit=True spike (Evaluate noit=True in longitudinal robust template generation #302), cross-sectional viz (Cross-sectional QC visualization pipeline #303), longitudinal viz (Longitudinal QC visualization pipeline #304).
• Stage 1 — Pure file moves, no behavior change. Split bids/longitudinal.py and orchestration/longitudinal.py, extract longitudinal_process from workflows/{anatomical,functional}.py into */longitudinal/ submodules. No re-export shims (no external importers — verified by grep). Atomic update.
• Stage 2 — rbc longitudinal template subcommand replaces scripts/build_robust_template.py (deleted). Uses rbc.core.fsl2itk and rbc.bids. Fixes per-subject volume bug. Renames xfm convention to from-<ses>_to-longitudinal_xfm (spike confirmed Bids.expect() supports this). noit=True ported as-is (see Evaluate noit=True in longitudinal robust template generation #302).
• Stage 3 — CLI restructure. Nested cli/longitudinal/*.py with long alias. Delete --anatomical --functional flag shape. --fs-license / FS_LICENSE env plumbing.
• Stage 4 — Drop tissue-mask transforms from longitudinal anat outputs.
• Stage 5 — Functional outputs + regressor reuse (rewrite of Additional outputs to longitudinal functional workflow Fix #190 #282). Split raw vs bandpass-filtered regressor files. Re-run regression on longitudinal-space BOLD using raw regressors from cross-sectional.
• Stage 6 — Metrics + minimal QC (Dice + pass/fail) in longitudinal space. rbc longitudinal all chains all four stages in-memory. Visualization deferred to Cross-sectional QC visualization pipeline #303/Longitudinal QC visualization pipeline #304.
• Stage 7 — Update docs/data_dictionary.md, release notes.

Testing (per-stage acceptance criteria, not a separate stage)

• Unit — tests/unit/{bids,cli,orchestration,core}/test_longitudinal_*.py
• Integration (<5 min) — tests/integration/longitudinal/
• Integration, slow — stage-by-stage vs rbc longitudinal all parity
• Full pipeline — tests/full_pipeline/longitudinal/ session-scoped fixture

Fixture

OpenNeuro ds000114 ("Test-Retest Reliability"). One subject, two sessions (ses-test, ses-retest), T1w + task-fingerfootlips BOLD per session. CC0, ~300 MB subset. Fetched via download_fixture.sh (using aws s3 --no-sign-request), cached in CI via actions/cache keyed on the script hash.

Task BOLD (not rest) is acceptable — the pipeline doesn't branch on task label. HNU1 is the rest-state fallback if ever needed. NKI is disqualified (auth required). Non-numeric ses-test/ses-retest labels require an explicit unit test since current code assumes nothing about ses format.

Decisions (resolved)

• Nested CLI with long alias (not boolean flags)
• Close-and-supersede stale PRs with Co-authored-by
• Delete template script after Stage 2
• Port noit=True as-is, follow-up issue for quality spike (Evaluate noit=True in longitudinal robust template generation #302)
• Minimal QC in Stage 6, follow-up issues for CS (Cross-sectional QC visualization pipeline #303) + longitudinal viz (Longitudinal QC visualization pipeline #304)
• Real fixture only (ds000114)

Non-goals

• Cross-sectional CLI changes
• crosssectional/ submodule peer — asymmetry is intentional
• Any third processing tier (group-level etc.)