braino 0.1.0__py3-none-any.whl
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/__init__.py +3 -0
- braino/cli.py +681 -0
- braino/context.py +132 -0
- braino/datasets/__init__.py +1 -0
- braino/datasets/_build_erpcore_manifest.py +97 -0
- braino/datasets/erpcore.py +144 -0
- braino/datasets/erpcore_manifest.json +4424 -0
- braino/datasets/erpcore_references.json +133 -0
- braino/eeg/__init__.py +8 -0
- braino/eeg/_quiet.py +26 -0
- braino/eeg/bad_channels.py +235 -0
- braino/eeg/epochs.py +243 -0
- braino/eeg/erp.py +130 -0
- braino/eeg/ica.py +205 -0
- braino/eeg/preprocess.py +234 -0
- braino/eeg/qc.py +255 -0
- braino/eeg/spectral.py +164 -0
- braino/eeg/tfr.py +153 -0
- braino/io/__init__.py +61 -0
- braino/io/batch.py +145 -0
- braino/io/bids.py +286 -0
- braino/io/dataset.py +128 -0
- braino/io/deidentify.py +290 -0
- braino/io/formats.py +358 -0
- braino/io/importer.py +121 -0
- braino/io/normalise.py +336 -0
- braino/io/readers.py +154 -0
- braino/pipelines/__init__.py +39 -0
- braino/pipelines/runner.py +456 -0
- braino/pipelines/spec.py +203 -0
- braino/pipelines/specs/erpcore-n170.yaml +48 -0
- braino/pipelines/specs/erpcore-p3.yaml +40 -0
- braino/provenance/__init__.py +28 -0
- braino/provenance/export.py +270 -0
- braino/provenance/models.py +87 -0
- braino/provenance/proposals.py +74 -0
- braino/provenance/recorder.py +209 -0
- braino/provenance/replay.py +203 -0
- braino/provenance/store.py +49 -0
- braino/py.typed +0 -0
- braino/stats/__init__.py +4 -0
- braino/stats/group.py +322 -0
- braino/tools/__init__.py +38 -0
- braino/tools/base.py +264 -0
- braino/tools/dataset.py +24 -0
- braino/tools/decisions.py +74 -0
- braino/tools/eeg.py +600 -0
- braino/tools/eeg_measures.py +360 -0
- braino/tools/recordings.py +272 -0
- braino/tools/registry.py +67 -0
- braino/tools/stats.py +392 -0
- braino/tools/system.py +32 -0
- braino/validation/__init__.py +1 -0
- braino/validation/erpcore.py +196 -0
- braino-0.1.0.dist-info/METADATA +316 -0
- braino-0.1.0.dist-info/RECORD +58 -0
- braino-0.1.0.dist-info/WHEEL +4 -0
- braino-0.1.0.dist-info/entry_points.txt +2 -0
braino/__init__.py
ADDED
braino/cli.py
ADDED
|
@@ -0,0 +1,681 @@
|
|
|
1
|
+
"""Command-line interface: ``braino --help``."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import json
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Annotated, Any, NoReturn
|
|
8
|
+
|
|
9
|
+
import typer
|
|
10
|
+
from pydantic import ValidationError
|
|
11
|
+
|
|
12
|
+
from braino import __version__
|
|
13
|
+
from braino.context import NoDatasetError, RunContext
|
|
14
|
+
from braino.provenance import ProposalNotFoundError, RunNotFoundError, list_runs, load_run
|
|
15
|
+
from braino.tools import (
|
|
16
|
+
PendingProposal,
|
|
17
|
+
ProposalAlreadyDecidedError,
|
|
18
|
+
ToolNotFoundError,
|
|
19
|
+
current_user,
|
|
20
|
+
decide,
|
|
21
|
+
registry,
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
app = typer.Typer(help="BrainO: EEG and fMRI analysis engine.", no_args_is_help=True)
|
|
25
|
+
tools_app = typer.Typer(help="List, inspect and run analysis tools.", no_args_is_help=True)
|
|
26
|
+
app.add_typer(tools_app, name="tools")
|
|
27
|
+
runs_app = typer.Typer(help="Inspect the provenance of past runs.", no_args_is_help=True)
|
|
28
|
+
app.add_typer(runs_app, name="runs")
|
|
29
|
+
proposals_app = typer.Typer(
|
|
30
|
+
help="Review, approve or reject what decision tools propose.", no_args_is_help=True
|
|
31
|
+
)
|
|
32
|
+
app.add_typer(proposals_app, name="proposals")
|
|
33
|
+
|
|
34
|
+
_DATASET_HELP = "Root of the BIDS dataset to work on"
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@app.command()
|
|
38
|
+
def version() -> None:
|
|
39
|
+
"""Print the BrainO version."""
|
|
40
|
+
typer.echo(__version__)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
@tools_app.command("list")
|
|
44
|
+
def list_tools() -> None:
|
|
45
|
+
"""List the registered tools."""
|
|
46
|
+
for t in registry:
|
|
47
|
+
summary = t.description.splitlines()[0]
|
|
48
|
+
typer.echo(f"{t.name:<32} {t.risk.value:<9} {summary}")
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
@tools_app.command("schema")
|
|
52
|
+
def tool_schema(
|
|
53
|
+
name: Annotated[str | None, typer.Argument(help="Tool name; omit for all tools")] = None,
|
|
54
|
+
) -> None:
|
|
55
|
+
"""Print the LLM-facing JSON schema of one tool, or of all tools."""
|
|
56
|
+
try:
|
|
57
|
+
schema = registry.get(name).llm_schema() if name else registry.schemas()
|
|
58
|
+
except ToolNotFoundError:
|
|
59
|
+
typer.echo(f"Unknown tool: {name}", err=True)
|
|
60
|
+
raise typer.Exit(code=1) from None
|
|
61
|
+
typer.echo(json.dumps(schema, indent=2))
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
@tools_app.command("run")
|
|
65
|
+
def run_tool(
|
|
66
|
+
name: Annotated[str, typer.Argument(help="Tool name, e.g. system.info")],
|
|
67
|
+
arguments: Annotated[str, typer.Option("--args", help="Tool arguments as JSON")] = "{}",
|
|
68
|
+
dataset: Annotated[Path | None, typer.Option("--dataset", help=_DATASET_HELP)] = None,
|
|
69
|
+
) -> None:
|
|
70
|
+
"""Run a tool and print its result as JSON."""
|
|
71
|
+
try:
|
|
72
|
+
t = registry.get(name)
|
|
73
|
+
except ToolNotFoundError:
|
|
74
|
+
typer.echo(f"Unknown tool: {name}", err=True)
|
|
75
|
+
raise typer.Exit(code=1) from None
|
|
76
|
+
|
|
77
|
+
parsed = _parse_json_object(arguments, "--args")
|
|
78
|
+
if t.requires_approval and dataset is None:
|
|
79
|
+
typer.echo(f"{name} is a decision tool; pass --dataset so its proposal is saved", err=True)
|
|
80
|
+
raise typer.Exit(code=1)
|
|
81
|
+
|
|
82
|
+
try:
|
|
83
|
+
context = RunContext(dataset_root=dataset)
|
|
84
|
+
except NotADirectoryError as exc:
|
|
85
|
+
typer.echo(str(exc), err=True)
|
|
86
|
+
raise typer.Exit(code=1) from None
|
|
87
|
+
if dataset is not None:
|
|
88
|
+
typer.echo(f"run {context.run_id}", err=True)
|
|
89
|
+
|
|
90
|
+
try:
|
|
91
|
+
result = t.run(parsed, context)
|
|
92
|
+
except (ValidationError, NoDatasetError) as exc:
|
|
93
|
+
typer.echo(str(exc), err=True)
|
|
94
|
+
raise typer.Exit(code=1) from None
|
|
95
|
+
typer.echo(result.model_dump_json(indent=2))
|
|
96
|
+
if isinstance(result, PendingProposal):
|
|
97
|
+
typer.echo(
|
|
98
|
+
f"proposal {result.proposal_id} awaits your decision: "
|
|
99
|
+
f"braino proposals approve|reject {result.proposal_id} --dataset {dataset}",
|
|
100
|
+
err=True,
|
|
101
|
+
)
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def _parse_json_object(text: str, option: str) -> dict[str, Any]:
|
|
105
|
+
try:
|
|
106
|
+
parsed = json.loads(text)
|
|
107
|
+
except json.JSONDecodeError as exc:
|
|
108
|
+
typer.echo(f"{option} is not valid JSON: {exc}", err=True)
|
|
109
|
+
raise typer.Exit(code=1) from None
|
|
110
|
+
if not isinstance(parsed, dict):
|
|
111
|
+
typer.echo(f"{option} must be a JSON object", err=True)
|
|
112
|
+
raise typer.Exit(code=1)
|
|
113
|
+
return parsed
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def _context(dataset: Path) -> RunContext:
|
|
117
|
+
try:
|
|
118
|
+
return RunContext(dataset_root=dataset)
|
|
119
|
+
except NotADirectoryError as exc:
|
|
120
|
+
typer.echo(str(exc), err=True)
|
|
121
|
+
raise typer.Exit(code=1) from None
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def _derivatives_root(dataset: Path) -> Path:
|
|
125
|
+
return _context(dataset).derivatives_root
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
@app.command("import")
|
|
129
|
+
def import_command(
|
|
130
|
+
source: Annotated[
|
|
131
|
+
Path | None, typer.Argument(help="Recording to import (or use --mapping)")
|
|
132
|
+
] = None,
|
|
133
|
+
dataset: Annotated[Path, typer.Option("--dataset", help="BIDS dataset to import into")] = Path(
|
|
134
|
+
"."
|
|
135
|
+
),
|
|
136
|
+
key: Annotated[
|
|
137
|
+
Path | None,
|
|
138
|
+
typer.Option("--key", help="Subject key file (private; must be outside the dataset)"),
|
|
139
|
+
] = None,
|
|
140
|
+
subject_id: Annotated[
|
|
141
|
+
str | None, typer.Option("--subject-id", help="The person's original ID (kept in the key)")
|
|
142
|
+
] = None,
|
|
143
|
+
task: Annotated[str | None, typer.Option("--task", help="Task label, e.g. rest")] = None,
|
|
144
|
+
session: Annotated[str | None, typer.Option("--session", help="Session label")] = None,
|
|
145
|
+
run: Annotated[int | None, typer.Option("--run", help="Run number")] = None,
|
|
146
|
+
line_freq: Annotated[
|
|
147
|
+
float | None, typer.Option("--line-freq", help="Power-line frequency in Hz, if known")
|
|
148
|
+
] = None,
|
|
149
|
+
mapping: Annotated[
|
|
150
|
+
Path | None,
|
|
151
|
+
typer.Option("--mapping", help="CSV with source,subject_id,task[,session,run,line_freq]"),
|
|
152
|
+
] = None,
|
|
153
|
+
overwrite: Annotated[bool, typer.Option("--overwrite", help="Replace recordings")] = False,
|
|
154
|
+
) -> None:
|
|
155
|
+
"""Import recordings into a BIDS dataset, removing personal details on the way.
|
|
156
|
+
|
|
157
|
+
Give one recording with --subject-id and --task, or many with --mapping.
|
|
158
|
+
"""
|
|
159
|
+
from braino.io.batch import ImportFailedError, ImportJob, MappingError, import_job, read_mapping
|
|
160
|
+
from braino.io.deidentify import SubjectKey, SubjectKeyError
|
|
161
|
+
|
|
162
|
+
if key is None:
|
|
163
|
+
_fail("--key is required: the private file that links subject labels to real IDs")
|
|
164
|
+
dataset.mkdir(parents=True, exist_ok=True)
|
|
165
|
+
try:
|
|
166
|
+
subject_key = SubjectKey.open(key, dataset_root=dataset)
|
|
167
|
+
if mapping is not None:
|
|
168
|
+
if source is not None:
|
|
169
|
+
_fail("give either a recording or --mapping, not both")
|
|
170
|
+
jobs = read_mapping(mapping, dataset_root=dataset)
|
|
171
|
+
else:
|
|
172
|
+
if source is None or subject_id is None or task is None:
|
|
173
|
+
_fail("give a recording with --subject-id and --task, or use --mapping")
|
|
174
|
+
jobs = [
|
|
175
|
+
ImportJob(
|
|
176
|
+
source=source,
|
|
177
|
+
subject_id=subject_id,
|
|
178
|
+
task=task,
|
|
179
|
+
session=session,
|
|
180
|
+
run=run,
|
|
181
|
+
line_freq=line_freq,
|
|
182
|
+
)
|
|
183
|
+
]
|
|
184
|
+
except (SubjectKeyError, MappingError, ValidationError) as exc:
|
|
185
|
+
_fail(str(exc))
|
|
186
|
+
|
|
187
|
+
context = _context(dataset)
|
|
188
|
+
typer.echo(f"run {context.run_id}", err=True)
|
|
189
|
+
failed = 0
|
|
190
|
+
for job in jobs:
|
|
191
|
+
try:
|
|
192
|
+
report = import_job(context, subject_key, job, overwrite=overwrite)
|
|
193
|
+
except ImportFailedError as exc:
|
|
194
|
+
failed += 1
|
|
195
|
+
typer.echo(f"FAILED {job.source}: {exc}", err=True)
|
|
196
|
+
continue
|
|
197
|
+
typer.echo(_import_line(report))
|
|
198
|
+
for text in report.deidentification.free_text_events:
|
|
199
|
+
typer.echo(f" check this event text by hand: {text!r}")
|
|
200
|
+
typer.echo(f"{len(jobs) - failed} of {len(jobs)} recordings imported into {dataset}")
|
|
201
|
+
if failed:
|
|
202
|
+
raise typer.Exit(code=1)
|
|
203
|
+
|
|
204
|
+
|
|
205
|
+
def _import_line(report: Any) -> str:
|
|
206
|
+
c = report.conversion
|
|
207
|
+
n = report.normalisation
|
|
208
|
+
line = f"line {c.line_freq:g} Hz ({c.line_freq_source})" if c.line_freq else "line n/a"
|
|
209
|
+
events = sum(n.events.values())
|
|
210
|
+
data_file = next((f for f in c.files if f.endswith((".vhdr", ".fif"))), c.files[0])
|
|
211
|
+
return (
|
|
212
|
+
f"OK {data_file} [{report.format}] {line}; positions: {n.positions}; {events} events"
|
|
213
|
+
)
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
@app.command("inspect")
|
|
217
|
+
def inspect_command(
|
|
218
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)] = Path("."),
|
|
219
|
+
as_json: Annotated[bool, typer.Option("--json", help="Print the full summary as JSON")] = False,
|
|
220
|
+
) -> None:
|
|
221
|
+
"""Summarise a BIDS dataset: subjects, tasks, and each recording's channels and events."""
|
|
222
|
+
summary: Any = registry.get("dataset.inspect").run({"max_recordings": 500}, _context(dataset))
|
|
223
|
+
if as_json:
|
|
224
|
+
typer.echo(summary.model_dump_json(indent=2))
|
|
225
|
+
return
|
|
226
|
+
typer.echo(f"{summary.name or 'Unnamed dataset'} (BIDS {summary.bids_version})")
|
|
227
|
+
typer.echo(
|
|
228
|
+
f"{summary.n_subjects} subjects, {summary.n_recordings} recordings, "
|
|
229
|
+
f"{summary.total_duration_s / 60:.1f} min; tasks: {', '.join(summary.tasks) or '-'}; "
|
|
230
|
+
f"sessions: {', '.join(summary.sessions) or '-'}"
|
|
231
|
+
)
|
|
232
|
+
for r in summary.recordings:
|
|
233
|
+
channels = ", ".join(f"{n} {t}" for t, n in sorted(r.channels.items()))
|
|
234
|
+
sfreq = f"{r.sampling_rate_hz:g} Hz" if r.sampling_rate_hz else "? Hz"
|
|
235
|
+
duration = f"{r.duration_s:.1f} s" if r.duration_s is not None else "? s"
|
|
236
|
+
bads = f"; {len(r.bad_channels)} bad" if r.bad_channels else ""
|
|
237
|
+
typer.echo(
|
|
238
|
+
f" {r.path} {sfreq}, {duration}; {channels}{bads}; {sum(r.events.values())} events"
|
|
239
|
+
)
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
@app.command("qc")
|
|
243
|
+
def qc_command(
|
|
244
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)] = Path("."),
|
|
245
|
+
subject: Annotated[
|
|
246
|
+
str | None, typer.Option("--subject", help="Subject label; omit to check every recording")
|
|
247
|
+
] = None,
|
|
248
|
+
task: Annotated[str | None, typer.Option("--task", help="Task label")] = None,
|
|
249
|
+
session: Annotated[str | None, typer.Option("--session", help="Session label")] = None,
|
|
250
|
+
run: Annotated[str | None, typer.Option("--run", help="Run number")] = None,
|
|
251
|
+
as_json: Annotated[bool, typer.Option("--json", help="Print the summaries as JSON")] = False,
|
|
252
|
+
) -> None:
|
|
253
|
+
"""Check data quality: flat and noisy channels, line noise, and time with large artifacts.
|
|
254
|
+
|
|
255
|
+
Changes nothing; per-channel tables are written to derivatives/braino/.
|
|
256
|
+
"""
|
|
257
|
+
from braino.io.dataset import scan_dataset
|
|
258
|
+
from braino.tools.eeg import RecordingNotFoundError
|
|
259
|
+
|
|
260
|
+
context = _context(dataset)
|
|
261
|
+
if subject is not None:
|
|
262
|
+
selectors = [{"subject": subject, "task": task, "session": session, "run": run}]
|
|
263
|
+
else:
|
|
264
|
+
selectors = [
|
|
265
|
+
{"subject": r.subject, "task": r.task, "session": r.session, "run": r.run}
|
|
266
|
+
for r in scan_dataset(context.dataset).recordings
|
|
267
|
+
if r.datatype in ("eeg", "ieeg", "meg")
|
|
268
|
+
]
|
|
269
|
+
qc = registry.get("eeg.qc_report")
|
|
270
|
+
results = []
|
|
271
|
+
for selector in selectors:
|
|
272
|
+
try:
|
|
273
|
+
result: Any = qc.run(selector, context)
|
|
274
|
+
except RecordingNotFoundError as exc:
|
|
275
|
+
_fail(str(exc))
|
|
276
|
+
results.append(result)
|
|
277
|
+
if not as_json:
|
|
278
|
+
typer.echo(_qc_line(result))
|
|
279
|
+
if as_json:
|
|
280
|
+
typer.echo(json.dumps([r.model_dump(mode="json") for r in results], indent=2))
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
def _qc_line(r: Any) -> str:
|
|
284
|
+
problems = []
|
|
285
|
+
if r.n_flat:
|
|
286
|
+
problems.append(f"{r.n_flat} flat ({', '.join(r.flat[:5])})")
|
|
287
|
+
if r.n_noisy:
|
|
288
|
+
problems.append(f"{r.n_noisy} noisy ({', '.join(n['channel'] for n in r.noisy[:5])})")
|
|
289
|
+
if r.n_strong_line_noise:
|
|
290
|
+
problems.append(f"strong line noise on {r.n_strong_line_noise}")
|
|
291
|
+
problems.append(f"{r.artifact_fraction:.0%} of time with large artifacts")
|
|
292
|
+
return f"{r.recording}: {r.n_channels_checked} channels; " + "; ".join(problems)
|
|
293
|
+
|
|
294
|
+
|
|
295
|
+
def _fail(message: str) -> NoReturn:
|
|
296
|
+
typer.echo(message, err=True)
|
|
297
|
+
raise typer.Exit(code=1)
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
@runs_app.command("list")
|
|
301
|
+
def runs_list(
|
|
302
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)],
|
|
303
|
+
) -> None:
|
|
304
|
+
"""List recorded runs, oldest first, with the tools each one called."""
|
|
305
|
+
root = _derivatives_root(dataset)
|
|
306
|
+
for run_id in list_runs(root):
|
|
307
|
+
calls = load_run(root, run_id).calls
|
|
308
|
+
failed = sum(call.status == "error" for call in calls)
|
|
309
|
+
tools = ", ".join(dict.fromkeys(call.tool for call in calls))
|
|
310
|
+
status = f"{len(calls)} calls" + (f", {failed} failed" if failed else "")
|
|
311
|
+
typer.echo(f"{run_id} {status:<20} {tools}")
|
|
312
|
+
|
|
313
|
+
|
|
314
|
+
@runs_app.command("show")
|
|
315
|
+
def runs_show(
|
|
316
|
+
run_id: Annotated[str, typer.Argument(help="Run ID, as printed by 'braino runs list'")],
|
|
317
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)],
|
|
318
|
+
) -> None:
|
|
319
|
+
"""Print the full provenance record of a run as JSON."""
|
|
320
|
+
try:
|
|
321
|
+
log = load_run(_derivatives_root(dataset), run_id)
|
|
322
|
+
except RunNotFoundError as exc:
|
|
323
|
+
typer.echo(str(exc), err=True)
|
|
324
|
+
raise typer.Exit(code=1) from None
|
|
325
|
+
typer.echo(log.model_dump_json(indent=2))
|
|
326
|
+
|
|
327
|
+
|
|
328
|
+
_OUTPUT_HELP = "Write the script here instead of printing it"
|
|
329
|
+
|
|
330
|
+
|
|
331
|
+
@runs_app.command("export")
|
|
332
|
+
def runs_export(
|
|
333
|
+
run_id: Annotated[str, typer.Argument(help="Run ID, as printed by 'braino runs list'")],
|
|
334
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)],
|
|
335
|
+
output: Annotated[Path | None, typer.Option("--output", "-o", help=_OUTPUT_HELP)] = None,
|
|
336
|
+
) -> None:
|
|
337
|
+
"""Export a run as a standalone Python script that re-runs it and checks its results."""
|
|
338
|
+
from braino.provenance.export import (
|
|
339
|
+
ExportError,
|
|
340
|
+
original_inputs,
|
|
341
|
+
render_script,
|
|
342
|
+
steps_from_run,
|
|
343
|
+
)
|
|
344
|
+
|
|
345
|
+
context = _context(dataset)
|
|
346
|
+
try:
|
|
347
|
+
steps, calls, environment = steps_from_run(
|
|
348
|
+
context.derivatives_root, run_id, context.proposals
|
|
349
|
+
)
|
|
350
|
+
except (RunNotFoundError, ExportError) as exc:
|
|
351
|
+
_fail(str(exc))
|
|
352
|
+
if not steps:
|
|
353
|
+
_fail(f"run {run_id} has no successful analysis steps to export")
|
|
354
|
+
script = render_script(
|
|
355
|
+
steps,
|
|
356
|
+
title=f"BrainO run {run_id}",
|
|
357
|
+
environment=environment,
|
|
358
|
+
inputs=original_inputs(calls),
|
|
359
|
+
)
|
|
360
|
+
_write_script(script, output)
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
def _write_script(script: str, output: Path | None) -> None:
|
|
364
|
+
if output is None:
|
|
365
|
+
typer.echo(script, nl=False)
|
|
366
|
+
return
|
|
367
|
+
output.write_text(script, encoding="utf-8")
|
|
368
|
+
typer.echo(f"wrote {output}", err=True)
|
|
369
|
+
|
|
370
|
+
|
|
371
|
+
@proposals_app.command("list")
|
|
372
|
+
def proposals_list(
|
|
373
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)],
|
|
374
|
+
pending: Annotated[bool, typer.Option("--pending", help="Only undecided proposals")] = False,
|
|
375
|
+
) -> None:
|
|
376
|
+
"""List proposals made by decision tools, oldest first."""
|
|
377
|
+
for record in _context(dataset).proposals.list():
|
|
378
|
+
if pending and record.status != "pending":
|
|
379
|
+
continue
|
|
380
|
+
typer.echo(f"{record.proposal_id} {record.status:<9} {record.tool}")
|
|
381
|
+
|
|
382
|
+
|
|
383
|
+
@proposals_app.command("show")
|
|
384
|
+
def proposals_show(
|
|
385
|
+
proposal_id: Annotated[str, typer.Argument(help="Proposal ID")],
|
|
386
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)],
|
|
387
|
+
) -> None:
|
|
388
|
+
"""Print a proposal and its decision, if any, as JSON."""
|
|
389
|
+
try:
|
|
390
|
+
record = _context(dataset).proposals.get(proposal_id)
|
|
391
|
+
except ProposalNotFoundError:
|
|
392
|
+
typer.echo(f"Unknown proposal: {proposal_id}", err=True)
|
|
393
|
+
raise typer.Exit(code=1) from None
|
|
394
|
+
typer.echo(record.model_dump_json(indent=2))
|
|
395
|
+
|
|
396
|
+
|
|
397
|
+
@proposals_app.command("approve")
|
|
398
|
+
def proposals_approve(
|
|
399
|
+
proposal_id: Annotated[str, typer.Argument(help="Proposal ID")],
|
|
400
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)],
|
|
401
|
+
edit: Annotated[
|
|
402
|
+
str | None,
|
|
403
|
+
typer.Option("--edit", help="JSON object of proposal fields to change before applying"),
|
|
404
|
+
] = None,
|
|
405
|
+
note: Annotated[str | None, typer.Option("--note", help="Reason for the decision")] = None,
|
|
406
|
+
) -> None:
|
|
407
|
+
"""Approve a proposal (optionally edited) and apply it."""
|
|
408
|
+
edits = _parse_json_object(edit, "--edit") if edit is not None else None
|
|
409
|
+
_decide(proposal_id, dataset, approve=True, edits=edits, note=note)
|
|
410
|
+
|
|
411
|
+
|
|
412
|
+
@proposals_app.command("reject")
|
|
413
|
+
def proposals_reject(
|
|
414
|
+
proposal_id: Annotated[str, typer.Argument(help="Proposal ID")],
|
|
415
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)],
|
|
416
|
+
note: Annotated[str | None, typer.Option("--note", help="Reason for the decision")] = None,
|
|
417
|
+
) -> None:
|
|
418
|
+
"""Reject a proposal; nothing is applied."""
|
|
419
|
+
_decide(proposal_id, dataset, approve=False, edits=None, note=note)
|
|
420
|
+
|
|
421
|
+
|
|
422
|
+
def _decide(
|
|
423
|
+
proposal_id: str,
|
|
424
|
+
dataset: Path,
|
|
425
|
+
*,
|
|
426
|
+
approve: bool,
|
|
427
|
+
edits: dict[str, Any] | None,
|
|
428
|
+
note: str | None,
|
|
429
|
+
) -> None:
|
|
430
|
+
context = _context(dataset)
|
|
431
|
+
try:
|
|
432
|
+
record = decide(
|
|
433
|
+
proposal_id,
|
|
434
|
+
context,
|
|
435
|
+
approve=approve,
|
|
436
|
+
decided_by=current_user(),
|
|
437
|
+
edits=edits,
|
|
438
|
+
note=note,
|
|
439
|
+
)
|
|
440
|
+
except ProposalNotFoundError:
|
|
441
|
+
typer.echo(f"Unknown proposal: {proposal_id}", err=True)
|
|
442
|
+
raise typer.Exit(code=1) from None
|
|
443
|
+
except (ProposalAlreadyDecidedError, ToolNotFoundError, ValidationError) as exc:
|
|
444
|
+
typer.echo(str(exc), err=True)
|
|
445
|
+
raise typer.Exit(code=1) from None
|
|
446
|
+
typer.echo(record.model_dump_json(indent=2))
|
|
447
|
+
|
|
448
|
+
|
|
449
|
+
# --- pipelines ----------------------------------------------------------------------------
|
|
450
|
+
|
|
451
|
+
pipeline_app = typer.Typer(
|
|
452
|
+
help="Run analyses declared as pipeline specs (YAML/JSON), with cached results.",
|
|
453
|
+
no_args_is_help=True,
|
|
454
|
+
)
|
|
455
|
+
app.add_typer(pipeline_app, name="pipeline")
|
|
456
|
+
|
|
457
|
+
_SPEC_HELP = "Spec file (.yaml/.json) or the name of a built-in spec"
|
|
458
|
+
WAITING_EXIT_CODE = 3
|
|
459
|
+
"""Exit code of ``braino pipeline run`` when it stopped at decisions waiting for a person."""
|
|
460
|
+
|
|
461
|
+
|
|
462
|
+
def _load_spec(source: str) -> Any:
|
|
463
|
+
from braino.pipelines import SpecError, load_spec
|
|
464
|
+
|
|
465
|
+
try:
|
|
466
|
+
return load_spec(source)
|
|
467
|
+
except (SpecError, OSError) as exc:
|
|
468
|
+
_fail(str(exc))
|
|
469
|
+
|
|
470
|
+
|
|
471
|
+
@pipeline_app.command("list")
|
|
472
|
+
def pipeline_list() -> None:
|
|
473
|
+
"""List the pipeline specs that come with BrainO."""
|
|
474
|
+
from braino.pipelines import builtin_specs, load_spec
|
|
475
|
+
|
|
476
|
+
for name, path in sorted(builtin_specs().items()):
|
|
477
|
+
typer.echo(f"{name:<24} {load_spec(path).description}")
|
|
478
|
+
|
|
479
|
+
|
|
480
|
+
@pipeline_app.command("show")
|
|
481
|
+
def pipeline_show(spec: Annotated[str, typer.Argument(help=_SPEC_HELP)]) -> None:
|
|
482
|
+
"""Print a spec (e.g. a built-in one, to copy and adapt)."""
|
|
483
|
+
from braino.pipelines import builtin_specs
|
|
484
|
+
|
|
485
|
+
path = builtin_specs().get(spec) or Path(spec)
|
|
486
|
+
if not path.is_file():
|
|
487
|
+
_fail(f"no spec {spec}")
|
|
488
|
+
_load_spec(str(path))
|
|
489
|
+
typer.echo(path.read_text(encoding="utf-8"), nl=False)
|
|
490
|
+
|
|
491
|
+
|
|
492
|
+
@pipeline_app.command("validate")
|
|
493
|
+
def pipeline_validate(spec: Annotated[str, typer.Argument(help=_SPEC_HELP)]) -> None:
|
|
494
|
+
"""Check a spec: its tools exist and accept the arguments given."""
|
|
495
|
+
loaded = _load_spec(spec)
|
|
496
|
+
typer.echo(
|
|
497
|
+
f"{loaded.name}: {len(loaded.steps)} steps per recording, {len(loaded.group)} group "
|
|
498
|
+
"steps; OK"
|
|
499
|
+
)
|
|
500
|
+
|
|
501
|
+
|
|
502
|
+
@pipeline_app.command("run")
|
|
503
|
+
def pipeline_run(
|
|
504
|
+
spec: Annotated[str, typer.Argument(help=_SPEC_HELP)],
|
|
505
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)] = Path("."),
|
|
506
|
+
subjects: Annotated[
|
|
507
|
+
str | None, typer.Option("--subjects", help="Comma-separated subset of the subjects")
|
|
508
|
+
] = None,
|
|
509
|
+
from_step: Annotated[
|
|
510
|
+
str | None, typer.Option("--from", help="Run this step and the ones after it again")
|
|
511
|
+
] = None,
|
|
512
|
+
auto_approve: Annotated[
|
|
513
|
+
bool,
|
|
514
|
+
typer.Option(
|
|
515
|
+
"--auto-approve",
|
|
516
|
+
help="Approve every proposal as made, in your name (e.g. for validation runs)",
|
|
517
|
+
),
|
|
518
|
+
] = False,
|
|
519
|
+
) -> None:
|
|
520
|
+
"""Run a pipeline over a dataset. Steps whose inputs and settings are unchanged are
|
|
521
|
+
skipped. Decision steps wait for your approval unless --auto-approve is given; approve
|
|
522
|
+
with 'braino proposals approve' and run again to continue."""
|
|
523
|
+
from braino.pipelines import SpecError, run_pipeline
|
|
524
|
+
|
|
525
|
+
loaded = _load_spec(spec)
|
|
526
|
+
context = _context(dataset)
|
|
527
|
+
typer.echo(f"run {context.run_id}", err=True)
|
|
528
|
+
approver = f"{current_user()} (auto-approved in a pipeline run)" if auto_approve else None
|
|
529
|
+
try:
|
|
530
|
+
report = run_pipeline(
|
|
531
|
+
loaded,
|
|
532
|
+
context,
|
|
533
|
+
subjects=subjects.split(",") if subjects else None,
|
|
534
|
+
from_step=from_step,
|
|
535
|
+
auto_approve=approver,
|
|
536
|
+
progress=lambda o: typer.echo(_outcome_line(o)),
|
|
537
|
+
)
|
|
538
|
+
except SpecError as exc:
|
|
539
|
+
_fail(str(exc))
|
|
540
|
+
counts = ", ".join(
|
|
541
|
+
f"{report.count(s)} {s}"
|
|
542
|
+
for s in ("ran", "cached", "pending", "rejected", "failed", "blocked")
|
|
543
|
+
if report.count(s)
|
|
544
|
+
)
|
|
545
|
+
typer.echo(f"{loaded.name}: {len(report.subjects)} subjects; steps {counts}")
|
|
546
|
+
if report.failed:
|
|
547
|
+
raise typer.Exit(code=1)
|
|
548
|
+
if report.pending:
|
|
549
|
+
typer.echo(
|
|
550
|
+
f"{len(report.pending)} decisions wait for you: braino proposals list --pending "
|
|
551
|
+
f"--dataset {dataset}",
|
|
552
|
+
err=True,
|
|
553
|
+
)
|
|
554
|
+
raise typer.Exit(code=WAITING_EXIT_CODE)
|
|
555
|
+
|
|
556
|
+
|
|
557
|
+
@pipeline_app.command("status")
|
|
558
|
+
def pipeline_status(
|
|
559
|
+
spec: Annotated[str, typer.Argument(help=_SPEC_HELP)],
|
|
560
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)] = Path("."),
|
|
561
|
+
) -> None:
|
|
562
|
+
"""Show, for each subject, which steps have a current result."""
|
|
563
|
+
from braino.pipelines import load_state
|
|
564
|
+
|
|
565
|
+
loaded = _load_spec(spec)
|
|
566
|
+
state = load_state(_context(dataset), loaded)
|
|
567
|
+
if not state.records:
|
|
568
|
+
typer.echo(f"{loaded.name} has not run on this dataset")
|
|
569
|
+
return
|
|
570
|
+
by_subject: dict[str, list[str]] = {}
|
|
571
|
+
for record in state.records.values():
|
|
572
|
+
mark = record.step
|
|
573
|
+
if record.proposal_id and record.apply is None:
|
|
574
|
+
mark += " (decision pending or rejected)"
|
|
575
|
+
by_subject.setdefault(record.subject, []).append(mark)
|
|
576
|
+
for subject, steps in sorted(by_subject.items()):
|
|
577
|
+
typer.echo(f"{subject:<8} {', '.join(steps)}")
|
|
578
|
+
|
|
579
|
+
|
|
580
|
+
@pipeline_app.command("export")
|
|
581
|
+
def pipeline_export(
|
|
582
|
+
spec: Annotated[str, typer.Argument(help=_SPEC_HELP)],
|
|
583
|
+
dataset: Annotated[Path, typer.Option("--dataset", help=_DATASET_HELP)] = Path("."),
|
|
584
|
+
output: Annotated[Path | None, typer.Option("--output", "-o", help=_OUTPUT_HELP)] = None,
|
|
585
|
+
) -> None:
|
|
586
|
+
"""Export a pipeline's current results as a standalone Python script that re-runs every
|
|
587
|
+
step (including steps reused from earlier runs) and checks the results."""
|
|
588
|
+
from braino.pipelines import load_state
|
|
589
|
+
from braino.provenance.export import (
|
|
590
|
+
ExportError,
|
|
591
|
+
original_inputs,
|
|
592
|
+
render_script,
|
|
593
|
+
steps_from_pipeline,
|
|
594
|
+
)
|
|
595
|
+
|
|
596
|
+
loaded = _load_spec(spec)
|
|
597
|
+
context = _context(dataset)
|
|
598
|
+
state = load_state(context, loaded)
|
|
599
|
+
try:
|
|
600
|
+
steps, calls, environment = steps_from_pipeline(
|
|
601
|
+
context.derivatives_root, state, loaded, context.proposals
|
|
602
|
+
)
|
|
603
|
+
except (RunNotFoundError, ExportError) as exc:
|
|
604
|
+
_fail(str(exc))
|
|
605
|
+
script = render_script(
|
|
606
|
+
steps,
|
|
607
|
+
title=f"BrainO pipeline {loaded.name}: {loaded.description}".rstrip(": "),
|
|
608
|
+
environment=environment,
|
|
609
|
+
inputs=original_inputs(calls),
|
|
610
|
+
)
|
|
611
|
+
_write_script(script, output)
|
|
612
|
+
|
|
613
|
+
|
|
614
|
+
def _outcome_line(outcome: Any) -> str:
|
|
615
|
+
where = outcome.subject if outcome.subject == "group" else f"sub-{outcome.subject}"
|
|
616
|
+
text = f"{where:<10} {outcome.step:<16} {outcome.status:<8}"
|
|
617
|
+
if outcome.message:
|
|
618
|
+
text += f" {outcome.message}"
|
|
619
|
+
return text
|
|
620
|
+
|
|
621
|
+
|
|
622
|
+
validate_app = typer.Typer(
|
|
623
|
+
help="Check BrainO's analyses against published results.", no_args_is_help=True
|
|
624
|
+
)
|
|
625
|
+
app.add_typer(validate_app, name="validate")
|
|
626
|
+
|
|
627
|
+
|
|
628
|
+
@validate_app.command("erpcore")
|
|
629
|
+
def validate_erpcore(
|
|
630
|
+
component: Annotated[str, typer.Argument(help="P3 or N170")],
|
|
631
|
+
subjects: Annotated[
|
|
632
|
+
str | None,
|
|
633
|
+
typer.Option("--subjects", help="Comma-separated participants, e.g. 001,002; default all"),
|
|
634
|
+
] = None,
|
|
635
|
+
as_json: Annotated[bool, typer.Option("--json", help="Print the full result as JSON")] = False,
|
|
636
|
+
) -> None:
|
|
637
|
+
"""Run the built-in ERP CORE pipeline and compare with the published scores.
|
|
638
|
+
|
|
639
|
+
Downloads the data on first use (P3 2.2 GB, N170 3.4 GB for all 40 participants) into
|
|
640
|
+
$BRAINO_DATA (default ~/.cache/braino). Decisions are auto-approved in your name.
|
|
641
|
+
"""
|
|
642
|
+
from braino.datasets.erpcore import DownloadError, references
|
|
643
|
+
from braino.validation.erpcore import run as run_validation
|
|
644
|
+
|
|
645
|
+
if component not in references():
|
|
646
|
+
_fail(f"unknown component {component!r}; choose from {', '.join(references())}")
|
|
647
|
+
try:
|
|
648
|
+
result = run_validation(
|
|
649
|
+
component,
|
|
650
|
+
subjects.split(",") if subjects else None,
|
|
651
|
+
progress=None if as_json else lambda o: typer.echo(_outcome_line(o), err=True),
|
|
652
|
+
)
|
|
653
|
+
except (DownloadError, OSError) as exc:
|
|
654
|
+
_fail(f"download failed ({exc}); run the command again to resume")
|
|
655
|
+
except ValueError as exc:
|
|
656
|
+
_fail(str(exc))
|
|
657
|
+
if as_json:
|
|
658
|
+
typer.echo(result.model_dump_json(indent=2))
|
|
659
|
+
return
|
|
660
|
+
for subject, reason in result.failed.items():
|
|
661
|
+
typer.echo(f"sub-{subject} failed at {reason}")
|
|
662
|
+
report = result.report
|
|
663
|
+
if report is None:
|
|
664
|
+
typer.echo("fewer than 3 participants scored; nothing to compare")
|
|
665
|
+
raise typer.Exit(code=1)
|
|
666
|
+
lo, hi = report.braino_ci95_uv
|
|
667
|
+
typer.echo(
|
|
668
|
+
f"{component}: BrainO {report.braino_mean_uv:+.2f} µV [95% CI {lo:+.2f}, {hi:+.2f}], "
|
|
669
|
+
f"n = {report.n_braino}; published {report.published_mean_uv:+.2f} µV"
|
|
670
|
+
)
|
|
671
|
+
if report.correlation is not None:
|
|
672
|
+
typer.echo(
|
|
673
|
+
f"participant level: r = {report.correlation:.3f} over {report.n_compared}, mean "
|
|
674
|
+
f"absolute difference {report.mean_abs_difference_uv:.2f} µV"
|
|
675
|
+
)
|
|
676
|
+
typer.echo(f"excluded (> 25% rejected): {', '.join(result.excluded) or 'none'}")
|
|
677
|
+
for check, ok in report.checks.items():
|
|
678
|
+
typer.echo(f" {'PASS' if ok else 'FAIL'} {check}")
|
|
679
|
+
typer.echo("REPRODUCED" if report.passed else "NOT REPRODUCED")
|
|
680
|
+
if not report.passed:
|
|
681
|
+
raise typer.Exit(code=1)
|