notebooks/08_bandpower.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# EEG bandpower\n",
    "\n",
    "This notebook demonstrates how to use YASA to calculate the spectral bandpower per channel and per sleep stage.\n",
    "\n",
    "Please make sure to install the latest version of YASA first by typing the following line in your terminal or command prompt:\n",
    "\n",
    "`pip install --upgrade yasa`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mne\n",
    "import yasa\n",
    "import numpy as np\n",
    "import seaborn as sns\n",
    "import matplotlib.pyplot as plt\n",
    "sns.set(style='white', font_scale=1.2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Data loading\n",
    "\n",
    "### EEG data\n",
    "\n",
    "Let's load ~45 min of mid-afternoon nap data (6 channels), sampled at 100 Hz. We use the [MNE library](https://mne.tools/stable/index.html), which includes various functions and utilities for reading EEG data and electrode locations. For a description of all the file formats supported by MNE, please refer to https://mne.tools/stable/auto_tutorials/io/plot_20_reading_eeg_data.html"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Chan = ['F3', 'F4', 'C3', 'C4', 'O1', 'O2']\n",
      "Sampling frequency = 100.0 Hz\n",
      "Data shape = (6, 294000)\n"
     ]
    }
   ],
   "source": [
    "# Load data as a MNE Raw file\n",
    "raw = mne.io.read_raw_fif('sub-02_mne_raw.fif', preload=True, verbose=0)\n",
    "\n",
    "# Keep only the EEG channels\n",
    "raw.pick_types(eeg=True)\n",
    "\n",
    "# Apply a bandpass filter between 0.5 - 45 Hz\n",
    "raw.filter(0.5, 45)\n",
    "\n",
    "# Extract the data and convert from V to uV\n",
    "data = raw.get_data(units=\"uV\")\n",
    "sf = raw.info['sfreq']\n",
    "chan = raw.ch_names\n",
    "\n",
    "# Let's have a look at the data\n",
    "print('Chan =', chan)\n",
    "print('Sampling frequency =', sf, 'Hz')\n",
    "print('Data shape =', data.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Hypnogram\n",
    "\n",
    "Let's now load the corresponding hypnogram (sleep staging) vector. In this case, the hypnogram is a simple text file in which one value represents 30 seconds of EEG data.\n",
    "\n",
    "The sleep stages are defined according to the [standard guidelines](https://aasm.org/clinical-resources/scoring-manual/):\n",
    "\n",
    "    W: Wake\n",
    "    N1: N1 sleep\n",
    "    N2: N2 sleep\n",
    "    N3: N3 sleep\n",
    "    R: REM sleep"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array(['W', 'W', 'W', 'W', 'W', 'W', 'W', 'W', 'W', 'W', 'W', 'W', 'W',\n",
       "       'W', 'W', 'W', 'W', 'W', 'W', 'W', 'W', 'W', 'N1', 'W', 'W', 'W',\n",
       "       'W', 'N1', 'N1', 'N1', 'W', 'W', 'N1', 'N1', 'N1', 'N1', 'N2',\n",
       "       'N2', 'N2', 'W', 'N1', 'N2', 'N2', 'N2', 'N2', 'N2', 'N2', 'N2',\n",
       "       'N2', 'N2', 'N2', 'N2', 'N2', 'N2', 'N2', 'N2', 'N2', 'N2', 'N2',\n",
       "       'N2', 'N2', 'N2', 'N2', 'N2', 'N2', 'N2', 'N2', 'N2', 'N2', 'N3',\n",
       "       'N3', 'N3', 'N3', 'N3', 'N3', 'N3', 'N3', 'N3', 'N3', 'N3', 'N3',\n",
       "       'N3', 'N3', 'N3', 'N3', 'N3', 'N3', 'N3', 'N3', 'N3', 'N3', 'W',\n",
       "       'W', 'W', 'W', 'W', 'W', 'W'], dtype='<U2')"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hypno = np.loadtxt('sub-02_hypno_30s.txt', dtype=str)\n",
    "hypno"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Conversion str => int**\n",
    "\n",
    "Our first step is to convert this text vector into a vector of integers, which is easier to work with. The default mapping is defined below:\n",
    "\n",
    "    W  => 0\n",
    "    N1 => 1\n",
    "    N2 => 2\n",
    "    N3 => 3\n",
    "    R  => 4\n",
    "    \n",
    "However, you can also apply a custom mapping using the `mapping_dict=` argument of the [hypno_str_to_int](https://raphaelvallat.com/yasa/build/html/generated/yasa.hypno_str_to_int.html#yasa.hypno_str_to_int) function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,\n",
       "       1, 0, 0, 0, 0, 1, 1, 1, 0, 0, 1, 1, 1, 1, 2, 2, 2, 0, 1, 2, 2, 2,\n",
       "       2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2,\n",
       "       2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3,\n",
       "       3, 3, 3, 0, 0, 0, 0, 0, 0, 0])"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "hypno_int = yasa.hypno_str_to_int(hypno)\n",
    "hypno_int"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Upsampling**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The last step is to upsample our hypnogram to the sampling frequency of the data. This step is *absolutely critical* and all YASA's function require that the data and hypnogram have the same sampling frequency and shape -- which makes life so much easier to mask and select specific sleep stages.\n",
    "\n",
    "Fortunately, YASA also provides a convenient function ([hypno_upsample_to_data](https://raphaelvallat.com/yasa/build/html/generated/yasa.hypno_upsample_to_data.html#yasa.hypno_upsample_to_data)) to automatically upsample and fit the hypnogram to a given sampling frequency and data length.\n",
    "This function requires the hypnogram and its sampling frequency, as well as the data and its sampling frequency. In our case, the sampling frequency of our hypnogram is 1 / 30 since there is one point per every 30 seconds of data. The sampling frequency of the data is 100 Hz.\n",
    "\n",
    "Note that if the upsampled hypnogram is shorter or longer than the length of data, a warning will be displayed and the hypnogram will be automatically padded or cropped to exactly match the length of data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "True\n",
      "294000 samples: [0 0 0 ... 0 0 0]\n"
     ]
    }
   ],
   "source": [
    "hypno_up = yasa.hypno_upsample_to_data(hypno=hypno_int, sf_hypno=(1/30), data=data, sf_data=sf)\n",
    "print(hypno_up.size == data.shape[1])  # Does the hypnogram have the same number of samples as data?\n",
    "print(hypno_up.size, 'samples:', hypno_up)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**************\n",
    "\n",
    "## Bandpowers in NREM sleep\n",
    "\n",
    "*For a primer on EEG spectral bandpower please refer to https://raphaelvallat.com/bandpower.html*\n",
    "\n",
    "Now that we have our data and hypnogram, how can we calculate the spectral bandpowers in, let's say, N2 and N3 sleep (commonly referred to as NREM sleep)?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Keep only N2 + N3 sleep\n",
    "\n",
    "Our first step is to apply a masking on the data to only keep samples that are in N2 or N3 sleep. Since our data and hypnogram now have the same sampling frequency and shape, this can be done using a [simple NumPy indexing](https://docs.scipy.org/doc/numpy/reference/generated/numpy.isin.html):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(6, 159000)\n"
     ]
    }
   ],
   "source": [
    "where_NREM = np.isin(hypno_up, [2, 3])  # True if sample is in N2 / N3, False otherwise\n",
    "data_NREM = data[:, where_NREM]\n",
    "print(data_NREM.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Calculate Welch's PSD\n",
    "\n",
    "The gold-standard and most widely-used method to calculate the power spectral density (PSD) of EEG data is the [Welch's sliding periodogram](https://en.wikipedia.org/wiki/Welch%27s_method), which is implemented in [SciPy](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.welch.html).\n",
    "\n",
    "The Welch's method improves the accuracy of the [classic periodogram](https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.periodogram.html). The reason is simple: EEG data are always time-varying, meaning that if you look at a 30 seconds of EEG data, it is very (very) unlikely that the signal will looks like a perfect sum of pure sines. Rather, the spectral content of the EEG changes over time, constantly modified by the neuronal activity at play under the scalp. Problem is, to return a true spectral estimate, a classic periodogram requires the spectral content of the signal to be stationnary (i.e. time-unvarying) over the time period considered. Because it is never the case, the periodogram is generally biased and contains way too much variance. By averaging the periodograms obtained over short segments of the windows, the Welch's method allows to drastically reduce this variance. This comes at the cost, however, of a lower frequency resolution. The frequency resolution in Welch's method is defined by the window length, such that $F = 1 / t$, with $t$ being the window length in seconds. In other words, a 4-sec sliding window will give a frequency resolution of 1 / 4 = 0.25 Hz.\n",
    "\n",
    "How do we define the optimal window duration then? A commonly used approach is to take a window sufficiently long to encompasses at least two full cycles of the lowest frequency of interest. So for instance, if our lowest frequency of interest is 1 Hz so we will choose a window of 2 / 1 = 2 seconds.\n",
    "\n",
    "Note that in the code below, I use a *median average* of all the resulting sliding windows. Indeed, this may result in less biased and more accurate PSD as explained [in this paper](https://www.biorxiv.org/content/10.1101/441626v2)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(201,) (6, 201)\n"
     ]
    },
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 432x288 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from scipy.signal import welch\n",
    "\n",
    "win = int(4 * sf)  # Window size is set to 4 seconds\n",
    "freqs, psd = welch(data_NREM, sf, nperseg=win, average='median')  # Works with single or multi-channel data\n",
    "\n",
    "print(freqs.shape, psd.shape)  # psd has shape (n_channels, n_frequencies)\n",
    "\n",
    "# Plot\n",
    "plt.plot(freqs, psd[1], 'k', lw=2)\n",
    "plt.fill_between(freqs, psd[1], cmap='Spectral')\n",
    "plt.xlim(0, 50)\n",
    "plt.yscale('log')\n",
    "sns.despine()\n",
    "plt.title(chan[1])\n",
    "plt.xlabel('Frequency [Hz]')\n",
    "plt.ylabel('PSD log($uV^2$/Hz)');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Extract bandpower\n",
    "\n",
    "Now that we have the PSD for each channel, we need to calculate the average power in specified bands. The power in a frequency band is defined by the area under the curve of the non-log-transformed PSD. For more details, please refer to https://raphaelvallat.com/bandpower.html.\n",
    "\n",
    "Here again, YASA provides a convenient function ([bandpower_from_psd](https://raphaelvallat.com/yasa/build/html/generated/yasa.bandpower_from_psd.html#yasa.bandpower_from_psd)) to extract the average bandpower in specified bands from a pre-computed PSD."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Relative power**\n",
    "\n",
    "Note that the `TotalAbsPow` column contains the total absolute (physical) power, summed across all bands."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Chan</th>\n",
       "      <th>Delta</th>\n",
       "      <th>Theta</th>\n",
       "      <th>Alpha</th>\n",
       "      <th>Sigma</th>\n",
       "      <th>Beta</th>\n",
       "      <th>Gamma</th>\n",
       "      <th>TotalAbsPow</th>\n",
       "      <th>FreqRes</th>\n",
       "      <th>Relative</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>F3</td>\n",
       "      <td>0.714872</td>\n",
       "      <td>0.166226</td>\n",
       "      <td>0.070516</td>\n",
       "      <td>0.037181</td>\n",
       "      <td>0.010598</td>\n",
       "      <td>0.000607</td>\n",
       "      <td>171.857703</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>F4</td>\n",
       "      <td>0.719722</td>\n",
       "      <td>0.140793</td>\n",
       "      <td>0.066615</td>\n",
       "      <td>0.041250</td>\n",
       "      <td>0.030450</td>\n",
       "      <td>0.001170</td>\n",
       "      <td>148.775375</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>C3</td>\n",
       "      <td>0.708896</td>\n",
       "      <td>0.151639</td>\n",
       "      <td>0.079097</td>\n",
       "      <td>0.046435</td>\n",
       "      <td>0.013303</td>\n",
       "      <td>0.000629</td>\n",
       "      <td>135.059684</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>C4</td>\n",
       "      <td>0.678407</td>\n",
       "      <td>0.137858</td>\n",
       "      <td>0.081388</td>\n",
       "      <td>0.055760</td>\n",
       "      <td>0.044579</td>\n",
       "      <td>0.002008</td>\n",
       "      <td>122.226789</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>O1</td>\n",
       "      <td>0.664873</td>\n",
       "      <td>0.151314</td>\n",
       "      <td>0.101223</td>\n",
       "      <td>0.068387</td>\n",
       "      <td>0.013804</td>\n",
       "      <td>0.000399</td>\n",
       "      <td>769.863787</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>O2</td>\n",
       "      <td>0.663774</td>\n",
       "      <td>0.157096</td>\n",
       "      <td>0.094293</td>\n",
       "      <td>0.066035</td>\n",
       "      <td>0.018334</td>\n",
       "      <td>0.000468</td>\n",
       "      <td>670.168631</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  Chan     Delta     Theta     Alpha     Sigma      Beta     Gamma  \\\n",
       "0   F3  0.714872  0.166226  0.070516  0.037181  0.010598  0.000607   \n",
       "1   F4  0.719722  0.140793  0.066615  0.041250  0.030450  0.001170   \n",
       "2   C3  0.708896  0.151639  0.079097  0.046435  0.013303  0.000629   \n",
       "3   C4  0.678407  0.137858  0.081388  0.055760  0.044579  0.002008   \n",
       "4   O1  0.664873  0.151314  0.101223  0.068387  0.013804  0.000399   \n",
       "5   O2  0.663774  0.157096  0.094293  0.066035  0.018334  0.000468   \n",
       "\n",
       "   TotalAbsPow  FreqRes  Relative  \n",
       "0   171.857703     0.25      True  \n",
       "1   148.775375     0.25      True  \n",
       "2   135.059684     0.25      True  \n",
       "3   122.226789     0.25      True  \n",
       "4   769.863787     0.25      True  \n",
       "5   670.168631     0.25      True  "
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Relative power: sum of all (non-overlapping and sequential) bands equals to 1\n",
    "yasa.bandpower_from_psd(psd, freqs, ch_names=chan)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Absolute power**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[(1, 12, 'Slow'), (12, 30, 'Beta')]\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Chan</th>\n",
       "      <th>Slow</th>\n",
       "      <th>Beta</th>\n",
       "      <th>TotalAbsPow</th>\n",
       "      <th>FreqRes</th>\n",
       "      <th>Relative</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>F3</td>\n",
       "      <td>118.157078</td>\n",
       "      <td>8.211144</td>\n",
       "      <td>126.368222</td>\n",
       "      <td>0.25</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>F4</td>\n",
       "      <td>104.003894</td>\n",
       "      <td>10.667229</td>\n",
       "      <td>114.671123</td>\n",
       "      <td>0.25</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>C3</td>\n",
       "      <td>95.300966</td>\n",
       "      <td>8.068256</td>\n",
       "      <td>103.369221</td>\n",
       "      <td>0.25</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>C4</td>\n",
       "      <td>84.098698</td>\n",
       "      <td>12.264104</td>\n",
       "      <td>96.362801</td>\n",
       "      <td>0.25</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>O1</td>\n",
       "      <td>522.730225</td>\n",
       "      <td>63.275577</td>\n",
       "      <td>586.005802</td>\n",
       "      <td>0.25</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>5</th>\n",
       "      <td>O2</td>\n",
       "      <td>460.613075</td>\n",
       "      <td>56.541394</td>\n",
       "      <td>517.154469</td>\n",
       "      <td>0.25</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  Chan        Slow       Beta  TotalAbsPow  FreqRes  Relative\n",
       "0   F3  118.157078   8.211144   126.368222     0.25     False\n",
       "1   F4  104.003894  10.667229   114.671123     0.25     False\n",
       "2   C3   95.300966   8.068256   103.369221     0.25     False\n",
       "3   C4   84.098698  12.264104    96.362801     0.25     False\n",
       "4   O1  522.730225  63.275577   586.005802     0.25     False\n",
       "5   O2  460.613075  56.541394   517.154469     0.25     False"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Absolute power, using different bands\n",
    "bp = yasa.bandpower_from_psd(psd, freqs, ch_names=chan, bands=[(1, 12, 'Slow'), (12, 30, 'Beta')], relative=False)\n",
    "print(bp.bands_)  # Tip: see the frequency bands that were used\n",
    "bp"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***********************\n",
    "\n",
    "## A one-liner function\n",
    "\n",
    "The above is great, but calculating the hypnogram mask and the PSD of data manually every time seems a bit tedious. Can we wrap all that into a single function? The good news is that, yes, you can directly apply the [bandpower](https://raphaelvallat.com/yasa/build/html/generated/yasa.bandpower.html#yasa.bandpower) function to raw EEG data (in numpy or MNE format), which will automatically run all the previous steps for you. In other words, the function will:\n",
    "\n",
    "1. Calculate an hypnogram mask, if wanted\n",
    "2. Calculate the Welch's PSD for each channel, and, if applicable, each sleep stage\n",
    "3. Return the bandpowers as a single dataframe.\n",
    "\n",
    "Let's see some example below.\n",
    "\n",
    "**Working with NumPy array**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Delta</th>\n",
       "      <th>Theta</th>\n",
       "      <th>Alpha</th>\n",
       "      <th>Sigma</th>\n",
       "      <th>Beta</th>\n",
       "      <th>Gamma</th>\n",
       "      <th>TotalAbsPow</th>\n",
       "      <th>FreqRes</th>\n",
       "      <th>Relative</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Chan</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>F3</th>\n",
       "      <td>0.636693</td>\n",
       "      <td>0.202645</td>\n",
       "      <td>0.103551</td>\n",
       "      <td>0.038842</td>\n",
       "      <td>0.017315</td>\n",
       "      <td>0.000954</td>\n",
       "      <td>127.618684</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>F4</th>\n",
       "      <td>0.632714</td>\n",
       "      <td>0.167312</td>\n",
       "      <td>0.102019</td>\n",
       "      <td>0.050122</td>\n",
       "      <td>0.046038</td>\n",
       "      <td>0.001794</td>\n",
       "      <td>116.091721</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C3</th>\n",
       "      <td>0.553818</td>\n",
       "      <td>0.203048</td>\n",
       "      <td>0.157099</td>\n",
       "      <td>0.059053</td>\n",
       "      <td>0.025890</td>\n",
       "      <td>0.001091</td>\n",
       "      <td>98.111686</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C4</th>\n",
       "      <td>0.550775</td>\n",
       "      <td>0.164835</td>\n",
       "      <td>0.148458</td>\n",
       "      <td>0.071653</td>\n",
       "      <td>0.061851</td>\n",
       "      <td>0.002427</td>\n",
       "      <td>98.797977</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O1</th>\n",
       "      <td>0.530968</td>\n",
       "      <td>0.193649</td>\n",
       "      <td>0.176263</td>\n",
       "      <td>0.076812</td>\n",
       "      <td>0.021669</td>\n",
       "      <td>0.000639</td>\n",
       "      <td>594.933458</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O2</th>\n",
       "      <td>0.507774</td>\n",
       "      <td>0.197531</td>\n",
       "      <td>0.182381</td>\n",
       "      <td>0.081835</td>\n",
       "      <td>0.029632</td>\n",
       "      <td>0.000847</td>\n",
       "      <td>490.549941</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         Delta     Theta     Alpha     Sigma      Beta     Gamma  TotalAbsPow  \\\n",
       "Chan                                                                            \n",
       "F3    0.636693  0.202645  0.103551  0.038842  0.017315  0.000954   127.618684   \n",
       "F4    0.632714  0.167312  0.102019  0.050122  0.046038  0.001794   116.091721   \n",
       "C3    0.553818  0.203048  0.157099  0.059053  0.025890  0.001091    98.111686   \n",
       "C4    0.550775  0.164835  0.148458  0.071653  0.061851  0.002427    98.797977   \n",
       "O1    0.530968  0.193649  0.176263  0.076812  0.021669  0.000639   594.933458   \n",
       "O2    0.507774  0.197531  0.182381  0.081835  0.029632  0.000847   490.549941   \n",
       "\n",
       "      FreqRes  Relative  \n",
       "Chan                     \n",
       "F3       0.25      True  \n",
       "F4       0.25      True  \n",
       "C3       0.25      True  \n",
       "C4       0.25      True  \n",
       "O1       0.25      True  \n",
       "O2       0.25      True  "
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Relative bandpower per channel on the whole recording (entire data)\n",
    "yasa.bandpower(data, sf=sf, ch_names=chan)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Delta</th>\n",
       "      <th>Theta</th>\n",
       "      <th>Alpha</th>\n",
       "      <th>Sigma</th>\n",
       "      <th>Beta</th>\n",
       "      <th>Gamma</th>\n",
       "      <th>TotalAbsPow</th>\n",
       "      <th>FreqRes</th>\n",
       "      <th>Relative</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Chan</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>F3</th>\n",
       "      <td>0.636302</td>\n",
       "      <td>0.203037</td>\n",
       "      <td>0.103482</td>\n",
       "      <td>0.038892</td>\n",
       "      <td>0.017333</td>\n",
       "      <td>0.000954</td>\n",
       "      <td>127.165849</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>F4</th>\n",
       "      <td>0.632742</td>\n",
       "      <td>0.167476</td>\n",
       "      <td>0.101868</td>\n",
       "      <td>0.050105</td>\n",
       "      <td>0.046014</td>\n",
       "      <td>0.001794</td>\n",
       "      <td>115.809269</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C3</th>\n",
       "      <td>0.553331</td>\n",
       "      <td>0.203450</td>\n",
       "      <td>0.157079</td>\n",
       "      <td>0.059126</td>\n",
       "      <td>0.025921</td>\n",
       "      <td>0.001093</td>\n",
       "      <td>97.747816</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C4</th>\n",
       "      <td>0.550317</td>\n",
       "      <td>0.165167</td>\n",
       "      <td>0.148445</td>\n",
       "      <td>0.071724</td>\n",
       "      <td>0.061915</td>\n",
       "      <td>0.002432</td>\n",
       "      <td>98.442674</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O1</th>\n",
       "      <td>0.530850</td>\n",
       "      <td>0.193851</td>\n",
       "      <td>0.176114</td>\n",
       "      <td>0.076870</td>\n",
       "      <td>0.021675</td>\n",
       "      <td>0.000639</td>\n",
       "      <td>593.352339</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O2</th>\n",
       "      <td>0.507184</td>\n",
       "      <td>0.197932</td>\n",
       "      <td>0.182403</td>\n",
       "      <td>0.081961</td>\n",
       "      <td>0.029673</td>\n",
       "      <td>0.000848</td>\n",
       "      <td>488.713172</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         Delta     Theta     Alpha     Sigma      Beta     Gamma  TotalAbsPow  \\\n",
       "Chan                                                                            \n",
       "F3    0.636302  0.203037  0.103482  0.038892  0.017333  0.000954   127.165849   \n",
       "F4    0.632742  0.167476  0.101868  0.050105  0.046014  0.001794   115.809269   \n",
       "C3    0.553331  0.203450  0.157079  0.059126  0.025921  0.001093    97.747816   \n",
       "C4    0.550317  0.165167  0.148445  0.071724  0.061915  0.002432    98.442674   \n",
       "O1    0.530850  0.193851  0.176114  0.076870  0.021675  0.000639   593.352339   \n",
       "O2    0.507184  0.197932  0.182403  0.081961  0.029673  0.000848   488.713172   \n",
       "\n",
       "      FreqRes  Relative  \n",
       "Chan                     \n",
       "F3       0.25      True  \n",
       "F4       0.25      True  \n",
       "C3       0.25      True  \n",
       "C4       0.25      True  \n",
       "O1       0.25      True  \n",
       "O2       0.25      True  "
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Same but after applying a FIR bandpass-filter\n",
    "# The frequencies are defined as the lowest and highest frequencies in bands, \n",
    "# respectively (default 0.5 to 40 hz)\n",
    "yasa.bandpower(data, sf=sf, ch_names=chan, bandpass=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th>Delta</th>\n",
       "      <th>Theta</th>\n",
       "      <th>Alpha</th>\n",
       "      <th>Sigma</th>\n",
       "      <th>Beta</th>\n",
       "      <th>Gamma</th>\n",
       "      <th>TotalAbsPow</th>\n",
       "      <th>FreqRes</th>\n",
       "      <th>Relative</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Stage</th>\n",
       "      <th>Chan</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th rowspan=\"6\" valign=\"top\">2</th>\n",
       "      <th>F3</th>\n",
       "      <td>0.627304</td>\n",
       "      <td>0.203762</td>\n",
       "      <td>0.093739</td>\n",
       "      <td>0.058738</td>\n",
       "      <td>0.015560</td>\n",
       "      <td>0.000897</td>\n",
       "      <td>120.004204</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>F4</th>\n",
       "      <td>0.633748</td>\n",
       "      <td>0.164128</td>\n",
       "      <td>0.089177</td>\n",
       "      <td>0.068108</td>\n",
       "      <td>0.043197</td>\n",
       "      <td>0.001643</td>\n",
       "      <td>104.510568</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C3</th>\n",
       "      <td>0.620138</td>\n",
       "      <td>0.174503</td>\n",
       "      <td>0.109323</td>\n",
       "      <td>0.075471</td>\n",
       "      <td>0.019631</td>\n",
       "      <td>0.000934</td>\n",
       "      <td>94.971948</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C4</th>\n",
       "      <td>0.589504</td>\n",
       "      <td>0.152978</td>\n",
       "      <td>0.108081</td>\n",
       "      <td>0.086052</td>\n",
       "      <td>0.060613</td>\n",
       "      <td>0.002772</td>\n",
       "      <td>89.487769</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O1</th>\n",
       "      <td>0.565617</td>\n",
       "      <td>0.189377</td>\n",
       "      <td>0.131287</td>\n",
       "      <td>0.094629</td>\n",
       "      <td>0.018514</td>\n",
       "      <td>0.000576</td>\n",
       "      <td>546.818728</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O2</th>\n",
       "      <td>0.555877</td>\n",
       "      <td>0.199497</td>\n",
       "      <td>0.125399</td>\n",
       "      <td>0.093607</td>\n",
       "      <td>0.024931</td>\n",
       "      <td>0.000689</td>\n",
       "      <td>470.163453</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"6\" valign=\"top\">3</th>\n",
       "      <th>F3</th>\n",
       "      <td>0.828649</td>\n",
       "      <td>0.108011</td>\n",
       "      <td>0.040972</td>\n",
       "      <td>0.016952</td>\n",
       "      <td>0.005122</td>\n",
       "      <td>0.000295</td>\n",
       "      <td>342.477172</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>F4</th>\n",
       "      <td>0.838153</td>\n",
       "      <td>0.092264</td>\n",
       "      <td>0.036461</td>\n",
       "      <td>0.017440</td>\n",
       "      <td>0.015089</td>\n",
       "      <td>0.000593</td>\n",
       "      <td>300.360463</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C3</th>\n",
       "      <td>0.821808</td>\n",
       "      <td>0.106564</td>\n",
       "      <td>0.043543</td>\n",
       "      <td>0.021145</td>\n",
       "      <td>0.006622</td>\n",
       "      <td>0.000318</td>\n",
       "      <td>257.981046</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C4</th>\n",
       "      <td>0.803859</td>\n",
       "      <td>0.101670</td>\n",
       "      <td>0.044725</td>\n",
       "      <td>0.025314</td>\n",
       "      <td>0.023397</td>\n",
       "      <td>0.001035</td>\n",
       "      <td>233.896876</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O1</th>\n",
       "      <td>0.796031</td>\n",
       "      <td>0.096900</td>\n",
       "      <td>0.061064</td>\n",
       "      <td>0.037892</td>\n",
       "      <td>0.007899</td>\n",
       "      <td>0.000214</td>\n",
       "      <td>1425.054797</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O2</th>\n",
       "      <td>0.796404</td>\n",
       "      <td>0.102136</td>\n",
       "      <td>0.055112</td>\n",
       "      <td>0.035793</td>\n",
       "      <td>0.010317</td>\n",
       "      <td>0.000238</td>\n",
       "      <td>1259.005568</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "               Delta     Theta     Alpha     Sigma      Beta     Gamma  \\\n",
       "Stage Chan                                                               \n",
       "2     F3    0.627304  0.203762  0.093739  0.058738  0.015560  0.000897   \n",
       "      F4    0.633748  0.164128  0.089177  0.068108  0.043197  0.001643   \n",
       "      C3    0.620138  0.174503  0.109323  0.075471  0.019631  0.000934   \n",
       "      C4    0.589504  0.152978  0.108081  0.086052  0.060613  0.002772   \n",
       "      O1    0.565617  0.189377  0.131287  0.094629  0.018514  0.000576   \n",
       "      O2    0.555877  0.199497  0.125399  0.093607  0.024931  0.000689   \n",
       "3     F3    0.828649  0.108011  0.040972  0.016952  0.005122  0.000295   \n",
       "      F4    0.838153  0.092264  0.036461  0.017440  0.015089  0.000593   \n",
       "      C3    0.821808  0.106564  0.043543  0.021145  0.006622  0.000318   \n",
       "      C4    0.803859  0.101670  0.044725  0.025314  0.023397  0.001035   \n",
       "      O1    0.796031  0.096900  0.061064  0.037892  0.007899  0.000214   \n",
       "      O2    0.796404  0.102136  0.055112  0.035793  0.010317  0.000238   \n",
       "\n",
       "            TotalAbsPow  FreqRes  Relative  \n",
       "Stage Chan                                  \n",
       "2     F3     120.004204     0.25      True  \n",
       "      F4     104.510568     0.25      True  \n",
       "      C3      94.971948     0.25      True  \n",
       "      C4      89.487769     0.25      True  \n",
       "      O1     546.818728     0.25      True  \n",
       "      O2     470.163453     0.25      True  \n",
       "3     F3     342.477172     0.25      True  \n",
       "      F4     300.360463     0.25      True  \n",
       "      C3     257.981046     0.25      True  \n",
       "      C4     233.896876     0.25      True  \n",
       "      O1    1425.054797     0.25      True  \n",
       "      O2    1259.005568     0.25      True  "
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Relative bandpower per channel, for N2 and N3 sleep separately\n",
    "yasa.bandpower(data, sf=sf, ch_names=chan, hypno=hypno_up, include=(2, 3))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Delta</th>\n",
       "      <th>Theta</th>\n",
       "      <th>Alpha</th>\n",
       "      <th>Sigma</th>\n",
       "      <th>Beta</th>\n",
       "      <th>Gamma</th>\n",
       "      <th>TotalAbsPow</th>\n",
       "      <th>FreqRes</th>\n",
       "      <th>Relative</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Chan</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>CHAN000</th>\n",
       "      <td>76.740490</td>\n",
       "      <td>24.432611</td>\n",
       "      <td>13.039698</td>\n",
       "      <td>4.750606</td>\n",
       "      <td>2.214708</td>\n",
       "      <td>0.122448</td>\n",
       "      <td>121.382099</td>\n",
       "      <td>0.5</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>CHAN001</th>\n",
       "      <td>67.080505</td>\n",
       "      <td>18.582526</td>\n",
       "      <td>11.481893</td>\n",
       "      <td>5.574031</td>\n",
       "      <td>5.297087</td>\n",
       "      <td>0.209542</td>\n",
       "      <td>108.376150</td>\n",
       "      <td>0.5</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>CHAN002</th>\n",
       "      <td>50.195613</td>\n",
       "      <td>19.384323</td>\n",
       "      <td>15.142030</td>\n",
       "      <td>5.633680</td>\n",
       "      <td>2.532756</td>\n",
       "      <td>0.106634</td>\n",
       "      <td>93.121585</td>\n",
       "      <td>0.5</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>CHAN003</th>\n",
       "      <td>49.937619</td>\n",
       "      <td>16.107595</td>\n",
       "      <td>14.601446</td>\n",
       "      <td>6.833524</td>\n",
       "      <td>6.060415</td>\n",
       "      <td>0.236358</td>\n",
       "      <td>94.013954</td>\n",
       "      <td>0.5</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>CHAN004</th>\n",
       "      <td>289.777098</td>\n",
       "      <td>114.721895</td>\n",
       "      <td>106.985385</td>\n",
       "      <td>47.043321</td>\n",
       "      <td>12.951929</td>\n",
       "      <td>0.385445</td>\n",
       "      <td>572.312838</td>\n",
       "      <td>0.5</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>CHAN005</th>\n",
       "      <td>226.634080</td>\n",
       "      <td>96.004044</td>\n",
       "      <td>91.664759</td>\n",
       "      <td>40.414813</td>\n",
       "      <td>14.576597</td>\n",
       "      <td>0.415770</td>\n",
       "      <td>469.398404</td>\n",
       "      <td>0.5</td>\n",
       "      <td>False</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "              Delta       Theta       Alpha      Sigma       Beta     Gamma  \\\n",
       "Chan                                                                          \n",
       "CHAN000   76.740490   24.432611   13.039698   4.750606   2.214708  0.122448   \n",
       "CHAN001   67.080505   18.582526   11.481893   5.574031   5.297087  0.209542   \n",
       "CHAN002   50.195613   19.384323   15.142030   5.633680   2.532756  0.106634   \n",
       "CHAN003   49.937619   16.107595   14.601446   6.833524   6.060415  0.236358   \n",
       "CHAN004  289.777098  114.721895  106.985385  47.043321  12.951929  0.385445   \n",
       "CHAN005  226.634080   96.004044   91.664759  40.414813  14.576597  0.415770   \n",
       "\n",
       "         TotalAbsPow  FreqRes  Relative  \n",
       "Chan                                     \n",
       "CHAN000   121.382099      0.5     False  \n",
       "CHAN001   108.376150      0.5     False  \n",
       "CHAN002    93.121585      0.5     False  \n",
       "CHAN003    94.013954      0.5     False  \n",
       "CHAN004   572.312838      0.5     False  \n",
       "CHAN005   469.398404      0.5     False  "
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Absolute bandpower using a 2-sec window\n",
    "# Note that since `ch_names` is not provided, channels are simply labelled as ['CHAN001', 'CHAN002', ...]\n",
    "yasa.bandpower(data, sf, win_sec=2, relative=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Working with MNE Raw object**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th>Delta</th>\n",
       "      <th>Theta</th>\n",
       "      <th>Alpha</th>\n",
       "      <th>Sigma</th>\n",
       "      <th>Beta</th>\n",
       "      <th>Gamma</th>\n",
       "      <th>TotalAbsPow</th>\n",
       "      <th>FreqRes</th>\n",
       "      <th>Relative</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Stage</th>\n",
       "      <th>Chan</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th rowspan=\"6\" valign=\"top\">2</th>\n",
       "      <th>F3</th>\n",
       "      <td>0.627304</td>\n",
       "      <td>0.203762</td>\n",
       "      <td>0.093739</td>\n",
       "      <td>0.058738</td>\n",
       "      <td>0.015560</td>\n",
       "      <td>0.000897</td>\n",
       "      <td>120.004204</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>F4</th>\n",
       "      <td>0.633748</td>\n",
       "      <td>0.164128</td>\n",
       "      <td>0.089177</td>\n",
       "      <td>0.068108</td>\n",
       "      <td>0.043197</td>\n",
       "      <td>0.001643</td>\n",
       "      <td>104.510568</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C3</th>\n",
       "      <td>0.620138</td>\n",
       "      <td>0.174503</td>\n",
       "      <td>0.109323</td>\n",
       "      <td>0.075471</td>\n",
       "      <td>0.019631</td>\n",
       "      <td>0.000934</td>\n",
       "      <td>94.971948</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C4</th>\n",
       "      <td>0.589504</td>\n",
       "      <td>0.152978</td>\n",
       "      <td>0.108081</td>\n",
       "      <td>0.086052</td>\n",
       "      <td>0.060613</td>\n",
       "      <td>0.002772</td>\n",
       "      <td>89.487769</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O1</th>\n",
       "      <td>0.565617</td>\n",
       "      <td>0.189377</td>\n",
       "      <td>0.131287</td>\n",
       "      <td>0.094629</td>\n",
       "      <td>0.018514</td>\n",
       "      <td>0.000576</td>\n",
       "      <td>546.818728</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O2</th>\n",
       "      <td>0.555877</td>\n",
       "      <td>0.199497</td>\n",
       "      <td>0.125399</td>\n",
       "      <td>0.093607</td>\n",
       "      <td>0.024931</td>\n",
       "      <td>0.000689</td>\n",
       "      <td>470.163453</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "               Delta     Theta     Alpha     Sigma      Beta     Gamma  \\\n",
       "Stage Chan                                                               \n",
       "2     F3    0.627304  0.203762  0.093739  0.058738  0.015560  0.000897   \n",
       "      F4    0.633748  0.164128  0.089177  0.068108  0.043197  0.001643   \n",
       "      C3    0.620138  0.174503  0.109323  0.075471  0.019631  0.000934   \n",
       "      C4    0.589504  0.152978  0.108081  0.086052  0.060613  0.002772   \n",
       "      O1    0.565617  0.189377  0.131287  0.094629  0.018514  0.000576   \n",
       "      O2    0.555877  0.199497  0.125399  0.093607  0.024931  0.000689   \n",
       "\n",
       "            TotalAbsPow  FreqRes  Relative  \n",
       "Stage Chan                                  \n",
       "2     F3     120.004204     0.25      True  \n",
       "      F4     104.510568     0.25      True  \n",
       "      C3      94.971948     0.25      True  \n",
       "      C4      89.487769     0.25      True  \n",
       "      O1     546.818728     0.25      True  \n",
       "      O2     470.163453     0.25      True  "
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# We do not  need to specify the `sf` or `ch_names` since these are\n",
    "# directly extracted from the MNE Raw structure\n",
    "yasa.bandpower(raw, hypno=hypno_up, include=(2))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Delta</th>\n",
       "      <th>Theta</th>\n",
       "      <th>Alpha</th>\n",
       "      <th>Sigma</th>\n",
       "      <th>Beta</th>\n",
       "      <th>Gamma</th>\n",
       "      <th>TotalAbsPow</th>\n",
       "      <th>FreqRes</th>\n",
       "      <th>Relative</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Chan</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>F3</th>\n",
       "      <td>0.636693</td>\n",
       "      <td>0.202645</td>\n",
       "      <td>0.103551</td>\n",
       "      <td>0.038842</td>\n",
       "      <td>0.017315</td>\n",
       "      <td>0.000954</td>\n",
       "      <td>127.618684</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>F4</th>\n",
       "      <td>0.632714</td>\n",
       "      <td>0.167312</td>\n",
       "      <td>0.102019</td>\n",
       "      <td>0.050122</td>\n",
       "      <td>0.046038</td>\n",
       "      <td>0.001794</td>\n",
       "      <td>116.091721</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C3</th>\n",
       "      <td>0.553818</td>\n",
       "      <td>0.203048</td>\n",
       "      <td>0.157099</td>\n",
       "      <td>0.059053</td>\n",
       "      <td>0.025890</td>\n",
       "      <td>0.001091</td>\n",
       "      <td>98.111686</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C4</th>\n",
       "      <td>0.550775</td>\n",
       "      <td>0.164835</td>\n",
       "      <td>0.148458</td>\n",
       "      <td>0.071653</td>\n",
       "      <td>0.061851</td>\n",
       "      <td>0.002427</td>\n",
       "      <td>98.797977</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O1</th>\n",
       "      <td>0.530968</td>\n",
       "      <td>0.193649</td>\n",
       "      <td>0.176263</td>\n",
       "      <td>0.076812</td>\n",
       "      <td>0.021669</td>\n",
       "      <td>0.000639</td>\n",
       "      <td>594.933458</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O2</th>\n",
       "      <td>0.507774</td>\n",
       "      <td>0.197531</td>\n",
       "      <td>0.182381</td>\n",
       "      <td>0.081835</td>\n",
       "      <td>0.029632</td>\n",
       "      <td>0.000847</td>\n",
       "      <td>490.549941</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "         Delta     Theta     Alpha     Sigma      Beta     Gamma  TotalAbsPow  \\\n",
       "Chan                                                                            \n",
       "F3    0.636693  0.202645  0.103551  0.038842  0.017315  0.000954   127.618684   \n",
       "F4    0.632714  0.167312  0.102019  0.050122  0.046038  0.001794   116.091721   \n",
       "C3    0.553818  0.203048  0.157099  0.059053  0.025890  0.001091    98.111686   \n",
       "C4    0.550775  0.164835  0.148458  0.071653  0.061851  0.002427    98.797977   \n",
       "O1    0.530968  0.193649  0.176263  0.076812  0.021669  0.000639   594.933458   \n",
       "O2    0.507774  0.197531  0.182381  0.081835  0.029632  0.000847   490.549941   \n",
       "\n",
       "      FreqRes  Relative  \n",
       "Chan                     \n",
       "F3       0.25      True  \n",
       "F4       0.25      True  \n",
       "C3       0.25      True  \n",
       "C4       0.25      True  \n",
       "O1       0.25      True  \n",
       "O2       0.25      True  "
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Bandpower of the full recording\n",
    "bp = yasa.bandpower(raw)\n",
    "bp"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>Delta</th>\n",
       "      <th>Theta</th>\n",
       "      <th>Alpha</th>\n",
       "      <th>Sigma</th>\n",
       "      <th>Beta</th>\n",
       "      <th>Gamma</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Chan</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>F3</th>\n",
       "      <td>81.253931</td>\n",
       "      <td>25.861325</td>\n",
       "      <td>13.215084</td>\n",
       "      <td>4.956925</td>\n",
       "      <td>2.209733</td>\n",
       "      <td>0.121686</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>F4</th>\n",
       "      <td>73.452884</td>\n",
       "      <td>19.423561</td>\n",
       "      <td>11.843600</td>\n",
       "      <td>5.818788</td>\n",
       "      <td>5.344603</td>\n",
       "      <td>0.208286</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C3</th>\n",
       "      <td>54.336066</td>\n",
       "      <td>19.921339</td>\n",
       "      <td>15.413273</td>\n",
       "      <td>5.793817</td>\n",
       "      <td>2.540105</td>\n",
       "      <td>0.107085</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C4</th>\n",
       "      <td>54.415473</td>\n",
       "      <td>16.285331</td>\n",
       "      <td>14.667380</td>\n",
       "      <td>7.079218</td>\n",
       "      <td>6.110783</td>\n",
       "      <td>0.239791</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O1</th>\n",
       "      <td>315.890752</td>\n",
       "      <td>115.208012</td>\n",
       "      <td>104.864643</td>\n",
       "      <td>45.698244</td>\n",
       "      <td>12.891758</td>\n",
       "      <td>0.380050</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O2</th>\n",
       "      <td>249.088677</td>\n",
       "      <td>96.898699</td>\n",
       "      <td>89.466897</td>\n",
       "      <td>40.144358</td>\n",
       "      <td>14.535813</td>\n",
       "      <td>0.415497</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "           Delta       Theta       Alpha      Sigma       Beta     Gamma\n",
       "Chan                                                                    \n",
       "F3     81.253931   25.861325   13.215084   4.956925   2.209733  0.121686\n",
       "F4     73.452884   19.423561   11.843600   5.818788   5.344603  0.208286\n",
       "C3     54.336066   19.921339   15.413273   5.793817   2.540105  0.107085\n",
       "C4     54.415473   16.285331   14.667380   7.079218   6.110783  0.239791\n",
       "O1    315.890752  115.208012  104.864643  45.698244  12.891758  0.380050\n",
       "O2    249.088677   96.898699   89.466897  40.144358  14.535813  0.415497"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# We can quickly recover the physical bandpower using the `TotalAbsPow`\n",
    "bands = ['Delta', 'Theta', 'Alpha', 'Sigma', 'Beta', 'Gamma']\n",
    "bp_abs = (bp[bands] * bp['TotalAbsPow'].values[..., None])\n",
    "bp_abs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th>Delta</th>\n",
       "      <th>Theta</th>\n",
       "      <th>Alpha</th>\n",
       "      <th>Sigma</th>\n",
       "      <th>Beta</th>\n",
       "      <th>Gamma</th>\n",
       "      <th>TotalAbsPow</th>\n",
       "      <th>FreqRes</th>\n",
       "      <th>Relative</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Stage</th>\n",
       "      <th>Chan</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <th>F3</th>\n",
       "      <td>0.626938</td>\n",
       "      <td>0.204079</td>\n",
       "      <td>0.093713</td>\n",
       "      <td>0.058804</td>\n",
       "      <td>0.015568</td>\n",
       "      <td>0.000898</td>\n",
       "      <td>119.605426</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <th>F3</th>\n",
       "      <td>0.828481</td>\n",
       "      <td>0.108190</td>\n",
       "      <td>0.040935</td>\n",
       "      <td>0.016974</td>\n",
       "      <td>0.005125</td>\n",
       "      <td>0.000294</td>\n",
       "      <td>341.404619</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "               Delta     Theta     Alpha     Sigma      Beta     Gamma  \\\n",
       "Stage Chan                                                               \n",
       "2     F3    0.626938  0.204079  0.093713  0.058804  0.015568  0.000898   \n",
       "3     F3    0.828481  0.108190  0.040935  0.016974  0.005125  0.000294   \n",
       "\n",
       "            TotalAbsPow  FreqRes  Relative  \n",
       "Stage Chan                                  \n",
       "2     F3     119.605426     0.25      True  \n",
       "3     F3     341.404619     0.25      True  "
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Single channel bandpower\n",
    "yasa.bandpower(raw.copy().pick(['F3']), hypno=hypno_up, include=(2, 3), bandpass=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['N1' 'N2' 'N3' 'W']\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th>Delta</th>\n",
       "      <th>Theta</th>\n",
       "      <th>Alpha</th>\n",
       "      <th>Sigma</th>\n",
       "      <th>Beta</th>\n",
       "      <th>Gamma</th>\n",
       "      <th>TotalAbsPow</th>\n",
       "      <th>FreqRes</th>\n",
       "      <th>Relative</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>Stage</th>\n",
       "      <th>Chan</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th rowspan=\"6\" valign=\"top\">N2</th>\n",
       "      <th>F3</th>\n",
       "      <td>0.627304</td>\n",
       "      <td>0.203762</td>\n",
       "      <td>0.093739</td>\n",
       "      <td>0.058738</td>\n",
       "      <td>0.015560</td>\n",
       "      <td>0.000897</td>\n",
       "      <td>120.004204</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>F4</th>\n",
       "      <td>0.633748</td>\n",
       "      <td>0.164128</td>\n",
       "      <td>0.089177</td>\n",
       "      <td>0.068108</td>\n",
       "      <td>0.043197</td>\n",
       "      <td>0.001643</td>\n",
       "      <td>104.510568</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C3</th>\n",
       "      <td>0.620138</td>\n",
       "      <td>0.174503</td>\n",
       "      <td>0.109323</td>\n",
       "      <td>0.075471</td>\n",
       "      <td>0.019631</td>\n",
       "      <td>0.000934</td>\n",
       "      <td>94.971948</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C4</th>\n",
       "      <td>0.589504</td>\n",
       "      <td>0.152978</td>\n",
       "      <td>0.108081</td>\n",
       "      <td>0.086052</td>\n",
       "      <td>0.060613</td>\n",
       "      <td>0.002772</td>\n",
       "      <td>89.487769</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O1</th>\n",
       "      <td>0.565617</td>\n",
       "      <td>0.189377</td>\n",
       "      <td>0.131287</td>\n",
       "      <td>0.094629</td>\n",
       "      <td>0.018514</td>\n",
       "      <td>0.000576</td>\n",
       "      <td>546.818728</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O2</th>\n",
       "      <td>0.555877</td>\n",
       "      <td>0.199497</td>\n",
       "      <td>0.125399</td>\n",
       "      <td>0.093607</td>\n",
       "      <td>0.024931</td>\n",
       "      <td>0.000689</td>\n",
       "      <td>470.163453</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th rowspan=\"6\" valign=\"top\">N3</th>\n",
       "      <th>F3</th>\n",
       "      <td>0.828649</td>\n",
       "      <td>0.108011</td>\n",
       "      <td>0.040972</td>\n",
       "      <td>0.016952</td>\n",
       "      <td>0.005122</td>\n",
       "      <td>0.000295</td>\n",
       "      <td>342.477172</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>F4</th>\n",
       "      <td>0.838153</td>\n",
       "      <td>0.092264</td>\n",
       "      <td>0.036461</td>\n",
       "      <td>0.017440</td>\n",
       "      <td>0.015089</td>\n",
       "      <td>0.000593</td>\n",
       "      <td>300.360463</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C3</th>\n",
       "      <td>0.821808</td>\n",
       "      <td>0.106564</td>\n",
       "      <td>0.043543</td>\n",
       "      <td>0.021145</td>\n",
       "      <td>0.006622</td>\n",
       "      <td>0.000318</td>\n",
       "      <td>257.981046</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>C4</th>\n",
       "      <td>0.803859</td>\n",
       "      <td>0.101670</td>\n",
       "      <td>0.044725</td>\n",
       "      <td>0.025314</td>\n",
       "      <td>0.023397</td>\n",
       "      <td>0.001035</td>\n",
       "      <td>233.896876</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O1</th>\n",
       "      <td>0.796031</td>\n",
       "      <td>0.096900</td>\n",
       "      <td>0.061064</td>\n",
       "      <td>0.037892</td>\n",
       "      <td>0.007899</td>\n",
       "      <td>0.000214</td>\n",
       "      <td>1425.054797</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>O2</th>\n",
       "      <td>0.796404</td>\n",
       "      <td>0.102136</td>\n",
       "      <td>0.055112</td>\n",
       "      <td>0.035793</td>\n",
       "      <td>0.010317</td>\n",
       "      <td>0.000238</td>\n",
       "      <td>1259.005568</td>\n",
       "      <td>0.25</td>\n",
       "      <td>True</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "               Delta     Theta     Alpha     Sigma      Beta     Gamma  \\\n",
       "Stage Chan                                                               \n",
       "N2    F3    0.627304  0.203762  0.093739  0.058738  0.015560  0.000897   \n",
       "      F4    0.633748  0.164128  0.089177  0.068108  0.043197  0.001643   \n",
       "      C3    0.620138  0.174503  0.109323  0.075471  0.019631  0.000934   \n",
       "      C4    0.589504  0.152978  0.108081  0.086052  0.060613  0.002772   \n",
       "      O1    0.565617  0.189377  0.131287  0.094629  0.018514  0.000576   \n",
       "      O2    0.555877  0.199497  0.125399  0.093607  0.024931  0.000689   \n",
       "N3    F3    0.828649  0.108011  0.040972  0.016952  0.005122  0.000295   \n",
       "      F4    0.838153  0.092264  0.036461  0.017440  0.015089  0.000593   \n",
       "      C3    0.821808  0.106564  0.043543  0.021145  0.006622  0.000318   \n",
       "      C4    0.803859  0.101670  0.044725  0.025314  0.023397  0.001035   \n",
       "      O1    0.796031  0.096900  0.061064  0.037892  0.007899  0.000214   \n",
       "      O2    0.796404  0.102136  0.055112  0.035793  0.010317  0.000238   \n",
       "\n",
       "            TotalAbsPow  FreqRes  Relative  \n",
       "Stage Chan                                  \n",
       "N2    F3     120.004204     0.25      True  \n",
       "      F4     104.510568     0.25      True  \n",
       "      C3      94.971948     0.25      True  \n",
       "      C4      89.487769     0.25      True  \n",
       "      O1     546.818728     0.25      True  \n",
       "      O2     470.163453     0.25      True  \n",
       "N3    F3     342.477172     0.25      True  \n",
       "      F4     300.360463     0.25      True  \n",
       "      C3     257.981046     0.25      True  \n",
       "      C4     233.896876     0.25      True  \n",
       "      O1    1425.054797     0.25      True  \n",
       "      O2    1259.005568     0.25      True  "
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Alternatively, if one prefer to work with a string hypnogram\n",
    "hypno_up_str = yasa.hypno_upsample_to_data(hypno=hypno, sf_hypno=(1/30), data=data, sf_data=sf)\n",
    "print(np.unique(hypno_up_str))\n",
    "yasa.bandpower(raw, hypno=hypno_up_str, include=('N2', 'N3'))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "***********************\n",
    "\n",
    "## To higher dimensions and beyond!\n",
    "\n",
    "Now, let's say that we're working with higher dimensions of data, such as for example a 3-D array of shape `(n_epochs, n_chan, n_samples)`. For instance, this can be the case if you use the [yasa.sliding_window](https://raphaelvallat.com/yasa/build/html/generated/yasa.sliding_window.html) function to segment 2-D data into 30-seconds epochs, as illustrated below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['F3', 'F4', 'C3', 'C4', 'O1', 'O2']\n",
      "(98, 6, 3000) 100.0\n"
     ]
    }
   ],
   "source": [
    "# Create a 3-D array\n",
    "data = raw.get_data(units=\"uV\")\n",
    "sf = raw.info['sfreq']\n",
    "\n",
    "_, data = yasa.sliding_window(data, sf, window=30)\n",
    "\n",
    "print(raw.ch_names)\n",
    "print(data.shape, sf)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* The first dimension of ``data`` corresponds to the 98 epochs that were extracted from the data using the [yasa.sliding_window](https://raphaelvallat.com/yasa/build/html/generated/yasa.sliding_window.html) function.\n",
    "* The second dimension is the 6 channels.\n",
    "* The last dimension refers to the number of samples present in each window (30-seconds @ 100 Hz: 3000 data points).\n",
    "\n",
    "This type of multi-dimensional data does not work with standard 2D tabular data, like pandas Datarame. We therefore have to use NumPy-based operations to calculate the bandpower. This can be done with the `yasa.bandpower_from_psd_ndarray` function. But first, we need to calculate the (PSD) on each epoch:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "((201,), (98, 6, 201))"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "win = int(4 * sf)  # Window size is set to 4 seconds\n",
    "freqs, psd = welch(data, sf, nperseg=win, axis=-1) \n",
    "\n",
    "freqs.shape, psd.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`psd` has now a shape of 98 epochs x 6 channels x 201 frequencies."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[[0.82, 0.85, 0.77, 0.57, 0.76, 0.44],\n",
       "        [0.78, 0.7 , 0.63, 0.74, 0.77, 0.53],\n",
       "        [0.53, 0.56, 0.2 , 0.23, 0.24, 0.2 ],\n",
       "        ...,\n",
       "        [0.63, 0.66, 0.37, 0.55, 0.56, 0.44],\n",
       "        [0.1 , 0.12, 0.09, 0.08, 0.14, 0.11],\n",
       "        [0.06, 0.06, 0.04, 0.03, 0.1 , 0.07]],\n",
       "\n",
       "       [[0.13, 0.08, 0.11, 0.14, 0.11, 0.13],\n",
       "        [0.12, 0.19, 0.13, 0.12, 0.07, 0.15],\n",
       "        [0.22, 0.17, 0.28, 0.22, 0.21, 0.18],\n",
       "        ...,\n",
       "        [0.25, 0.19, 0.23, 0.16, 0.19, 0.19],\n",
       "        [0.03, 0.02, 0.04, 0.02, 0.06, 0.05],\n",
       "        [0.02, 0.02, 0.02, 0.01, 0.05, 0.04]],\n",
       "\n",
       "       [[0.03, 0.03, 0.08, 0.18, 0.09, 0.33],\n",
       "        [0.07, 0.08, 0.19, 0.1 , 0.13, 0.25],\n",
       "        [0.19, 0.17, 0.41, 0.4 , 0.46, 0.51],\n",
       "        ...,\n",
       "        [0.07, 0.1 , 0.35, 0.22, 0.21, 0.32],\n",
       "        [0.02, 0.01, 0.05, 0.03, 0.1 , 0.12],\n",
       "        [0.01, 0.01, 0.03, 0.02, 0.09, 0.11]],\n",
       "\n",
       "       [[0.01, 0.02, 0.02, 0.07, 0.02, 0.07],\n",
       "        [0.02, 0.02, 0.03, 0.02, 0.02, 0.04],\n",
       "        [0.03, 0.04, 0.06, 0.08, 0.07, 0.07],\n",
       "        ...,\n",
       "        [0.02, 0.02, 0.03, 0.03, 0.03, 0.04],\n",
       "        [0.01, 0.01, 0.01, 0.01, 0.03, 0.03],\n",
       "        [0.01, 0.01, 0.01, 0.01, 0.02, 0.03]],\n",
       "\n",
       "       [[0.01, 0.02, 0.02, 0.05, 0.01, 0.03],\n",
       "        [0.01, 0.02, 0.03, 0.01, 0.01, 0.03],\n",
       "        [0.02, 0.06, 0.05, 0.07, 0.03, 0.03],\n",
       "        ...,\n",
       "        [0.02, 0.03, 0.03, 0.03, 0.01, 0.02],\n",
       "        [0.83, 0.84, 0.82, 0.86, 0.66, 0.68],\n",
       "        [0.9 , 0.9 , 0.89, 0.93, 0.72, 0.76]]])"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "bands=[(0.5, 4, 'Delta'), (4, 8, 'Theta'), (8, 12, 'Alpha'), \n",
    "       (12, 16, 'Sigma'), (16, 30, 'Beta')]\n",
    "\n",
    "# Calculate the bandpower on 3-D PSD array\n",
    "bandpower = yasa.bandpower_from_psd_ndarray(psd, freqs, bands)\n",
    "np.round(bandpower, 2)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(5, 98, 6)"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "bandpower.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The shape of `bandpower` is now n_bands, n_epochs, n_chan. For example, to get the delta power on the first epoch of the first channel:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.8175389993433952"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "bandpower[0, 0, 0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And to get the average theta power across all epochs of the second channel:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "0.15169517794177534"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "bandpower.mean(axis=-2)[1, 1]"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}