{ "cells": [ { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "# Spectral analyses" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "## Introductory notes:\n", "This notebook presents spectral analyses functionality:\n", "* Power spectral density (PSD) per sleep stage\n", "* Spectrogram & hypnogram\n", "* Topomaps for the spectra per sleep stage\n", "* Spectral parametrization with FOOOF\n", "* Additional results such as sleep statistics.\n", "\n", "Recommended watching and reading:\n", "1. [Mike X Cohen: Static spectral analysis](https://youtube.com/playlist?list=PLn0OLiymPak2jxGCbWrcgmXUtt9Lbjj_A)\n", "2. [MNE: The Spectrum and EpochsSpectrum classes: frequency-domain data](https://mne.tools/stable/auto_tutorials/time-freq/10_spectrum_class.html#)\n", "3. [FOOOF: Tutorials](https://fooof-tools.github.io/fooof/auto_tutorials/index.html)\n", "4. [MNE: SpectrumArray class](https://mne.tools/stable/generated/mne.time_frequency.SpectrumArray.html)" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "## Import data" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "### Import module" ] }, { "cell_type": "code", "execution_count": 1, "metadata": { "ExecuteTime": { "end_time": "2024-08-06T10:28:51.815149Z", "start_time": "2024-08-06T10:28:50.805578Z" } }, "outputs": [], "source": [ "from sleepeegpy.pipeline import SpectralPipe\n", "from os import makedirs,path\n", "import mne\n", "mne.set_log_level('ERROR')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "By default, all the input files are assumed to be saved in input_files, which will be created (if not already exists) in the notebook path.\n", "Change the following string to use another path" ] }, { "cell_type": "code", "execution_count": 2, "metadata": { "ExecuteTime": { "end_time": "2024-08-06T10:28:56.171331Z", "start_time": "2024-08-06T10:28:56.167805Z" } }, "outputs": [], "source": [ "output_dir = \"output_folder\" # Output path and name can be changed here\n", "input_dir = \"input_files\" # input files dir can be changed here\n", "makedirs(input_dir, exist_ok=True)\n", "makedirs(output_dir, exist_ok=True)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Add required files\n", "* Put all your files in the input folder.\n", "* Modify your eeg file name below. The file can be any format supported by the mne.read_raw() function.\n", "* Modify your hypnogram file name (Point-per-row type of hypnogram) below.\n", "* If needed, change Hypnogram's sampling frequency \n", "* For more information about the supported formats, see [mne documentation](https://mne.tools/stable/generated/mne.io.Raw.html)" ] }, { "cell_type": "code", "execution_count": 3, "metadata": { "ExecuteTime": { "end_time": "2024-08-06T10:28:57.628705Z", "start_time": "2024-08-06T10:28:57.625830Z" } }, "outputs": [], "source": [ "eeg_file_name= \"cleaned_raw.fif\" # add your eeg_path here\n", "hypnogram_filename = \"staging.txt\" # Point-per-row type of hypnogram.\n", "hypno_freq = 1 # If required, change Hypnogram's sampling frequency (visbrain's hypnograms default to 1)" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "### Initialize SpectralPipe object" ] }, { "cell_type": "code", "execution_count": 4, "metadata": { "ExecuteTime": { "end_time": "2024-08-06T10:29:02.254784Z", "start_time": "2024-08-06T10:28:59.465933Z" } }, "outputs": [ { "name": "stderr", "output_type": "stream", "text": [ "Hypnogram is SHORTER than data by 0.43 seconds. Padding hypnogram with last value to match data.size.\n" ] } ], "source": [ "path_to_eeg = path.join(input_dir,eeg_file_name)\n", "hypnogram_path = path.join(input_dir,hypnogram_filename)\n", "assert path.isfile(path_to_eeg) and path.isfile(hypnogram_path), f\"{path_to_eeg} or {hypnogram_path} not exist\"\n", "\n", "spectral_pipe = SpectralPipe(\n", " path_to_eeg=path_to_eeg, \n", " output_dir=output_dir,\n", " path_to_hypno=hypnogram_path,\n", " hypno_freq=hypno_freq, \n", ")" ] }, { "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ "## Compute PSD" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "ExecuteTime": { "end_time": "2024-08-06T10:29:06.378672Z", "start_time": "2024-08-06T10:29:05.034643Z" } }, "outputs": [], "source": [ "spectral_pipe.compute_psd(\n", " # A dict describing stages and their indices in the hypnogram file.\n", " sleep_stages={\"Wake\": 0, \"N1\": 1, \"N2\": 2, \"N3\": 3, \"REM\": 4},\n", " # Rereferencing to apply. Can be list of str channels or \"average\".\n", " # If None, will not change the reference.\n", " reference=\"average\",\n", " fmin=0, # Lower frequency bound.\n", " fmax=60, # Upper frequency bound.\n", " picks=\"eeg\", # Channels to compute the PSD for.\n", " reject_by_annotation=True, # Whether to reject epochs annotated as BAD.\n", " save=True, # Whether to save the PSD hdf5 file for each sleep stage.\n", " overwrite=True, # Whether to overwrite hdf5 files if there are any.\n", " # Additional arguments passed to the PSD computing method, i.e., welch or multitaper:\n", " n_fft=1024,\n", " n_per_seg=1024,\n", " n_overlap=512,\n", " window=\"hamming\",\n", " n_jobs=-1, \n", " verbose=False, \n", ")" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "ExecuteTime": { "end_time": "2024-08-06T10:29:15.088131Z", "start_time": "2024-08-06T10:29:15.076810Z" } }, "outputs": [ { "data": { "text/plain": [ "array([[1.20544608e-10, 9.13856487e-10, 4.32137885e-10, ...,\n", " 2.00851069e-14, 2.02085506e-14, 1.96803265e-14],\n", " [9.16359851e-11, 6.92785547e-10, 3.43649234e-10, ...,\n", " 1.07580601e-14, 1.03970152e-14, 1.02861636e-14],\n", " [4.65226376e-11, 3.45777189e-10, 1.85735238e-10, ...,\n", " 1.18917446e-14, 1.20680226e-14, 1.20086151e-14],\n", " ...,\n", " [2.18358859e-11, 1.40802821e-10, 8.09673291e-11, ...,\n", " 1.62120327e-14, 1.51799036e-14, 1.53065000e-14],\n", " [9.57268940e-12, 6.17214444e-11, 3.82661443e-11, ...,\n", " 1.17953057e-14, 1.11716153e-14, 1.09855943e-14],\n", " [1.02225625e-11, 6.66994068e-11, 5.10107331e-11, ...,\n", " 3.09470840e-14, 3.19075520e-14, 3.06672304e-14]])" ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "spectral_pipe.psds[\"REM\"].get_data()" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "ExecuteTime": { "end_time": "2024-08-06T10:29:16.408054Z", "start_time": "2024-08-06T10:29:16.395687Z" } }, "outputs": [ { "data": { "text/html": [ "
\n", " | freq | \n", "E1 | \n", "E2 | \n", "E3 | \n", "E4 | \n", "E5 | \n", "E6 | \n", "E7 | \n", "E8 | \n", "E9 | \n", "... | \n", "E248 | \n", "E249 | \n", "E250 | \n", "E251 | \n", "E252 | \n", "E253 | \n", "E254 | \n", "E255 | \n", "E256 | \n", "VREF | \n", "
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
0 | \n", "0.000000 | \n", "1.205446e-10 | \n", "9.163599e-11 | \n", "4.652264e-11 | \n", "2.361730e-11 | \n", "1.874374e-11 | \n", "1.450813e-11 | \n", "2.218452e-11 | \n", "1.122231e-11 | \n", "9.538333e-12 | \n", "... | \n", "1.817369e-10 | \n", "6.496992e-11 | \n", "2.793785e-11 | \n", "2.312580e-11 | \n", "2.281494e-10 | \n", "6.776294e-11 | \n", "4.518227e-11 | \n", "2.183589e-11 | \n", "9.572689e-12 | \n", "1.022256e-11 | \n", "
1 | \n", "0.244141 | \n", "9.138565e-10 | \n", "6.927855e-10 | \n", "3.457772e-10 | \n", "1.662492e-10 | \n", "1.119225e-10 | \n", "8.076044e-11 | \n", "9.857186e-11 | \n", "6.725583e-11 | \n", "5.687559e-11 | \n", "... | \n", "1.323533e-09 | \n", "4.610354e-10 | \n", "1.892631e-10 | \n", "1.584058e-10 | \n", "1.669154e-09 | \n", "5.028152e-10 | \n", "3.291209e-10 | \n", "1.408028e-10 | \n", "6.172144e-11 | \n", "6.669941e-11 | \n", "
2 | \n", "0.488281 | \n", "4.321379e-10 | \n", "3.436492e-10 | \n", "1.857352e-10 | \n", "1.034098e-10 | \n", "7.332040e-11 | \n", "5.620539e-11 | \n", "5.915940e-11 | \n", "5.096347e-11 | \n", "4.554884e-11 | \n", "... | \n", "6.524901e-10 | \n", "2.370033e-10 | \n", "1.048493e-10 | \n", "8.556182e-11 | \n", "8.178159e-10 | \n", "2.516436e-10 | \n", "1.669304e-10 | \n", "8.096733e-11 | \n", "3.826614e-11 | \n", "5.101073e-11 | \n", "
3 | \n", "0.732422 | \n", "1.305058e-10 | \n", "1.122229e-10 | \n", "6.907628e-11 | \n", "4.777266e-11 | \n", "3.865387e-11 | \n", "3.290459e-11 | \n", "3.159175e-11 | \n", "3.215459e-11 | \n", "2.766479e-11 | \n", "... | \n", "2.076041e-10 | \n", "8.276927e-11 | \n", "4.225638e-11 | \n", "3.487731e-11 | \n", "2.510315e-10 | \n", "8.321513e-11 | \n", "6.082972e-11 | \n", "3.462790e-11 | \n", "1.804304e-11 | \n", "3.009207e-11 | \n", "
4 | \n", "0.976562 | \n", "5.479270e-11 | \n", "4.879642e-11 | \n", "3.398966e-11 | \n", "2.742932e-11 | \n", "2.447354e-11 | \n", "2.202644e-11 | \n", "2.154214e-11 | \n", "2.232954e-11 | \n", "1.853072e-11 | \n", "... | \n", "8.822444e-11 | \n", "3.922727e-11 | \n", "2.295007e-11 | \n", "2.046545e-11 | \n", "1.020850e-10 | \n", "3.707458e-11 | \n", "2.900152e-11 | \n", "1.940715e-11 | \n", "1.125545e-11 | \n", "1.945493e-11 | \n", "
... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "... | \n", "
241 | \n", "58.837891 | \n", "2.052002e-14 | \n", "1.080107e-14 | \n", "1.185645e-14 | \n", "9.236874e-15 | \n", "9.386774e-15 | \n", "9.163107e-15 | \n", "1.086743e-14 | \n", "1.460974e-14 | \n", "1.055531e-14 | \n", "... | \n", "2.084268e-14 | \n", "2.363470e-14 | \n", "1.887338e-14 | \n", "2.243271e-14 | \n", "1.669183e-14 | \n", "1.151799e-14 | \n", "1.420598e-14 | \n", "1.654172e-14 | \n", "1.119376e-14 | \n", "3.135501e-14 | \n", "
242 | \n", "59.082031 | \n", "2.008716e-14 | \n", "1.057612e-14 | \n", "1.171000e-14 | \n", "9.409765e-15 | \n", "8.857569e-15 | \n", "9.199416e-15 | \n", "1.060803e-14 | \n", "1.466554e-14 | \n", "9.855808e-15 | \n", "... | \n", "2.169877e-14 | \n", "2.232925e-14 | \n", "1.901087e-14 | \n", "2.242874e-14 | \n", "1.711121e-14 | \n", "1.185718e-14 | \n", "1.410618e-14 | \n", "1.592892e-14 | \n", "1.118600e-14 | \n", "2.988033e-14 | \n", "
243 | \n", "59.326172 | \n", "2.008511e-14 | \n", "1.075806e-14 | \n", "1.189174e-14 | \n", "9.523270e-15 | \n", "8.751198e-15 | \n", "9.190660e-15 | \n", "1.006159e-14 | \n", "1.388243e-14 | \n", "9.746180e-15 | \n", "... | \n", "2.054704e-14 | \n", "2.285352e-14 | \n", "1.953269e-14 | \n", "2.312350e-14 | \n", "1.555995e-14 | \n", "1.160546e-14 | \n", "1.403677e-14 | \n", "1.621203e-14 | \n", "1.179531e-14 | \n", "3.094708e-14 | \n", "
244 | \n", "59.570312 | \n", "2.020855e-14 | \n", "1.039702e-14 | \n", "1.206802e-14 | \n", "9.175959e-15 | \n", "8.892312e-15 | \n", "8.748358e-15 | \n", "1.008715e-14 | \n", "1.370326e-14 | \n", "9.504832e-15 | \n", "... | \n", "2.022414e-14 | \n", "2.315599e-14 | \n", "1.872794e-14 | \n", "2.186576e-14 | \n", "1.540562e-14 | \n", "1.114618e-14 | \n", "1.346594e-14 | \n", "1.517990e-14 | \n", "1.117162e-14 | \n", "3.190755e-14 | \n", "
245 | \n", "59.814453 | \n", "1.968033e-14 | \n", "1.028616e-14 | \n", "1.200862e-14 | \n", "9.139879e-15 | \n", "8.727308e-15 | \n", "8.709531e-15 | \n", "1.034216e-14 | \n", "1.343112e-14 | \n", "9.215188e-15 | \n", "... | \n", "2.012729e-14 | \n", "2.342522e-14 | \n", "1.859850e-14 | \n", "2.136766e-14 | \n", "1.595666e-14 | \n", "1.116042e-14 | \n", "1.342614e-14 | \n", "1.530650e-14 | \n", "1.098559e-14 | \n", "3.066723e-14 | \n", "
246 rows × 258 columns
\n", "