{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Generating monophasic and biphasic pulses\n\n*This example shows how to build and visualize monophasic and biphasic\nstimuli.*\n\n.. important ::\n\n    Stimuli specify electrical currents in microamps (uA) and time in\n    milliseconds (ms). When in doubt, check the docstring of the function\n    you are trying to use.\n\n## A monophasic pulse\n\nA :py:class:`~pulse2percept.stimuli.MonophasicPulse` has a single phase and can\nbe either anodic (by definition: has a positive current amplitude) or cathodic\n(negative current amplitude).\n\nMonophasic pulses require an amplitude (in uA) and a phase duration (in ms).\nYou can also specify the total stimulus duration: zeros will be inserted after\nthe pulse up to the desired duration:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from pulse2percept.stimuli import MonophasicPulse\n\nmono = MonophasicPulse(-20, 1, stim_dur=50)\nmono.plot()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. note ::\n\n    The sign of ``amp`` will determine whether the pulse is cathodic\n    (negative current) or anodic (positive current).\n\n## A (symmetric) biphasic pulse\n\nA :py:class:`~pulse2percept.stimuli.BiphasicPulse` consists of a cathodic and\nan anodic phase, optionally separated by an interphase gap.\nBoth cathodic and anodic phases will have the same duration (\"symmetric\").\n\nFor example, to generate a cathodic-first biphasic pulse with phase duration\n0.78 ms, separated by a 0.2 ms interphase gap, use the following:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from pulse2percept.stimuli import BiphasicPulse\n\nbiphasic = BiphasicPulse(10, 0.78, interphase_dur=0.2, stim_dur=100)\nbiphasic.plot()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Similarly, you can generate an anodic-first pulse delivered after an initial\ndelay of 25 ms:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "biphasic = BiphasicPulse(10, 0.78, delay_dur=25, stim_dur=100,\n                         cathodic_first=False)\nbiphasic.plot()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "A biphasic pulse is typically considered \"charge-balanced\" (i.e., its net\ncurrent sums to zero over time):\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "biphasic.is_charge_balanced"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. note ::\n\n    The sign of ``amp`` will be automatically adjusted depending on the\n    ``cathodic_first`` flag.\n\n## An asymmetric biphasic pulse\n\nAnalogously, an :py:class:`~pulse2percept.stimuli.AsymmetricBiphasicPulse`\nconsists of a cathodic and an anodic phase with different amplitude and\nduration.\n\nA common pulse consists of a short cathodic phase (e.g., -20 uA, 1 ms)\nfollowed by a long anodic phase (e.g., 4 uA, 5 ms):\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from pulse2percept.stimuli import AsymmetricBiphasicPulse\n\nasymmetric = AsymmetricBiphasicPulse(-20, 2, 1, 10, stim_dur=100)\nasymmetric.plot()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "When choosing amplitudes and durations accordingly, it is still possible to\ngenerate a charge-balanced pulse:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "asymmetric.is_charge_balanced"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Multi-electrode stimuli\n\nThe easiest way to build a multi-electrode stimulus from a number of pulses\nis to pass a dictionary to the :py:class:`~pulse2percept.stimuli.Stimulus`\nobject:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from pulse2percept.stimuli import Stimulus\n\nstim = Stimulus({\n    'A1': MonophasicPulse(-20, 1, stim_dur=75),\n    'C7': AsymmetricBiphasicPulse(-20, 2, 1, 10, delay_dur=25, stim_dur=100)\n})\nstim.plot()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Note how the different stimuli will be padded as necessary to bring all of\nthem to a common stimulus duration.\n\nAlternatively, you can also pass the stimuli as a list, in which case you\nmight want to specify the electrode names in a list as well:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "stim = Stimulus([MonophasicPulse(-20, 1, stim_dur=100),\n                 AsymmetricBiphasicPulse(-20, 2, 1, 10, delay_dur=25,\n                                         stim_dur=100)],\n                electrodes=['A1', 'C7'])\nstim.plot()"
      ]
    }
  ],
  "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
}