Merge pull request #29 from OpenScience-Collective/feature/issue-2-phase1-rerun

phase1: re-run preprocessing for 3 subjects

Author: neuromechanist

derivatives/preproc/README.md

@@ -0,0 +1,66 @@
+# Phase 1 preprocess: 3-subject re-run
+
+Re-run of the channel-level preprocessing for the first 3 eligible Healthy Brain Network (HBN) Release 3 (R3) subjects with a complete `ThePresent` run, recovered after the original Stage B derivatives were lost in a repo transfer. Generated by `phase1_preprocess(SmokeSubjectCount=3)` on 2026-05-12.
+
+## What is tracked in git
+
+```
+derivatives/preproc/
+  README.md                                 (this file)
+  qa_channels.csv                           per-subject QA table, all 3 rows
+  params.json                               full parameter snapshot + tool versions
+  sub-<ID>/figures/
+    sub-<ID>_stage-00-raw_psd.png           power spectral density (PSD) per stage
+    sub-<ID>_stage-01-hpf_psd.png
+    sub-<ID>_stage-02-cleanline_psd.png
+    sub-<ID>_stage-03-chanreject_psd.png
+```
+
+## What is NOT tracked
+
+Heavy intermediate checkpoints stay out of git (`.set`, `.fdt`, `.bdf`, `.mat`, plus the `_bids_import_scratch/` directory). To regenerate them, see the reproduce section below.
+
+```
+sub-<ID>/eeg/sub-<ID>_task-ThePresent_desc-clean_eeg.set    (ignored)
+sub-<ID>/eeg/sub-<ID>_task-ThePresent_desc-clean_eeg.fdt    (ignored)
+_bids_import_scratch/                                         (ignored)
+```
+
+## Subjects in this run
+
+| Participant      | Channels before | Channels after | Channels rejected                                     | srate |
+| ---------------- | --------------- | -------------- | ----------------------------------------------------- | ----- |
+| sub-NDARAA948VFH | 129             | 123            | 6 (E7, E15, E48, E67, E80, Cz)                        | 100   |
+| sub-NDARAC853DTE | 129             | 112            | 17 (E7, E31, E32, E43, E48, E55, E67, E68, E73, E80, E105, E106, E112, E113, E119, E127, Cz) | 100 |
+| sub-NDARAD774HAZ | 129             | 98             | 31 (E2, E4, E6, E7, E13, E20, E24, E26, E30, E31, E32, E38, E39, E43, E48, E55, E64, E68, E73, E74, E80, E87, E95, E99, E105, E106, E112, E113, E119, E127, Cz) | 100 |
+
+All 3 match the original Stage B counts (6 / 17 / 31) recorded in `.context/plan.md` on 2026-04-21. `Cz` is rejected in every subject because it is the dataset reference and is flat by construction (`clean_rawdata` correctly catches it; documented in `.context/scratch_history.md`).
+
+## Parameters
+
+Pinned at the values locked in `.context/ideas.md` and `.context/research.md`:
+
+| Parameter            | Value                                                |
+| -------------------- | ---------------------------------------------------- |
+| Task                 | `ThePresent`                                         |
+| BIDS root            | `/Volumes/S1/Datasets/HBN/L100/R3_L100_bdf`          |
+| High-pass filter     | 1 Hz (FIR, transition band 1 Hz, passband edge 1 Hz) |
+| Cleanline            | gated, skipped at 100 Hz (Nyquist = 50 Hz)           |
+| ChannelCriterion     | 0.8 (clean_rawdata)                                  |
+| LineNoiseCriterion   | 5 (clean_rawdata; ignored since cleanline gated)     |
+| ASR / interpolation  | OFF (channel-level rejection only this phase)        |
+
+See `params.json` for the canonical snapshot plus MATLAB / EEGLAB versions, git SHA, and ISO timestamp.
+
+## Reproduce
+
+```bash
+# From the repo root, with the phase1-rerun branch checked out
+matlab -batch "run('scripts/run_phase1_three_subjects.m')"
+```
+
+The runner script anchors all paths to its own location so MATLAB's `run()` chdir does not break `addpath`. EEGLAB is expected at `/Users/yahya/Documents/git/eeg/eeglab`. Wall-time on the local 100 Hz tier: ~3 minutes total for 3 subjects (excluding BIDS import scratch, which is cached after the first run).
+
+## Per-phase QA review
+
+The `eeg-qa-neuroscientist` agent (`.claude/agents/eeg-qa-neuroscientist.md`) reviews these figures before the PR opens. Findings live in the PR description, not here.

derivatives/preproc/params.json

@@ -0,0 +1,25 @@
+{
+  "BidsRoot": "/Volumes/S1/Datasets/HBN/L100/R3_L100_bdf",
+  "Task": "ThePresent",
+  "OutDir": "derivatives/preproc",
+  "Subjects": [],
+  "HpfHz": 1,
+  "RunCleanline": false,
+  "LineNoiseHz": [
+    60,
+    120,
+    180
+  ],
+  "ChannelCriterion": 0.8,
+  "LineNoiseCriterion": 5,
+  "SmokeSubjectCount": 3,
+  "n_subjects_eligible": 3,
+  "n_subjects_ok": 3,
+  "n_subjects_failed": 0,
+  "n_subjects_missing_from_import": 0,
+  "bids_import_scratch": "derivatives/preproc/_bids_import_scratch",
+  "matlab_version": "25.2.0.3055257 (R2025b) Update 2",
+  "eeglab_version": "dev",
+  "git_sha": "d1471fef1dc241e38fd3cd7bfb7c43e638057e67",
+  "timestamp_iso": "2026-05-13T05:16:15Z"
+}

derivatives/preproc/qa_channels.csv

@@ -0,0 +1,4 @@
+participant_id,status,n_channels_before,n_channels_after,rejected_channels,srate,cleanline_status,duration_s,error_message
+sub-NDARAA948VFH,ok,129,123,E7;E15;E48;E67;E80;Cz,100,skipped_nyquist,18.243,
+sub-NDARAC853DTE,ok,129,112,E7;E31;E32;E43;E48;E55;E67;E68;E73;E80;E105;E106;E112;E113;E119;E127;Cz,100,skipped_nyquist,7.389,
+sub-NDARAD774HAZ,ok,129,98,E2;E4;E6;E7;E13;E20;E24;E26;E30;E31;E32;E38;E39;E43;E48;E55;E64;E68;E73;E74;E80;E87;E95;E99;E105;E106;E112;E113;E119;E127;Cz,100,skipped_nyquist,6.771,