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.
Files changed (58) hide show
  1. braino/__init__.py +3 -0
  2. braino/cli.py +681 -0
  3. braino/context.py +132 -0
  4. braino/datasets/__init__.py +1 -0
  5. braino/datasets/_build_erpcore_manifest.py +97 -0
  6. braino/datasets/erpcore.py +144 -0
  7. braino/datasets/erpcore_manifest.json +4424 -0
  8. braino/datasets/erpcore_references.json +133 -0
  9. braino/eeg/__init__.py +8 -0
  10. braino/eeg/_quiet.py +26 -0
  11. braino/eeg/bad_channels.py +235 -0
  12. braino/eeg/epochs.py +243 -0
  13. braino/eeg/erp.py +130 -0
  14. braino/eeg/ica.py +205 -0
  15. braino/eeg/preprocess.py +234 -0
  16. braino/eeg/qc.py +255 -0
  17. braino/eeg/spectral.py +164 -0
  18. braino/eeg/tfr.py +153 -0
  19. braino/io/__init__.py +61 -0
  20. braino/io/batch.py +145 -0
  21. braino/io/bids.py +286 -0
  22. braino/io/dataset.py +128 -0
  23. braino/io/deidentify.py +290 -0
  24. braino/io/formats.py +358 -0
  25. braino/io/importer.py +121 -0
  26. braino/io/normalise.py +336 -0
  27. braino/io/readers.py +154 -0
  28. braino/pipelines/__init__.py +39 -0
  29. braino/pipelines/runner.py +456 -0
  30. braino/pipelines/spec.py +203 -0
  31. braino/pipelines/specs/erpcore-n170.yaml +48 -0
  32. braino/pipelines/specs/erpcore-p3.yaml +40 -0
  33. braino/provenance/__init__.py +28 -0
  34. braino/provenance/export.py +270 -0
  35. braino/provenance/models.py +87 -0
  36. braino/provenance/proposals.py +74 -0
  37. braino/provenance/recorder.py +209 -0
  38. braino/provenance/replay.py +203 -0
  39. braino/provenance/store.py +49 -0
  40. braino/py.typed +0 -0
  41. braino/stats/__init__.py +4 -0
  42. braino/stats/group.py +322 -0
  43. braino/tools/__init__.py +38 -0
  44. braino/tools/base.py +264 -0
  45. braino/tools/dataset.py +24 -0
  46. braino/tools/decisions.py +74 -0
  47. braino/tools/eeg.py +600 -0
  48. braino/tools/eeg_measures.py +360 -0
  49. braino/tools/recordings.py +272 -0
  50. braino/tools/registry.py +67 -0
  51. braino/tools/stats.py +392 -0
  52. braino/tools/system.py +32 -0
  53. braino/validation/__init__.py +1 -0
  54. braino/validation/erpcore.py +196 -0
  55. braino-0.1.0.dist-info/METADATA +316 -0
  56. braino-0.1.0.dist-info/RECORD +58 -0
  57. braino-0.1.0.dist-info/WHEEL +4 -0
  58. braino-0.1.0.dist-info/entry_points.txt +2 -0
braino/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """BrainO analysis engine."""
2
+
3
+ __version__ = "0.1.0"
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)