{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 1 - Introductory tutorial\n",
    "\n",
    "In this short tutorial, we will load some data stored into MATLAB files, and see how we can get help dyconnmap's functions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- - -"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Load data\n",
    "\n",
    "First things first. We are going to use scipy's `io` submodule to load our MATLAB workspace with some sample EEG signals."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import scipy\n",
    "from scipy import io"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`dyconnmap` supports the standard NumPy arrays, so, it's up to the user to import the data. For example, one could load a Nifti file (using i.e. nibabel) and fetch the internal structure that is a standard numpy array."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "data = scipy.io.loadmat('sample_eeg/eyes_open.mat')\n",
    "eeg = np.squeeze(data['eyes_open'])\n",
    "\n",
    "fs = 160.0\n",
    "num_trials = 101\n",
    "num_samples_vis = 160 * 3"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After loading the data, inspect them; find out home many channels and samples are available."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "  trials: 101\n",
      "channels: 64\n",
      " samples: 9600\n",
      "\n"
     ]
    }
   ],
   "source": [
    "num_channels, num_samples = np.shape(eeg[0])\n",
    "\n",
    "print(\"\"\"\n",
    "  trials: {0}\n",
    "channels: {1}\n",
    " samples: {2}\n",
    "\"\"\".format(num_trials, num_channels, num_samples))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "eeg1 = eeg[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### dyconnmap and Help"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "dyconnmap's available submodules are \n",
    "* `fc` for functional connectivity\n",
    "* `graphs` for graph analysis,\n",
    "* `cluster` for clustering algorithms\n",
    "* `ts` for (symbolic) time series"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "import warnings\n",
    "warnings.simplefilter(action='ignore', category=FutureWarning)\n",
    "\n",
    "from dyconnmap.fc import iplv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Most estimators' functions signatures rely on the same inputs. One can reference to the docstrings or simply read the whole documentation with the command (i.e.) `help(iplv)`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function iplv in module dyconnmap.fc.iplv:\n",
      "\n",
      "iplv(data, fb, fs, pairs=None)\n",
      "    Imaginary part of Phase Locking Value\n",
      "    \n",
      "    Compute the Imaginary part of Phase Locking Value for the given *data*,\n",
      "    between the *pairs* (if given) of channels.\n",
      "    \n",
      "    \n",
      "    Parameters\n",
      "    ----------\n",
      "    data : array-like, shape(n_channels, n_samples)\n",
      "        Multichannel recording data.\n",
      "    \n",
      "    fb : list of length 2\n",
      "        The low and high frequencies.\n",
      "    \n",
      "    fs : float\n",
      "        Sampling frequency.\n",
      "    \n",
      "    pairs : array-like or `None`\n",
      "        - If an `array-like` is given, notice that each element is a tuple of length two.\n",
      "        - If `None` is passed, complete connectivity will be assumed.\n",
      "    \n",
      "    \n",
      "    Returns\n",
      "    -------\n",
      "    ts : array-like, shape(n_channels, n_channels, n_samples)\n",
      "        Estimated IPLV time series.\n",
      "    \n",
      "    avg : array-like, shape = [n_electrodes, n_electrodes]\n",
      "        Average IPLV.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(iplv)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `pairs` argument is optional, and usually is ignored. "
   ]
  }
 ],
 "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.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}