{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Data from Nanduri et al. (2012)\n\nThis example shows how to use the Nanduri et al. (2012) dataset.\n\n[Nanduri2012]_ used a set of psychophysical detection tasks to determine\nsize and brightness of phosphenes by modulating current amplitude and stimulating frequency in one Argus I user.\n\n.. important ::\n\n        You will need to install [Pandas](https://pandas.pydata.org)\n        (``pip install pandas``) for this dataset.\n\n## Loading the dataset\n\nThe dataset can be loaded as a Pandas ``DataFrame``:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from pulse2percept.datasets import load_nanduri2012\ndata = load_nanduri2012()\nprint(data)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Inspecting the DataFrame tells us that there are 128 measurements\n(the rows) each with 17 different attributes (the columns).\n\nThese attributes include specifiers such as \"subject\", \"electrode\", and\n\"freq\". We can print all column names using:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "data.columns"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. note ::\n\n    The meaning of all column names is explained in the docstring of\n    the :py:func:`~pulse2percept.datasets.load_nanduri2012` function.\n\nFor example, \"freq\" corresponds to the different stimulation frequency (hz) that\nwere used in the paper:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "data.freq.unique()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "To select all the rows where the stimulation frequency was 20hz, we can index into the DataFrame as\nfollows:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(data[data.freq == 20.0])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "This leaves us with 88 rows.\n\nOne of the important points of the paper is to investigate the relationship between\nphosphene brightness and size as either the stimulation amplitude factor or frequency varies.\nWe can easily load in all data points where phosphene brightness was recorded when initially loading in the data set.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(load_nanduri2012(task='rate'))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Likewise, we can load in all data points where phosphene size was recorded when initially loading in the data set.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(load_nanduri2012(task='size'))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. note ::\n\n    Please see the documentation for :py:func:`~pulse2percept.datasets.load_nanduri2012`\n    to see all available parameters for data subset loading.\n\n\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Plotting the data\n\nTo see the relationship between phosphene brightness as the amplitude factor varies,\nwe can recreate figure 4 a, from the paper.\nFurthermore, the dataset available in :py:func:`~pulse2percept.datasets.load_nanduri2012`\nis used to create figures 4 and 5, a-d in the paper.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import matplotlib.pyplot as plt\nimport numpy as np\n\n# load subset of the dataset concerning brightness data\nbrightness_data = load_nanduri2012(task='rate')\n\n# get data where stimulation amplitude is varied\nvary_amp = brightness_data[brightness_data.varied_param == 'amp']\n\n# get the list of electrodes\nelectrodes = data['electrode'].unique()\n\n# iterate over all electrodes\nfor electrode in electrodes:\n    # get relevant data for this specific electrode\n    electrode_data = vary_amp[vary_amp.electrode == electrode]\n\n    # normalize the amplitude\n    normalized_amp = electrode_data.amp_factor / electrode_data.ref_amp_factor\n\n    # set brightness rating\n    brightness_rating = electrode_data.brightness\n\n    # perform a first order linear best fit\n    linear_fit = np.poly1d(np.polyfit(normalized_amp, brightness_rating, 1))\n\n    # plot the linear best fit\n    plt.plot(normalized_amp, linear_fit(normalized_amp), label=electrode)\n\n# display legend on plot\nplt.legend()\n\n# set plot axes\nplt.xlim(0, 7)\nplt.ylim(0, 60)\n\n# set plot labels and title\nplt.xlabel('Amplitude (uA) / Threshold (uA)')\nplt.ylabel('Brightness Rating')\nplt.title('Amplitude Modulation Brightness')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Using Built-In Plotting Functionality\n\nArguably the most important column is \"freq\". This is the current\namplitude of the different stimuli (single pulse, pulse trains, etc.) used\nat threshold.\n\nWe might be interested in seeing how the phosphene brightness varies as a function\nof pulse frequency. We could either use Matplotlib to generate a scatter plot\nor use pulse2percept's own visualization function:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from pulse2percept.viz import scatter_correlation\nscatter_correlation(data.freq, data.brightness)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ":py:func:`~pulse2percept.viz.scatter_correlation` above generates a scatter\nplot of the phosphene brightness as a function of pulse frequency, and performs\nlinear regression to calculate a correlation $r$ and a $p$ value.\nAs expected from the literature, now it becomes evident that phosphene\nbrightness is positively correlated with pulse frequency\n\n\n"
      ]
    }
  ],
  "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.7.9"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}