docs/source/quickstart.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quickstart"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib qt\n",
    "import mindaffectBCI.online_bci"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## System Architecture\n",
    "\n",
    "The system consists of 3 main components as illustrated here.\n",
    "\n",
    "![SystemArchitecture.png](images/SystemArchitecture.png)\n",
    "\n",
    "To actually run the BCI we need to start each of these components:\n",
    "- UtopiaHub: This component is the central server which coordinates all the other pieces, and saves the data for offline analysis\n",
    "\n",
    "- Acquisition: This component talks to the *EEG Headset* and streams the data to the Hub\n",
    "\n",
    "- Decoder: This component analysis the EEG data to fit the subject specific model and generate predictions\n",
    "\n",
    "- Presentation: This component presents the User-Interface to the user, including any BCI specific stimuli which need to be presented. It also selects outputs when the BCI is sufficiently confident and generates the appropriate output\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before we launch the BCI to start these components:\n",
    " * Power on the OpenBCI Ganglion. (toggle on/off button)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we load the configuration we would like to use from the configuration .json file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# load the config-file to use.  Here we use the default noisetag config file:\n",
    "config = mindaffectBCI.online_bci.load_config(\"noisetag_bci\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Then we can run this configuration, with the following command.   "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# N.B. uncomment the following to run with fakedata driver, if you don't have an amp connected\n",
    "# config['acquisition']='fakedata'\n",
    "\n",
    "mindaffectBCI.online_bci.run(**config)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If this worked correctly you should see a screen like below.  (Note: it may start minimized to check for a new python window in your task bar).\n",
    "\n",
    "<img src='images/mainmenu.png' width=300>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using the MindAffect BCI "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that the system is up and running, you can go through the following steps to use the BCI!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. EEG headset Setup\n",
    "Prepare a headset such that it follows the [MindAffect headset layout.pdf](https://github.com/mindaffect/Headset/blob/master/MindAffect%20headset%20layout.pdf) in our Headset repository or prepare the headset delivered with your kit by following [MindAffect headset setup.pdf](https://github.com/mindaffect/Headset/raw/master/MindAffect%20Headset%20Set%20up%20instructions.pdf)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Signal Quality\n",
    "\n",
    "Check the signal quality by pressing 0 in the main menu.  You should see a screen which looks like this:\n",
    "\n",
    "<img src=\"images/ElectrodeQuality.png\" width=\"300\"/>\n",
    "\n",
    "In this window you see a horizontial line for each channel showing the current *live* measurments.  You also see a colored box at the left of each line with a number in it.  The color of this box and the number indicate the current *estimated* noise-to-signal ratio for that channel.  Ideally this number should be less than 5 and the box should be green.  \n",
    "\n",
    "### It is critical for eventual BCI performance that the noise-to-signal ratio is as low as possible, and ideally less than 5.\n",
    "\n",
    "Try to adjust the headset until all electrodes are green, or noise to signal ratio is below 5.\n",
    "\n",
    "You can try to improve the signal for an electrode by pressing it firmly into your head. After releasing pressure, wait a few seconds to see if the signal improves. If not, remove the electrode, and apply more water to the sponge. The sponges should feel wet on your scalp.\n",
    "\n",
    "If the noise to signal ratio does not improve by adjusting the headset, try to distance yourself from power outlets and other electronics."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Calibration\n",
    "\n",
    "Start calibration by pressing 1 in the main menu. You should see an instruction screen telling you to look at the green cued button.  Followed by a screen which looks like this:\n",
    "\n",
    "<img src=\"images/CalibrationScreen.png\" width=\"300\"/>\n",
    "\n",
    "Do what it says, after 10 cues the stimulus will stop and after a few seconds you should see a 'calibration performance' screen like this:\n",
    "\n",
    "<img src='images/CalibrationPerformance.png' width=300>\n",
    "\n",
    "Hopefully, you got a similar performance level?\n",
    "\n",
    "In addition you should see 3-windows pop-up showing more information about the performance.  These windows are:\n",
    "    \n",
    "  1. Model and Performance:  \n",
    "  \n",
    "  <img src='images/ModelAndPerformance.png' width=300>\n",
    "\n",
    "  This window shows (in left-to-right order).\n",
    "    a) the fitted models spatial-filter -- which shows the importance of each EEG channel, \n",
    "    b) the models impulse response -- which shows how the brain responds over time to the different types of stimulus event, and \n",
    "    c) the decoding-performance -- which shows how the accurately the model is able to decode the cued target with increasing data length, and the models estimate of it's own accuracy.       \n",
    "\n",
    "  2. ERP (Event Related Potentional): \n",
    "\n",
    "  <img src='images/ERP.png' width=300>\n",
    "  \n",
    "  This window shows for each EEG channel the *averaged* measured response over time after the triggering stimulus.  This is the conventional plot that you find in many neuroscientific publications.\n",
    "  \n",
    "  3. Summary Statistics:\n",
    "  \n",
    "  <img src='images/SummaryStatistics.png' width=300>\n",
    "  \n",
    "  This window shows the summary statistics for the calibration data.  This has vertically 3 sub-parts.\n",
    "    a) Cxx : this is the spatial cross-correlation of the EEG channels.\n",
    "    b) Cxy : this is the cross-correlation of the stimulus with the EEG.  Which for discrete stimuli as used in this BCI is essentially another view of the ERP.\n",
    "    c) Cyy : this is the *temporal* cross-correlation of the stimulus."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Brain Control.\n",
    "\n",
    "If calibration worked well and you have good calibration performance, then you can proceed to brain-control.  Press either 3 for *cued* prediction, where like calibration you are told where to look.  Whilst not much fun, this is useful to get on-line datasets for training improved models.   Or press 4 for free-spelling, where you can select what 'button' you want in an un-cued fashion.\n",
    "\n",
    "In both cases, BCI feedback is shown in blue.  Initially, while the system is unsure by changing the color of the central letter, and later when a selection has been made by making the whole button blue.  Selected letters will be added to the spelling box at the top of the screen.\n",
    "\n",
    "**Struggling to get the system to work? Consult our** [FAQ](https://mindaffect-bci.readthedocs.io/en/latest/FAQ.html) **section for info on how to improve calibration accuracy, prediction performance, and more!**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Do you not want to run this notebook everytime when using the BCI?\n",
    "Simply run it from your command prompt:    \n",
    "  \n",
    "``` python3 -m mindaffectBCI.online_bci```  \n",
    "   \n",
    "Or specify your own configuration file and save location:  \n",
    "  \n",
    "``` python3 -m mindaffectBCI.online_bci --config_file noisetag_bci --logdir .```  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. SHUTDOWN \n",
    "\n",
    "In the mainmenu, press 5 to shutdown the BCI."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# shutdown the background processes.\n",
    "# N.B. only needed if shutdown from the main-menu window doesn't work.\n",
    "mindaffectBCI.online_bci.shutdown()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Going Further\n",
    "\n",
    " 1. Try other BCI types using our alternative configuration files.\n",
    "     * [noisetag.json](https://github.com/mindaffect/pymindaffectBCI/tree/open_source/mindaffectBCI/noisetag_bci.json) : example for a [noise-tagging](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0133797) (or c-VEP) BCI (Default)\n",
    "     * [rc5x5.json](https://github.com/mindaffect/pymindaffectBCI/tree/open_source/mindaffectBCI/rc5x5_bci.json) : example for a classic visual P300 odd-ball type BCI with row-column stimulus.\n",
    "     * [ssvep.json](https://github.com/mindaffect/pymindaffectBCI/tree/open_source/mindaffectBCI/ssvep_bci.json) : example for a classic [steady-state-visual-response](https://arxiv.org/abs/2002.01171) BCI.\n",
    "\n",
    "2. Write your own presentation system by following this guide (https://mindaffect-bci.readthedocs.io/en/latest/simple_presentation_tutorial.html)\n",
    "\n",
    "3. Write your own output system to make *interesting* things happen when a brain control is activated following this guide (https://mindaffect-bci.readthedocs.io/en/latest/simple_output_tutorial.html)\n",
    "\n",
    "4. Build your own BCI following this guide to develop your own compents. (https://mindaffect-bci.readthedocs.io/en/latest/first_run.html)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}