:orphan:

.. _examples:

===============
Example Gallery
===============

This gallery contains a number of usage examples and case studies to highlight
the ease-of-use and flexibility of pulse2percept.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>


Implants
========

The :py:mod:`~pulse2percept.implants` module provides access to various
state-of-the-art retinal prostheses, such as
:py:class:`~pulse2percept.implants.ArgusI` and
:py:class:`~pulse2percept.implants.ArgusII` (epiretinal),
:py:class:`~pulse2percept.implants.Alpha-IMS` and
:py:class:`~pulse2percept.implants.PRIMA` (subretinal),
as well as :py:class:`~pulse2percept.implants.BVT24` (suprachoroidal).

Other implants can be added by creating a new 
:py:class:`~pulse2percept.implants.ProsthesisSystem` object.



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="pulse2percept supports the following cortical implants:">

.. only:: html

  .. image:: /examples/implants/images/thumb/sphx_glr_plot_implants_cortical_thumb.png
    :alt:

  :ref:`sphx_glr_examples_implants_plot_implants_cortical.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Cortical implant gallery</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use :py~pulse2percept.implants.ElectrodeGrid.">

.. only:: html

  .. image:: /examples/implants/images/thumb/sphx_glr_plot_electrode_grid_thumb.png
    :alt:

  :ref:`sphx_glr_examples_implants_plot_electrode_grid.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Creating a grid of electrodes</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="pulse2percept supports the following implants:">

.. only:: html

  .. image:: /examples/implants/images/thumb/sphx_glr_plot_implants_thumb.png
    :alt:

  :ref:`sphx_glr_examples_implants_plot_implants.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Retinal implant gallery</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Background ----------">

.. only:: html

  .. image:: /examples/implants/images/thumb/sphx_glr_plot_argus_thumb.png
    :alt:

  :ref:`sphx_glr_examples_implants_plot_argus.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Simulating Argus II</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to create a new :py~pulse2percept.implants.ElectrodeArray object.">

.. only:: html

  .. image:: /examples/implants/images/thumb/sphx_glr_plot_custom_electrode_array_thumb.png
    :alt:

  :ref:`sphx_glr_examples_implants_plot_custom_electrode_array.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Creating your own electrode array</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


Stimuli
=======

The :py:mod:`~pulse2percept.stimuli` module provides a number of common
electrical stimulus types, such as 
:py:class:`~pulse2percept.stimuli.BiphasicPulseTrain`,
which can be assigned to electrodes of a 
:py:class:`~pulse2percept.implants.ProsthesisSystem` object.

Stimuli can also be created from images 
(:py:class:`~pulse2percept.stimuli.ImageStimulus`) and videos
(:py:class:`~pulse2percept.stimuli.VideoStimulus`).


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use videos as input stimuli for a retinal implant.">

.. only:: html

  .. image:: /examples/stimuli/images/thumb/sphx_glr_plot_video_stim_thumb.png
    :alt:

  :ref:`sphx_glr_examples_stimuli_plot_video_stim.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Generating a stimulus from a video</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to build and visualize monophasic and biphasic stimuli.">

.. only:: html

  .. image:: /examples/stimuli/images/thumb/sphx_glr_plot_pulses_thumb.png
    :alt:

  :ref:`sphx_glr_examples_stimuli_plot_pulses.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Generating monophasic and biphasic pulses</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use :py~pulse2percept.stimuli.PulseTrain and its variants.">

.. only:: html

  .. image:: /examples/stimuli/images/thumb/sphx_glr_plot_pulse_trains_thumb.png
    :alt:

  :ref:`sphx_glr_examples_stimuli_plot_pulse_trains.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Generating pulse trains</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use drifting psychophysics-based stimuli for a retinal implant.">

.. only:: html

  .. image:: /examples/stimuli/images/thumb/sphx_glr_plot_psychophysics_thumb.png
    :alt:

  :ref:`sphx_glr_examples_stimuli_plot_psychophysics.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Generating a drifting sinusoidal grating or drifting bar stimulus</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use images as input stimuli for a retinal implant.">

.. only:: html

  .. image:: /examples/stimuli/images/thumb/sphx_glr_plot_image_stim_thumb.png
    :alt:

  :ref:`sphx_glr_examples_stimuli_plot_image_stim.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Generating a stimulus from an image</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to build a sinusoidal pulse train from scratch.">

.. only:: html

  .. image:: /examples/stimuli/images/thumb/sphx_glr_plot_sinusoidal_thumb.png
    :alt:

  :ref:`sphx_glr_examples_stimuli_plot_sinusoidal.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Generating a sinusoidal pulse train</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


Models
======

The :mod:`pulse2percept.models` module provides a number of published and
verified computational models that can be used to predict neural responses or
visual percepts resulting from electrical stimulation, such as
:py:class:`~pulse2percept.models.Nanduri2012Model` and
:py:class:`~pulse2percept.models.AxonMapModel`.

New models can be created by mixing-and-matching spatial and temporal models,
or by creating a new one from scratch.


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Neuropythy [Benson2018]_ is a python package that predicts patient-specific visuotopies based on MRI scans of the human visual cortex. It is possible to use Neuropythy within pulse2percept as the visual field map for cortical models.">

.. only:: html

  .. image:: /examples/models/images/thumb/sphx_glr_plot_neuropythy_thumb.png
    :alt:

  :ref:`sphx_glr_examples_models_plot_neuropythy.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Neuropythy and Neuralink: Patient specific visual field maps based on MRI</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to apply the :py~pulse2percept.models.ScoreboardModel to a :py~pulse2percept.implants.PRIMA75 implant.">

.. only:: html

  .. image:: /examples/models/images/thumb/sphx_glr_plot_beyeler2019_scoreboard_thumb.png
    :alt:

  :ref:`sphx_glr_examples_models_plot_beyeler2019_scoreboard.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Beyeler et al. (2019): Focal percepts with the scoreboard model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use the :py~pulse2percept.models.Thompson2003Model.">

.. only:: html

  .. image:: /examples/models/images/thumb/sphx_glr_plot_thompson2003_thumb.png
    :alt:

  :ref:`sphx_glr_examples_models_plot_thompson2003.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Thompson et al. (2003): Circular phosphenes</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to apply the :py~pulse2percept.models.AxonMapModel to an :py~pulse2percept.implants.ArgusII implant.">

.. only:: html

  .. image:: /examples/models/images/thumb/sphx_glr_plot_beyeler2019_axonmap_thumb.png
    :alt:

  :ref:`sphx_glr_examples_models_plot_beyeler2019_axonmap.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Beyeler et al. (2019): Axonal streaks with the axon map model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Every computational model needs to assume a mapping between retinal and visual field coordinates (``vfmap``). A number of these visual field maps are provided in the :py~pulse2percept.topography module:">

.. only:: html

  .. image:: /examples/models/images/thumb/sphx_glr_plot_visual_field_maps_thumb.png
    :alt:

  :ref:`sphx_glr_examples_models_plot_visual_field_maps.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Predicting the perceptual effects of different visual field maps</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use the :py~pulse2percept.models.BiphasicAxonMapModel to model the effects of  biphasic pulse train parameters phosphene appearance in an epiretinal implant such as :py~pulse2percept.implants.ArgusII. ">

.. only:: html

  .. image:: /examples/models/images/thumb/sphx_glr_plot_granley2021_biphasic_thumb.png
    :alt:

  :ref:`sphx_glr_examples_models_plot_granley2021_biphasic.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Granley et al. (2021): Effects of Biphasic Pulse Parameters with the BiphasicAxonMapModel</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to apply the :py~pulse2percept.models.cortex.DynaphosModel (original and official  implementation available here) to an :py~pulse2percept.implants.cortex.Orion implant.">

.. only:: html

  .. image:: /examples/models/images/thumb/sphx_glr_plot_dynaphos_thumb.png
    :alt:

  :ref:`sphx_glr_examples_models_plot_dynaphos.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">van der Grinten, de Ruyter van Steveninck, Lozano et al. (2023): Phosphene simulation using cortical prostheses</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use the :py~pulse2percept.models.Horsager2009Model.">

.. only:: html

  .. image:: /examples/models/images/thumb/sphx_glr_plot_horsager2009_thumb.png
    :alt:

  :ref:`sphx_glr_examples_models_plot_horsager2009.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Horsager et al. (2009): Predicting temporal sensitivity</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use the :py~pulse2percept.models.Nanduri2012Model.">

.. only:: html

  .. image:: /examples/models/images/thumb/sphx_glr_plot_nanduri2012_thumb.png
    :alt:

  :ref:`sphx_glr_examples_models_plot_nanduri2012.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Nanduri et al. (2012): Frequency vs. amplitude modulation</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


Datasets
========

The :mod:`pulse2percept.datasets` module provides helper functions
that can be used to load datasets from the bionic vision community,
such as :py:func:`~pulse2percept.datasets.load_horsager2009`,
:py:func:`~pulse2percept.datasets.fetch_beyeler2019`,
:py:func:`~pulse2percept.datasets.load_nanduri2012` and
:py:func:`~pulse2percept.datasets.load_fornos2012`.


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use the Horsager et al. (2009) dataset.">

.. only:: html

  .. image:: /examples/datasets/images/thumb/sphx_glr_plot_data_horsager2009_thumb.png
    :alt:

  :ref:`sphx_glr_examples_datasets_plot_data_horsager2009.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Threshold data from Horsager et al. (2009)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use the Greenwald et al. (2009) dataset.">

.. only:: html

  .. image:: /examples/datasets/images/thumb/sphx_glr_plot_greenwald2009_thumb.png
    :alt:

  :ref:`sphx_glr_examples_datasets_plot_greenwald2009.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Data from Greenwald et al. (2009)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use the Perez Fornos et al. (2012) dataset.">

.. only:: html

  .. image:: /examples/datasets/images/thumb/sphx_glr_plot_perezfornos2012_thumb.png
    :alt:

  :ref:`sphx_glr_examples_datasets_plot_perezfornos2012.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Phosphene fading data from Perez Fornos et al. (2012)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use the Nanduri et al. (2012) dataset.">

.. only:: html

  .. image:: /examples/datasets/images/thumb/sphx_glr_plot_data_nanduri2012_thumb.png
    :alt:

  :ref:`sphx_glr_examples_datasets_plot_data_nanduri2012.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Data from Nanduri et al. (2012)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example shows how to use the Beyeler et al. (2019) dataset.">

.. only:: html

  .. image:: /examples/datasets/images/thumb/sphx_glr_plot_data_beyeler2019_thumb.png
    :alt:

  :ref:`sphx_glr_examples_datasets_plot_data_beyeler2019.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Phosphene drawings from Beyeler et al. (2019)</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


For developers
==============

Code examples for people interested in :ref:`contributing to pulse2percept <dev-contributing>`.


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In this tutorial, you will learn how to write a test case for your contributed code, and make sure the test passes.">

.. only:: html

  .. image:: /examples/developers/images/thumb/sphx_glr_plot_tests_thumb.png
    :alt:

  :ref:`sphx_glr_examples_developers_plot_tests.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Writing your own test case</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /examples/implants/index.rst
   /examples/stimuli/index.rst
   /examples/models/index.rst
   /examples/datasets/index.rst
   /examples/developers/index.rst


.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-gallery

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

      :download:`Download all examples in Python source code: examples_python.zip </examples/examples_python.zip>`

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

      :download:`Download all examples in Jupyter notebooks: examples_jupyter.zip </examples/examples_jupyter.zip>`


.. only:: html

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

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