Note
Go to the end to download the full example code.
Studies¶
A Study is an interface to an external dataset: it
knows how to download data, iterate over recording sessions, and load
events. A handful of synthetic/testing studies (Fake2025Meg, Mne2013Sample,
…) ship with NeuralSet; the full catalog of public datasets is provided
by the NeuralFetch
package — no data is bundled, only the code that accesses it.
Note
The examples below use Fake2025Meg which includes audio events.
If you haven’t already:
pip install 'neuralset[tutorials]'
What is a Study?¶
A Study encapsulates three responsibilities:
Download raw data to a local path (
download())Iterate timelines — each timeline is one recording session for one subject (
iter_timelines())Load events for each timeline into a validated events DataFrame (
run())
A timeline groups events that share a common time axis. Timelines are useful because they allow (1) loading data from simultaneous recordings (e.g. fMRI + EEG) and (2) keeping separate sessions (e.g. pre- and post-training).
Browsing the Catalog¶
Study.catalog() returns
all registered studies (from neuralfetch and any other installed
package):
import neuralset as ns
all_studies = ns.Study.catalog()
print(f"{len(all_studies)} studies available")
144 studies available
Loading a Study¶
Instantiate a Study by name.
Study(name="X", ...) automatically finds and returns the concrete
subclass X — it is equivalent to X(...) directly.
Public-data studies are registered through the neuralfetch package —
see the NeuralFetch documentation for the full
catalog.
Call run() to load all timelines and concatenate them into a
single validated events DataFrame. The subject, timeline, and
study columns are added automatically.
# ns.CACHE_FOLDER defaults to ~/.cache/neuralset/
study = ns.Study(name="Fake2025Meg", path=ns.CACHE_FOLDER)
events = study.run()
print(f"{len(events)} events across {events.subject.nunique()} subjects")
print(events[["type", "start", "duration", "timeline"]].head(8).to_string())
Fetching 1 file for the sample dataset ...
0%| | 0.00/1.65G [00:00<?, ?B/s]
0%| | 395k/1.65G [00:00<06:59, 3.94MB/s]
0%| | 4.92M/1.65G [00:00<00:59, 27.9MB/s]
1%|▎ | 13.9M/1.65G [00:00<00:29, 55.9MB/s]
1%|▌ | 22.8M/1.65G [00:00<00:23, 69.0MB/s]
2%|▋ | 29.7M/1.65G [00:00<00:27, 58.2MB/s]
2%|▊ | 37.8M/1.65G [00:00<00:24, 65.1MB/s]
3%|█ | 46.6M/1.65G [00:00<00:22, 72.0MB/s]
3%|█▏ | 54.1M/1.65G [00:01<00:43, 36.8MB/s]
4%|█▎ | 59.7M/1.65G [00:01<00:44, 35.9MB/s]
4%|█▌ | 68.5M/1.65G [00:01<00:34, 45.6MB/s]
5%|█▋ | 74.7M/1.65G [00:01<00:33, 47.3MB/s]
5%|█▊ | 80.6M/1.65G [00:01<00:35, 43.8MB/s]
5%|█▉ | 85.8M/1.65G [00:01<00:35, 44.0MB/s]
6%|██ | 93.9M/1.65G [00:01<00:29, 52.7MB/s]
6%|██▎ | 103M/1.65G [00:02<00:25, 61.3MB/s]
7%|██▌ | 111M/1.65G [00:02<00:22, 68.0MB/s]
7%|██▊ | 120M/1.65G [00:02<00:20, 73.4MB/s]
8%|██▉ | 129M/1.65G [00:02<00:19, 77.4MB/s]
8%|███▏ | 138M/1.65G [00:02<00:18, 80.4MB/s]
9%|███▎ | 146M/1.65G [00:02<00:18, 82.3MB/s]
9%|███▌ | 155M/1.65G [00:02<00:17, 84.0MB/s]
10%|███▊ | 164M/1.65G [00:02<00:17, 85.1MB/s]
10%|███▉ | 173M/1.65G [00:02<00:17, 85.9MB/s]
11%|████▏ | 182M/1.65G [00:02<00:17, 86.5MB/s]
12%|████▍ | 190M/1.65G [00:03<00:16, 87.0MB/s]
12%|████▌ | 199M/1.65G [00:03<00:16, 87.2MB/s]
13%|████▊ | 208M/1.65G [00:03<00:16, 87.6MB/s]
13%|████▉ | 217M/1.65G [00:03<00:16, 88.1MB/s]
14%|█████▏ | 226M/1.65G [00:03<00:16, 88.1MB/s]
14%|█████▍ | 234M/1.65G [00:03<00:16, 87.9MB/s]
15%|█████▌ | 243M/1.65G [00:03<00:16, 87.6MB/s]
15%|█████▊ | 252M/1.65G [00:03<00:15, 87.7MB/s]
16%|█████▉ | 261M/1.65G [00:03<00:15, 87.7MB/s]
16%|██████▏ | 270M/1.65G [00:03<00:15, 87.6MB/s]
17%|██████▍ | 278M/1.65G [00:04<00:15, 87.7MB/s]
17%|██████▌ | 287M/1.65G [00:04<00:15, 87.5MB/s]
18%|██████▊ | 296M/1.65G [00:04<00:15, 87.7MB/s]
18%|███████ | 305M/1.65G [00:04<00:15, 87.9MB/s]
19%|███████▏ | 314M/1.65G [00:04<00:15, 88.0MB/s]
20%|███████▍ | 322M/1.65G [00:04<00:15, 88.1MB/s]
20%|███████▌ | 331M/1.65G [00:04<00:15, 88.0MB/s]
21%|███████▊ | 340M/1.65G [00:04<00:14, 87.9MB/s]
21%|████████ | 349M/1.65G [00:04<00:14, 87.8MB/s]
22%|████████▏ | 358M/1.65G [00:04<00:14, 88.1MB/s]
22%|████████▍ | 367M/1.65G [00:05<00:14, 88.1MB/s]
23%|████████▋ | 375M/1.65G [00:05<00:14, 88.1MB/s]
23%|████████▊ | 384M/1.65G [00:05<00:14, 88.0MB/s]
24%|█████████ | 393M/1.65G [00:05<00:14, 87.9MB/s]
24%|█████████▏ | 402M/1.65G [00:05<00:14, 87.9MB/s]
25%|█████████▍ | 411M/1.65G [00:05<00:14, 88.0MB/s]
25%|█████████▋ | 419M/1.65G [00:05<00:14, 88.1MB/s]
26%|█████████▊ | 428M/1.65G [00:05<00:13, 88.2MB/s]
26%|██████████ | 437M/1.65G [00:05<00:13, 88.2MB/s]
27%|██████████▎ | 446M/1.65G [00:05<00:13, 88.6MB/s]
28%|██████████▍ | 455M/1.65G [00:06<00:13, 88.4MB/s]
28%|██████████▋ | 464M/1.65G [00:06<00:13, 88.4MB/s]
29%|██████████▊ | 473M/1.65G [00:06<00:13, 88.0MB/s]
29%|███████████ | 481M/1.65G [00:06<00:13, 87.9MB/s]
30%|███████████▎ | 490M/1.65G [00:06<00:13, 87.6MB/s]
30%|███████████▍ | 499M/1.65G [00:06<00:13, 87.5MB/s]
31%|███████████▋ | 508M/1.65G [00:06<00:13, 87.6MB/s]
31%|███████████▉ | 517M/1.65G [00:06<00:12, 88.0MB/s]
32%|████████████ | 526M/1.65G [00:06<00:12, 88.3MB/s]
32%|████████████▎ | 534M/1.65G [00:07<00:16, 66.1MB/s]
33%|████████████▍ | 542M/1.65G [00:07<00:16, 66.6MB/s]
33%|████████████▋ | 551M/1.65G [00:07<00:20, 53.4MB/s]
34%|████████████▊ | 557M/1.65G [00:08<00:43, 25.0MB/s]
34%|████████████▉ | 561M/1.65G [00:08<00:43, 25.0MB/s]
34%|█████████████ | 566M/1.65G [00:08<00:39, 27.2MB/s]
34%|█████████████ | 570M/1.65G [00:08<00:39, 27.2MB/s]
35%|█████████████▎ | 579M/1.65G [00:08<00:29, 37.0MB/s]
36%|█████████████▌ | 587M/1.65G [00:08<00:22, 47.2MB/s]
36%|█████████████▋ | 596M/1.65G [00:08<00:18, 56.6MB/s]
37%|█████████████▉ | 605M/1.65G [00:08<00:16, 64.4MB/s]
37%|██████████████ | 614M/1.65G [00:09<00:14, 70.5MB/s]
38%|██████████████▎ | 622M/1.65G [00:09<00:24, 42.0MB/s]
38%|██████████████▍ | 629M/1.65G [00:09<00:21, 46.6MB/s]
39%|██████████████▋ | 638M/1.65G [00:09<00:18, 55.1MB/s]
39%|██████████████▊ | 647M/1.65G [00:09<00:16, 62.6MB/s]
40%|███████████████ | 655M/1.65G [00:09<00:14, 69.0MB/s]
40%|███████████████▎ | 664M/1.65G [00:09<00:13, 74.0MB/s]
41%|███████████████▍ | 673M/1.65G [00:10<00:12, 77.9MB/s]
41%|███████████████▋ | 682M/1.65G [00:10<00:11, 81.2MB/s]
42%|███████████████▉ | 691M/1.65G [00:10<00:11, 83.6MB/s]
42%|████████████████ | 700M/1.65G [00:10<00:12, 77.2MB/s]
43%|████████████████▎ | 709M/1.65G [00:10<00:11, 80.3MB/s]
43%|████████████████▍ | 717M/1.65G [00:10<00:11, 82.6MB/s]
44%|████████████████▋ | 726M/1.65G [00:10<00:10, 84.5MB/s]
44%|████████████████▉ | 735M/1.65G [00:10<00:10, 84.0MB/s]
45%|█████████████████ | 744M/1.65G [00:10<00:10, 85.2MB/s]
46%|█████████████████▎ | 753M/1.65G [00:10<00:10, 86.0MB/s]
46%|█████████████████▌ | 761M/1.65G [00:11<00:10, 86.4MB/s]
47%|█████████████████▋ | 770M/1.65G [00:11<00:10, 86.6MB/s]
47%|█████████████████▉ | 779M/1.65G [00:11<00:10, 86.8MB/s]
48%|██████████████████ | 788M/1.65G [00:11<00:09, 87.7MB/s]
48%|██████████████████▎ | 797M/1.65G [00:11<00:09, 87.7MB/s]
49%|██████████████████▌ | 805M/1.65G [00:11<00:09, 87.8MB/s]
49%|██████████████████▋ | 814M/1.65G [00:11<00:09, 88.1MB/s]
50%|██████████████████▉ | 823M/1.65G [00:11<00:09, 88.0MB/s]
50%|███████████████████▏ | 832M/1.65G [00:11<00:09, 88.4MB/s]
51%|███████████████████▎ | 841M/1.65G [00:11<00:09, 88.4MB/s]
51%|███████████████████▌ | 850M/1.65G [00:12<00:09, 88.3MB/s]
52%|███████████████████▋ | 858M/1.65G [00:12<00:08, 88.5MB/s]
52%|███████████████████▉ | 867M/1.65G [00:12<00:08, 88.8MB/s]
53%|████████████████████▏ | 876M/1.65G [00:12<00:12, 63.2MB/s]
53%|████████████████████▎ | 884M/1.65G [00:12<00:12, 63.5MB/s]
54%|████████████████████▍ | 891M/1.65G [00:12<00:12, 62.6MB/s]
54%|████████████████████▋ | 900M/1.65G [00:12<00:10, 69.1MB/s]
55%|████████████████████▊ | 907M/1.65G [00:13<00:15, 49.0MB/s]
55%|████████████████████▉ | 913M/1.65G [00:13<00:14, 51.0MB/s]
56%|█████████████████████▏ | 919M/1.65G [00:13<00:18, 39.8MB/s]
56%|█████████████████████▎ | 928M/1.65G [00:13<00:14, 49.5MB/s]
57%|█████████████████████▍ | 934M/1.65G [00:13<00:15, 46.1MB/s]
57%|█████████████████████▋ | 942M/1.65G [00:13<00:13, 50.9MB/s]
58%|█████████████████████▊ | 951M/1.65G [00:13<00:11, 59.2MB/s]
58%|██████████████████████ | 960M/1.65G [00:14<00:10, 66.1MB/s]
59%|██████████████████████▎ | 968M/1.65G [00:14<00:09, 71.8MB/s]
59%|██████████████████████▍ | 977M/1.65G [00:14<00:08, 76.2MB/s]
60%|██████████████████████▋ | 986M/1.65G [00:14<00:08, 79.8MB/s]
60%|██████████████████████▊ | 995M/1.65G [00:14<00:08, 82.1MB/s]
61%|██████████████████████▍ | 1.00G/1.65G [00:14<00:07, 83.6MB/s]
61%|██████████████████████▋ | 1.01G/1.65G [00:14<00:07, 85.3MB/s]
62%|██████████████████████▊ | 1.02G/1.65G [00:14<00:07, 86.3MB/s]
62%|███████████████████████ | 1.03G/1.65G [00:14<00:07, 87.0MB/s]
63%|███████████████████████▎ | 1.04G/1.65G [00:14<00:07, 87.3MB/s]
63%|███████████████████████▍ | 1.05G/1.65G [00:15<00:06, 87.8MB/s]
64%|███████████████████████▋ | 1.06G/1.65G [00:15<00:10, 58.3MB/s]
64%|███████████████████████▊ | 1.07G/1.65G [00:15<00:09, 64.7MB/s]
65%|████████████████████████ | 1.07G/1.65G [00:15<00:08, 70.3MB/s]
66%|████████████████████████▏ | 1.08G/1.65G [00:15<00:07, 74.7MB/s]
66%|████████████████████████▍ | 1.09G/1.65G [00:15<00:07, 78.3MB/s]
67%|████████████████████████▋ | 1.10G/1.65G [00:15<00:06, 81.3MB/s]
67%|████████████████████████▊ | 1.11G/1.65G [00:15<00:06, 83.2MB/s]
68%|█████████████████████████ | 1.12G/1.65G [00:15<00:06, 84.5MB/s]
68%|█████████████████████████▏ | 1.13G/1.65G [00:16<00:06, 85.8MB/s]
69%|█████████████████████████▍ | 1.14G/1.65G [00:16<00:05, 86.5MB/s]
69%|█████████████████████████▋ | 1.15G/1.65G [00:16<00:05, 87.1MB/s]
70%|█████████████████████████▊ | 1.15G/1.65G [00:16<00:07, 70.5MB/s]
70%|█████████████████████████▉ | 1.16G/1.65G [00:16<00:10, 49.1MB/s]
71%|██████████████████████████▏ | 1.17G/1.65G [00:16<00:10, 45.1MB/s]
71%|██████████████████████████▎ | 1.17G/1.65G [00:17<00:11, 41.4MB/s]
71%|██████████████████████████▎ | 1.18G/1.65G [00:17<00:12, 37.8MB/s]
72%|██████████████████████████▍ | 1.18G/1.65G [00:17<00:13, 35.1MB/s]
72%|██████████████████████████▌ | 1.19G/1.65G [00:17<00:14, 33.2MB/s]
72%|██████████████████████████▋ | 1.19G/1.65G [00:17<00:14, 32.3MB/s]
72%|██████████████████████████▋ | 1.19G/1.65G [00:17<00:13, 35.2MB/s]
73%|██████████████████████████▊ | 1.20G/1.65G [00:17<00:14, 32.4MB/s]
73%|██████████████████████████▉ | 1.20G/1.65G [00:18<00:15, 28.8MB/s]
73%|██████████████████████████▉ | 1.21G/1.65G [00:18<00:14, 30.1MB/s]
73%|███████████████████████████ | 1.21G/1.65G [00:18<00:12, 36.3MB/s]
74%|███████████████████████████▎ | 1.22G/1.65G [00:18<00:10, 43.0MB/s]
74%|███████████████████████████▍ | 1.23G/1.65G [00:18<00:07, 54.9MB/s]
75%|███████████████████████████▌ | 1.23G/1.65G [00:18<00:09, 46.6MB/s]
75%|███████████████████████████▊ | 1.24G/1.65G [00:18<00:07, 56.5MB/s]
75%|███████████████████████████▉ | 1.25G/1.65G [00:19<00:10, 37.6MB/s]
76%|████████████████████████████ | 1.26G/1.65G [00:19<00:08, 47.4MB/s]
77%|████████████████████████████▎ | 1.26G/1.65G [00:19<00:06, 56.3MB/s]
77%|████████████████████████████▍ | 1.27G/1.65G [00:19<00:06, 59.6MB/s]
77%|████████████████████████████▋ | 1.28G/1.65G [00:19<00:05, 66.9MB/s]
78%|████████████████████████████▊ | 1.29G/1.65G [00:19<00:05, 72.4MB/s]
79%|█████████████████████████████ | 1.30G/1.65G [00:19<00:04, 76.6MB/s]
79%|█████████████████████████████▎ | 1.31G/1.65G [00:19<00:04, 79.5MB/s]
80%|█████████████████████████████▍ | 1.32G/1.65G [00:19<00:04, 82.2MB/s]
80%|█████████████████████████████▋ | 1.32G/1.65G [00:19<00:03, 83.8MB/s]
81%|█████████████████████████████▊ | 1.33G/1.65G [00:20<00:03, 85.0MB/s]
81%|██████████████████████████████ | 1.34G/1.65G [00:20<00:03, 86.0MB/s]
82%|██████████████████████████████▏ | 1.35G/1.65G [00:20<00:03, 80.4MB/s]
82%|██████████████████████████████▍ | 1.36G/1.65G [00:20<00:03, 74.7MB/s]
83%|██████████████████████████████▌ | 1.37G/1.65G [00:20<00:03, 78.0MB/s]
83%|██████████████████████████████▊ | 1.38G/1.65G [00:20<00:03, 80.6MB/s]
84%|██████████████████████████████▉ | 1.38G/1.65G [00:20<00:03, 69.9MB/s]
84%|███████████████████████████████▏ | 1.39G/1.65G [00:20<00:03, 74.5MB/s]
85%|███████████████████████████████▍ | 1.40G/1.65G [00:20<00:03, 77.9MB/s]
85%|███████████████████████████████▌ | 1.41G/1.65G [00:21<00:02, 80.7MB/s]
86%|███████████████████████████████▊ | 1.42G/1.65G [00:21<00:02, 82.7MB/s]
86%|███████████████████████████████▉ | 1.43G/1.65G [00:21<00:02, 84.2MB/s]
87%|████████████████████████████████▏ | 1.44G/1.65G [00:21<00:02, 85.1MB/s]
87%|████████████████████████████████▎ | 1.45G/1.65G [00:21<00:02, 85.6MB/s]
88%|████████████████████████████████▌ | 1.45G/1.65G [00:21<00:02, 86.4MB/s]
89%|████████████████████████████████▊ | 1.46G/1.65G [00:21<00:02, 86.8MB/s]
89%|████████████████████████████████▉ | 1.47G/1.65G [00:21<00:02, 73.7MB/s]
90%|█████████████████████████████████▏ | 1.48G/1.65G [00:21<00:02, 69.1MB/s]
90%|█████████████████████████████████▎ | 1.49G/1.65G [00:22<00:02, 74.1MB/s]
91%|█████████████████████████████████▌ | 1.50G/1.65G [00:22<00:01, 77.9MB/s]
91%|█████████████████████████████████▋ | 1.51G/1.65G [00:22<00:01, 80.7MB/s]
92%|█████████████████████████████████▉ | 1.52G/1.65G [00:22<00:01, 82.8MB/s]
92%|██████████████████████████████████ | 1.52G/1.65G [00:22<00:01, 84.3MB/s]
93%|██████████████████████████████████▎ | 1.53G/1.65G [00:22<00:01, 85.1MB/s]
93%|██████████████████████████████████▌ | 1.54G/1.65G [00:22<00:01, 86.1MB/s]
94%|██████████████████████████████████▋ | 1.55G/1.65G [00:22<00:01, 86.6MB/s]
94%|██████████████████████████████████▉ | 1.56G/1.65G [00:22<00:01, 87.0MB/s]
95%|███████████████████████████████████ | 1.57G/1.65G [00:22<00:00, 87.1MB/s]
95%|███████████████████████████████████▎ | 1.58G/1.65G [00:23<00:00, 87.4MB/s]
96%|███████████████████████████████████▍ | 1.59G/1.65G [00:23<00:00, 87.3MB/s]
96%|███████████████████████████████████▋ | 1.59G/1.65G [00:23<00:00, 87.5MB/s]
97%|███████████████████████████████████▉ | 1.60G/1.65G [00:23<00:00, 87.8MB/s]
98%|████████████████████████████████████ | 1.61G/1.65G [00:23<00:00, 87.6MB/s]
98%|████████████████████████████████████▎| 1.62G/1.65G [00:23<00:00, 87.2MB/s]
99%|████████████████████████████████████▍| 1.63G/1.65G [00:23<00:00, 87.0MB/s]
99%|████████████████████████████████████▋| 1.64G/1.65G [00:23<00:00, 87.5MB/s]
100%|████████████████████████████████████▊| 1.65G/1.65G [00:23<00:00, 88.0MB/s]
0%| | 0.00/1.65G [00:00<?, ?B/s]
100%|█████████████████████████████████████| 1.65G/1.65G [00:00<00:00, 8.17TB/s]
Attempting to create new mne-python configuration file:
/home/runner/.mne/mne-python.json
Could not read the /home/runner/.mne/mne-python.json json file during the writing. Assuming it is empty. Got: Expecting value: line 1 column 1 (char 0)
Download complete in 49s (1576.2 MB)
1588 events across 2 subjects
type start duration timeline
0 Meg 42.955971 277.715346 Fake2025Meg:subject=sample0
1 Text 46.578924 210.637433 Fake2025Meg:subject=sample0
2 Audio 46.578924 210.637375 Fake2025Meg:subject=sample0
3 Sentence 46.578924 2.264551 Fake2025Meg:subject=sample0
4 Word 46.578924 0.200000 Fake2025Meg:subject=sample0
5 Stimulus 46.578924 0.006660 Fake2025Meg:subject=sample0
6 Word 47.191629 0.200000 Fake2025Meg:subject=sample0
7 Image 47.191629 0.200000 Fake2025Meg:subject=sample0
Inspecting Timelines¶
Before loading data, study_summary() shows one row per timeline
with metadata columns:
summary = study.study_summary(apply_query=False)
print(summary[["subject", "timeline"]].to_string())
subject timeline
0 Fake2025Meg/sample0 Fake2025Meg:subject=sample0
1 Fake2025Meg/sample1 Fake2025Meg:subject=sample1
Querying Timelines¶
Use the query parameter to filter which timelines get loaded.
The query string is evaluated by query_with_index(),
which auto-generates virtual index columns such as timeline_index
and subject_timeline_index so you can slice by position:
study_q = ns.Study(
name="Fake2025Meg",
path=ns.CACHE_FOLDER,
query="timeline_index < 1",
)
events_q = study_q.run()
print(f"With query: {events_q.timeline.nunique()} timelines, {len(events_q)} events")
With query: 1 timelines, 794 events
Downloading Data¶
For real studies, call study.download() before run() to
fetch the raw data to the study path. This is a one-time operation:
Many curated studies handle downloading from OpenNeuro automatically.
Tip
path can be a shared parent folder — each study resolves
its own subfolder automatically. This lets all studies share one
path, so you only need to configure it once.
Caching¶
Study loading can be cached via the infra parameter. infra.folder
automatically propagates to timelines.infra.folder, so a single
infra caches both the merged events DataFrame and each timeline:
Cache modes (set via infra.mode, also propagates):
Mode |
Behaviour |
|---|---|
|
Use cache if available, compute otherwise |
|
Recompute this step and all downstream steps |
|
Recompute only if previous run failed |
|
Only read from cache; error if not cached |
See Caching & Cluster Execution for all backend options and
cluster configuration (including how to disable parallel timeline
loading via timelines={"infra": None} when debugging).
Create Your Own (optional)¶
To create a custom study, subclass Study
and implement iter_timelines() and _load_timeline_events().
If your data uses non-standard event types, define them as
Event subclasses — they are automatically
registered and can carry any typed fields you need:
import typing as tp
import pandas as pd
from neuralset.events import etypes
class FaceStimulus(etypes.Event):
"""Custom event for face stimuli."""
identity: str = ""
expression: str = "neutral"
class FaceStudy(ns.Study):
"""A minimal study generating synthetic face events."""
def iter_timelines(self) -> tp.Iterator[dict[str, tp.Any]]:
for subject in ["alice", "bob"]:
yield dict(subject=subject)
def _load_timeline_events(self, timeline: dict[str, tp.Any]) -> pd.DataFrame:
rows = [
dict(
type="FaceStimulus",
start=float(i),
duration=2.0,
identity=f"face_{i:03d}",
expression=expr,
)
for i, expr in enumerate(["happy", "neutral", "sad"])
]
return pd.DataFrame(rows)
The same run() interface works for custom studies:
import tempfile
from pathlib import Path
# ``timelines={"infra": None}`` loads timelines inline and uncached, so the
# locally-defined FaceStudy class never needs to be pickled to worker processes.
custom_study = FaceStudy(path=Path(tempfile.mkdtemp()), timelines={"infra": None})
custom_events = custom_study.run()
print(custom_events[["type", "start", "identity", "expression", "timeline"]].to_string())
type start identity expression timeline
0 FaceStimulus 0.0 face_000 happy FaceStudy:subject=alice
1 FaceStimulus 1.0 face_001 neutral FaceStudy:subject=alice
2 FaceStimulus 2.0 face_002 sad FaceStudy:subject=alice
3 FaceStimulus 0.0 face_000 happy FaceStudy:subject=bob
4 FaceStimulus 1.0 face_001 neutral FaceStudy:subject=bob
5 FaceStimulus 2.0 face_002 sad FaceStudy:subject=bob
For a full worked example with real MEG data, channel positions, and NeuralFetch integration, see the NeuralFetch extending tutorial.
Next Steps¶
Modify events with transforms: Transforms
Extract features from events: Extractors
Total running time of the script: (0 minutes 50.481 seconds)