phase3: iclabel classification + non-brain IC flagging

[neuromechanist]

Summary

Phase 3 of the HBN ERSP epic. Per subject: load Phase 2 .set → pop_iclabel('default') → flag ICs where brain probability < 0.69 (the locked threshold per .context/ideas.md) → render class summary + brain-IC topo PNGs → save .set checkpoint → qa_iclabel.csv row.

Flag, not delete. ICs below threshold get written to EEG.reject.gcompreject so Phase 4 (epoching) can still inspect them. The rich classifications stay in EEG.etc.ic_classification.ICLabel for downstream use.

Refs epic #1, closes #4 once the 3-subject derivatives + QA review land on this branch.

Code (this commit)

• src/matlab/phase3_iclabel.m — entrypoint. BrainThreshold default 0.69, IcLabelVersion default "default" (locked), MinBrainIcs default 5 with status="ok_low_brain" on subjects below the floor.
• src/matlab/+hbn/run_iclabel.m — wraps pop_iclabel. Validates that EEG.etc.ic_classification.ICLabel is populated. Heads-up: ICLabel's docstring says ic_classifications (plural) but the implementation writes ic_classification (singular). Caught locally; downstream code uses the singular form everywhere.
• src/matlab/+hbn/flag_non_brain_ics.m — validates the class ordering (Brain, Muscle, Eye, Heart, Line Noise, Channel Noise, Other), writes gcompreject, returns argmax-based per-class counts.
• src/matlab/+hbn/save_ic_class_figure.m — two-panel PNG: per-class bar (brain split into kept vs dropped) + brain-prob scatter vs IC index with the 0.69 threshold line.
• src/matlab/+hbn/save_brain_ic_topo_figure.m — kept brain ICs on a tight tile grid. Uses the snapshot-handles pattern from Phase 2 so pop_topoplot's own figure gets captured. Writes a labeled placeholder PNG if no brain IC survives, instead of silently erroring.
• src/matlab/+hbn/write_qa_iclabel_csv.m — schema: participant_id, status, n_components, brain_count, muscle_count, eye_count, heart_count, line_noise_count, channel_noise_count, other_count, brain_threshold, iclabel_version, duration_s, error_message.

Tests

• tests/matlab/test_phase3_smoke.m — chains Phase 1 → Phase 2 (IcaMethod=runica, MaxIter=100) → Phase 3 on the fixture. Asserts classifications attached, gcompreject length matches IC count, qa_iclabel.csv row consistent, params.json schema complete. Accepts ok or ok_low_brain (the 60s/100-iter wiring smoke is structurally below the brain floor — expected).
• tests/matlab/run_all_tests.m — adds test_phase3_smoke (6 tests total, all green locally).

Runner

• scripts/run_phase3_three_subjects.m — production runner. Regenerates Phase 1 + Phase 2 if their .set checkpoints are missing (they are gitignored). Currently running locally; derivatives + QA agent review will be added as a follow-up commit on this branch.

Local verification

test_phase3_smoke: OK (118 ICs, 3 brain kept, 115 flagged)

(Wiring smoke; not a quality signal. Real interpretive numbers come from the AMICA-based 3-subject run.)

Test plan

• Local smoke (runica + 100 iter): 118 ICs / 3 brain kept / 115 flagged. Smoke wiring works.
• CI green on this branch.
• 3-subject AMICA-based run on the local R3 dataset (in flight, ~80 min wall-time).
• eeg-qa-neuroscientist Phase 3 review on the real-data figures.
• Derivatives committed; PR body updated.

Follow-up

Phase 4 (event expansion + epoching) picks up the flagged .set files. ICs already in EEG.reject.gcompreject will be honored by std_precomp in Phase 5.