phase2: amica + dipfit (code + CI wiring; data run in flight)

[neuromechanist]

Summary

Phase 2 of the HBN ERSP epic: AMICA decomposition + dipfit5 dipole localization, with a pluggable ICA dispatcher so CI (Ubuntu, no MPI libs) can run Infomax while production (local macOS, full MPI) uses AMICA.

Refs epic #1, closes #3.

What landed

Code

• src/matlab/phase2_amica.m — entrypoint with IcaMethod opt (amica or runica, default amica). Per-subject: load Phase 1 .set -> ICA -> attach weights -> dipfit -> figures -> AMICA checkpoint -> qa_amica.csv row.
• src/matlab/+hbn/run_amica.m — wraps runamica15. Passes EEG.data(:,:) (matrix path); passing the struct or the .fdt path either crashed the macOS binary (forrtl-66 in arg parsing) or tripped Linux file-type detection ("unknown file type"). Matrix path works everywhere.
• src/matlab/+hbn/run_infomax.m — runs pop_runica('icatype','runica'). Used by the CI smoke test because AMICA's Linux binary needs MPI Fortran runtime that Ubuntu runners do not have in a stable combination.
• src/matlab/+hbn/fit_dipoles.m — pop_dipfit_settings (standard MNI BEM) + pop_multifit.
• src/matlab/+hbn/save_ic_topo_figure.m, save_dipole_figure.m — first 30 IC topographies + dipole top view.
• src/matlab/+hbn/write_qa_amica_csv.m — schema: participant_id, status, ica_method, n_components, final_ll, iterations, reached_max_iter, median_rv, num_models, max_threads, duration_s, error_message.
• scripts/run_phase2_three_subjects.m — production 3-subject runner.
• scripts/regenerate_phase2_figures.m — rebuilds figures from existing AMICA .set checkpoints (used after the figure-export bug).
• tests/matlab/test_phase2_smoke.m — chains Phase 1 -> Phase 2 on the fixture with IcaMethod=runica, MaxIter=100, DoReject=false.

CI workflow

• .github/workflows/matlab-tests.yml auto-installs Biosig, amica, Fieldtrip-lite. AMICA isn't usable on the runner anyway (libmpifort.so.12); install kept for parity / future probing. Cache key eeglab-2026.0.0-v2-amica. Timeout 45 min.

Derivatives

• derivatives/amica/ (tracked via the .gitignore allow-list):
  • README.md, qa_amica.csv, params.json
  • sub-<ID>/figures/*.png (6 total)
• derivatives/**/_amica/ (heavy AMICA model binaries) and tmpflist (AMICA scratch) added to denylist.

3-subject AMICA results

Participant	n_components	iterations	reached_max_iter	median_rv	wall-time
sub-NDARAA948VFH	123	2000	true	0.368	~32 min
sub-NDARAC853DTE	112	2000	true	0.420	~22 min
sub-NDARAD774HAZ	98	2000	true	0.368	~19 min

n_components matches Phase 1 n_channels_after for every subject. Cz is rejected upstream and absent from the ICA. AMICA hit the iteration ceiling on all 3 — expected at this data size (~210 s × 100 Hz vs 30×N² floor for stable ICA at 120 channels). Reference pipeline mitigates by concatenating tasks; we intentionally process ThePresent only.

eeg-qa-neuroscientist review

Two passes; both attached for transparency.

Pass 1 verdict: FAIL

All six PNG figures are empty white canvases. File sizes byte-identical across subjects, which is impossible for genuine renders of independent ICA decompositions.

Root cause: save_ic_topo_figure and save_dipole_figure pre-allocated a figure handle and passed it to exportgraphics. But pop_topoplot and pop_dipplot open their own figures; the pre-allocated handle stayed empty. Both helpers now snapshot handles before/after the pop_* call and capture the new figure.

Pass 2 verdict: PASS-WITH-FINDINGS

Critical: IC 1-5 in the topo montage were occluded by my added sgtitle. Dropped sgtitle; pop_topoplot's own title arg is sufficient. Verified by reading the regenerated sub-NDARAA948VFH_ic-topos.png — IC 1 through 30 all visible.

Important (not blocking): tail ICs (beyond ~15) look noisy; consistent with AMICA's documented under-convergence. Phase 3 ICLabel filters at the locked 0.69 brain threshold. Dipole figures show pop_dipplot's MRI volume render pinstripe pattern; helper now hides axes, residual pinstripe is pop_dipplot's own rendering style and acknowledged as cosmetic.

Test plan

• Local: 5/5 tests green (test_list_eligible_subjects, test_write_qa_channels_csv, test_phase1_no_subjects, test_phase1_smoke, test_phase2_smoke).
• Local: 3-subject Phase 2 run on real R3 data with IcaMethod=amica, MaxIter=2000. All 3 ok; channel counts consistent with Phase 1.
• Local: figures regenerated after the export bug fix; IC 1 visible.
• CI: matlab-tests workflow green (uses IcaMethod=runica).
• eeg-qa-neuroscientist re-review on the final regenerated figures.

Follow-up

Phase 3 ICLabel will pick up where this leaves off. AMICA non-convergence + RV findings stay on the subject watch list per .context/research.md L92-94 escalation path.