Automated EEG Analysis

AEA is an open library of 22 EEG analysis skills and 10 recipes. They give Codex CLI or Claude Code the domain instructions to generate and run analysis code with MNE-Python. You specify the study and approve the plan; the workflow keeps the code, results, figures, methods text, and review together.

Each skill specifies inputs, parameters, code templates, outputs, and checks. A recipe combines skills for a particular paradigm. The library has a numerically certified core; coverage depends on the output and configuration.

Install AEA Find a recipe Try the N400 tutorial

AEA workflow: skills and recipes guide an LLM coding agent, the researcher approves the plan, and MNE-Python executes the analysis. — Skills and recipes specify the analysis; you approve the plan, the agent adapts the code, and MNE-Python produces inspectable outputs. View full size.

Installation

Both routes use Git and Conda; start with the shared Python setup and figure fonts. To run the fixed N400 tutorial, add the EEG data and run the Python script. It needs no agent client, model account, skills installation or reviewer.

With a coding agent

This route needs a signed-in Codex CLI or Claude Code client and skill links. Choose a recipe that matches your paradigm. The example below uses compatible semantic-priming data; replace n400-semantic with the recipe for your study.

Keep the repository root as your working directory. Put your study's data in projects/my-study/raw/ before running the recipe, or follow the data setup guide for another layout. For official ERP CORE data, use the copy-ready N400 brief and approval prompt to keep the nested raw-data directory unchanged.

In your terminal

git clone https://github.com/dengzhe-hou/auto-eeg-analysis.git
cd auto-eeg-analysis
conda env create -f environment.yml
conda activate aeais
python tools/install_skills.py --agent codex
codex

Inside Codex

$eeg-recipe n400-semantic --data projects/my-study

In your terminal

git clone https://github.com/dengzhe-hou/auto-eeg-analysis.git
cd auto-eeg-analysis
conda env create -f environment.yml
conda activate aeais
python tools/install_skills.py --agent claude
claude

Inside Claude Code

/eeg-recipe n400-semantic --data projects/my-study

JavaScript enables client switching and copy buttons. For Claude Code, use --agent claude, launch claude, and invoke /eeg-recipe. Both clients are covered in the setup guide.

Review the detected data and confirm the analysis plan before execution. Configure the reviewer for this route's default audit, even when Claude Code runs the analysis.

See Getting started for the complete setup, and Platform support for environment checks, Windows, and optional dependencies. These commands use main; see version selection for the fixed v0.3.2 release.

Usage

Run a recipe eeg-recipe: Choose a recipe for your paradigm, check its data requirements, confirm the plan, and run the specified analysis.
Custom analysis eeg-pipeline: Define the claims, contrasts, and design. Combine the relevant skills with a frozen analysis plan and recorded outputs.
Review an analysis eeg-audit: A fresh reviewer checks whether the plan, statistics, figures, and methods support the reported findings.

N400 with a coding agent

Research request. Test whether unrelated target words evoke a more negative N400 than related targets.
Researcher approval. Confirm event labels, CPz/Cz/Pz, 300–500 ms, cleaning and statistics; review ambiguous ICA components.
Generated code and results. The agent writes and runs scripts, retaining condition averages, statistics, figures, methods and review records.

The recorded agent example used ICA, local AutoReject and 1024 Hz sampling. The fixed tutorial below omits ICA and uses 256 Hz; its results are separate.

Skills and recipes

Skills are plain Markdown specifications with code paths, reporting requirements, and documented failure modes. They cover preprocessing, analysis, statistics, figures, and reporting. Use the task reference to find a skill and the choices your analysis plan needs.

All 22 skills

eeg-preprocessFiltering, reference, bad channels
eeg-icaICA and component labeling
eeg-epochSegmentation and artifact rejection
eeg-erpERPs and component measures
eeg-tfrTime-frequency analysis
eeg-spectralPower spectra and spectral parameters
eeg-statsStatistical inference
eeg-decodingMVPA and temporal generalization
eeg-behaviorBehavioral and trial-level associations
eeg-connectivityFunctional and directed connectivity
eeg-microstateMaps and temporal dynamics
eeg-complexityEntropy and complexity measures
eeg-sourceSource localization
eeg-bidsBIDS-EEG conversion
eeg-qcData-quality checks
eeg-group-compareGroup comparisons and effect sizes
eeg-figureFigures and data-fidelity checks
eeg-methods-textCOBIDAS-MEEG methods text
eeg-auditIndependent model review
eeg-reportReports and reproducibility receipts
eeg-pipelineAnalysis orchestration
eeg-recipeRecipe execution and version tracking

Checks apply to specific outputs and configurations. See the per-skill evidence.

Recipes

Select a recipe to read its data requirements, parameters, and source references. Declared status and available validation are separate; follow the recipe's configuration when reproducing a result.

Ten analysis recipes and their declared statuses
Recipe	Analysis	Declared status
`ern-flankers`	N2, response-related negativity, frontal theta	Validated
`mmn-oddball`	Auditory mismatch negativity	Validated
`p300-oddball`	P300 to rare targets	ExperimentalGroup-validation results recorded
`n170-faces`	Faces versus non-face controls	Validated
`n170-face-inversion`	Upright versus inverted faces	Experimental
`n400-semantic`	Semantic priming	Validated
`alpha-attention-cueing`	Posterior alpha modulation	Experimental
`resting-microstate`	Resting microstate maps and dynamics	Validated
`resting-spectral-connectivity`	Power spectra, aperiodic fits, connectivity	Validated
`complexity-anesthesia`	Continuous complexity and entropy	ValidatedAwake-state check; anesthesia untested here

Recipe files and source references are in the source catalogue.

N400 tutorial

This fixed Python example needs the analysis environment, EEG data and Arial or Helvetica; it uses no agent or model account. Follow a complete semantic-priming recipe with 20 ERP CORE participants. The runner saves the plan, program, epochs, participant averages, statistics, figures, and methods text. Replay recomputes group statistics from the saved averages.

N400 results from 20 ERP CORE participants: related, unrelated, and difference ERPs at CPz/Cz/Pz, a descriptive scalp map, and all participant amplitude differences. — Saved results from 20 participants. (a) CPz/Cz/Pz ERPs; shading is ±1 SEM across participants, and the grey window is 300–500 ms. (b) Descriptive difference scalp map at the ROI peak in that window. (c) Each participant's mean unrelated-minus-related amplitude in 300–500 ms; the line is the group mean. View full size · Settings and replay scope.

Run. Supply an existing N400 BIDS dataset and a new output directory.
Check. Inspect the results and the recorded configuration.
Replay. Recompute group statistics without preprocessing again.

Replot without raw EEG · Get the data · Adapt to your study · Saved numerical results

Recorded results and scope

The CPz/Cz/Pz analysis at 300–500 ms retained 60 trials per condition for each participant. Unrelated minus related amplitude was −2.957 µV (SEM 0.466), with one cluster at p = .0002. In the saved run, replay reproduced t maps, cluster masks, p values, and permutation null values exactly. The figure can also be regenerated from the compact public arrays.

This documented branch omits ICA and amplitude rejection. The 20-person worked-example cohort is smaller than the 40-person source cohort, and its ROI test is separate from the historical all-channel certification. Scalp maps are descriptive; clusters do not localize each electrode or time point. This post-v0.3.2 example does not measure LLM success rate, time savings, held-out performance, or clinical efficacy.

Earlier N100 and Flankers examples

These single-participant examples were corrected after v0.3.2. Figures, scripts, original plans, positive and null results, and correction records remain accessible through the historical examples. They do not establish population effects or LLM-related speedup.

Validation

The numerically certified core covers ERP amplitudes and cluster statistics in selected configurations, plus spectral band power checked against an independent Welch implementation. Other checks have their own stated scope; certification does not apply to every option or generated workflow.

MNE-Python is the primary backend. EEGLAB and FieldTrip provide independent comparisons and selected alternative paths, with the numerical conventions documented for each capability.

Methods text

AEA reads pipeline logs and writes a COBIDAS-MEEG paragraph. Every number from disk, not memory. No other EEG tool does this.

Project

AEA builds on the ARIS architecture and EEG domain knowledge, with MNE-Python for computation. The source code and development history are on GitHub.

Significant contributors are invited as co-authors on the AEA paper. See the contribution guide for details.

Software uses the MIT licence. Recipe metadata uses CC BY 4.0.