Skip to content

Commit af20ae6

Browse files
bruAristimunhabruAristimunha
committed
1 parent 2ae28e4 commit af20ae6

97 files changed

Lines changed: 2093 additions & 549 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎dev/_downloads/07fcc19ba03226cd3d83d4e40ec44385/auto_examples_python.zip‎

8.81 KB
Binary file not shown.

‎dev/_downloads/137d0b161de96c88644fd65258fc20b5/tutorial_create_fixed_window_length.ipynb‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"\n# Fixed-Length Windows Extraction\n :depth: 2\n"
8+
]
9+
},
10+
{
11+
"cell_type": "markdown",
12+
"metadata": {},
13+
"source": [
14+
"## Introduction to Fixed-Length Windows Function\n\nIn many EEG decoding tasks, such as self-supervised pre-training,\nit is useful to split long continuous recordings\ninto **fixed-length, overlapping or non-overlapping windows**\n\nThe function :func:`braindecode.preprocessing.create_fixed_length_windows`\nprovides an easy way to slice a continuous EEG recording into such windows.\n\nThis tutorial explains how to use it, what its parameters mean, and how\nit can be applied to EEG datasets.\n\n\n"
15+
]
16+
},
17+
{
18+
"cell_type": "markdown",
19+
"metadata": {},
20+
"source": [
21+
"## Overview of create_fixed_length_windows\n\nThe function:\n\n```python\ncreate_fixed_length_windows(\n concat_ds,\n start_offset_samples=0,\n stop_offset_samples=None,\n window_size_samples=None,\n window_stride_samples=None,\n drop_last_window=None,\n mapping=None,\n preload=False,\n picks=None,\n reject=None,\n flat=None,\n targets_from='metadata',\n last_target_only=True,\n lazy_metadata=False,\n on_missing='error',\n n_jobs=1,\n verbose='error',\n)\n```\n"
22+
]
23+
},
24+
{
25+
"cell_type": "markdown",
26+
"metadata": {},
27+
"source": [
28+
"## Parameters\n\n**concat_ds** : `ConcatDataset`\n - A concat of base datasets each holding raw and description.\n\n**start_offset_samples** : int (default=0)\n - Start offset from beginning of recording in samples.\n\n**stop_offset_samples** : int or None (default=None)\n - Stop offset from beginning of recording in samples. If None, set to be the end of the recording.\n\n**window_size_samples** : int or None\n - Window size in samples. If None, set to be the maximum possible window size, ie length of the recording, once offsets are accounted for.\n\n**window_stride_samples** : int or None\n - Stride between windows in samples. If None, set to be equal to winddow_size_samples, so windows will not overlap.\n\n**drop_last_window** : bool or None\n - Whether or not have a last overlapping window, when windows do not equally divide the continuous signal. Must be set to a bool if window size and stride are not None.\n\n**mapping** : dict(str: int) or None\n - Mapping from event description to target value.\n\n**preload** : bool (default=False)\n - If True, preload the data of the Epochs objects.\n\n**picks** : str | list | slice | None\n - Channels to include. If None, all available channels are used. See mne.Epochs.\n\n**reject** : dict or None\n - Epoch rejection parameters based on peak-to-peak amplitude. If None, no rejection is done based on peak-to-peak amplitude. See mne.Epochs.\n\n**flat** : dict or None\n - Epoch rejection parameters based on flatness of signals. If None, no rejection based on flatness is done. See mne.Epochs.\n\n**targets_from** : str (default='metadata')\n - Choose where to get targets from: either 'metadata' or 'events'\n\n**last_target_only** : bool (default=True)\n - If `True`, only use the last target in the window.\n\n**lazy_metadata** : bool (default=False)\n - If True, metadata is not computed immediately, but only when accessed by using the _LazyDataFrame (experimental).\n\n**on_missing** : str (default='error')\n - What to do if one or several event ids are not found in the recording. Valid keys are \u2018error\u2019 | \u2018warning\u2019 | \u2018ignore\u2019. See mne.Epochs.\n\n**n_jobs** : int (default=1)\n - Number of jobs to use to parallelize the windowing.\n\n**verbose** : bool | str | int | None\n - Control verbosity of the logging output when calling mne.Epochs.\n\n"
29+
]
30+
},
31+
{
32+
"cell_type": "markdown",
33+
"metadata": {},
34+
"source": [
35+
"## Example 1: Basic 2-Second, 50% Overlapping Windows\n\n\n"
36+
]
37+
},
38+
{
39+
"cell_type": "code",
40+
"execution_count": null,
41+
"metadata": {
42+
"collapsed": false
43+
},
44+
"outputs": [],
45+
"source": [
46+
"from numpy import multiply\n\nfrom braindecode.datasets import MOABBDataset\nfrom braindecode.preprocessing import (\n Filter,\n Pick,\n Preprocessor,\n create_fixed_length_windows,\n preprocess,\n)"
47+
]
48+
},
49+
{
50+
"cell_type": "code",
51+
"execution_count": null,
52+
"metadata": {
53+
"collapsed": false
54+
},
55+
"outputs": [],
56+
"source": [
57+
"# Load the EEG dataset\ndataset = MOABBDataset(dataset_name=\"BNCI2014_001\", subject_ids=[1])"
58+
]
59+
},
60+
{
61+
"cell_type": "markdown",
62+
"metadata": {},
63+
"source": [
64+
"Preprocessing\n\n"
65+
]
66+
},
67+
{
68+
"cell_type": "code",
69+
"execution_count": null,
70+
"metadata": {
71+
"collapsed": false
72+
},
73+
"outputs": [],
74+
"source": [
75+
"preprocessors = [\n Pick(eeg=True, meg=False, stim=False),\n Preprocessor(lambda data: multiply(data, 1e6)),\n Filter(l_freq=4.0, h_freq=38.0),\n]\npreprocess(dataset, preprocessors)\n\n# Sampling frequency\nsfreq = dataset.datasets[0].raw.info[\"sfreq\"]"
76+
]
77+
},
78+
{
79+
"cell_type": "markdown",
80+
"metadata": {},
81+
"source": [
82+
"Create windows\n\n"
83+
]
84+
},
85+
{
86+
"cell_type": "code",
87+
"execution_count": null,
88+
"metadata": {
89+
"collapsed": false
90+
},
91+
"outputs": [],
92+
"source": [
93+
"window_size_samples = int(sfreq * 2) # 2-second windows\nwindow_stride_samples = int(window_size_samples * 0.5) # 50% overlap\n\nwindows_dataset = create_fixed_length_windows(\n concat_ds=dataset,\n start_offset_samples=0,\n stop_offset_samples=None,\n window_size_samples=window_size_samples,\n window_stride_samples=window_stride_samples,\n drop_last_window=True,\n mapping=None,\n preload=True,\n picks=\"eeg\", # Only EEG channels\n reject=dict(eeg=150e-6), # Reject windows where EEG p2p > 150 \u00b5V\n flat=None,\n targets_from=\"metadata\",\n last_target_only=True,\n on_missing=\"warning\",\n n_jobs=1,\n verbose=\"error\",\n)\n\n# Let's inspect the output to better understand what we created.\n\n# Check how many windows were created\nprint(f\"Number of windows: {len(windows_dataset)}\")\n\n# Each window contains EEG data of fixed size\nX, y = windows_dataset[0]\nprint(f\"Window data shape: {X.shape}\")\nprint(f\"Window label: {y}\")"
94+
]
95+
},
96+
{
97+
"cell_type": "markdown",
98+
"metadata": {},
99+
"source": [
100+
"## Working with Targets\nIn `create_fixed_length_windows`, targets can be derived in two ways:\n\n1. From the recording metadata (e.g., \"session\", \"condition\"). This is the default when `targets_from='metadata'`.\n2. From signal channels themselves when `targets_from='channels'`, useful for cases like sleep staging where\n annotations are stored in auxiliary channels.\n\n\nAdditionally:\n\n- **mapping**: Optionally map target values (e.g. from \"0train\" / \"1test\" to 0 / 1).\n- **last_target_only=True** (default): If multiple targets are present within a window (as in time-varying labels),\n use only the final target value in that window.\n\n"
101+
]
102+
},
103+
{
104+
"cell_type": "code",
105+
"execution_count": null,
106+
"metadata": {
107+
"collapsed": false
108+
},
109+
"outputs": [],
110+
"source": [
111+
"# Example: mapping session names (\"0train\" and \"1test\") to integers\n\nmapping = {\"0train\": 0, \"1test\": 1}\n\nwindows_dataset = create_fixed_length_windows(\n dataset,\n window_size_samples=window_size_samples,\n window_stride_samples=window_stride_samples,\n drop_last_window=True,\n mapping=mapping,\n preload=True,\n)\n\n# View first few targets\nprint(\"Targets for first 10 windows:\")\nprint(windows_dataset.datasets[0].windows.get_metadata()[\"target\"][:10])"
112+
]
113+
},
114+
{
115+
"cell_type": "markdown",
116+
"metadata": {},
117+
"source": [
118+
"## Example: Rejecting Windows Based on Amplitude\n\nYou can set rejection criteria to exclude windows with extreme values:\n\n"
119+
]
120+
},
121+
{
122+
"cell_type": "code",
123+
"execution_count": null,
124+
"metadata": {
125+
"collapsed": false
126+
},
127+
"outputs": [],
128+
"source": [
129+
"reject_criteria = dict(eeg=150e-6) # 150 \u00b5V max peak-to-peak allowed\n\nwindows_with_rejection = create_fixed_length_windows(\n concat_ds=dataset,\n window_size_samples=200,\n window_stride_samples=100,\n reject=reject_criteria,\n drop_last_window=True,\n)\n\nprint(windows_with_rejection)"
130+
]
131+
},
132+
{
133+
"cell_type": "markdown",
134+
"metadata": {},
135+
"source": [
136+
"## Example: Using lazy metadata generation\n\nFor large datasets, it can be faster to generate metadata on-demand:\n\n"
137+
]
138+
},
139+
{
140+
"cell_type": "code",
141+
"execution_count": null,
142+
"metadata": {
143+
"collapsed": false
144+
},
145+
"outputs": [],
146+
"source": [
147+
"lazy_windows = create_fixed_length_windows(\n concat_ds=dataset,\n window_size_samples=200,\n window_stride_samples=100,\n drop_last_window=True,\n lazy_metadata=True,\n)\n\nprint(lazy_windows)"
148+
]
149+
},
150+
{
151+
"cell_type": "markdown",
152+
"metadata": {},
153+
"source": [
154+
"## Example: Shifted Windows\n\nYou can also create shifted windows by using ``start_offset_samples`` or ``stop_offset_samples``.\nFor example, start windowing 500 ms later into the recording.\n\n"
155+
]
156+
},
157+
{
158+
"cell_type": "code",
159+
"execution_count": null,
160+
"metadata": {
161+
"collapsed": false
162+
},
163+
"outputs": [],
164+
"source": [
165+
"start_offset_seconds = 0.5\nstart_offset_samples = int(start_offset_seconds * sfreq)\n\nshifted_windows_dataset = create_fixed_length_windows(\n dataset,\n start_offset_samples=start_offset_samples,\n window_size_samples=window_size_samples,\n window_stride_samples=window_stride_samples,\n drop_last_window=True,\n preload=True,\n)\n\nprint(f\"Number of shifted windows: {len(shifted_windows_dataset)}\")"
166+
]
167+
}
168+
],
169+
"metadata": {
170+
"kernelspec": {
171+
"display_name": "Python 3",
172+
"language": "python",
173+
"name": "python3"
174+
},
175+
"language_info": {
176+
"codemirror_mode": {
177+
"name": "ipython",
178+
"version": 3
179+
},
180+
"file_extension": ".py",
181+
"mimetype": "text/x-python",
182+
"name": "python",
183+
"nbconvert_exporter": "python",
184+
"pygments_lexer": "ipython3",
185+
"version": "3.12.12"
186+
}
187+
},
188+
"nbformat": 4,
189+
"nbformat_minor": 0
190+
}

0 commit comments

Comments
 (0)