
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples\stimuli\plot_pulses.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_examples_stimuli_plot_pulses.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_examples_stimuli_plot_pulses.py:


===============================================================================
Generating monophasic and biphasic pulses
===============================================================================

*This example shows how to build and visualize monophasic and biphasic
stimuli.*

.. important ::

    Stimuli specify electrical currents in microamps (uA) and time in
    milliseconds (ms). When in doubt, check the docstring of the function
    you are trying to use.

A monophasic pulse
------------------

A :py:class:`~pulse2percept.stimuli.MonophasicPulse` has a single phase and can
be either anodic (by definition: has a positive current amplitude) or cathodic
(negative current amplitude).

Monophasic pulses require an amplitude (in uA) and a phase duration (in ms).
You can also specify the total stimulus duration: zeros will be inserted after
the pulse up to the desired duration:

.. GENERATED FROM PYTHON SOURCE LINES 28-34

.. code-block:: Python


    from pulse2percept.stimuli import MonophasicPulse

    mono = MonophasicPulse(-20, 1, stim_dur=50)
    mono.plot()




.. image-sg:: /examples/stimuli/images/sphx_glr_plot_pulses_001.png
   :alt: plot pulses
   :srcset: /examples/stimuli/images/sphx_glr_plot_pulses_001.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Axes: ylabel='0'>



.. GENERATED FROM PYTHON SOURCE LINES 36-50

.. note ::

    The sign of ``amp`` will determine whether the pulse is cathodic
    (negative current) or anodic (positive current).

A (symmetric) biphasic pulse
----------------------------

A :py:class:`~pulse2percept.stimuli.BiphasicPulse` consists of a cathodic and
an anodic phase, optionally separated by an interphase gap.
Both cathodic and anodic phases will have the same duration ("symmetric").

For example, to generate a cathodic-first biphasic pulse with phase duration
0.78 ms, separated by a 0.2 ms interphase gap, use the following:

.. GENERATED FROM PYTHON SOURCE LINES 50-56

.. code-block:: Python


    from pulse2percept.stimuli import BiphasicPulse

    biphasic = BiphasicPulse(10, 0.78, interphase_dur=0.2, stim_dur=100)
    biphasic.plot()




.. image-sg:: /examples/stimuli/images/sphx_glr_plot_pulses_002.png
   :alt: plot pulses
   :srcset: /examples/stimuli/images/sphx_glr_plot_pulses_002.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Axes: ylabel='0'>



.. GENERATED FROM PYTHON SOURCE LINES 57-59

Similarly, you can generate an anodic-first pulse delivered after an initial
delay of 25 ms:

.. GENERATED FROM PYTHON SOURCE LINES 59-64

.. code-block:: Python


    biphasic = BiphasicPulse(10, 0.78, delay_dur=25, stim_dur=100,
                             cathodic_first=False)
    biphasic.plot()




.. image-sg:: /examples/stimuli/images/sphx_glr_plot_pulses_003.png
   :alt: plot pulses
   :srcset: /examples/stimuli/images/sphx_glr_plot_pulses_003.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Axes: ylabel='0'>



.. GENERATED FROM PYTHON SOURCE LINES 65-67

A biphasic pulse is typically considered "charge-balanced" (i.e., its net
current sums to zero over time):

.. GENERATED FROM PYTHON SOURCE LINES 67-70

.. code-block:: Python


    biphasic.is_charge_balanced





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    True



.. GENERATED FROM PYTHON SOURCE LINES 71-85

.. note ::

    The sign of ``amp`` will be automatically adjusted depending on the
    ``cathodic_first`` flag.

An asymmetric biphasic pulse
----------------------------

Analogously, an :py:class:`~pulse2percept.stimuli.AsymmetricBiphasicPulse`
consists of a cathodic and an anodic phase with different amplitude and
duration.

A common pulse consists of a short cathodic phase (e.g., -20 uA, 1 ms)
followed by a long anodic phase (e.g., 4 uA, 5 ms):

.. GENERATED FROM PYTHON SOURCE LINES 85-91

.. code-block:: Python


    from pulse2percept.stimuli import AsymmetricBiphasicPulse

    asymmetric = AsymmetricBiphasicPulse(-20, 2, 1, 10, stim_dur=100)
    asymmetric.plot()




.. image-sg:: /examples/stimuli/images/sphx_glr_plot_pulses_004.png
   :alt: plot pulses
   :srcset: /examples/stimuli/images/sphx_glr_plot_pulses_004.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Axes: ylabel='0'>



.. GENERATED FROM PYTHON SOURCE LINES 92-94

When choosing amplitudes and durations accordingly, it is still possible to
generate a charge-balanced pulse:

.. GENERATED FROM PYTHON SOURCE LINES 94-97

.. code-block:: Python


    asymmetric.is_charge_balanced





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    False



.. GENERATED FROM PYTHON SOURCE LINES 98-104

Multi-electrode stimuli
-----------------------

The easiest way to build a multi-electrode stimulus from a number of pulses
is to pass a dictionary to the :py:class:`~pulse2percept.stimuli.Stimulus`
object:

.. GENERATED FROM PYTHON SOURCE LINES 104-113

.. code-block:: Python


    from pulse2percept.stimuli import Stimulus

    stim = Stimulus({
        'A1': MonophasicPulse(-20, 1, stim_dur=75),
        'C7': AsymmetricBiphasicPulse(-20, 2, 1, 10, delay_dur=25, stim_dur=100)
    })
    stim.plot()




.. image-sg:: /examples/stimuli/images/sphx_glr_plot_pulses_005.png
   :alt: plot pulses
   :srcset: /examples/stimuli/images/sphx_glr_plot_pulses_005.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    array([<Axes: ylabel='A1'>, <Axes: ylabel='C7'>], dtype=object)



.. GENERATED FROM PYTHON SOURCE LINES 114-119

Note how the different stimuli will be padded as necessary to bring all of
them to a common stimulus duration.

Alternatively, you can also pass the stimuli as a list, in which case you
might want to specify the electrode names in a list as well:

.. GENERATED FROM PYTHON SOURCE LINES 119-125

.. code-block:: Python


    stim = Stimulus([MonophasicPulse(-20, 1, stim_dur=100),
                     AsymmetricBiphasicPulse(-20, 2, 1, 10, delay_dur=25,
                                             stim_dur=100)],
                    electrodes=['A1', 'C7'])
    stim.plot()



.. image-sg:: /examples/stimuli/images/sphx_glr_plot_pulses_006.png
   :alt: plot pulses
   :srcset: /examples/stimuli/images/sphx_glr_plot_pulses_006.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    array([<Axes: ylabel='A1'>, <Axes: ylabel='C7'>], dtype=object)




.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.760 seconds)


.. _sphx_glr_download_examples_stimuli_plot_pulses.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_pulses.ipynb <plot_pulses.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_pulses.py <plot_pulses.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_pulses.zip <plot_pulses.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_
