daftar 0.3.3__tar.gz → 0.4.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 (42) hide show
  1. {daftar-0.3.3 → daftar-0.4.0}/CHANGELOG.md +50 -0
  2. {daftar-0.3.3 → daftar-0.4.0}/INSTALL.md +7 -4
  3. {daftar-0.3.3/src/daftar.egg-info → daftar-0.4.0}/PKG-INFO +15 -4
  4. {daftar-0.3.3 → daftar-0.4.0}/README.md +11 -3
  5. {daftar-0.3.3 → daftar-0.4.0}/ROADMAP.md +11 -16
  6. {daftar-0.3.3 → daftar-0.4.0}/TESTING.md +13 -5
  7. {daftar-0.3.3 → daftar-0.4.0}/examples/adapter_usage.py +44 -1
  8. {daftar-0.3.3 → daftar-0.4.0}/pyproject.toml +3 -2
  9. daftar-0.4.0/src/daftar/__version__.py +1 -0
  10. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/adapters/__init__.py +7 -2
  11. daftar-0.4.0/src/daftar/adapters/mne_adapter.py +372 -0
  12. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/capture.py +2 -1
  13. {daftar-0.3.3 → daftar-0.4.0/src/daftar.egg-info}/PKG-INFO +15 -4
  14. {daftar-0.3.3 → daftar-0.4.0}/src/daftar.egg-info/SOURCES.txt +1 -0
  15. {daftar-0.3.3 → daftar-0.4.0}/src/daftar.egg-info/requires.txt +4 -0
  16. {daftar-0.3.3 → daftar-0.4.0}/tests/test_adapters_live.py +184 -0
  17. {daftar-0.3.3 → daftar-0.4.0}/tests/test_core.py +1 -1
  18. daftar-0.3.3/src/daftar/__version__.py +0 -1
  19. {daftar-0.3.3 → daftar-0.4.0}/LICENSE +0 -0
  20. {daftar-0.3.3 → daftar-0.4.0}/MANIFEST.in +0 -0
  21. {daftar-0.3.3 → daftar-0.4.0}/PUBLISHING.md +0 -0
  22. {daftar-0.3.3 → daftar-0.4.0}/TROUBLESHOOTING.md +0 -0
  23. {daftar-0.3.3 → daftar-0.4.0}/examples/daftar_in_notebooks.ipynb +0 -0
  24. {daftar-0.3.3 → daftar-0.4.0}/examples/demo_end_to_end.py +0 -0
  25. {daftar-0.3.3 → daftar-0.4.0}/setup.cfg +0 -0
  26. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/__init__.py +0 -0
  27. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/adapters/base.py +0 -0
  28. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/adapters/brian2_adapter.py +0 -0
  29. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/adapters/cpm_adapter.py +0 -0
  30. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/adapters/jaxley_adapter.py +0 -0
  31. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/adapters/meltingpot_adapter.py +0 -0
  32. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/cli.py +0 -0
  33. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/diff.py +0 -0
  34. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/manifest.py +0 -0
  35. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/notebook.py +0 -0
  36. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/run.py +0 -0
  37. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/store.py +0 -0
  38. {daftar-0.3.3 → daftar-0.4.0}/src/daftar/sweep.py +0 -0
  39. {daftar-0.3.3 → daftar-0.4.0}/src/daftar.egg-info/dependency_links.txt +0 -0
  40. {daftar-0.3.3 → daftar-0.4.0}/src/daftar.egg-info/entry_points.txt +0 -0
  41. {daftar-0.3.3 → daftar-0.4.0}/src/daftar.egg-info/top_level.txt +0 -0
  42. {daftar-0.3.3 → daftar-0.4.0}/tests/test_notebook.py +0 -0
@@ -1,5 +1,55 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.0 — MNE-Python
4
+
5
+ MNE preprocessing is largely a sequence of **human decisions that are never
6
+ written down**. Which channels you marked bad, which ICA components you excluded
7
+ after looking at topographies, which epochs were dropped and why: each changes
8
+ every downstream number, and each typically survives only in the analyst's
9
+ memory.
10
+
11
+ **`ica.exclude` is the headline.** It is the most consequential unrecorded
12
+ decision in EEG/MEG analysis. A reviewer asking "which components did you
13
+ remove?" is usually asking a question with no surviving answer six months later.
14
+ The adapter records the exclusion list, the count, and the decomposition it
15
+ indexes into.
16
+
17
+ **Whether ICA converged.** `n_iter_ == max_iter` means FastICA hit the iteration
18
+ limit and stopped, not that it finished. MNE warns at fit time and stores
19
+ nothing you would notice afterwards. Recorded as `result.ica.converged`.
20
+
21
+ **`random_state=None` is flagged loudly.** ICA without a seed is not
22
+ reproducible, and neither are the component indices the exclusions refer to.
23
+ The manifest records `none (NOT REPRODUCIBLE)` rather than a bare `None`.
24
+
25
+ **Filter design, not just the band.** `raw.filter()` updates `info["highpass"]`
26
+ and `info["lowpass"]` and then discards `fir_design`, `phase`, `window` and the
27
+ transition bandwidths. A zero-phase FIR with a wide transition band and a causal
28
+ IIR are different filters, and "1–40 Hz" in a methods section does not
29
+ distinguish them. `filter_raw()` records the design and flags which values were
30
+ MNE defaults you never passed.
31
+
32
+ **`epochs.drop_log`.** How many epochs were rejected and for what reason. An
33
+ evoked average over 40 surviving epochs is a different quantity from one over
34
+ 180, and the average alone does not say which you have.
35
+
36
+ ### On subject data
37
+
38
+ This adapter runs against human neuroimaging recordings, so it records structure
39
+ and never content. `subject_info` and file paths are **hashed, not stored**, and
40
+ `meas_date` is recorded only as present or absent, because dates of service are
41
+ themselves identifiers. Manifests get committed to public repositories; nothing
42
+ the adapter writes should make that a mistake.
43
+
44
+ This is also why an MNE adapter is possible at all. The original feasibility
45
+ plan deferred fMRI/EEG because human neuroimaging is health data — but that risk
46
+ lived in *hosting* it. daftar is local, offline, and never transmits anything, so
47
+ an adapter can record provenance about an analysis without touching a subject's
48
+ recordings.
49
+
50
+ Six live tests against real MNE objects. MNE requires only `scipy>=1.13`, so it
51
+ shares an environment with cpm's `scipy<1.18` pin.
52
+
3
53
  ## 0.3.3 — documentation and cleanup
4
54
 
5
55
  No behaviour changes. The four adapters, notebook support and the CLI are all
@@ -23,7 +23,7 @@ daftar doctor
23
23
  Here the honest answer is more complicated than a single command, and it is
24
24
  worth understanding why before you start.
25
25
 
26
- **The four target frameworks cannot currently share one environment.** Each pins
26
+ **The five target frameworks cannot currently share one environment.** Each pins
27
27
  its dependencies loosely, and their dependencies remove APIs on schedules the
28
28
  frameworks do not track. As of this writing:
29
29
 
@@ -33,6 +33,7 @@ frameworks do not track. As of this writing:
33
33
  | cpm-toolbox 0.25.6 | needs **scipy < 1.18** | passes `disp=` to `fmin_l_bfgs_b`, removed in SciPy 1.18.0 |
34
34
  | dm-meltingpot | needs **dmlab2d**, narrow wheel coverage | weakest on macOS arm64; often needs Python 3.11 or a source build |
35
35
  | jaxley ≥ 0.14 | fine on current JAX | 0.13.0 was broken; upgrade rather than pin |
36
+ | mne ≥ 1.12 | `scipy >= 1.13`, Python ≥ 3.10 | compatible with cpm's `scipy<1.18` pin, so they share an environment |
36
37
 
37
38
  This is not anyone's fault and it is not unusual. It is the normal condition of
38
39
  a scientific Python environment, and it is a large part of why daftar records
@@ -41,15 +42,15 @@ a scientific Python environment, and it is a large part of why daftar records
41
42
  **Do not try to force all four into one environment.** Use two, and let the test
42
43
  suite skip whatever is absent in each — both suites go green.
43
44
 
44
- ### Environment A — brian2, jaxley, cpm (Python 3.12)
45
+ ### Environment A — brian2, jaxley, cpm, mne (Python 3.12)
45
46
 
46
47
  ```bash
47
48
  conda create --name daftar312 python=3.12
48
49
  conda activate daftar312
49
50
 
50
51
  pip install daftar
51
- pip install brian2 jaxley cpm-toolbox
52
- pip install "scipy<1.18" # required by cpm-toolbox 0.25.6
52
+ pip install brian2 jaxley cpm-toolbox mne
53
+ pip install "scipy<1.18" # required by cpm-toolbox 0.25.6; mne is fine with it
53
54
  pip install pytest ipython # for the test suite and notebook support
54
55
 
55
56
  daftar doctor
@@ -65,6 +66,7 @@ python 3.12.14 on Darwin arm64
65
66
  cpm ok
66
67
  jaxley ok
67
68
  meltingpot - not installed
69
+ mne ok
68
70
  ```
69
71
 
70
72
  ### Environment B — meltingpot (Python 3.11)
@@ -104,6 +106,7 @@ The extras exist for convenience, but read the constraints above before using
104
106
  pip install "daftar[jaxley]"
105
107
  pip install "daftar[cpm]"
106
108
  pip install "daftar[brian2]"
109
+ pip install "daftar[mne]"
107
110
  pip install "daftar[meltingpot]"
108
111
  pip install "daftar[all]" # will not resolve cleanly on one interpreter
109
112
  pip install "daftar[dev]" # pytest, numpy, ipython
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: daftar
3
- Version: 0.3.3
3
+ Version: 0.4.0
4
4
  Summary: Record what produced each computational result: environment, code, parameters, seeds, inputs.
5
5
  Author: Aslan Satary Dizaji
6
6
  License-Expression: Apache-2.0
@@ -23,6 +23,8 @@ Provides-Extra: meltingpot
23
23
  Requires-Dist: dm-meltingpot; extra == "meltingpot"
24
24
  Provides-Extra: brian2
25
25
  Requires-Dist: brian2; extra == "brian2"
26
+ Provides-Extra: mne
27
+ Requires-Dist: mne; extra == "mne"
26
28
  Provides-Extra: dev
27
29
  Requires-Dist: pytest>=7; extra == "dev"
28
30
  Requires-Dist: numpy; extra == "dev"
@@ -34,6 +36,7 @@ Requires-Dist: jaxley; extra == "all"
34
36
  Requires-Dist: cpm-toolbox; extra == "all"
35
37
  Requires-Dist: dm-meltingpot; extra == "all"
36
38
  Requires-Dist: brian2; extra == "all"
39
+ Requires-Dist: mne; extra == "all"
37
40
  Dynamic: license-file
38
41
 
39
42
  # daftar
@@ -47,8 +50,8 @@ past run can be rebuilt.
47
50
 
48
51
  Experiment trackers solved this for deep learning, where an experiment is
49
52
  `model.fit()`. They do not help when the experiment is a Hodgkin–Huxley
50
- simulation of 302 neurons, a hierarchical fit across 60 participants, a spiking
51
- network, or a 200-episode multi-agent sweep. Those runs have no epochs, no loss
53
+ simulation of 302 neurons, a hierarchical fit across 60 participants, an EEG
54
+ preprocessing pipeline, or a 200-episode multi-agent sweep. Those runs have no epochs, no loss
52
55
  curves, and no checkpoints. They have parameter grids, solver tolerances, random
53
56
  seeds, and derived quantities.
54
57
 
@@ -315,6 +318,7 @@ knowing something a generic tracker cannot infer.
315
318
  | `jaxley` | morphology (compartments, branches, channels, synapses), `jx.integrate` defaults you never passed, `jax_enable_x64`, backend |
316
319
  | `cpm` | parameter **bounds and priors** (resolved to the scipy distribution and its arguments), estimator and its scipy settings, restart counts and the initial guesses themselves, per-participant convergence, cohort hash |
317
320
  | `brian2` | **the integration method Brian2 actually chose** — its default is a candidate list and the winner is stored nowhere — plus resolved `codegen.target`, network schedule, equation hashes, realised synapse counts |
321
+ | `mne` | **which ICA components were excluded** and whether ICA converged, filter *design* rather than just the band, bad channels, epoch drop counts and reasons — with subject data hashed, never stored |
318
322
  | `meltingpot` | resolved substrate ConfigDict hash, roles, episode-length cap, pinned bot checkpoints, per-player returns and Gini |
319
323
 
320
324
  ```python
@@ -324,12 +328,19 @@ with daftar.track("balanced-net", seed=42) as run:
324
328
  b2a.run_network(net, 1*second, run)
325
329
  ```
326
330
 
331
+ The MNE adapter deserves a note on privacy: it runs against human neuroimaging
332
+ recordings, so it records structure and never content. `subject_info` and file
333
+ paths are hashed rather than stored, and `meas_date` is recorded only as present
334
+ or absent, because dates of service are themselves identifiers. Manifests get
335
+ committed to public repositories; nothing the adapter writes should make that a
336
+ mistake.
337
+
327
338
  Adapters never import their framework at module load, so `import daftar` works
328
339
  with none of them installed. Every probe is best-effort: a provenance tool that
329
340
  crashes a four-hour simulation because a framework renamed an attribute has done
330
341
  far more harm than the missing field was worth.
331
342
 
332
- All four are verified against live installs by `tests/test_adapters_live.py`.
343
+ All five are verified against live installs by `tests/test_adapters_live.py`.
333
344
  See `examples/adapter_usage.py` for the pattern for each, and
334
345
  [INSTALL.md](INSTALL.md) for which environment each needs — they do not all fit
335
346
  in one.
@@ -9,8 +9,8 @@ past run can be rebuilt.
9
9
 
10
10
  Experiment trackers solved this for deep learning, where an experiment is
11
11
  `model.fit()`. They do not help when the experiment is a Hodgkin–Huxley
12
- simulation of 302 neurons, a hierarchical fit across 60 participants, a spiking
13
- network, or a 200-episode multi-agent sweep. Those runs have no epochs, no loss
12
+ simulation of 302 neurons, a hierarchical fit across 60 participants, an EEG
13
+ preprocessing pipeline, or a 200-episode multi-agent sweep. Those runs have no epochs, no loss
14
14
  curves, and no checkpoints. They have parameter grids, solver tolerances, random
15
15
  seeds, and derived quantities.
16
16
 
@@ -277,6 +277,7 @@ knowing something a generic tracker cannot infer.
277
277
  | `jaxley` | morphology (compartments, branches, channels, synapses), `jx.integrate` defaults you never passed, `jax_enable_x64`, backend |
278
278
  | `cpm` | parameter **bounds and priors** (resolved to the scipy distribution and its arguments), estimator and its scipy settings, restart counts and the initial guesses themselves, per-participant convergence, cohort hash |
279
279
  | `brian2` | **the integration method Brian2 actually chose** — its default is a candidate list and the winner is stored nowhere — plus resolved `codegen.target`, network schedule, equation hashes, realised synapse counts |
280
+ | `mne` | **which ICA components were excluded** and whether ICA converged, filter *design* rather than just the band, bad channels, epoch drop counts and reasons — with subject data hashed, never stored |
280
281
  | `meltingpot` | resolved substrate ConfigDict hash, roles, episode-length cap, pinned bot checkpoints, per-player returns and Gini |
281
282
 
282
283
  ```python
@@ -286,12 +287,19 @@ with daftar.track("balanced-net", seed=42) as run:
286
287
  b2a.run_network(net, 1*second, run)
287
288
  ```
288
289
 
290
+ The MNE adapter deserves a note on privacy: it runs against human neuroimaging
291
+ recordings, so it records structure and never content. `subject_info` and file
292
+ paths are hashed rather than stored, and `meas_date` is recorded only as present
293
+ or absent, because dates of service are themselves identifiers. Manifests get
294
+ committed to public repositories; nothing the adapter writes should make that a
295
+ mistake.
296
+
289
297
  Adapters never import their framework at module load, so `import daftar` works
290
298
  with none of them installed. Every probe is best-effort: a provenance tool that
291
299
  crashes a four-hour simulation because a framework renamed an attribute has done
292
300
  far more harm than the missing field was worth.
293
301
 
294
- All four are verified against live installs by `tests/test_adapters_live.py`.
302
+ All five are verified against live installs by `tests/test_adapters_live.py`.
295
303
  See `examples/adapter_usage.py` for the pattern for each, and
296
304
  [INSTALL.md](INSTALL.md) for which environment each needs — they do not all fit
297
305
  in one.
@@ -2,8 +2,8 @@
2
2
 
3
3
  ## Where this stands
4
4
 
5
- Four adapters, all verified against live installed frameworks. Notebook and
6
- Colab support. 0.3.3 on PyPI, zero runtime dependencies, Apache 2.0.
5
+ Five adapters, all verified against live installed frameworks. Notebook and
6
+ Colab support. 0.4.0 on PyPI, zero runtime dependencies, Apache 2.0.
7
7
 
8
8
  | | Status |
9
9
  |---|---|
@@ -12,13 +12,14 @@ Colab support. 0.3.3 on PyPI, zero runtime dependencies, Apache 2.0.
12
12
  | cpm adapter | verified live |
13
13
  | MeltingPot adapter | verified live |
14
14
  | Brian2 adapter | verified live |
15
+ | MNE-Python adapter | verified live |
15
16
  | Notebook / Colab (`%%daftar`, cell + session hashing) | shipped |
16
17
  | `daftar doctor` | shipped |
17
18
 
18
19
  ```
19
20
  tests/test_core.py 44 passed
20
21
  tests/test_notebook.py 15 passed
21
- tests/test_adapters_live.py 11 (skip whatever is absent)
22
+ tests/test_adapters_live.py 17 (skip whatever is absent)
22
23
  ```
23
24
 
24
25
  The initial version is done. Everything below is about what comes next, and the
@@ -33,7 +34,7 @@ what it does not say: number of adapters. Adapter count is a vanity metric — i
33
34
  is legible, it feels like progress, and it is almost entirely decoupled from
34
35
  whether anyone uses the thing.
35
36
 
36
- Four adapters with zero users and eight adapters with zero users are the same
37
+ Five adapters with zero users and ten adapters with zero users are the same
37
38
  outcome. One adapter with fifteen users who would complain if it disappeared is
38
39
  a different category of thing.
39
40
 
@@ -82,7 +83,7 @@ An adapter is worth writing only if all five hold:
82
83
  eLife, SNUFA, Neuromatch and Mathematics of Neuroscience. An adapter you
83
84
  cannot distribute is a hobby.
84
85
  4. **The framework is stable enough not to rot.** Every adapter is a maintenance
85
- liability against someone else's release schedule — and three of the four
86
+ liability against someone else's release schedule — and three of the five
86
87
  existing ones have already broken against a dependency.
87
88
  5. **It stays inside the envelope.** Unregulated, non-dual-use, Python, runs on
88
89
  a laptop.
@@ -115,18 +116,12 @@ Harder than Brian2 — hoc, C++, and a much older API surface.
115
116
 
116
117
  ### Tier 2
117
118
 
118
- **3. MNE-Python** — EEG/MEG analysis.
119
+ **3. FieldTrip / EEGLAB interop** — reading what other toolboxes produced.
119
120
 
120
- Much larger user base than Jaxley, cpm and Brian2 combined, and preprocessing is
121
- a notorious provenance disaster: filter settings, montage, re-referencing, and
122
- above all **manually rejected ICA components**, a human decision that usually
123
- exists only in someone's memory.
124
-
125
- The original feasibility plan deferred fMRI/EEG because human neuroimaging is
126
- health data. That objection largely dissolves under the current architecture:
127
- daftar is local, offline, and never transmits data, so an adapter records
128
- provenance about an analysis without touching a subject's recordings. The
129
- regulatory risk lived in hosting, and there is no hosting.
121
+ Much of the EEG world is still MATLAB. daftar cannot instrument EEGLAB, but it
122
+ can record the provenance of data *imported* from it: which `.set` file, which
123
+ preprocessing was already applied before Python saw it. Lower value than a
124
+ native adapter and much cheaper to build.
130
125
 
131
126
  ### Tier 3
132
127
 
@@ -7,9 +7,17 @@ pip install -e ".[dev]"
7
7
  pytest -q
8
8
  ```
9
9
 
10
- Expect **64 passed, 6 skipped** with no frameworks installed. The six skips are
11
- the live adapter tests, which need their frameworks. Nothing else should ever
12
- skip.
10
+ What you should see depends on which frameworks are installed:
11
+
12
+ | Environment | Result |
13
+ |---|---|
14
+ | daftar only | **60 passed, 16 skipped** — the core and notebook suites, plus the adapter status report which always runs |
15
+ | Environment A (brian2, jaxley, cpm, mne) | **74 passed, 2 skipped** — only MeltingPot missing |
16
+ | Environment B (meltingpot) | **62 passed, 14 skipped** |
17
+
18
+ **The core and notebook suites must always pass — 59 tests, no exceptions.**
19
+ Every skip should be a live adapter test whose framework is absent. If anything
20
+ in `test_core.py` or `test_notebook.py` skips, something is wrong.
13
21
 
14
22
  ---
15
23
 
@@ -19,7 +27,7 @@ skip.
19
27
  |---|---|---|---|
20
28
  | `tests/test_core.py` | 44 | nothing | manifests, capture, diff verdicts, sweeps, replay, export, store |
21
29
  | `tests/test_notebook.py` | 15 | `ipython` | cell hashing, session history, the `%%daftar` magic |
22
- | `tests/test_adapters_live.py` | 11 | the frameworks | real workloads through each adapter |
30
+ | `tests/test_adapters_live.py` | 17 | the frameworks | real workloads through each adapter |
23
31
 
24
32
  The core and notebook suites must always pass. They have no optional
25
33
  dependencies beyond IPython and they are fast.
@@ -32,7 +40,7 @@ These are separated because they need heavy optional dependencies and are slow.
32
40
  They are also the **only** tests that can catch adapter rot.
33
41
 
34
42
  ```bash
35
- # Environment A: brian2, jaxley, cpm
43
+ # Environment A: brian2, jaxley, cpm, mne
36
44
  conda activate daftar312
37
45
  pytest tests/test_adapters_live.py -v
38
46
 
@@ -99,6 +99,49 @@ with daftar.track("balanced-net", seed=42) as run:
99
99
  # different graph every run.
100
100
  '''
101
101
 
102
+ # ------------------------------------------------------------------- MNE ---
103
+ MNE = '''
104
+ import mne
105
+ import daftar
106
+ from daftar.adapters import mne as mnea
107
+
108
+ raw = mne.io.read_raw_fif("sub-01_raw.fif", preload=True)
109
+ raw.info["bads"] = ["EEG 053"]
110
+
111
+ with daftar.track("preproc", seed=42) as run:
112
+ mnea.describe_environment(run)
113
+ mnea.filter_raw(raw, run, l_freq=1.0, h_freq=40.0)
114
+
115
+ ica = mne.preprocessing.ICA(n_components=20, random_state=97)
116
+ ica.fit(raw)
117
+ ica.exclude = [0, 3] # <- the decision nothing else records
118
+ mnea.apply_ica(ica, raw, run)
119
+
120
+ epochs = mne.Epochs(raw, events, tmin=-0.2, tmax=0.5,
121
+ reject=dict(eeg=150e-6), preload=True)
122
+ mnea.describe_epochs(epochs, run)
123
+ mnea.describe_evoked(epochs.average(), run)
124
+
125
+ # Recorded automatically:
126
+ # ica.exclude = [0, 3] <- the human decision, otherwise unrecorded
127
+ # ica.n_excluded = 2
128
+ # ica.random_state = 97 <- None would read "none (NOT REPRODUCIBLE)"
129
+ # result.ica.converged <- n_iter_ == max_iter means it stopped, not finished
130
+ # filter.phase = zero filter.phase.was_default = true
131
+ # filter.fir_design, .l_trans_bandwidth, .h_trans_bandwidth
132
+ # recording.bads, .n_bads <- another human judgement
133
+ # result.epochs.n_epochs_dropped, .drop_rate, .drop_reasons
134
+ #
135
+ # ica.exclude is the point. A reviewer asking "which components did you remove?"
136
+ # is usually asking a question with no surviving answer. raw.filter() is the
137
+ # same shape of problem: info["highpass"]/["lowpass"] survive, the design that
138
+ # produced them does not.
139
+ #
140
+ # On privacy: subject_info and file paths are hashed, never stored, and
141
+ # meas_date is recorded only as present/absent. Dates of service are
142
+ # identifiers, and manifests get committed to public repositories.
143
+ '''
144
+
102
145
  # ------------------------------------------------------------ MeltingPot ---
103
146
  MELTINGPOT = '''
104
147
  import daftar
@@ -156,7 +199,7 @@ def main():
156
199
 
157
200
  print("\nReference usage:")
158
201
  for title, snippet in (
159
- ("Jaxley", JAXLEY), ("cpm", CPM), ("Brian2", BRIAN2),
202
+ ("Jaxley", JAXLEY), ("cpm", CPM), ("Brian2", BRIAN2), ("MNE-Python", MNE),
160
203
  ("MeltingPot", MELTINGPOT),
161
204
  ):
162
205
  print(f"\n{'-' * 70}\n{title}\n{'-' * 70}{snippet}")
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "daftar"
7
- version = "0.3.3"
7
+ version = "0.4.0"
8
8
  description = "Record what produced each computational result: environment, code, parameters, seeds, inputs."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -30,9 +30,10 @@ jaxley = ["jaxley"]
30
30
  cpm = ["cpm-toolbox"]
31
31
  meltingpot = ["dm-meltingpot"]
32
32
  brian2 = ["brian2"]
33
+ mne = ["mne"]
33
34
  dev = ["pytest>=7", "numpy", "ipython"]
34
35
  notebook = ["ipython"]
35
- all = ["jaxley", "cpm-toolbox", "dm-meltingpot", "brian2"]
36
+ all = ["jaxley", "cpm-toolbox", "dm-meltingpot", "brian2", "mne"]
36
37
 
37
38
  [project.scripts]
38
39
  daftar = "daftar.cli:main"
@@ -0,0 +1 @@
1
+ __version__ = "0.4.0"
@@ -7,7 +7,9 @@ at module load.
7
7
 
8
8
  from __future__ import annotations
9
9
 
10
- from . import brian2_adapter, cpm_adapter, jaxley_adapter, meltingpot_adapter
10
+ from . import (
11
+ brian2_adapter, cpm_adapter, jaxley_adapter, meltingpot_adapter, mne_adapter,
12
+ )
11
13
  from .base import (
12
14
  AVAILABLE, BROKEN, MISSING, Adapter, AdapterRegistry, probe_import,
13
15
  record_optional, safe,
@@ -18,11 +20,13 @@ registry.register("jaxley", jaxley_adapter)
18
20
  registry.register("cpm", cpm_adapter)
19
21
  registry.register("meltingpot", meltingpot_adapter)
20
22
  registry.register("brian2", brian2_adapter)
23
+ registry.register("mne", mne_adapter)
21
24
 
22
25
  jaxley = jaxley_adapter
23
26
  cpm = cpm_adapter
24
27
  meltingpot = meltingpot_adapter
25
28
  brian2 = brian2_adapter
29
+ mne = mne_adapter
26
30
 
27
31
 
28
32
  def available() -> list[str]:
@@ -54,8 +58,9 @@ def get(name: str):
54
58
 
55
59
  __all__ = [
56
60
  "registry", "available", "get",
57
- "jaxley", "cpm", "meltingpot", "brian2",
61
+ "jaxley", "cpm", "meltingpot", "brian2", "mne",
58
62
  "jaxley_adapter", "cpm_adapter", "meltingpot_adapter", "brian2_adapter",
63
+ "mne_adapter",
59
64
  "Adapter", "AdapterRegistry", "safe", "record_optional",
60
65
  "status", "probe_import", "AVAILABLE", "MISSING", "BROKEN",
61
66
  ]
@@ -0,0 +1,372 @@
1
+ """MNE-Python adapter.
2
+
3
+ MNE preprocessing is largely a sequence of **human decisions that are never
4
+ written down**. Which channels you marked bad, which ICA components you excluded
5
+ after looking at the topographies, which epochs were dropped and why: each one
6
+ changes every downstream number, and each one typically survives only in the
7
+ analyst's memory and a `.fif` file.
8
+
9
+ What this records that a generic tracker cannot:
10
+
11
+ * **`ica.exclude`.** The single most consequential unrecorded decision in EEG/MEG
12
+ analysis. A reviewer asking "which components did you remove?" is asking a
13
+ question that usually has no answer six months later.
14
+ * **Whether ICA converged.** `n_iter_ == max_iter` means FastICA hit the
15
+ iteration limit and stopped, not that it finished. MNE reports this as a
16
+ warning at fit time and stores nothing you would notice afterwards.
17
+ * **`random_state=None`.** ICA without a seed is not reproducible, and the
18
+ resulting components -- and therefore the exclusions -- differ between runs.
19
+ * **Filter design parameters.** `raw.filter()` updates `info['highpass']` and
20
+ `info['lowpass']` and then discards `fir_design`, `phase`, `window` and the
21
+ transition bandwidths. Two analyses filtered "1--40 Hz" can differ
22
+ substantially. :func:`filter_raw` records them.
23
+ * **`epochs.drop_log`.** How many epochs were rejected and for what reason. An
24
+ evoked average over 40 surviving epochs is a different quantity from one over
25
+ 180, and the average alone does not say which you have.
26
+
27
+ **On subject data.** This adapter runs against human neuroimaging recordings, so
28
+ it records structure and never content: `subject_info` and file paths are
29
+ hashed, not stored, and `meas_date` is recorded only as present or absent
30
+ because dates of service are themselves identifiers. Manifests get committed to
31
+ public repositories; nothing here should make that a mistake.
32
+ """
33
+
34
+ from __future__ import annotations
35
+
36
+ import hashlib
37
+ from typing import Any
38
+
39
+ from ..run import Run
40
+ from .base import AVAILABLE, probe_import, safe
41
+
42
+ name = "mne"
43
+
44
+
45
+ def availability() -> tuple[str, str]:
46
+ """``(status, reason)`` -- see ``adapters.base.probe_import``."""
47
+ return probe_import("mne")
48
+
49
+
50
+ def is_available() -> bool:
51
+ return availability()[0] == AVAILABLE
52
+
53
+
54
+ def _sha(text: str) -> str:
55
+ return hashlib.sha256(str(text).encode("utf-8", "replace")).hexdigest()[:16]
56
+
57
+
58
+ def _round(value: Any, digits: int = 6) -> Any:
59
+ return safe(lambda: round(float(value), digits), value)
60
+
61
+
62
+ # --------------------------------------------------------------------------
63
+ # Info
64
+ # --------------------------------------------------------------------------
65
+
66
+ def describe_info(info: Any, run: Run, prefix: str = "recording") -> None:
67
+ """Record acquisition and preprocessing state from an ``mne.Info``.
68
+
69
+ Note what is *not* here: no subject identifiers, no measurement date, no
70
+ file paths. See the module docstring.
71
+ """
72
+ run.log_param(f"{prefix}.sfreq", _round(safe(lambda: info["sfreq"])))
73
+ run.log_param(f"{prefix}.nchan", safe(lambda: int(info["nchan"]), "unknown"))
74
+
75
+ # The filter band as MNE currently believes it to be. The *design* that
76
+ # produced it is not in Info; see filter_raw().
77
+ run.log_param(f"{prefix}.highpass", _round(safe(lambda: info["highpass"])))
78
+ run.log_param(f"{prefix}.lowpass", _round(safe(lambda: info["lowpass"])))
79
+ run.log_param(f"{prefix}.line_freq", safe(lambda: info["line_freq"], "unset"))
80
+
81
+ # Bad channels are a human judgement that silently changes every average,
82
+ # every ICA decomposition and every source estimate downstream.
83
+ bads = safe(lambda: sorted(info["bads"]), [])
84
+ run.log_param(f"{prefix}.bads", bads)
85
+ run.log_param(f"{prefix}.n_bads", len(bads))
86
+
87
+ ref = safe(lambda: info["custom_ref_applied"])
88
+ if ref is not None:
89
+ run.log_param(f"{prefix}.custom_ref_applied", str(ref))
90
+
91
+ projs = safe(lambda: list(info["projs"]), [])
92
+ run.log_param(f"{prefix}.n_projs", len(projs))
93
+ if projs:
94
+ run.log_param(
95
+ f"{prefix}.projs",
96
+ safe(lambda: sorted(f"{p['desc']}({'on' if p['active'] else 'off'})"
97
+ for p in projs), []),
98
+ )
99
+
100
+ dig = safe(lambda: info["dig"])
101
+ run.log_param(f"{prefix}.has_montage", dig is not None)
102
+ if dig is not None:
103
+ run.log_param(f"{prefix}.n_dig_points", safe(lambda: len(dig), "unknown"))
104
+
105
+ # Present-or-absent only. A date of service is an identifier.
106
+ run.log_param(f"{prefix}.meas_date_set",
107
+ safe(lambda: info["meas_date"], None) is not None)
108
+
109
+ subject = safe(lambda: info["subject_info"])
110
+ if subject:
111
+ # Hashed so a changed or swapped subject is detectable without the
112
+ # manifest carrying anything about who they are.
113
+ run.log_param(f"{prefix}.subject_info_sha256",
114
+ _sha(sorted(map(str, subject.items()))))
115
+
116
+
117
+ def _channel_type_counts(obj: Any) -> dict[str, int]:
118
+ def _counts():
119
+ from collections import Counter
120
+ return dict(Counter(obj.get_channel_types()))
121
+ return safe(_counts, {}) or {}
122
+
123
+
124
+ # --------------------------------------------------------------------------
125
+ # Raw
126
+ # --------------------------------------------------------------------------
127
+
128
+ def describe_raw(raw: Any, run: Run, prefix: str = "recording") -> None:
129
+ """Record a Raw object: info, duration, channel composition, annotations."""
130
+ run.log_param(f"{prefix}.type", type(raw).__name__)
131
+ describe_info(safe(lambda: raw.info), run, prefix)
132
+
133
+ run.log_param(f"{prefix}.n_times", safe(lambda: int(raw.n_times), "unknown"))
134
+ run.log_param(f"{prefix}.duration_s",
135
+ _round(safe(lambda: raw.times[-1]), 3))
136
+ run.log_param(f"{prefix}.preload", bool(safe(lambda: raw.preload, False)))
137
+
138
+ for ch_type, count in sorted(_channel_type_counts(raw).items()):
139
+ run.log_param(f"{prefix}.n_{ch_type}", count)
140
+
141
+ # File paths can contain subject identifiers, so hash them. The count still
142
+ # distinguishes a single recording from a concatenation.
143
+ files = safe(lambda: [str(f) for f in raw.filenames], [])
144
+ if files:
145
+ run.log_param(f"{prefix}.n_source_files", len(files))
146
+ run.log_param(f"{prefix}.source_files_sha256", _sha("\n".join(sorted(files))))
147
+
148
+ ann = safe(lambda: raw.annotations)
149
+ if ann is not None:
150
+ run.log_param(f"{prefix}.n_annotations", safe(lambda: len(ann), 0))
151
+ descriptions = safe(lambda: sorted(set(map(str, ann.description))), [])
152
+ if descriptions:
153
+ run.log_param(f"{prefix}.annotation_kinds", descriptions)
154
+
155
+
156
+ # --------------------------------------------------------------------------
157
+ # Filtering
158
+ # --------------------------------------------------------------------------
159
+
160
+ #: ``raw.filter`` defaults, recorded explicitly when not passed. MNE stores the
161
+ #: resulting band in ``info`` and discards the design, so a future change of
162
+ #: default would otherwise be invisible.
163
+ FILTER_DEFAULTS = {
164
+ "method": "fir",
165
+ "fir_design": "firwin",
166
+ "fir_window": "hamming",
167
+ "phase": "zero",
168
+ "l_trans_bandwidth": "auto",
169
+ "h_trans_bandwidth": "auto",
170
+ "filter_length": "auto",
171
+ "pad": "reflect_limited",
172
+ }
173
+
174
+
175
+ def filter_raw(raw: Any, run: Run, l_freq=None, h_freq=None,
176
+ prefix: str = "filter", **kwargs: Any):
177
+ """``raw.filter()`` with the filter *design* recorded, not just the band.
178
+
179
+ ::
180
+
181
+ with daftar.track("preproc", seed=42) as run:
182
+ mne_adapter.filter_raw(raw, run, l_freq=1.0, h_freq=40.0)
183
+
184
+ After a plain ``raw.filter(1, 40)``, ``info['highpass']`` and
185
+ ``info['lowpass']`` hold 1 and 40 and everything else is gone. But a
186
+ zero-phase FIR with a 0.5 Hz transition band and a causal IIR are different
187
+ filters, and "1--40 Hz" in a methods section does not distinguish them.
188
+ """
189
+ resolved = dict(FILTER_DEFAULTS)
190
+ resolved.update(kwargs)
191
+
192
+ run.log_param(f"{prefix}.l_freq", l_freq if l_freq is not None else "none")
193
+ run.log_param(f"{prefix}.h_freq", h_freq if h_freq is not None else "none")
194
+ for key, value in sorted(resolved.items()):
195
+ run.log_param(f"{prefix}.{key}", value)
196
+ if key in FILTER_DEFAULTS and key not in kwargs:
197
+ run.log_param(f"{prefix}.{key}.was_default", True)
198
+
199
+ out = raw.filter(l_freq=l_freq, h_freq=h_freq, **kwargs)
200
+ describe_info(safe(lambda: raw.info), run, "recording")
201
+ return out
202
+
203
+
204
+ def describe_resample(raw: Any, run: Run, old_sfreq: float,
205
+ prefix: str = "resample") -> None:
206
+ """Record a resampling step, which is lossy and not reversible."""
207
+ run.log_param(f"{prefix}.sfreq_before", _round(old_sfreq))
208
+ run.log_param(f"{prefix}.sfreq_after",
209
+ _round(safe(lambda: raw.info["sfreq"])))
210
+
211
+
212
+ # --------------------------------------------------------------------------
213
+ # Epochs
214
+ # --------------------------------------------------------------------------
215
+
216
+ def describe_epochs(epochs: Any, run: Run, prefix: str = "epochs") -> None:
217
+ """Record epoching parameters and, importantly, what was thrown away.
218
+
219
+ ``drop_log`` is the interesting part. An evoked average over 40 surviving
220
+ epochs is a different quantity from one over 180, and the average alone does
221
+ not say which you are looking at. The reasons matter too: epochs dropped for
222
+ amplitude rejection and epochs dropped because the event was missing are
223
+ different problems.
224
+ """
225
+ run.log_param(f"{prefix}.type", type(epochs).__name__)
226
+ run.log_param(f"{prefix}.tmin", _round(safe(lambda: epochs.tmin)))
227
+ run.log_param(f"{prefix}.tmax", _round(safe(lambda: epochs.tmax)))
228
+ run.log_param(f"{prefix}.baseline", str(safe(lambda: epochs.baseline, "none")))
229
+ run.log_param(f"{prefix}.reject", safe(lambda: epochs.reject, "none") or "none")
230
+ run.log_param(f"{prefix}.flat", safe(lambda: epochs.flat, "none") or "none")
231
+ run.log_param(f"{prefix}.decim", safe(lambda: getattr(epochs, "decim", 1), 1))
232
+ run.log_param(f"{prefix}.detrend", safe(lambda: epochs.detrend, "none"))
233
+
234
+ event_id = safe(lambda: dict(epochs.event_id), {})
235
+ if event_id:
236
+ run.log_param(f"{prefix}.event_id", event_id)
237
+ run.log_param(f"{prefix}.n_conditions", len(event_id))
238
+
239
+ n_kept = safe(lambda: len(epochs), 0)
240
+ run.log_result(f"{prefix}.n_epochs_kept", n_kept)
241
+
242
+ drop_log = safe(lambda: epochs.drop_log)
243
+ if drop_log is not None:
244
+ total = len(drop_log)
245
+ dropped = [d for d in drop_log if d]
246
+ run.log_result(f"{prefix}.n_epochs_total", total)
247
+ run.log_result(f"{prefix}.n_epochs_dropped", len(dropped))
248
+ if total:
249
+ run.log_result(f"{prefix}.drop_rate",
250
+ round(len(dropped) / total, 4))
251
+
252
+ def _reasons():
253
+ from collections import Counter
254
+ counts = Counter()
255
+ for entry in dropped:
256
+ for reason in entry:
257
+ counts[str(reason)] += 1
258
+ return dict(counts.most_common())
259
+
260
+ reasons = safe(_reasons, {})
261
+ if reasons:
262
+ run.log_result(f"{prefix}.drop_reasons", reasons)
263
+
264
+
265
+ def describe_evoked(evoked: Any, run: Run, prefix: str = "evoked") -> None:
266
+ """Summarise an evoked response as comparable scalars, not a waveform."""
267
+ run.log_result(f"{prefix}.n_averaged", safe(lambda: int(evoked.nave), "unknown"))
268
+ run.log_result(f"{prefix}.comment", safe(lambda: str(evoked.comment), ""))
269
+
270
+ def _stats():
271
+ import numpy as np
272
+ data = np.asarray(evoked.data)
273
+ return {
274
+ "peak_abs": float(np.abs(data).max()),
275
+ "mean": float(data.mean()),
276
+ "rms": float(np.sqrt((data ** 2).mean())),
277
+ "n_nonfinite": int((~np.isfinite(data)).sum()),
278
+ }
279
+
280
+ for key, value in (safe(_stats, {}) or {}).items():
281
+ run.log_result(f"{prefix}.{key}",
282
+ value if key == "n_nonfinite" else round(value, 12))
283
+
284
+
285
+ # --------------------------------------------------------------------------
286
+ # ICA -- the reason this adapter exists
287
+ # --------------------------------------------------------------------------
288
+
289
+ def describe_ica(ica: Any, run: Run, prefix: str = "ica") -> None:
290
+ """Record an ICA decomposition, including the exclusions and convergence.
291
+
292
+ ``ica.exclude`` is the most consequential unrecorded decision in EEG/MEG
293
+ preprocessing: a person looked at topographies and time courses and chose
294
+ which components were artefact. Nothing downstream records that choice, and
295
+ a reviewer asking "which components did you remove?" is usually asking a
296
+ question with no surviving answer.
297
+ """
298
+ run.log_param(f"{prefix}.method", safe(lambda: str(ica.method), "unknown"))
299
+ run.log_param(f"{prefix}.n_components_requested",
300
+ safe(lambda: ica.n_components, "auto"))
301
+ run.log_param(f"{prefix}.n_components_fitted",
302
+ safe(lambda: int(ica.n_components_), "unknown"))
303
+ run.log_param(f"{prefix}.max_iter", safe(lambda: ica.max_iter, "unknown"))
304
+
305
+ # random_state=None means the decomposition is not reproducible, and neither
306
+ # are the component indices the exclusions refer to.
307
+ random_state = safe(lambda: ica.random_state)
308
+ run.log_param(f"{prefix}.random_state",
309
+ "none (NOT REPRODUCIBLE)" if random_state is None else random_state)
310
+
311
+ fit_params = safe(lambda: dict(ica.fit_params or {}), {})
312
+ for key, value in sorted(fit_params.items()):
313
+ run.log_param(f"{prefix}.fit_params.{key}", value)
314
+
315
+ n_iter = safe(lambda: int(ica.n_iter_))
316
+ max_iter = safe(lambda: ica.max_iter)
317
+ if n_iter is not None:
318
+ run.log_result(f"{prefix}.n_iter", n_iter)
319
+ # Hitting the iteration limit means it stopped, not that it finished.
320
+ if isinstance(max_iter, int):
321
+ run.log_result(f"{prefix}.converged", n_iter < max_iter)
322
+
323
+ run.log_param(f"{prefix}.n_channels_used",
324
+ safe(lambda: len(ica.ch_names), "unknown"))
325
+ run.log_param(f"{prefix}.n_samples", safe(lambda: int(ica.n_samples_), "unknown"))
326
+
327
+ exclude = sorted(safe(lambda: [int(i) for i in ica.exclude], []) or [])
328
+ run.log_param(f"{prefix}.exclude", exclude)
329
+ run.log_param(f"{prefix}.n_excluded", len(exclude))
330
+
331
+
332
+ def apply_ica(ica: Any, inst: Any, run: Run, prefix: str = "ica", **kwargs: Any):
333
+ """``ica.apply()`` with the decomposition and exclusions recorded first.
334
+
335
+ ::
336
+
337
+ with daftar.track("preproc", seed=42) as run:
338
+ ica.exclude = [0, 3]
339
+ mne_adapter.apply_ica(ica, raw, run)
340
+
341
+ Recording happens *before* the call, so the exclusion list that was actually
342
+ applied is what lands in the manifest even if it is edited afterwards.
343
+ """
344
+ describe_ica(ica, run, prefix)
345
+ for key, value in sorted(kwargs.items()):
346
+ run.log_param(f"{prefix}.apply.{key}", value)
347
+ return ica.apply(inst, **kwargs)
348
+
349
+
350
+ # --------------------------------------------------------------------------
351
+ # environment
352
+ # --------------------------------------------------------------------------
353
+
354
+ def describe_environment(run: Run, prefix: str = "mne") -> None:
355
+ import mne
356
+
357
+ run.log_param(f"{prefix}.version", safe(lambda: mne.__version__, "unknown"))
358
+
359
+
360
+ def describe(obj: Any, run: Run, prefix: str | None = None) -> None:
361
+ """Dispatch on whatever MNE object is handed in."""
362
+ cls = type(obj).__name__
363
+ if cls == "ICA":
364
+ describe_ica(obj, run, prefix or "ica")
365
+ elif "Epochs" in cls:
366
+ describe_epochs(obj, run, prefix or "epochs")
367
+ elif cls in ("Evoked", "EvokedArray"):
368
+ describe_evoked(obj, run, prefix or "evoked")
369
+ elif cls == "Info":
370
+ describe_info(obj, run, prefix or "recording")
371
+ else:
372
+ describe_raw(obj, run, prefix or "recording")
@@ -27,7 +27,8 @@ from typing import Any
27
27
  # guarantees the usual suspects appear even if imported lazily later.
28
28
  _ALWAYS_RECORD = (
29
29
  "numpy", "scipy", "pandas", "jax", "jaxlib", "jaxley", "torch",
30
- "equinox", "brian2", "neuron", "cpm-toolbox", "cpm", "cython", "sympy", "dm-meltingpot",
30
+ "equinox", "brian2", "neuron", "cpm-toolbox", "cpm", "cython", "sympy",
31
+ "mne", "scikit-learn", "sklearn", "dm-meltingpot",
31
32
  "dmlab2d", "gdm-concordia", "matplotlib", "scikit-learn",
32
33
  )
33
34
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: daftar
3
- Version: 0.3.3
3
+ Version: 0.4.0
4
4
  Summary: Record what produced each computational result: environment, code, parameters, seeds, inputs.
5
5
  Author: Aslan Satary Dizaji
6
6
  License-Expression: Apache-2.0
@@ -23,6 +23,8 @@ Provides-Extra: meltingpot
23
23
  Requires-Dist: dm-meltingpot; extra == "meltingpot"
24
24
  Provides-Extra: brian2
25
25
  Requires-Dist: brian2; extra == "brian2"
26
+ Provides-Extra: mne
27
+ Requires-Dist: mne; extra == "mne"
26
28
  Provides-Extra: dev
27
29
  Requires-Dist: pytest>=7; extra == "dev"
28
30
  Requires-Dist: numpy; extra == "dev"
@@ -34,6 +36,7 @@ Requires-Dist: jaxley; extra == "all"
34
36
  Requires-Dist: cpm-toolbox; extra == "all"
35
37
  Requires-Dist: dm-meltingpot; extra == "all"
36
38
  Requires-Dist: brian2; extra == "all"
39
+ Requires-Dist: mne; extra == "all"
37
40
  Dynamic: license-file
38
41
 
39
42
  # daftar
@@ -47,8 +50,8 @@ past run can be rebuilt.
47
50
 
48
51
  Experiment trackers solved this for deep learning, where an experiment is
49
52
  `model.fit()`. They do not help when the experiment is a Hodgkin–Huxley
50
- simulation of 302 neurons, a hierarchical fit across 60 participants, a spiking
51
- network, or a 200-episode multi-agent sweep. Those runs have no epochs, no loss
53
+ simulation of 302 neurons, a hierarchical fit across 60 participants, an EEG
54
+ preprocessing pipeline, or a 200-episode multi-agent sweep. Those runs have no epochs, no loss
52
55
  curves, and no checkpoints. They have parameter grids, solver tolerances, random
53
56
  seeds, and derived quantities.
54
57
 
@@ -315,6 +318,7 @@ knowing something a generic tracker cannot infer.
315
318
  | `jaxley` | morphology (compartments, branches, channels, synapses), `jx.integrate` defaults you never passed, `jax_enable_x64`, backend |
316
319
  | `cpm` | parameter **bounds and priors** (resolved to the scipy distribution and its arguments), estimator and its scipy settings, restart counts and the initial guesses themselves, per-participant convergence, cohort hash |
317
320
  | `brian2` | **the integration method Brian2 actually chose** — its default is a candidate list and the winner is stored nowhere — plus resolved `codegen.target`, network schedule, equation hashes, realised synapse counts |
321
+ | `mne` | **which ICA components were excluded** and whether ICA converged, filter *design* rather than just the band, bad channels, epoch drop counts and reasons — with subject data hashed, never stored |
318
322
  | `meltingpot` | resolved substrate ConfigDict hash, roles, episode-length cap, pinned bot checkpoints, per-player returns and Gini |
319
323
 
320
324
  ```python
@@ -324,12 +328,19 @@ with daftar.track("balanced-net", seed=42) as run:
324
328
  b2a.run_network(net, 1*second, run)
325
329
  ```
326
330
 
331
+ The MNE adapter deserves a note on privacy: it runs against human neuroimaging
332
+ recordings, so it records structure and never content. `subject_info` and file
333
+ paths are hashed rather than stored, and `meas_date` is recorded only as present
334
+ or absent, because dates of service are themselves identifiers. Manifests get
335
+ committed to public repositories; nothing the adapter writes should make that a
336
+ mistake.
337
+
327
338
  Adapters never import their framework at module load, so `import daftar` works
328
339
  with none of them installed. Every probe is best-effort: a provenance tool that
329
340
  crashes a four-hour simulation because a framework renamed an attribute has done
330
341
  far more harm than the missing field was worth.
331
342
 
332
- All four are verified against live installs by `tests/test_adapters_live.py`.
343
+ All five are verified against live installs by `tests/test_adapters_live.py`.
333
344
  See `examples/adapter_usage.py` for the pattern for each, and
334
345
  [INSTALL.md](INSTALL.md) for which environment each needs — they do not all fit
335
346
  in one.
@@ -33,6 +33,7 @@ src/daftar/adapters/brian2_adapter.py
33
33
  src/daftar/adapters/cpm_adapter.py
34
34
  src/daftar/adapters/jaxley_adapter.py
35
35
  src/daftar/adapters/meltingpot_adapter.py
36
+ src/daftar/adapters/mne_adapter.py
36
37
  tests/test_adapters_live.py
37
38
  tests/test_core.py
38
39
  tests/test_notebook.py
@@ -4,6 +4,7 @@ jaxley
4
4
  cpm-toolbox
5
5
  dm-meltingpot
6
6
  brian2
7
+ mne
7
8
 
8
9
  [brian2]
9
10
  brian2
@@ -22,5 +23,8 @@ jaxley
22
23
  [meltingpot]
23
24
  dm-meltingpot
24
25
 
26
+ [mne]
27
+ mne
28
+
25
29
  [notebook]
26
30
  ipython
@@ -570,3 +570,187 @@ def test_brian2_dt_change_is_a_cause_not_a_mystery(store):
570
570
  causes = [c.key for c in d.causes]
571
571
  assert "param.brian2.defaultclock_dt" in causes
572
572
  assert d.effects, "changing dt should move the spike count"
573
+
574
+
575
+ # ==========================================================================
576
+ # MNE-Python
577
+ # ==========================================================================
578
+
579
+ def _mne_raw(n_channels=6, sfreq=250.0, seconds=12, seed=0):
580
+ """A small synthetic EEG recording with one channel marked bad."""
581
+ import numpy as np
582
+ import mne
583
+
584
+ mne.set_log_level("ERROR")
585
+ names = [f"EEG{i:03d}" for i in range(n_channels)]
586
+ info = mne.create_info(names, sfreq, "eeg")
587
+ rng = np.random.default_rng(seed)
588
+ data = rng.normal(scale=2e-5, size=(n_channels, int(sfreq * seconds)))
589
+ raw = mne.io.RawArray(data, info)
590
+ raw.info["bads"] = [names[2]]
591
+ return raw
592
+
593
+
594
+ @_require("mne")
595
+ def test_mne_records_recording_state_without_subject_data(store):
596
+ """Structure is recorded; subject identifiers are not."""
597
+ import mne
598
+
599
+ from daftar.adapters import mne as mnea
600
+
601
+ raw = _mne_raw()
602
+ raw.info["subject_info"] = {"his_id": "PATIENT-12345", "sex": 1}
603
+ raw.info["line_freq"] = 50.0
604
+
605
+ with daftar.track("preproc", seed=42, store=store) as run:
606
+ mnea.describe_environment(run)
607
+ mnea.describe_raw(raw, run)
608
+ rid = run.run_id
609
+
610
+ m = store.load(rid)
611
+
612
+ assert m.get("param.recording.sfreq") == "250.0"
613
+ assert m.get("param.recording.nchan") == "6"
614
+ assert m.get("param.recording.n_eeg") == "6"
615
+ assert m.get("param.recording.line_freq") == "50.0"
616
+
617
+ # Bad channels are a human judgement that changes everything downstream.
618
+ assert "EEG002" in m.get("param.recording.bads")
619
+ assert m.get("param.recording.n_bads") == "1"
620
+
621
+ # Subject data is hashed, never stored. Manifests get committed.
622
+ assert m.get("param.recording.subject_info_sha256")
623
+ assert "PATIENT-12345" not in m.to_json()
624
+ assert m.get("param.recording.meas_date_set") in ("true", "false")
625
+ assert mne.__version__ == m.get("param.mne.version")
626
+
627
+
628
+ @_require("mne")
629
+ def test_mne_filter_records_the_design_not_just_the_band(store):
630
+ """info['highpass']/['lowpass'] survive raw.filter(); the design does not.
631
+
632
+ A zero-phase FIR with a wide transition band and a causal IIR are different
633
+ filters. "1-40 Hz" in a methods section does not distinguish them.
634
+ """
635
+ from daftar.adapters import mne as mnea
636
+
637
+ raw = _mne_raw()
638
+ with daftar.track("filt", seed=42, store=store) as run:
639
+ mnea.filter_raw(raw, run, l_freq=1.0, h_freq=40.0, fir_design="firwin")
640
+ rid = run.run_id
641
+
642
+ m = store.load(rid)
643
+ assert m.get("param.filter.l_freq") == "1.0"
644
+ assert m.get("param.filter.h_freq") == "40.0"
645
+ assert m.get("param.filter.fir_design") == "firwin"
646
+ # Defaults the caller never passed are recorded and flagged as defaults, so
647
+ # a future change of MNE default shows up as a diff.
648
+ assert m.get("param.filter.phase") == "zero"
649
+ assert m.get("param.filter.phase.was_default") == "true"
650
+ assert m.get("param.filter.fir_design.was_default") is None
651
+ # The resulting band is refreshed from Info afterwards.
652
+ assert m.get("param.recording.highpass") == "1.0"
653
+
654
+
655
+ @_require("mne")
656
+ def test_mne_epochs_record_what_was_thrown_away(store):
657
+ """An average over 40 surviving epochs differs from one over 180."""
658
+ import numpy as np
659
+ import mne
660
+
661
+ from daftar.adapters import mne as mnea
662
+
663
+ raw = _mne_raw(seconds=12)
664
+ events = np.array([[int(250 * t), 0, 1] for t in range(1, 11)])
665
+
666
+ with daftar.track("epoch", seed=42, store=store) as run:
667
+ epochs = mne.Epochs(raw, events, event_id={"stim": 1},
668
+ tmin=-0.2, tmax=0.5, baseline=(None, 0),
669
+ reject=dict(eeg=1e-6), # aggressive: drops most
670
+ preload=True)
671
+ mnea.describe_epochs(epochs, run)
672
+ rid = run.run_id
673
+
674
+ m = store.load(rid)
675
+ assert m.get("param.epochs.tmin") == "-0.2"
676
+ assert m.get("param.epochs.tmax") == "0.5"
677
+ assert "eeg" in m.get("param.epochs.reject")
678
+ assert m.get("param.epochs.n_conditions") == "1"
679
+
680
+ total = int(m.get("result.epochs.n_epochs_total"))
681
+ dropped = int(m.get("result.epochs.n_epochs_dropped"))
682
+ assert total == 10
683
+ assert dropped > 0, "the aggressive reject threshold should drop epochs"
684
+ assert m.get("result.epochs.drop_rate")
685
+ # Why they were dropped, not just how many.
686
+ assert m.get("result.epochs.drop_reasons")
687
+
688
+
689
+ @_require("mne")
690
+ def test_mne_ica_records_exclusions_and_convergence(store):
691
+ """ica.exclude is the most consequential unrecorded decision in EEG."""
692
+ import mne
693
+
694
+ from daftar.adapters import mne as mnea
695
+
696
+ raw = _mne_raw(n_channels=6)
697
+ ica = mne.preprocessing.ICA(n_components=4, method="fastica",
698
+ random_state=97, max_iter=200)
699
+ ica.fit(raw)
700
+ ica.exclude = [0, 2]
701
+
702
+ with daftar.track("ica", seed=42, store=store) as run:
703
+ mnea.apply_ica(ica, raw.copy(), run)
704
+ rid = run.run_id
705
+
706
+ m = store.load(rid)
707
+
708
+ assert m.get("param.ica.method") == "fastica"
709
+ assert m.get("param.ica.random_state") == "97"
710
+ assert m.get("param.ica.n_components_fitted") == "4"
711
+
712
+ # The human decision.
713
+ assert m.get("param.ica.exclude") == "[0, 2]"
714
+ assert m.get("param.ica.n_excluded") == "2"
715
+
716
+ # n_iter_ == max_iter means it stopped, not that it finished.
717
+ assert m.get("result.ica.n_iter")
718
+ assert m.get("result.ica.converged") in ("true", "false")
719
+
720
+
721
+ @_require("mne")
722
+ def test_mne_unseeded_ica_is_flagged_as_irreproducible(store):
723
+ """random_state=None means the components -- and the exclusions indexing
724
+ into them -- differ between runs. The manifest must say so loudly."""
725
+ import mne
726
+
727
+ from daftar.adapters import mne as mnea
728
+
729
+ ica = mne.preprocessing.ICA(n_components=3, method="fastica",
730
+ random_state=None, max_iter=100)
731
+ ica.fit(_mne_raw(n_channels=5))
732
+
733
+ with daftar.track("ica-unseeded", store=store) as run:
734
+ mnea.describe_ica(ica, run)
735
+ rid = run.run_id
736
+
737
+ assert "NOT REPRODUCIBLE" in store.load(rid).get("param.ica.random_state")
738
+
739
+
740
+ @_require("mne")
741
+ def test_mne_bad_channel_change_is_a_cause(store):
742
+ """Marking one more channel bad changes every downstream number."""
743
+ from daftar.adapters import mne as mnea
744
+
745
+ ids = []
746
+ for bads in (["EEG002"], ["EEG002", "EEG004"]):
747
+ raw = _mne_raw()
748
+ raw.info["bads"] = bads
749
+ with daftar.track("preproc", seed=42, store=store) as run:
750
+ mnea.describe_raw(raw, run)
751
+ ids.append(run.run_id)
752
+
753
+ causes = [c.key for c in
754
+ daftar.diff_manifests(store.load(ids[0]), store.load(ids[1])).causes]
755
+ assert "param.recording.bads" in causes
756
+ assert "param.recording.n_bads" in causes
@@ -430,7 +430,7 @@ def test_manifests_are_valid_json_on_disk(store):
430
430
 
431
431
  def test_adapters_import_without_their_frameworks():
432
432
  from daftar import adapters
433
- assert set(adapters.registry.all()) == {"jaxley", "cpm", "meltingpot", "brian2"}
433
+ assert set(adapters.registry.all()) == {"jaxley", "cpm", "meltingpot", "brian2", "mne"}
434
434
  for name in adapters.registry.all():
435
435
  assert isinstance(adapters.get(name).is_available(), bool)
436
436
 
@@ -1 +0,0 @@
1
- __version__ = "0.3.3"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes