Unit C: contrast-enhanced T1 detection + non-contrast anchor preference

[davidj-brewster]

Summary

• Detection (is_contrast_enhanced_t1 in src/modules/reference_space_selection.sh): inspects the dcm2niix JSON sidecar first (via jq or grep fallback) for ContrastBolusAgent and ImageType CONTRAST; falls back to conservative filename heuristics only when no sidecar is available. All ${var^^} bash-4-only expansions replaced with portable printf '%s' | tr for bash 3.2 compatibility (macOS system shell).

• Preference/swap (Unit C block in src/pipeline.sh): when PREFER_EXTERNAL_NONCONTRAST_T1=true and the in-study T1 is detected as contrast-enhanced, the external non-contrast anchor (ANATOMICAL_REFERENCE_T1) is adopted as the structural reference. The in-study contrast-enhanced T1 is never deleted — it is exported as CONTRAST_ENHANCED_T1 so downstream analysis can use it as an enhancement signal. The swap is graceful: missing/unset ANATOMICAL_REFERENCE_T1 logs a WARNING and keeps the contrast T1 in place.

• Shared helper refactor (adopt_external_anatomical_t1): the ~30-line copy + size-check + sanity-check + provenance block that was duplicated across Unit A and Unit C is now a single shared helper. Both Unit A (no in-study T1) and Unit C (contrast swap) call it. Behavior of both paths is preserved exactly.

• Additional self-review fixes applied:

  • Removed ambiguous filename tokens +c and _c_ from the heuristic fallback to prevent false-positives on names like acq+contrast.
  • Removed dead code: redundant [ "${agent_upper}" != "" ] condition (identical to the preceding [ -n "${agent_upper}" ]).
  • Collapsed redundant double-grep on ImageType into a single piped check.

• Backward compatibility: the Unit C preference/swap block is guarded by [ "${PREFER_EXTERNAL_NONCONTRAST_T1:-false}" = "true" ]. With the default false, the entire block is unreachable and pipeline behaviour is byte-identical to before. Unit A's no-T1 adoption path is also unchanged in behaviour after the helper extraction.

Test plan

• bash -n src/modules/reference_space_selection.sh — syntax OK
• bash -n src/pipeline.sh — syntax OK
• shellcheck --severity=error both files — 0 findings
• bash tests/test_environment_unit.sh — 100/100 PASS
• bash tests/test_pipeline_control_unit.sh — 98/98 PASS
• bash tests/test_import_unit.sh — 29/29 PASS
• bash src/pipeline.sh --help | grep -q "Usage:" — PASS
• declare -f is_contrast_enhanced_t1 resolves after sourcing module — OK
• Staged PII scan (git diff --cached | grep -nEi '/Users/|...') — CLEAN
• git diff --stat shows only 2 files

🤖 Generated with Claude Code