braino 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- braino-0.1.0/.gitignore +39 -0
- braino-0.1.0/PKG-INFO +316 -0
- braino-0.1.0/README.md +266 -0
- braino-0.1.0/pyproject.toml +106 -0
- braino-0.1.0/src/braino/__init__.py +3 -0
- braino-0.1.0/src/braino/cli.py +681 -0
- braino-0.1.0/src/braino/context.py +132 -0
- braino-0.1.0/src/braino/datasets/__init__.py +1 -0
- braino-0.1.0/src/braino/datasets/_build_erpcore_manifest.py +97 -0
- braino-0.1.0/src/braino/datasets/erpcore.py +144 -0
- braino-0.1.0/src/braino/datasets/erpcore_manifest.json +4424 -0
- braino-0.1.0/src/braino/datasets/erpcore_references.json +133 -0
- braino-0.1.0/src/braino/eeg/__init__.py +8 -0
- braino-0.1.0/src/braino/eeg/_quiet.py +26 -0
- braino-0.1.0/src/braino/eeg/bad_channels.py +235 -0
- braino-0.1.0/src/braino/eeg/epochs.py +243 -0
- braino-0.1.0/src/braino/eeg/erp.py +130 -0
- braino-0.1.0/src/braino/eeg/ica.py +205 -0
- braino-0.1.0/src/braino/eeg/preprocess.py +234 -0
- braino-0.1.0/src/braino/eeg/qc.py +255 -0
- braino-0.1.0/src/braino/eeg/spectral.py +164 -0
- braino-0.1.0/src/braino/eeg/tfr.py +153 -0
- braino-0.1.0/src/braino/io/__init__.py +61 -0
- braino-0.1.0/src/braino/io/batch.py +145 -0
- braino-0.1.0/src/braino/io/bids.py +286 -0
- braino-0.1.0/src/braino/io/dataset.py +128 -0
- braino-0.1.0/src/braino/io/deidentify.py +290 -0
- braino-0.1.0/src/braino/io/formats.py +358 -0
- braino-0.1.0/src/braino/io/importer.py +121 -0
- braino-0.1.0/src/braino/io/normalise.py +336 -0
- braino-0.1.0/src/braino/io/readers.py +154 -0
- braino-0.1.0/src/braino/pipelines/__init__.py +39 -0
- braino-0.1.0/src/braino/pipelines/runner.py +456 -0
- braino-0.1.0/src/braino/pipelines/spec.py +203 -0
- braino-0.1.0/src/braino/pipelines/specs/erpcore-n170.yaml +48 -0
- braino-0.1.0/src/braino/pipelines/specs/erpcore-p3.yaml +40 -0
- braino-0.1.0/src/braino/provenance/__init__.py +28 -0
- braino-0.1.0/src/braino/provenance/export.py +270 -0
- braino-0.1.0/src/braino/provenance/models.py +87 -0
- braino-0.1.0/src/braino/provenance/proposals.py +74 -0
- braino-0.1.0/src/braino/provenance/recorder.py +209 -0
- braino-0.1.0/src/braino/provenance/replay.py +203 -0
- braino-0.1.0/src/braino/provenance/store.py +49 -0
- braino-0.1.0/src/braino/py.typed +0 -0
- braino-0.1.0/src/braino/stats/__init__.py +4 -0
- braino-0.1.0/src/braino/stats/group.py +322 -0
- braino-0.1.0/src/braino/tools/__init__.py +38 -0
- braino-0.1.0/src/braino/tools/base.py +264 -0
- braino-0.1.0/src/braino/tools/dataset.py +24 -0
- braino-0.1.0/src/braino/tools/decisions.py +74 -0
- braino-0.1.0/src/braino/tools/eeg.py +600 -0
- braino-0.1.0/src/braino/tools/eeg_measures.py +360 -0
- braino-0.1.0/src/braino/tools/recordings.py +272 -0
- braino-0.1.0/src/braino/tools/registry.py +67 -0
- braino-0.1.0/src/braino/tools/stats.py +392 -0
- braino-0.1.0/src/braino/tools/system.py +32 -0
- braino-0.1.0/src/braino/validation/__init__.py +1 -0
- braino-0.1.0/src/braino/validation/erpcore.py +196 -0
- braino-0.1.0/tests/conftest.py +53 -0
- braino-0.1.0/tests/sample_data.py +131 -0
- braino-0.1.0/tests/synthetic_eeg.py +121 -0
- braino-0.1.0/tests/test_cli.py +57 -0
- braino-0.1.0/tests/test_cli_import.py +209 -0
- braino-0.1.0/tests/test_context.py +63 -0
- braino-0.1.0/tests/test_decisions.py +215 -0
- braino-0.1.0/tests/test_eeg_analysis.py +231 -0
- braino-0.1.0/tests/test_eeg_preprocess.py +151 -0
- braino-0.1.0/tests/test_eeg_qc.py +137 -0
- braino-0.1.0/tests/test_erpcore.py +131 -0
- braino-0.1.0/tests/test_export.py +185 -0
- braino-0.1.0/tests/test_io_bids.py +231 -0
- braino-0.1.0/tests/test_io_dataset.py +91 -0
- braino-0.1.0/tests/test_io_deidentify.py +241 -0
- braino-0.1.0/tests/test_io_formats.py +254 -0
- braino-0.1.0/tests/test_io_normalise.py +224 -0
- braino-0.1.0/tests/test_io_readers.py +105 -0
- braino-0.1.0/tests/test_pipelines.py +252 -0
- braino-0.1.0/tests/test_provenance.py +193 -0
- braino-0.1.0/tests/test_sample_data.py +41 -0
- braino-0.1.0/tests/test_stats_group.py +151 -0
- braino-0.1.0/tests/test_tools.py +172 -0
- braino-0.1.0/tests/test_tools_eeg.py +261 -0
braino-0.1.0/.gitignore
ADDED
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# OS / editors
|
|
2
|
+
.DS_Store
|
|
3
|
+
Thumbs.db
|
|
4
|
+
.vscode/*
|
|
5
|
+
!.vscode/extensions.json
|
|
6
|
+
.idea/
|
|
7
|
+
|
|
8
|
+
# Python (engine/)
|
|
9
|
+
__pycache__/
|
|
10
|
+
*.py[cod]
|
|
11
|
+
.venv/
|
|
12
|
+
venv/
|
|
13
|
+
*.egg-info/
|
|
14
|
+
build/
|
|
15
|
+
dist/
|
|
16
|
+
.pytest_cache/
|
|
17
|
+
.mypy_cache/
|
|
18
|
+
.ruff_cache/
|
|
19
|
+
.coverage
|
|
20
|
+
htmlcov/
|
|
21
|
+
|
|
22
|
+
# Local data and models (never commit participant data or model weights)
|
|
23
|
+
/data/
|
|
24
|
+
*.gguf
|
|
25
|
+
*.safetensors
|
|
26
|
+
|
|
27
|
+
# Unity (viewer/)
|
|
28
|
+
viewer/[Ll]ibrary/
|
|
29
|
+
viewer/[Tt]emp/
|
|
30
|
+
viewer/[Oo]bj/
|
|
31
|
+
viewer/[Bb]uild/
|
|
32
|
+
viewer/[Bb]uilds/
|
|
33
|
+
viewer/[Ll]ogs/
|
|
34
|
+
viewer/[Uu]ser[Ss]ettings/
|
|
35
|
+
viewer/[Mm]emoryCaptures/
|
|
36
|
+
viewer/*.csproj
|
|
37
|
+
viewer/*.sln
|
|
38
|
+
viewer/*.unityproj
|
|
39
|
+
viewer/.vs/
|
braino-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: braino
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: EEG and fMRI analysis engine with a local AI analysis agent
|
|
5
|
+
Project-URL: Homepage, https://github.com/kmnuddin/BrainO_v2
|
|
6
|
+
Project-URL: Documentation, https://kmnuddin.github.io/BrainO_v2/
|
|
7
|
+
Project-URL: Source, https://github.com/kmnuddin/BrainO_v2
|
|
8
|
+
Project-URL: Issues, https://github.com/kmnuddin/BrainO_v2/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/kmnuddin/BrainO_v2/blob/main/CHANGELOG.md
|
|
10
|
+
Author: Kazi Ashraf Moinuddin
|
|
11
|
+
License: GPL-3.0-or-later
|
|
12
|
+
Keywords: BIDS,EEG,MNE,agent,fMRI,neuroscience
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Science/Research
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
|
|
20
|
+
Requires-Python: >=3.11
|
|
21
|
+
Requires-Dist: pydantic>=2.6
|
|
22
|
+
Requires-Dist: pyyaml>=6.0
|
|
23
|
+
Requires-Dist: typer>=0.12
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: bids-validator>=1.14; extra == 'dev'
|
|
26
|
+
Requires-Dist: mypy>=1.10; extra == 'dev'
|
|
27
|
+
Requires-Dist: pooch>=1.8; extra == 'dev'
|
|
28
|
+
Requires-Dist: pytest-cov>=5; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
30
|
+
Requires-Dist: ruff>=0.5; extra == 'dev'
|
|
31
|
+
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
|
|
32
|
+
Provides-Extra: docs
|
|
33
|
+
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
|
|
34
|
+
Requires-Dist: mkdocs>=1.6; extra == 'docs'
|
|
35
|
+
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
|
|
36
|
+
Provides-Extra: eeg
|
|
37
|
+
Requires-Dist: autoreject>=0.4.3; extra == 'eeg'
|
|
38
|
+
Requires-Dist: curryreader>=0.1; extra == 'eeg'
|
|
39
|
+
Requires-Dist: mffpy>=0.10; extra == 'eeg'
|
|
40
|
+
Requires-Dist: mne-bids>=0.20; extra == 'eeg'
|
|
41
|
+
Requires-Dist: mne-icalabel>=0.7; extra == 'eeg'
|
|
42
|
+
Requires-Dist: mne>=1.13; extra == 'eeg'
|
|
43
|
+
Requires-Dist: numpy>=2.1; extra == 'eeg'
|
|
44
|
+
Requires-Dist: onnxruntime>=1.18; extra == 'eeg'
|
|
45
|
+
Requires-Dist: pybv>=0.7; extra == 'eeg'
|
|
46
|
+
Requires-Dist: pyprep>=0.4.3; extra == 'eeg'
|
|
47
|
+
Requires-Dist: python-picard>=0.8; extra == 'eeg'
|
|
48
|
+
Requires-Dist: scipy>=1.13; extra == 'eeg'
|
|
49
|
+
Description-Content-Type: text/markdown
|
|
50
|
+
|
|
51
|
+
# BrainO engine
|
|
52
|
+
|
|
53
|
+
The Python analysis engine behind BrainO: data import, EEG/fMRI analysis, statistics and the local
|
|
54
|
+
AI analysis agent. It can be used on its own from Python or the command line.
|
|
55
|
+
|
|
56
|
+
> Status: alpha (v0.1). Documentation: <https://kmnuddin.github.io/BrainO_v2/>. Roadmap:
|
|
57
|
+
> [`docs/PLAN.md`](https://github.com/kmnuddin/BrainO_v2/blob/main/docs/PLAN.md).
|
|
58
|
+
|
|
59
|
+
## Install (development)
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
cd engine
|
|
63
|
+
python -m venv .venv && source .venv/bin/activate # or: uv venv && source .venv/bin/activate
|
|
64
|
+
pip install -e ".[dev,eeg]"
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Python 3.11 or newer is required. The `eeg` extra installs the scientific stack (MNE-Python,
|
|
68
|
+
MNE-BIDS, NumPy and extra file readers); without it, the core (tools, provenance, CLI) still
|
|
69
|
+
works.
|
|
70
|
+
|
|
71
|
+
## Command line
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
# Import recordings (any supported format) into a de-identified BIDS dataset. The key file links
|
|
75
|
+
# subject labels to real IDs: keep it private and outside the dataset.
|
|
76
|
+
braino import raw/patient_a.edf --subject-id "patient A" --task rest --dataset study_bids --key private/key.json
|
|
77
|
+
braino import --mapping recordings.csv --dataset study_bids --key private/key.json
|
|
78
|
+
# recordings.csv columns: source,subject_id,task[,session,run,line_freq]
|
|
79
|
+
|
|
80
|
+
braino inspect --dataset study_bids # subjects, tasks, channels, events per recording
|
|
81
|
+
braino qc --dataset study_bids # flat/noisy channels, line noise, artifacts
|
|
82
|
+
braino qc --dataset study_bids --subject 001 --json
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
braino version
|
|
87
|
+
braino tools list # registered analysis tools and their risk level
|
|
88
|
+
braino tools schema system.info # JSON schema the AI agent sees for a tool
|
|
89
|
+
braino tools run system.info # run a tool, print the result as JSON
|
|
90
|
+
braino tools run <tool> --args '{"key": "value"}'
|
|
91
|
+
braino tools run <tool> --dataset path/to/bids # for tools that read a dataset or write outputs
|
|
92
|
+
braino runs list --dataset path/to/bids # recorded runs and the tools they called
|
|
93
|
+
braino runs show <run-id> --dataset path/to/bids # full provenance record of a run, as JSON
|
|
94
|
+
braino proposals list --pending --dataset path/to/bids # decisions waiting for you
|
|
95
|
+
braino proposals approve <id> --dataset path/to/bids [--edit '{"channels": ["T7"]}'] [--note ...]
|
|
96
|
+
braino proposals reject <id> --dataset path/to/bids [--note ...]
|
|
97
|
+
braino runs export <run-id> --dataset path/to/bids -o analysis.py # a script that re-runs it
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
braino pipeline list # built-in pipeline specs
|
|
102
|
+
braino pipeline show erpcore-p3 > p3.yaml # copy one to adapt
|
|
103
|
+
braino pipeline validate p3.yaml # tools exist, arguments fit
|
|
104
|
+
braino pipeline run p3.yaml --dataset path/to/bids # cached; stops at decisions
|
|
105
|
+
braino pipeline run p3.yaml --dataset path/to/bids --from epochs # redo from a step
|
|
106
|
+
braino pipeline status p3.yaml --dataset path/to/bids
|
|
107
|
+
braino pipeline export p3.yaml --dataset path/to/bids -o p3.py
|
|
108
|
+
braino validate erpcore P3 [--subjects 001,002,003] # reproduce the published P3
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## Tools
|
|
112
|
+
|
|
113
|
+
Every analysis step is a **tool**: a function that takes one Pydantic model and returns another.
|
|
114
|
+
The same tool is used by the CLI, the desktop app and the AI agent.
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
from pydantic import BaseModel, Field
|
|
118
|
+
|
|
119
|
+
from braino.tools import Risk, tool
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
class BandPowerInput(BaseModel):
|
|
123
|
+
recording: str = Field(description="Path to a BIDS EEG recording")
|
|
124
|
+
band: tuple[float, float] = Field(description="Frequency band in Hz, e.g. [8, 12]")
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
class BandPowerOutput(BaseModel):
|
|
128
|
+
power_per_channel: dict[str, float]
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
@tool(name="eeg.band_power", risk=Risk.COMPUTE)
|
|
132
|
+
def band_power(params: BandPowerInput) -> BandPowerOutput:
|
|
133
|
+
"""Compute mean power in a frequency band for each channel."""
|
|
134
|
+
...
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
- The **docstring** and the **field descriptions** are what the language model reads, so write
|
|
138
|
+
them for a reader who has never seen the code.
|
|
139
|
+
- **Risk levels:** `read` (inspect only), `compute` (produces new results), `decision` (changes
|
|
140
|
+
which data or statistical model the results rest on, e.g. dropping channels; the agent must
|
|
141
|
+
ask the user before running these).
|
|
142
|
+
|
|
143
|
+
### Run context
|
|
144
|
+
|
|
145
|
+
A tool that reads a dataset or writes outputs takes a second parameter, a `RunContext`. It says
|
|
146
|
+
which BIDS dataset the run works on, gives the run an ID, and hands out output folders under
|
|
147
|
+
`<dataset>/derivatives/braino/` (a BIDS-Derivatives dataset). The caller supplies the context;
|
|
148
|
+
it is not part of the tool's input schema, so the AI agent cannot choose where data is read from
|
|
149
|
+
or written to.
|
|
150
|
+
|
|
151
|
+
```python
|
|
152
|
+
from pathlib import Path
|
|
153
|
+
|
|
154
|
+
from braino.tools import RunContext, registry
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
@tool(name="eeg.band_power", risk=Risk.COMPUTE)
|
|
158
|
+
def band_power(params: BandPowerInput, ctx: RunContext) -> BandPowerOutput:
|
|
159
|
+
"""Compute mean power in a frequency band for each channel."""
|
|
160
|
+
raw = ctx.record_input(ctx.dataset / params.recording) # hashed for provenance
|
|
161
|
+
out = ctx.record_output(ctx.output_dir("sub-01", "eeg") / "band_power.json")
|
|
162
|
+
...
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
ctx = RunContext(dataset_root=Path("path/to/bids"))
|
|
166
|
+
registry.get("eeg.band_power").run({"recording": "...", "band": [8, 12]}, ctx)
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Provenance
|
|
170
|
+
|
|
171
|
+
Every tool call run with a context is recorded: tool, risk level, validated arguments, result,
|
|
172
|
+
success or error, timing, and the SHA-256 hash of each file declared with `record_input` /
|
|
173
|
+
`record_output`. A run's records are written to `derivatives/braino/runs/<run-id>/`:
|
|
174
|
+
`run.json` holds the environment (BrainO, Python, OS and analysis-library versions) and
|
|
175
|
+
`calls.jsonl` holds one line per tool call. Runs without a dataset keep their records in memory
|
|
176
|
+
(`ctx.provenance.calls`). Tools must not call other tools; chaining is the job of the pipeline
|
|
177
|
+
runner and the agent.
|
|
178
|
+
|
|
179
|
+
### Decision tools
|
|
180
|
+
|
|
181
|
+
A `decision` tool works in two steps, so that nothing the results rest on changes without a
|
|
182
|
+
person's approval:
|
|
183
|
+
|
|
184
|
+
1. **Propose.** Running the tool computes a proposal (e.g. channels to drop), saves it to
|
|
185
|
+
`derivatives/braino/proposals/<id>.json` and returns a `PendingProposal`. Nothing changes yet.
|
|
186
|
+
2. **Decide.** A person approves (optionally editing fields), or rejects, with
|
|
187
|
+
`braino proposals approve|reject` or `braino.tools.decide(...)`. On approval the tool's `apply`
|
|
188
|
+
function commits the final version. The proposal file keeps the original, the final version,
|
|
189
|
+
who decided, when, and why.
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
def apply_bad_channels(proposal: BadChannels, ctx: RunContext) -> Applied:
|
|
193
|
+
"""Mark the approved channels as bad in the derivatives."""
|
|
194
|
+
...
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
@tool(name="eeg.detect_bad_channels", risk=Risk.DECISION, apply=apply_bad_channels)
|
|
198
|
+
def detect_bad_channels(params: DetectInput, ctx: RunContext) -> BadChannels:
|
|
199
|
+
"""Find noisy or flat channels and propose them for removal."""
|
|
200
|
+
...
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
The AI agent can run decision tools, which only creates proposals; approving is never one of its
|
|
204
|
+
tools.
|
|
205
|
+
|
|
206
|
+
## Importing recordings
|
|
207
|
+
|
|
208
|
+
`braino.io.import_recording` turns one recording, in any supported format, into a de-identified
|
|
209
|
+
BIDS dataset entry: it detects the format, reads it, normalises channel names, types, positions
|
|
210
|
+
and events, removes personal details, and writes new BIDS files (the originals are only read).
|
|
211
|
+
|
|
212
|
+
```python
|
|
213
|
+
from braino.io import SubjectKey, import_recording
|
|
214
|
+
|
|
215
|
+
# The subject key links labels (sub-001, ...) to real identities. Keep it private, and outside
|
|
216
|
+
# the dataset folder; BrainO refuses to put it inside.
|
|
217
|
+
key = SubjectKey.open("private/subjects.json", dataset_root="study_bids")
|
|
218
|
+
report = import_recording(
|
|
219
|
+
"raw/patient_a.edf", "study_bids", key=key, original_id="patient A", task="rest"
|
|
220
|
+
)
|
|
221
|
+
print(report.conversion.files) # what was written, relative to the dataset
|
|
222
|
+
print(report.deidentification.free_text_events) # event text to check by hand
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
Each step is also available on its own: `detect_format`, `read_raw`, `normalise`, `deidentify`
|
|
226
|
+
and `write_bids`.
|
|
227
|
+
|
|
228
|
+
## Analysing EEG
|
|
229
|
+
|
|
230
|
+
The analysis tools work on one recording at a time, then on the group. Each writes new files to
|
|
231
|
+
`derivatives/braino/` (nothing is changed in place) and the next one reads them:
|
|
232
|
+
|
|
233
|
+
| Step | Tool | Writes |
|
|
234
|
+
|---|---|---|
|
|
235
|
+
| Filter, resample, re-reference | `eeg.preprocess` | `*_desc-preproc_eeg.fif` |
|
|
236
|
+
| Remove eye/heart components (decision) | `eeg.ica_clean` | `*_desc-preproc_ica.fif`, then `*_desc-clean_eeg.fif` |
|
|
237
|
+
| Mark bad channels (decision) | `eeg.detect_bad_channels` | `*_desc-preproc_channels.tsv` |
|
|
238
|
+
| Epoch, reject or repair artifacts | `eeg.epoch` | `*_desc-<label>_epo.fif` |
|
|
239
|
+
| Averages, difference waves, amplitudes | `eeg.erp` | `*_ave.fif`, `*_erp.tsv` |
|
|
240
|
+
| Spectra and band power | `eeg.spectral` | `*_psd.npz`, `*_bands.tsv` |
|
|
241
|
+
| Time-frequency power | `eeg.tfr` | `*_tfr.npz` |
|
|
242
|
+
| Group tests (FDR/Bonferroni/max-stat) | `stats.mass_univariate` | `group/task-<task>/*_stats.tsv` |
|
|
243
|
+
| Cluster permutation tests | `stats.cluster_permutation` | `group/task-<task>/*_clusters.tsv` |
|
|
244
|
+
|
|
245
|
+
ICA before bad-channel detection works best: eye activity then no longer makes the channels near
|
|
246
|
+
the eyes look bad (they are needed to remove it), and a broken channel shows up in ICA as a
|
|
247
|
+
"channel noise" component. Approved bad channels are interpolated when epoching. If an earlier
|
|
248
|
+
step is re-run, decisions made on its old output are refused until they are made again.
|
|
249
|
+
|
|
250
|
+
```python
|
|
251
|
+
from braino.tools import RunContext, decide, registry
|
|
252
|
+
|
|
253
|
+
ctx = RunContext(dataset_root="study_bids")
|
|
254
|
+
run = lambda tool, **args: registry.get(tool).run({"subject": "001", "task": "P3", **args}, ctx)
|
|
255
|
+
|
|
256
|
+
run("eeg.preprocess", l_freq=0.1, h_freq=30, resample_hz=256, reference=["P9", "P10"])
|
|
257
|
+
proposal = run("eeg.ica_clean") # proposes components to remove
|
|
258
|
+
decide(proposal.proposal_id, ctx, approve=True, decided_by="user:alice")
|
|
259
|
+
proposal = run("eeg.detect_bad_channels") # proposes channels to mark bad
|
|
260
|
+
decide(proposal.proposal_id, ctx, approve=True, decided_by="user:alice")
|
|
261
|
+
run("eeg.epoch", conditions={"rare": ["stimulus/11"], "frequent": ["stimulus/12"]})
|
|
262
|
+
run(
|
|
263
|
+
"eeg.erp",
|
|
264
|
+
contrasts=[{"name": "difference", "plus": "rare", "minus": "frequent"}],
|
|
265
|
+
measures=[{"name": "P3", "channels": ["Pz"], "tmin": 0.3, "tmax": 0.6}],
|
|
266
|
+
)
|
|
267
|
+
|
|
268
|
+
registry.get("stats.cluster_permutation").run({"task": "P3", "conditions": ["difference"]}, ctx)
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
From the command line, the same tools run with `braino tools run <tool> --args '{...}' --dataset
|
|
272
|
+
study_bids`, and decisions with `braino proposals approve|reject`.
|
|
273
|
+
|
|
274
|
+
## Validation against published results
|
|
275
|
+
|
|
276
|
+
BrainO's analysis pipeline is checked against ERP CORE (Kappenman et al., 2021, *NeuroImage*
|
|
277
|
+
225:117465; CC-BY-4.0): it must reproduce the published P3 and N170 effects, participant by
|
|
278
|
+
participant.
|
|
279
|
+
|
|
280
|
+
```python
|
|
281
|
+
from braino.datasets import erpcore
|
|
282
|
+
from braino.validation.erpcore import compare
|
|
283
|
+
|
|
284
|
+
root = erpcore.fetch("P3", ["001", "002"]) # BIDS data, hash-checked, cached in ~/.cache/braino
|
|
285
|
+
erpcore.references()["P3"] # what the authors measured and found
|
|
286
|
+
|
|
287
|
+
scores = {"001": 6.1, "002": 17.0, "003": 9.5} # BrainO's per-participant P3 amplitudes, µV
|
|
288
|
+
report = compare("P3", scores) # group and participant-level checks
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
`braino validate erpcore P3` (or `braino.validation.erpcore.run("P3")`) does all of it: downloads
|
|
292
|
+
the data, runs the built-in `erpcore-p3` pipeline with its decisions auto-approved, excludes
|
|
293
|
+
participants with more than 25% of trials rejected (ERP CORE's rule) and compares.
|
|
294
|
+
|
|
295
|
+
The full download is large (P3 2.2 GB, N170 3.4 GB), so it is not part of CI; the test that
|
|
296
|
+
downloads one participant runs with `BRAINO_LARGE_DOWNLOADS=1`.
|
|
297
|
+
|
|
298
|
+
## Test data
|
|
299
|
+
|
|
300
|
+
Tests that need real recordings download small public sample files (one recording per supported
|
|
301
|
+
format, about 33 MB in total) from MNE-Python's test data repository, check their SHA-256
|
|
302
|
+
hashes, and cache them. They are marked `network`.
|
|
303
|
+
|
|
304
|
+
- Cache folder: the OS cache folder, or `BRAINO_TEST_DATA=/some/path`.
|
|
305
|
+
- Offline: `BRAINO_SKIP_NETWORK=1 pytest` skips the download tests.
|
|
306
|
+
- In tests: `sample_data.fetch_recording("brainvision")` returns the path to open, and the
|
|
307
|
+
`synthetic_raw` fixture gives a small deterministic MNE recording that needs no download.
|
|
308
|
+
- Adding a file: see the docstring of [`tests/sample_data.py`](https://github.com/kmnuddin/BrainO_v2/blob/main/engine/tests/sample_data.py).
|
|
309
|
+
|
|
310
|
+
## Checks
|
|
311
|
+
|
|
312
|
+
Run these before committing; CI runs the same commands.
|
|
313
|
+
|
|
314
|
+
```bash
|
|
315
|
+
ruff check . && ruff format --check . && mypy && pytest
|
|
316
|
+
```
|
braino-0.1.0/README.md
ADDED
|
@@ -0,0 +1,266 @@
|
|
|
1
|
+
# BrainO engine
|
|
2
|
+
|
|
3
|
+
The Python analysis engine behind BrainO: data import, EEG/fMRI analysis, statistics and the local
|
|
4
|
+
AI analysis agent. It can be used on its own from Python or the command line.
|
|
5
|
+
|
|
6
|
+
> Status: alpha (v0.1). Documentation: <https://kmnuddin.github.io/BrainO_v2/>. Roadmap:
|
|
7
|
+
> [`docs/PLAN.md`](https://github.com/kmnuddin/BrainO_v2/blob/main/docs/PLAN.md).
|
|
8
|
+
|
|
9
|
+
## Install (development)
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
cd engine
|
|
13
|
+
python -m venv .venv && source .venv/bin/activate # or: uv venv && source .venv/bin/activate
|
|
14
|
+
pip install -e ".[dev,eeg]"
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
Python 3.11 or newer is required. The `eeg` extra installs the scientific stack (MNE-Python,
|
|
18
|
+
MNE-BIDS, NumPy and extra file readers); without it, the core (tools, provenance, CLI) still
|
|
19
|
+
works.
|
|
20
|
+
|
|
21
|
+
## Command line
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
# Import recordings (any supported format) into a de-identified BIDS dataset. The key file links
|
|
25
|
+
# subject labels to real IDs: keep it private and outside the dataset.
|
|
26
|
+
braino import raw/patient_a.edf --subject-id "patient A" --task rest --dataset study_bids --key private/key.json
|
|
27
|
+
braino import --mapping recordings.csv --dataset study_bids --key private/key.json
|
|
28
|
+
# recordings.csv columns: source,subject_id,task[,session,run,line_freq]
|
|
29
|
+
|
|
30
|
+
braino inspect --dataset study_bids # subjects, tasks, channels, events per recording
|
|
31
|
+
braino qc --dataset study_bids # flat/noisy channels, line noise, artifacts
|
|
32
|
+
braino qc --dataset study_bids --subject 001 --json
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
braino version
|
|
37
|
+
braino tools list # registered analysis tools and their risk level
|
|
38
|
+
braino tools schema system.info # JSON schema the AI agent sees for a tool
|
|
39
|
+
braino tools run system.info # run a tool, print the result as JSON
|
|
40
|
+
braino tools run <tool> --args '{"key": "value"}'
|
|
41
|
+
braino tools run <tool> --dataset path/to/bids # for tools that read a dataset or write outputs
|
|
42
|
+
braino runs list --dataset path/to/bids # recorded runs and the tools they called
|
|
43
|
+
braino runs show <run-id> --dataset path/to/bids # full provenance record of a run, as JSON
|
|
44
|
+
braino proposals list --pending --dataset path/to/bids # decisions waiting for you
|
|
45
|
+
braino proposals approve <id> --dataset path/to/bids [--edit '{"channels": ["T7"]}'] [--note ...]
|
|
46
|
+
braino proposals reject <id> --dataset path/to/bids [--note ...]
|
|
47
|
+
braino runs export <run-id> --dataset path/to/bids -o analysis.py # a script that re-runs it
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
braino pipeline list # built-in pipeline specs
|
|
52
|
+
braino pipeline show erpcore-p3 > p3.yaml # copy one to adapt
|
|
53
|
+
braino pipeline validate p3.yaml # tools exist, arguments fit
|
|
54
|
+
braino pipeline run p3.yaml --dataset path/to/bids # cached; stops at decisions
|
|
55
|
+
braino pipeline run p3.yaml --dataset path/to/bids --from epochs # redo from a step
|
|
56
|
+
braino pipeline status p3.yaml --dataset path/to/bids
|
|
57
|
+
braino pipeline export p3.yaml --dataset path/to/bids -o p3.py
|
|
58
|
+
braino validate erpcore P3 [--subjects 001,002,003] # reproduce the published P3
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Tools
|
|
62
|
+
|
|
63
|
+
Every analysis step is a **tool**: a function that takes one Pydantic model and returns another.
|
|
64
|
+
The same tool is used by the CLI, the desktop app and the AI agent.
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
from pydantic import BaseModel, Field
|
|
68
|
+
|
|
69
|
+
from braino.tools import Risk, tool
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class BandPowerInput(BaseModel):
|
|
73
|
+
recording: str = Field(description="Path to a BIDS EEG recording")
|
|
74
|
+
band: tuple[float, float] = Field(description="Frequency band in Hz, e.g. [8, 12]")
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
class BandPowerOutput(BaseModel):
|
|
78
|
+
power_per_channel: dict[str, float]
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
@tool(name="eeg.band_power", risk=Risk.COMPUTE)
|
|
82
|
+
def band_power(params: BandPowerInput) -> BandPowerOutput:
|
|
83
|
+
"""Compute mean power in a frequency band for each channel."""
|
|
84
|
+
...
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
- The **docstring** and the **field descriptions** are what the language model reads, so write
|
|
88
|
+
them for a reader who has never seen the code.
|
|
89
|
+
- **Risk levels:** `read` (inspect only), `compute` (produces new results), `decision` (changes
|
|
90
|
+
which data or statistical model the results rest on, e.g. dropping channels; the agent must
|
|
91
|
+
ask the user before running these).
|
|
92
|
+
|
|
93
|
+
### Run context
|
|
94
|
+
|
|
95
|
+
A tool that reads a dataset or writes outputs takes a second parameter, a `RunContext`. It says
|
|
96
|
+
which BIDS dataset the run works on, gives the run an ID, and hands out output folders under
|
|
97
|
+
`<dataset>/derivatives/braino/` (a BIDS-Derivatives dataset). The caller supplies the context;
|
|
98
|
+
it is not part of the tool's input schema, so the AI agent cannot choose where data is read from
|
|
99
|
+
or written to.
|
|
100
|
+
|
|
101
|
+
```python
|
|
102
|
+
from pathlib import Path
|
|
103
|
+
|
|
104
|
+
from braino.tools import RunContext, registry
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
@tool(name="eeg.band_power", risk=Risk.COMPUTE)
|
|
108
|
+
def band_power(params: BandPowerInput, ctx: RunContext) -> BandPowerOutput:
|
|
109
|
+
"""Compute mean power in a frequency band for each channel."""
|
|
110
|
+
raw = ctx.record_input(ctx.dataset / params.recording) # hashed for provenance
|
|
111
|
+
out = ctx.record_output(ctx.output_dir("sub-01", "eeg") / "band_power.json")
|
|
112
|
+
...
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
ctx = RunContext(dataset_root=Path("path/to/bids"))
|
|
116
|
+
registry.get("eeg.band_power").run({"recording": "...", "band": [8, 12]}, ctx)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Provenance
|
|
120
|
+
|
|
121
|
+
Every tool call run with a context is recorded: tool, risk level, validated arguments, result,
|
|
122
|
+
success or error, timing, and the SHA-256 hash of each file declared with `record_input` /
|
|
123
|
+
`record_output`. A run's records are written to `derivatives/braino/runs/<run-id>/`:
|
|
124
|
+
`run.json` holds the environment (BrainO, Python, OS and analysis-library versions) and
|
|
125
|
+
`calls.jsonl` holds one line per tool call. Runs without a dataset keep their records in memory
|
|
126
|
+
(`ctx.provenance.calls`). Tools must not call other tools; chaining is the job of the pipeline
|
|
127
|
+
runner and the agent.
|
|
128
|
+
|
|
129
|
+
### Decision tools
|
|
130
|
+
|
|
131
|
+
A `decision` tool works in two steps, so that nothing the results rest on changes without a
|
|
132
|
+
person's approval:
|
|
133
|
+
|
|
134
|
+
1. **Propose.** Running the tool computes a proposal (e.g. channels to drop), saves it to
|
|
135
|
+
`derivatives/braino/proposals/<id>.json` and returns a `PendingProposal`. Nothing changes yet.
|
|
136
|
+
2. **Decide.** A person approves (optionally editing fields), or rejects, with
|
|
137
|
+
`braino proposals approve|reject` or `braino.tools.decide(...)`. On approval the tool's `apply`
|
|
138
|
+
function commits the final version. The proposal file keeps the original, the final version,
|
|
139
|
+
who decided, when, and why.
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
def apply_bad_channels(proposal: BadChannels, ctx: RunContext) -> Applied:
|
|
143
|
+
"""Mark the approved channels as bad in the derivatives."""
|
|
144
|
+
...
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
@tool(name="eeg.detect_bad_channels", risk=Risk.DECISION, apply=apply_bad_channels)
|
|
148
|
+
def detect_bad_channels(params: DetectInput, ctx: RunContext) -> BadChannels:
|
|
149
|
+
"""Find noisy or flat channels and propose them for removal."""
|
|
150
|
+
...
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The AI agent can run decision tools, which only creates proposals; approving is never one of its
|
|
154
|
+
tools.
|
|
155
|
+
|
|
156
|
+
## Importing recordings
|
|
157
|
+
|
|
158
|
+
`braino.io.import_recording` turns one recording, in any supported format, into a de-identified
|
|
159
|
+
BIDS dataset entry: it detects the format, reads it, normalises channel names, types, positions
|
|
160
|
+
and events, removes personal details, and writes new BIDS files (the originals are only read).
|
|
161
|
+
|
|
162
|
+
```python
|
|
163
|
+
from braino.io import SubjectKey, import_recording
|
|
164
|
+
|
|
165
|
+
# The subject key links labels (sub-001, ...) to real identities. Keep it private, and outside
|
|
166
|
+
# the dataset folder; BrainO refuses to put it inside.
|
|
167
|
+
key = SubjectKey.open("private/subjects.json", dataset_root="study_bids")
|
|
168
|
+
report = import_recording(
|
|
169
|
+
"raw/patient_a.edf", "study_bids", key=key, original_id="patient A", task="rest"
|
|
170
|
+
)
|
|
171
|
+
print(report.conversion.files) # what was written, relative to the dataset
|
|
172
|
+
print(report.deidentification.free_text_events) # event text to check by hand
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Each step is also available on its own: `detect_format`, `read_raw`, `normalise`, `deidentify`
|
|
176
|
+
and `write_bids`.
|
|
177
|
+
|
|
178
|
+
## Analysing EEG
|
|
179
|
+
|
|
180
|
+
The analysis tools work on one recording at a time, then on the group. Each writes new files to
|
|
181
|
+
`derivatives/braino/` (nothing is changed in place) and the next one reads them:
|
|
182
|
+
|
|
183
|
+
| Step | Tool | Writes |
|
|
184
|
+
|---|---|---|
|
|
185
|
+
| Filter, resample, re-reference | `eeg.preprocess` | `*_desc-preproc_eeg.fif` |
|
|
186
|
+
| Remove eye/heart components (decision) | `eeg.ica_clean` | `*_desc-preproc_ica.fif`, then `*_desc-clean_eeg.fif` |
|
|
187
|
+
| Mark bad channels (decision) | `eeg.detect_bad_channels` | `*_desc-preproc_channels.tsv` |
|
|
188
|
+
| Epoch, reject or repair artifacts | `eeg.epoch` | `*_desc-<label>_epo.fif` |
|
|
189
|
+
| Averages, difference waves, amplitudes | `eeg.erp` | `*_ave.fif`, `*_erp.tsv` |
|
|
190
|
+
| Spectra and band power | `eeg.spectral` | `*_psd.npz`, `*_bands.tsv` |
|
|
191
|
+
| Time-frequency power | `eeg.tfr` | `*_tfr.npz` |
|
|
192
|
+
| Group tests (FDR/Bonferroni/max-stat) | `stats.mass_univariate` | `group/task-<task>/*_stats.tsv` |
|
|
193
|
+
| Cluster permutation tests | `stats.cluster_permutation` | `group/task-<task>/*_clusters.tsv` |
|
|
194
|
+
|
|
195
|
+
ICA before bad-channel detection works best: eye activity then no longer makes the channels near
|
|
196
|
+
the eyes look bad (they are needed to remove it), and a broken channel shows up in ICA as a
|
|
197
|
+
"channel noise" component. Approved bad channels are interpolated when epoching. If an earlier
|
|
198
|
+
step is re-run, decisions made on its old output are refused until they are made again.
|
|
199
|
+
|
|
200
|
+
```python
|
|
201
|
+
from braino.tools import RunContext, decide, registry
|
|
202
|
+
|
|
203
|
+
ctx = RunContext(dataset_root="study_bids")
|
|
204
|
+
run = lambda tool, **args: registry.get(tool).run({"subject": "001", "task": "P3", **args}, ctx)
|
|
205
|
+
|
|
206
|
+
run("eeg.preprocess", l_freq=0.1, h_freq=30, resample_hz=256, reference=["P9", "P10"])
|
|
207
|
+
proposal = run("eeg.ica_clean") # proposes components to remove
|
|
208
|
+
decide(proposal.proposal_id, ctx, approve=True, decided_by="user:alice")
|
|
209
|
+
proposal = run("eeg.detect_bad_channels") # proposes channels to mark bad
|
|
210
|
+
decide(proposal.proposal_id, ctx, approve=True, decided_by="user:alice")
|
|
211
|
+
run("eeg.epoch", conditions={"rare": ["stimulus/11"], "frequent": ["stimulus/12"]})
|
|
212
|
+
run(
|
|
213
|
+
"eeg.erp",
|
|
214
|
+
contrasts=[{"name": "difference", "plus": "rare", "minus": "frequent"}],
|
|
215
|
+
measures=[{"name": "P3", "channels": ["Pz"], "tmin": 0.3, "tmax": 0.6}],
|
|
216
|
+
)
|
|
217
|
+
|
|
218
|
+
registry.get("stats.cluster_permutation").run({"task": "P3", "conditions": ["difference"]}, ctx)
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
From the command line, the same tools run with `braino tools run <tool> --args '{...}' --dataset
|
|
222
|
+
study_bids`, and decisions with `braino proposals approve|reject`.
|
|
223
|
+
|
|
224
|
+
## Validation against published results
|
|
225
|
+
|
|
226
|
+
BrainO's analysis pipeline is checked against ERP CORE (Kappenman et al., 2021, *NeuroImage*
|
|
227
|
+
225:117465; CC-BY-4.0): it must reproduce the published P3 and N170 effects, participant by
|
|
228
|
+
participant.
|
|
229
|
+
|
|
230
|
+
```python
|
|
231
|
+
from braino.datasets import erpcore
|
|
232
|
+
from braino.validation.erpcore import compare
|
|
233
|
+
|
|
234
|
+
root = erpcore.fetch("P3", ["001", "002"]) # BIDS data, hash-checked, cached in ~/.cache/braino
|
|
235
|
+
erpcore.references()["P3"] # what the authors measured and found
|
|
236
|
+
|
|
237
|
+
scores = {"001": 6.1, "002": 17.0, "003": 9.5} # BrainO's per-participant P3 amplitudes, µV
|
|
238
|
+
report = compare("P3", scores) # group and participant-level checks
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
`braino validate erpcore P3` (or `braino.validation.erpcore.run("P3")`) does all of it: downloads
|
|
242
|
+
the data, runs the built-in `erpcore-p3` pipeline with its decisions auto-approved, excludes
|
|
243
|
+
participants with more than 25% of trials rejected (ERP CORE's rule) and compares.
|
|
244
|
+
|
|
245
|
+
The full download is large (P3 2.2 GB, N170 3.4 GB), so it is not part of CI; the test that
|
|
246
|
+
downloads one participant runs with `BRAINO_LARGE_DOWNLOADS=1`.
|
|
247
|
+
|
|
248
|
+
## Test data
|
|
249
|
+
|
|
250
|
+
Tests that need real recordings download small public sample files (one recording per supported
|
|
251
|
+
format, about 33 MB in total) from MNE-Python's test data repository, check their SHA-256
|
|
252
|
+
hashes, and cache them. They are marked `network`.
|
|
253
|
+
|
|
254
|
+
- Cache folder: the OS cache folder, or `BRAINO_TEST_DATA=/some/path`.
|
|
255
|
+
- Offline: `BRAINO_SKIP_NETWORK=1 pytest` skips the download tests.
|
|
256
|
+
- In tests: `sample_data.fetch_recording("brainvision")` returns the path to open, and the
|
|
257
|
+
`synthetic_raw` fixture gives a small deterministic MNE recording that needs no download.
|
|
258
|
+
- Adding a file: see the docstring of [`tests/sample_data.py`](https://github.com/kmnuddin/BrainO_v2/blob/main/engine/tests/sample_data.py).
|
|
259
|
+
|
|
260
|
+
## Checks
|
|
261
|
+
|
|
262
|
+
Run these before committing; CI runs the same commands.
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
ruff check . && ruff format --check . && mypy && pytest
|
|
266
|
+
```
|