|
| 1 | +# Phase 2 AMICA: 3-subject re-run |
| 2 | + |
| 3 | +AMICA decomposition + dipfit5 dipole localization for the same 3 Healthy Brain Network (HBN) Release 3 (R3) subjects processed by Phase 1 (`derivatives/preproc/`). Generated by `phase2_amica()` invoked from `scripts/run_phase2_three_subjects.m` on 2026-05-13. |
| 4 | + |
| 5 | +## What is tracked in git |
| 6 | + |
| 7 | +``` |
| 8 | +derivatives/amica/ |
| 9 | + README.md (this file) |
| 10 | + qa_amica.csv per-subject QA table, 3 rows |
| 11 | + params.json full parameter snapshot + tool versions |
| 12 | + sub-<ID>/figures/ |
| 13 | + sub-<ID>_ic-topos.png first 30 independent component (IC) topographies |
| 14 | + sub-<ID>_dipoles.png dipole montage (top view) |
| 15 | +``` |
| 16 | + |
| 17 | +## What is NOT tracked |
| 18 | + |
| 19 | +Heavy AMICA checkpoints and intermediate files stay out of git (`.set`, `.fdt`, `.mat`, plus the `_amica/` model directory per subject which contains the AMICA `W`, `S`, `LL`, `mods` binaries). To regenerate them, see the reproduce section. |
| 20 | + |
| 21 | +``` |
| 22 | +sub-<ID>/eeg/sub-<ID>_task-ThePresent_desc-amica_eeg.set (ignored) |
| 23 | +sub-<ID>/eeg/sub-<ID>_task-ThePresent_desc-amica_eeg.fdt (ignored) |
| 24 | +sub-<ID>/_amica/ (ignored) |
| 25 | +``` |
| 26 | + |
| 27 | +## Subjects in this run |
| 28 | + |
| 29 | +| Participant | n_components | iterations | reached_max_iter | median_rv | wall-time (s) | |
| 30 | +| ---------------- | ------------ | ---------- | ---------------- | --------- | ------------- | |
| 31 | +| sub-NDARAA948VFH | 123 | 2000 | true | 0.368 | 1891 (~32 min) | |
| 32 | +| sub-NDARAC853DTE | 112 | 2000 | true | 0.420 | 1313 (~22 min) | |
| 33 | +| sub-NDARAD774HAZ | 98 | 2000 | true | 0.368 | 1156 (~19 min) | |
| 34 | + |
| 35 | +`n_components` matches the post-rejection channel count from Phase 1 (no Principal Component Analysis (PCA) reduction was applied; AMICA decomposes at full rank). `Cz` is rejected upstream so it does not appear here. |
| 36 | + |
| 37 | +### Known QA findings on this pilot |
| 38 | + |
| 39 | +- **All 3 subjects hit `reached_max_iter=true` at iteration 2000.** AMICA did not reach the log-likelihood convergence criterion within the budget. This is expected at the data-size we have: ~210 s × 100 Hz = 21,000 samples for ~120 channels, which falls below the conventional 30 × N² floor for stable Independent Component Analysis (ICA). The reference pipeline concatenates several HBN tasks to enlarge the sample pool; this project intentionally processes `ThePresent` only, so under-convergence is structural. |
| 40 | +- **Median residual variance (RV) is 0.37 to 0.42 across subjects.** Above the agent's "interesting" floor (suspect when >0.50) but well above the ideal <0.30 for clean brain ICs. Read alongside the topographies: the first ~20 ICs per subject look component-like, the tail looks noisy. |
| 41 | +- **Subjects are kept on the pilot watch list, not dropped.** Phase 3 (ICLabel) will decide which ICs survive the brain-threshold filter. If a subject ends up with fewer than 5 brain ICs at the locked threshold of 0.69, it gets dropped from group stats (per `.context/research.md` L92-94 escalation path). |
| 42 | + |
| 43 | +## Parameters |
| 44 | + |
| 45 | +| Parameter | Value | |
| 46 | +| -------------------- | ---------------------------------------------------- | |
| 47 | +| Task | `ThePresent` | |
| 48 | +| Preproc input | `derivatives/preproc/sub-*/eeg/*_desc-clean_eeg.set` | |
| 49 | +| Independent Component Analysis method | `amica` | |
| 50 | +| AMICA models | 1 | |
| 51 | +| AMICA max iterations | 2000 | |
| 52 | +| AMICA threads | 14 (host has 14 logical cores) | |
| 53 | +| Time-point rejection | enabled, 5 rejection iterations, 4 sigma threshold | |
| 54 | +| Head model | EEGLAB standard MNI Boundary Element Model | |
| 55 | +| Dipole fit | `pop_multifit`, RV threshold 100 (keep everything) | |
| 56 | + |
| 57 | +See `params.json` for the canonical snapshot plus MATLAB / EEGLAB versions, git SHA, and ISO timestamp. |
| 58 | + |
| 59 | +## Reproduce |
| 60 | + |
| 61 | +```bash |
| 62 | +# From the repo root |
| 63 | +matlab -batch "addpath('scripts'); run_phase2_three_subjects()" |
| 64 | +``` |
| 65 | + |
| 66 | +The runner regenerates Phase 1 `.set` checkpoints automatically if they are missing (the heavy checkpoints are gitignored). Wall-time on the local 14-core machine: ~75 minutes total for AMICA + dipfit across 3 subjects. |
| 67 | + |
| 68 | +## Per-phase QA review |
| 69 | + |
| 70 | +The `eeg-qa-neuroscientist` agent reviews these figures, the QA Comma-Separated Values table, and `params.json` before the PR opens. Findings live in the PR description, not here. |
0 commit comments