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.
Files changed (82) hide show
  1. braino-0.1.0/.gitignore +39 -0
  2. braino-0.1.0/PKG-INFO +316 -0
  3. braino-0.1.0/README.md +266 -0
  4. braino-0.1.0/pyproject.toml +106 -0
  5. braino-0.1.0/src/braino/__init__.py +3 -0
  6. braino-0.1.0/src/braino/cli.py +681 -0
  7. braino-0.1.0/src/braino/context.py +132 -0
  8. braino-0.1.0/src/braino/datasets/__init__.py +1 -0
  9. braino-0.1.0/src/braino/datasets/_build_erpcore_manifest.py +97 -0
  10. braino-0.1.0/src/braino/datasets/erpcore.py +144 -0
  11. braino-0.1.0/src/braino/datasets/erpcore_manifest.json +4424 -0
  12. braino-0.1.0/src/braino/datasets/erpcore_references.json +133 -0
  13. braino-0.1.0/src/braino/eeg/__init__.py +8 -0
  14. braino-0.1.0/src/braino/eeg/_quiet.py +26 -0
  15. braino-0.1.0/src/braino/eeg/bad_channels.py +235 -0
  16. braino-0.1.0/src/braino/eeg/epochs.py +243 -0
  17. braino-0.1.0/src/braino/eeg/erp.py +130 -0
  18. braino-0.1.0/src/braino/eeg/ica.py +205 -0
  19. braino-0.1.0/src/braino/eeg/preprocess.py +234 -0
  20. braino-0.1.0/src/braino/eeg/qc.py +255 -0
  21. braino-0.1.0/src/braino/eeg/spectral.py +164 -0
  22. braino-0.1.0/src/braino/eeg/tfr.py +153 -0
  23. braino-0.1.0/src/braino/io/__init__.py +61 -0
  24. braino-0.1.0/src/braino/io/batch.py +145 -0
  25. braino-0.1.0/src/braino/io/bids.py +286 -0
  26. braino-0.1.0/src/braino/io/dataset.py +128 -0
  27. braino-0.1.0/src/braino/io/deidentify.py +290 -0
  28. braino-0.1.0/src/braino/io/formats.py +358 -0
  29. braino-0.1.0/src/braino/io/importer.py +121 -0
  30. braino-0.1.0/src/braino/io/normalise.py +336 -0
  31. braino-0.1.0/src/braino/io/readers.py +154 -0
  32. braino-0.1.0/src/braino/pipelines/__init__.py +39 -0
  33. braino-0.1.0/src/braino/pipelines/runner.py +456 -0
  34. braino-0.1.0/src/braino/pipelines/spec.py +203 -0
  35. braino-0.1.0/src/braino/pipelines/specs/erpcore-n170.yaml +48 -0
  36. braino-0.1.0/src/braino/pipelines/specs/erpcore-p3.yaml +40 -0
  37. braino-0.1.0/src/braino/provenance/__init__.py +28 -0
  38. braino-0.1.0/src/braino/provenance/export.py +270 -0
  39. braino-0.1.0/src/braino/provenance/models.py +87 -0
  40. braino-0.1.0/src/braino/provenance/proposals.py +74 -0
  41. braino-0.1.0/src/braino/provenance/recorder.py +209 -0
  42. braino-0.1.0/src/braino/provenance/replay.py +203 -0
  43. braino-0.1.0/src/braino/provenance/store.py +49 -0
  44. braino-0.1.0/src/braino/py.typed +0 -0
  45. braino-0.1.0/src/braino/stats/__init__.py +4 -0
  46. braino-0.1.0/src/braino/stats/group.py +322 -0
  47. braino-0.1.0/src/braino/tools/__init__.py +38 -0
  48. braino-0.1.0/src/braino/tools/base.py +264 -0
  49. braino-0.1.0/src/braino/tools/dataset.py +24 -0
  50. braino-0.1.0/src/braino/tools/decisions.py +74 -0
  51. braino-0.1.0/src/braino/tools/eeg.py +600 -0
  52. braino-0.1.0/src/braino/tools/eeg_measures.py +360 -0
  53. braino-0.1.0/src/braino/tools/recordings.py +272 -0
  54. braino-0.1.0/src/braino/tools/registry.py +67 -0
  55. braino-0.1.0/src/braino/tools/stats.py +392 -0
  56. braino-0.1.0/src/braino/tools/system.py +32 -0
  57. braino-0.1.0/src/braino/validation/__init__.py +1 -0
  58. braino-0.1.0/src/braino/validation/erpcore.py +196 -0
  59. braino-0.1.0/tests/conftest.py +53 -0
  60. braino-0.1.0/tests/sample_data.py +131 -0
  61. braino-0.1.0/tests/synthetic_eeg.py +121 -0
  62. braino-0.1.0/tests/test_cli.py +57 -0
  63. braino-0.1.0/tests/test_cli_import.py +209 -0
  64. braino-0.1.0/tests/test_context.py +63 -0
  65. braino-0.1.0/tests/test_decisions.py +215 -0
  66. braino-0.1.0/tests/test_eeg_analysis.py +231 -0
  67. braino-0.1.0/tests/test_eeg_preprocess.py +151 -0
  68. braino-0.1.0/tests/test_eeg_qc.py +137 -0
  69. braino-0.1.0/tests/test_erpcore.py +131 -0
  70. braino-0.1.0/tests/test_export.py +185 -0
  71. braino-0.1.0/tests/test_io_bids.py +231 -0
  72. braino-0.1.0/tests/test_io_dataset.py +91 -0
  73. braino-0.1.0/tests/test_io_deidentify.py +241 -0
  74. braino-0.1.0/tests/test_io_formats.py +254 -0
  75. braino-0.1.0/tests/test_io_normalise.py +224 -0
  76. braino-0.1.0/tests/test_io_readers.py +105 -0
  77. braino-0.1.0/tests/test_pipelines.py +252 -0
  78. braino-0.1.0/tests/test_provenance.py +193 -0
  79. braino-0.1.0/tests/test_sample_data.py +41 -0
  80. braino-0.1.0/tests/test_stats_group.py +151 -0
  81. braino-0.1.0/tests/test_tools.py +172 -0
  82. braino-0.1.0/tests/test_tools_eeg.py +261 -0
@@ -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
+ ```