pulse2percept.implants¶

Different retinal prosthetic implants, such as Argus II, Alpha-IMS, BVT-24, and PRIMA.

`base`	`ProsthesisSystem`
`electrodes`	`Electrode`, `PointSource`, `DiskElectrode`, `SquareElectrode`, `HexElectrode`
`electrode_arrays`	`ElectrodeArray`, `ElectrodeGrid`
`argus`	`ArgusI`, `ArgusII`
`alpha`	`AlphaIMS`, `AlphaAMS`
`bvt`	`BVT24`, `BVT44`
`imie`	`IMIE`
`prima`	`PhotovoltaicPixel`, `PRIMA`, `PRIMA75`, `PRIMA55`, `PRIMA40`

See also

Basic Concepts > Visual Prostheses

class pulse2percept.implants.AlphaAMS(x=0, y=0, z=0, rot=0, eye='RE', stim=None, preprocess=True, safe_mode=False)[source]¶

Alpha-AMS

This class creates an Alpha-AMS array with 1600 photovoltaic pixels (each 30um in diameter) as described in [Stingl2017], and places it in the subretinal space, such that the center of the array is located at (x,y,z), given in microns, and the array is rotated by rotation angle rot, given in degrees.

The device consists of 1600 30um-wide round pixels, arranged on a 40x40 rectangular grid with 70um pixel pitch.

The array is oriented upright in the visual field, such that an array with center (0,0) has the top three rows lie in the lower retina (upper visual field), as shown below:

An electrode can be addressed by name, row/column index, or integer index (into the flattened array).

Note

Column order is reversed in a left-eye implant.

Parameters:

x/y/z (double) – 3D location of the center of the electrode array. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance). z can either be a list with 1600 entries or a scalar that is applied to all electrodes.
rot (float) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
eye ({'RE', 'LE'}, optional) – Eye in which array is implanted.
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

Examples

Create an AlphaAMS array centered on the fovea, at 100um distance from the retina, rotated counter-clockwise by 5 degrees:

>>> from pulse2percept.implants import AlphaAMS
>>> AlphaAMS(x=0, y=0, z=100, rot=5)  # doctest: +NORMALIZE_WHITESPACE
AlphaAMS(earray=ElectrodeGrid, eye='RE', preprocess=True,
         safe_mode=False, shape=(40, 40), stim=None)

Get access to the third electrode in the top row (by name or by row/column index):

>>> alpha_ims = AlphaAMS(x=0, y=0, z=100, rot=0)
>>> alpha_ims['A3']  # doctest: +NORMALIZE_WHITESPACE
DiskElectrode(activated=True, name='A3', r=15.0, x=-1225.0,
              y=-1365.0, z=100.0)
>>> alpha_ims[0, 2]  # doctest: +NORMALIZE_WHITESPACE
DiskElectrode(activated=True, name='A3', r=15.0, x=-1225.0,
              y=-1365.0, z=100.0)

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})

class pulse2percept.implants.AlphaIMS(x=0, y=0, z=-100, rot=0, eye='RE', stim=None, preprocess=True, safe_mode=False)[source]¶

Alpha-IMS

This class creates an Alpha-IMS array with 1500 photovoltaic pixels (each 50um in diameter) as described in [Stingl2013], and places it in the subretinal space, such that the center of the array is located at (x,y,z), given in microns, and the array is rotated by rotation angle rot, given in degrees.

The device consists of 1500 50um-wide square pixels, arranged on a 39x39 rectangular grid with 72um pixel pitch.

The array is oriented upright in the visual field, such that an array with center (0,0) has the top three rows lie in the lower retina (upper visual field).

An electrode can be addressed by name, row/column index, or integer index (into the flattened array).

Note

Column order is reversed in a left-eye implant.

Parameters:

x/y/z (double) – 3D location of the center of the electrode array. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance). z can either be a list with 1500 entries or a scalar that is applied to all electrodes.
rot (float) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
eye ({'RE', 'LE'}, optional) – Eye in which array is implanted.
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

Examples

Create an Alpha-IMS array centered on the fovea, at 100um distance from the retina, rotated counter-clockwise by 5 degrees:

>>> from pulse2percept.implants import AlphaIMS
>>> AlphaIMS(x=0, y=0, z=100, rot=5)  # doctest: +NORMALIZE_WHITESPACE
AlphaIMS(earray=ElectrodeGrid, eye='RE', preprocess=True,
         safe_mode=False, shape=(39, 39), stim=None)

Get access to the third electrode in the top row (by name or by row/column index):

>>> alpha_ims = AlphaIMS(x=0, y=0, z=100, rot=0)
>>> alpha_ims['A3']  # doctest: +NORMALIZE_WHITESPACE
SquareElectrode(a=50.0, activated=True, name='A3',
                x=-1224.0, y=-1368.0, z=100.0)
>>> alpha_ims[0, 2]  # doctest: +NORMALIZE_WHITESPACE
SquareElectrode(a=50.0, activated=True, name='A3',
                x=-1224.0, y=-1368.0, z=100.0)

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})

class pulse2percept.implants.ArgusI(x=0, y=0, z=0, rot=0, eye='RE', stim=None, preprocess=True, safe_mode=False, use_legacy_names=False)[source]¶

Create an Argus I array on the retina

This function creates an Argus I array and places it on the retina such that the center of the array is located at 3D location (x,y,z), given in microns, and the array is rotated by rotation angle rot, given in degrees.

Argus I is a modified cochlear implant containing 16 electrodes in a 4x4 array with a center-to-center separation of 800 um, and two electrode diameters (250 um and 500 um) arranged in a checkerboard pattern [Yue2020].

The array is oriented in the visual field as shown in Fig. 1 of [Horsager2009]; that is, if placed in (0,0), the top two rows will lie in the lower retina (upper visual field):

  -->x    A1 B1 C1 D1                     260 520 260 520
  |       A2 B2 C2 D2   where electrode   520 260 520 260
  v       A3 B3 C3 D3   diameters are:    260 520 260 520
   y      A4 B4 C4 D4                     520 260 520 260

Electrode order is: A1, B1, C1, D1, A2, B2, …, D4.

If use_legacy_names is True, electrode order is: L6, L2, M8, M4, …

An electrode can be addressed by name, row/column index, or integer index (into the flattened array).

Note

Column order is reversed in a left-eye implant.

Parameters:

x/y/z (double) – 3D location of the center of the electrode array. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance). z can either be a list with 16 entries or a scalar that is applied to all electrodes.
rot (float, optional) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
eye ({'RE', 'LE'}, optional) – Eye in which array is implanted.
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.
use_legacy_names (bool, optional) – If True, uses L/M based electrode names from older papers (e.g., L6, L2) instead of A1-A16.

Examples

Create an Argus I array centered on the fovea, at 100um distance from the retina, rotated counter-clockwise by 5 degrees:

>>> from pulse2percept.implants import ArgusI
>>> ArgusI(x=0, y=0, z=100, rot=5)  # doctest: +NORMALIZE_WHITESPACE
ArgusI(earray=ElectrodeGrid, eye='RE', preprocess=True,
       safe_mode=False, shape=(4, 4), stim=None)

Get access to electrode ‘B1’, either by name or by row/column index:

>>> argus = ArgusI(x=0, y=0, z=100, rot=0)
>>> argus['B1']  # doctest: +NORMALIZE_WHITESPACE
DiskElectrode(activated=True, name='B1', r=250.0, x=-400.0,
              y=-1200.0, z=100.0)
>>> argus[0, 1]  # doctest: +NORMALIZE_WHITESPACE
DiskElectrode(activated=True, name='B1', r=250.0, x=-400.0,
              y=-1200.0, z=100.0)

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})

class pulse2percept.implants.ArgusII(x=0, y=0, z=0, rot=0, eye='RE', stim=None, preprocess=True, safe_mode=False)[source]¶

Create an Argus II array on the retina

This function creates an Argus II array and places it on the retina such that the center of the array is located at (x,y,z), given in microns, and the array is rotated by rotation angle rot, given in degrees.

Argus II contains 60 electrodes of 225 um diameter arranged in a 6 x 10 grid (575 um center-to-center separation) [Yue2020].

The array is oriented upright in the visual field, such that an array with center (0,0) has the top three rows lie in the lower retina (upper visual field), as shown below:

          A1 A2 A3 A4 A5 A6 A7 A8 A9 A10
  -- x    B1 B2 B3 B4 B5 B6 B7 B8 B9 B10
  |       C1 C2 C3 C4 C5 C6 C7 C8 C9 C10
  v       D1 D2 D3 D4 D5 D6 D7 D8 D9 D10
   y      E1 E2 E3 E4 E5 E6 E7 E8 E9 E10
          F1 F2 F3 F4 F5 F6 F7 F8 F9 F10

Electrode order is: A1, A2, …, A10, B1, B2, …, F10.

An electrode can be addressed by name, row/column index, or integer index (into the flattened array).

Note

Column order is reversed in a left-eye implant.

Parameters:

x/y/z (double) – 3D location of the center of the electrode array. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance). z can either be a list with 60 entries or a scalar that is applied to all electrodes.
rot (float) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
eye ({'RE', 'LE'}, optional) – Eye in which array is implanted.
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

Examples

Create an ArgusII array centered on the fovea, at 100um distance from the retina, rotated counter-clockwise by 5 degrees:

>>> from pulse2percept.implants import ArgusII
>>> ArgusII(x=0, y=0, z=100, rot=5)  # doctest: +NORMALIZE_WHITESPACE
ArgusII(earray=ElectrodeGrid, eye='RE', preprocess=True,
        safe_mode=False, shape=(6, 10), stim=None)

Get access to electrode ‘E7’, either by name or by row/column index:

>>> argus = ArgusII(x=0, y=0, z=100, rot=0)
>>> argus['E7']  # doctest: +NORMALIZE_WHITESPACE
DiskElectrode(activated=True, name='E7', r=112.5, x=862.5,
              y=862.5, z=100.0)
>>> argus[4, 6]  # doctest: +NORMALIZE_WHITESPACE
DiskElectrode(activated=True, name='E7', r=112.5, x=862.5,
              y=862.5, z=100.0)

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})

class pulse2percept.implants.BVT24(x=0, y=0, z=0, rot=0, eye='RE', stim=None, preprocess=False, safe_mode=False)[source]¶

24-channel suprachoroidal retinal prosthesis

This class creates a 24-channel suprachoroidal retinal prosthesis [Layton2014], which was developed by the Bionic Vision Australia Consortium and commercialized by Bionic Vision Technologies (BVT). The center of the array is located at (x,y,z), given in microns, and the array is rotated counter-clockwise by rotation angle rot, given in degrees.

The array consists of:

33 platinum stimulating electrodes:
- 30 electrodes with 600um diameter (Electrodes C1-20 (except C9, C17, C19) and Electrodes C21a-m),
- 3 electrodes with 400um diameter (Electrodes C9, C17, C19)
2 return electrodes with 2000um diameter (Electrodes R1, R2)

Electrodes C21a-m are typically being ganged to provide an external ring for common ground. The center of the array is assumed to lie between Electrodes C7, C8, C9, and C13.

Note

Column order for electrode numbering is reversed in a left-eye implant.

New in version 0.6.

Parameters:

x/y/z (double) – 3D location of the center of the electrode array. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance). z can either be a list with 35 entries or a scalar that is applied to all electrodes.
rot (float) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
eye ({'RE', 'LE'}, optional) – Eye in which array is implanted.
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})

class pulse2percept.implants.BVT44(x=0, y=0, z=0, rot=0, eye='LE', stim=None, preprocess=False, safe_mode=False)[source]¶

44-channel suprachoroidal retinal prosthesis

This class creates a 44-channel suprachoroidal retinal prosthesis [Petoe2021], which was developed by the Bionic Vision Australia Consortium and commercialized by Bionic Vision Technologies (BVT).

The center of the array (x,y,z) is located at the center of electrodes D4, D5, C4, and E4, and the array is rotated counter-clockwise by rotation angle rot, given in degrees.

The array consists of:

44 platinum stimulating electrodes with 1000um exposed diameter
2 return electrodes with 2000um diameter (Electrodes R1, R2)

The position of each electrode is measured from Figure 7 in [Petoe2021].

Note

Column order for electrode numbering is reversed in a left-eye implant.

New in version 0.8.

Parameters:

x/y/z (double) – 3D location of the center of the electrode array. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance). z can either be a list with 35 entries or a scalar that is applied to all electrodes.
rot (float) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
eye ({'RE', 'LE'}, optional) – Eye in which array is implanted.
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})

class pulse2percept.implants.DiskElectrode(x, y, z, r, name=None, activated=True)[source]¶

Circular disk electrode

Parameters:

x/y/z (double) – 3D location of the electrode. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance).
r (double) – Disk radius in the x,y plane
name (str, optional) – Electrode name
activated (bool) – To deactivate, set to False. Deactivated electrodes cannot receive stimuli.

electric_potential(x, y, z, v0)[source]¶

Calculate electric potential at (x, y, z)

Parameters:	x/y/z (double) – 3D location at which to evaluate the electric potential v0 (double) – The quasi-static disk potential relative to a ground electrode at infinity
Returns:	pot (double) – The electric potential at (x, y, z).

The electric potential \(V(r,z)\) of a disk electrode is given by [WileyWebster1982]:

\[V(r,z) = \sin^{-1} \bigg\{ \frac{2a}{\sqrt{(r-a)^2 + z^2} + \sqrt{(r+a)^2 + z^2}} \bigg\} \times \frac{2 V_0}{\pi},\]

for \(z \neq 0\), where \(r\) and \(z\) are the radial and axial distances from the center of the disk, \(V_0\) is the disk potential, \(\sigma\) is the medium conductivity, and \(a\) is the disk radius.

plot(autoscale=False, ax=None)[source]¶

Plot

Parameters:	autoscale (bool, optional) – Whether to adjust the x,y limits of the plot ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None given, a new one will be created.
Returns:	ax (`matplotlib.axes.Axes`) – Returns the axis object of the plot

class pulse2percept.implants.Electrode(x, y, z, name=None, activated=True)[source]¶

Abstract base class for all electrodes.

Parameters:

x/y/z (double) – 3D location of the electrode. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance).
name (str, optional) – Electrode name
activated (bool) – To deactivate, set to False. Deactivated electrodes cannot receive stimuli.

plot(autoscale=False, ax=None)[source]¶

Plot

Parameters:	autoscale (bool, optional) – Whether to adjust the x,y limits of the plot ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None given, a new one will be created.
Returns:	ax (`matplotlib.axes.Axes`) – Returns the axis object of the plot

class pulse2percept.implants.ElectrodeArray(electrodes)[source]¶

Electrode array

A collection of Electrode objects.

Parameters:	electrodes (array-like) – Either a single `Electrode` object or a dict, list, or NumPy array thereof. The keys of the dict will serve as electrode names. Otherwise electrodes will be indexed 0..N. Note If you pass multiple electrodes in a dictionary, the keys of the dictionary will automatically be sorted. Thus the original order of electrodes might not be preserved.

Examples

Electrode array made from a single DiskElectrode:

>>> from pulse2percept.implants import ElectrodeArray, DiskElectrode
>>> earray = ElectrodeArray(DiskElectrode(0, 0, 0, 100))
>>> earray.electrodes  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
OrderedDict([(0,
              DiskElectrode(activated=True, name=None, r=100..., x=0..., y=0...,
              z=0...))])

Electrode array made from a single DiskElectrode with name ‘A1’:

>>> from pulse2percept.implants import ElectrodeArray, DiskElectrode
>>> earray = ElectrodeArray({'A1': DiskElectrode(0, 0, 0, 100)})
>>> earray.electrodes  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
OrderedDict([('A1',
              DiskElectrode(activated=True, name=None, r=100..., x=0..., y=0...,
              z=0...))])

add_electrode(name, electrode)[source]¶

Add an electrode to the array

Parameters:	name (int\|str\|...) – Electrode name or index electrode (implants.Electrode) – An Electrode object, such as a PointSource or a DiskElectrode.

electrode_names¶: Return a list of all electrode names in the array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in earray.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the electrode array object, e.g. earray['A1'] or earray[0].

plot(annotate=False, autoscale=True, ax=None, color_stim=None, cmap='OrRd')[source]¶

Plot the electrode array

Parameters:

annotate (bool, optional) – Flag whether to label electrodes in the implant.
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
color_stim (pulse2percept.stimuli.Stimulus, or None) – If provided, colors the earray based on the stimulus amplitudes
cmap (str) – Matplotlib colormap to use for stimulus coloring.

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

remove_electrode(name)[source]¶

Remove an electrode from the array

name: int|str|…: Electrode name or index

class pulse2percept.implants.ElectrodeGrid(shape, spacing, x=0, y=0, z=0, rot=0, names=('A', '1'), type='rect', orientation='horizontal', etype=<class 'pulse2percept.implants.electrodes.PointSource'>, **kwargs)[source]¶

2D grid of electrodes

Parameters:

shape ((rows, cols)) – A tuple containing the number of rows x columns in the grid
spacing (double or (x_spacing, y_spacing)) – Electrode-to-electrode spacing in microns. Must be either a tuple specifying the spacing in x and y directions or a float (assuming the same spacing in x and y). If a tuple is specified for a horizontal hex grid, x_spacing will define the electrode-to-electrode distance, and y_spacing will define the vertical distance between adjacent hexagon centers. In a vertical hex grid, the order is reversed.
type ({'rect', 'hex'}, optional) – Grid type (‘rect’: rectangular, ‘hex’: hexagonal).
orientation ({'horizontal', 'vertical'}, optional) – In a hex grid, ‘horizontal’ orientation will shift every other row to the right, whereas ‘vertical’ will shift every other column up.
x/y/z (double) – 3D location of the center of the grid. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance).
rot (double, optional) – Rotation of the grid in degrees (positive angle: counter-clockwise rotation on the retinal surface)
names ((name_rows, name_cols), each of which either 'A' or '1') – Naming convention for rows and columns, respectively. If ‘A’, rows or columns will be labeled alphabetically: A-Z, AA-AZ, BA-BZ, CA-CZ, etc. ‘-A’ will reverse the order. If ‘1’, rows or columns will be labeled numerically. ‘-1’ will reverse. Letters will always precede numbers in electrode names. For example (‘1’, ‘A’) will number rows numerically and columns alphabetically; first row: ‘A1’, ‘B1’, ‘C1’, NOT ‘1A’, ‘1B’, ‘1C’.
etype (Electrode, optional) – A valid Electrode class. By default, PointSource is used.
**kwargs – Any additional arguments that should be passed to the Electrode constructor, such as radius r for DiskElectrode. See examples below.

Examples

A hexagonal electrode grid with 3 rows and 4 columns, made of disk electrodes with 10um radius spaced 20um apart, centered at (10, 20)um, and located 500um away from the retinal surface, with names like this:

A1 A2 A3 A4 B1 B2 B3 B4 C1 C2 C3 C4

>>> from pulse2percept.implants import ElectrodeGrid, DiskElectrode
>>> ElectrodeGrid((3, 4), 20, x=10, y=20, z=500, names=('A', '1'), r=10,
...               type='hex', etype=DiskElectrode) # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
ElectrodeGrid(rot=0, shape=(3, 4), spacing=20, type='hex')

A rectangular electrode grid with 2 rows and 4 columns, made of disk electrodes with 10um radius spaced 20um apart, centered at (10, 20)um, and located 500um away from the retinal surface, with names like this:

A1 A2 A3 A4 B1 B2 B3 B4

>>> from pulse2percept.implants import ElectrodeGrid, DiskElectrode
>>> ElectrodeGrid((2, 4), 20, x=10, y=20, z=500, names=('A', '1'), r=10,
...               type='rect', etype=DiskElectrode) # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
ElectrodeGrid(rot=0, shape=(2, 4), spacing=20, type='rect')

There are three ways to access (e.g.) the last electrode in the grid, either by name (grid['C3']), by row/column index (grid[2, 2]), or by index into the flattened array (grid[8]):

>>> from pulse2percept.implants import ElectrodeGrid
>>> grid = ElectrodeGrid((3, 3), 20, names=('A', '1'))
>>> grid['C3']  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
PointSource(activated=True, name='C3', x=20..., y=20...,
            z=0...)
>>> grid['C3'] == grid[8] == grid[2, 2]
True

You can also access multiple electrodes at the same time by passing a list of indices/names (it’s ok to mix-and-match):

>>> from pulse2percept.implants import ElectrodeGrid, DiskElectrode
>>> grid = ElectrodeGrid((3, 3), 20, etype=DiskElectrode, r=10)
>>> grid[['A1', 1, (0, 2)]]  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
[DiskElectrode(activated=True, name='A1', r=10..., x=-20.0,
               y=-20.0, z=0...),
 DiskElectrode(activated=True, name='A2', r=10..., x=0.0,
               y=-20.0, z=0...),
 DiskElectrode(activated=True, name='A3', r=10..., x=20.0,
               y=-20.0, z=0...)]

add_electrode(name, electrode)[source]¶

Add an electrode to the array

Parameters:	name (int\|str\|...) – Electrode name or index electrode (implants.Electrode) – An Electrode object, such as a PointSource or a DiskElectrode.

electrode_names¶: Return a list of all electrode names in the array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in earray.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the electrode array object, e.g. earray['A1'] or earray[0].

plot(annotate=False, autoscale=True, ax=None, color_stim=None, cmap='OrRd')[source]¶

Plot the electrode array

Parameters:

annotate (bool, optional) – Flag whether to label electrodes in the implant.
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
color_stim (pulse2percept.stimuli.Stimulus, or None) – If provided, colors the earray based on the stimulus amplitudes
cmap (str) – Matplotlib colormap to use for stimulus coloring.

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

remove_electrode(name)[source]¶

Remove an electrode from the array

name: int|str|…: Electrode name or index

class pulse2percept.implants.HexElectrode(x, y, z, a, name=None, activated=True)[source]¶

Hexagonal electrode

New in version 0.7.

Parameters:

x/y/z (double) – 3D location of the electrode. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance).
a (double) – Length of line drawn from the center of the hexagon to the midpoint of one of its sides.
name (str, optional) – Electrode name
activated (bool) – To deactivate, set to False. Deactivated electrodes cannot receive stimuli.

plot(autoscale=False, ax=None)[source]¶

Plot

Parameters:	autoscale (bool, optional) – Whether to adjust the x,y limits of the plot ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None given, a new one will be created.
Returns:	ax (`matplotlib.axes.Axes`) – Returns the axis object of the plot

class pulse2percept.implants.PhotovoltaicPixel(x, y, z, r, a, name=None, activated=True)[source]¶

Photovoltaic pixel

New in version 0.7.

Parameters:

x/y/z (double) – 3D location of the electrode. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance).
r (double) – Disk radius in the x,y plane
a (double) – Length of line drawn from the center of the hexagon to the midpoint of one of its sides.
activated (bool) – To deactivate, set to False. Deactivated electrodes cannot receive stimuli.

plot(autoscale=False, ax=None)[source]¶

Plot

Parameters:	autoscale (bool, optional) – Whether to adjust the x,y limits of the plot ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None given, a new one will be created.
Returns:	ax (`matplotlib.axes.Axes`) – Returns the axis object of the plot

class pulse2percept.implants.PointSource(x, y, z, name=None, activated=True)[source]¶

Idealized current point source

Parameters:

x/y/z (double) – 3D location of the electrode. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance).
name (str, optional) – Electrode name
activated (bool) – To deactivate, set to False. Deactivated electrodes cannot receive stimuli.

electric_potential(x, y, z, amp, sigma)[source]¶

Calculate electric potential at (x, y, z)

Parameters:

x/y/z (double) – 3D location at which to evaluate the electric potential
amp (double) – amplitude of the constant current pulse
sigma (double) – resistivity of the extracellular solution

Returns:

pot (double) – The electric potential at (x, y, z)
The electric potential \(V(r)\) of a point source is given by
.. math:: – V(r) = frac{sigma I}{4 pi r},
where \(\sigma\) is the resistivity of the extracellular solution
(typically Ames medium, \(\sigma = 110 \Ohm cm\)),
\(I\) is the amplitude of the constant current pulse,
and \(r\) is the distance from the stimulating electrode to the
point at which the voltage is being computed.

plot(autoscale=False, ax=None)[source]¶

Plot

Parameters:	autoscale (bool, optional) – Whether to adjust the x,y limits of the plot ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None given, a new one will be created.
Returns:	ax (`matplotlib.axes.Axes`) – Returns the axis object of the plot

class pulse2percept.implants.PRIMA(x=0, y=0, z=-100, rot=0, eye='RE', stim=None, preprocess=False, safe_mode=False)[source]¶

Create a PRIMA-100 array on the retina

This class creates a PRIMA array with 378 photovoltaic pixels (each 100um in diameter) as used in the clinical trial [Palanker2020], and places it in the subretinal space such that the center of the array is located at 3D location (x,y,z), given in microns, and the array is rotated by rotation angle rot, given in degrees.

The device consists of 378 85um-wide pixels separated by 15um trenches, arranged in a 2-mm wide hexagonal pattern.

This corresponds to a 100um pitch, with adjacent rows separated by 87um. The active electrode is a disk with 28um diameter.

New in version 0.7.

Parameters:

x/y/z (double) – 3D location of the center of the electrode array. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance). z can either be a list with 378 entries or a scalar that is applied to all electrodes.
rot (float, optional) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
eye ({'RE', 'LE'}, optional) – Eye in which array is implanted.
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

Notes

The diameter of the active electrode and the trench width were estimated from Fig.1 in [Palanker2020].

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})

class pulse2percept.implants.PRIMA75(x=0, y=0, z=-100, rot=0, eye='RE', stim=None, preprocess=False, safe_mode=False)[source]¶

Create a PRIMA-75 array on the retina

This class creates a PRIMA array with 142 photovoltaic pixels (each 75um in diameter) as described in [Lorach2015], and places it in the subretinal space, such that that the center of the array is located at 3D location (x,y,z), given in microns, and the array is rotated by rotation angle rot, given in degrees.

The device consists of 142 70um-wide pixels separated by 5um trenches, arranged in a 1-mm wide hexagonal pattern.

This corresponds to a 75um pitch, with adjacent rows separated by 65um. The active electrode is a disk with 20um diameter.

New in version 0.7.

Parameters:

x/y/z (double) – 3D location of the center of the electrode array. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance). z can either be a list with 142 entries or a scalar that is applied to all electrodes.
rot (float, optional) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
eye ({'RE', 'LE'}, optional) – Eye in which array is implanted.
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})

class pulse2percept.implants.PRIMA55(x=0, y=0, z=-100, rot=0, eye='RE', stim=None, preprocess=False, safe_mode=False)[source]¶

Create a PRIMA-55 array on the retina

This class creates a PRIMA array with 273 photovoltaic pixels (each 55um in diameter), and places it in the subretinal space, such that that the center of the array is located at 3D location (x,y,z), given in microns, and the array is rotated by rotation angle rot, given in degrees.

The device consists of 273 50um-wide pixels separated by 5um trenches, arranged in a 1-mm wide hexagonal pattern.

This corresponds to a 55um pitch, with adjacent rows separated by 48um. The active electrode is a disk with 16um diameter.

Warning

The exact shape of the device has not been published yet. We assume the array fits on a circular 1mm-diameter substrate, which leaves us with 273 electrodes.

New in version 0.7.

Parameters:

x/y/z (double) – 3D location of the center of the electrode array. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance). z can either be a list with 378 entries or a scalar that is applied to all electrodes.
rot (float, optional) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
eye ({'RE', 'LE'}, optional) – Eye in which array is implanted.
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})

class pulse2percept.implants.PRIMA40(x=0, y=0, z=-100, rot=0, eye='RE', stim=None, preprocess=False, safe_mode=False)[source]¶

Create a PRIMA-40 array on the retina

This class creates a PRIMA array with 532 photovoltaic pixels (each 40um in diameter), and places it in the subretinal space, such that that the center of the array is located at 3D location (x,y,z), given in microns, and the array is rotated by rotation angle rot, given in degrees.

The device consists of 532 35um-wide pixels separated by 5um trenches, arranged in a 1-mm wide hexagonal pattern.

This corresponds to a 40um pitch, with adjacent rows separated by 48um. The active electrode is a disk with 16um diameter.

Important

The exact shape of the device has not been published yet. We assume the array fits on a circular 1mm-diameter substrate, which leaves us with 532 electrodes.

New in version 0.7.

Parameters:

x/y/z (double) – 3D location of the center of the electrode array. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance). z can either be a list with 532 entries or a scalar that is applied to all electrodes.
rot (float, optional) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
eye ({'LE', 'RE'}, optional) – Eye in which array is implanted.
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})

class pulse2percept.implants.ProsthesisSystem(earray, stim=None, eye='RE', preprocess=False, safe_mode=False)[source]¶

Visual prosthesis system

A visual prosthesis combines an electrode array and (optionally) a stimulus. This is the base class for prosthesis systems such as ArgusII and AlphaIMS.

New in version 0.6.

Parameters:

earray (ElectrodeArray or) – Electrode The electrode array used to deliver electrical stimuli to the retina.
stim (Stimulus source type) – A valid source type for the Stimulus object (e.g., scalar, NumPy array, pulse train).
eye ('LE' or 'RE') – A string indicating whether the system is implanted in the left (‘LE’) or right eye (‘RE’)
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

Examples

A system in the left eye made from a single DiskElectrode with radius r=100um sitting at x=200um, y=-50um, z=10um:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> implant = ProsthesisSystem(DiskElectrode(200, -50, 10, 100), eye='LE')

Note

A stimulus can also be assigned later (see stim).

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})

class pulse2percept.implants.SquareElectrode(x, y, z, a, name=None, activated=True)[source]¶

Square electrode

New in version 0.7.

Parameters:

x/y/z (double) – 3D location of the electrode. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance).
a (double) – Side length of the square
name (str, optional) – Electrode name
activated (bool) – To deactivate, set to False. Deactivated electrodes cannot receive stimuli.

plot(autoscale=False, ax=None)[source]¶

Plot

Parameters:	autoscale (bool, optional) – Whether to adjust the x,y limits of the plot ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None given, a new one will be created.
Returns:	ax (`matplotlib.axes.Axes`) – Returns the axis object of the plot

class pulse2percept.implants.IMIE(x=0, y=0, z=0, rot=0, eye='RE', stim=None, preprocess=True, safe_mode=False)[source]¶

The 256-channel epiretinal prosthesis system (IMIE 256)

This class implements a 256-channel Intelligent Micro Implant Eye epiretinal prosthesis system (IMIE 256) [Xu2021]. It was co-developed by Golden Eye Bionic, LLC (Pasadena CA) and IntelliMicro Medical Co., Ltd. (Changsha, Hunan Province, China) and is manufactured by IntelliMicro.

IMIE contains 248 large electrodes (210 µm in diameter) and 8 smaller electrodes (160 µm in diameter) arranged in a 4.75mm×6.50mm area.

The array is oriented upright in the visual field, such that an array with center (0,0) has the top three rows lie in the lower retina (upper visual field):

Parameters:

x/y/z (double) – 3D location of the center of the electrode array. The coordinate system is centered over the fovea. Positive x values move the electrode into the nasal retina. Positive y values move the electrode into the superior retina. Positive z values move the electrode away from the retina into the vitreous humor (sometimes called electrode-retina distance). z can either be a list with 35 entries or a scalar that is applied to all electrodes.
rot (float) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
eye ({'RE', 'LE'}, optional) – Eye in which array is implanted.
preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).
safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

check_stim(stim)[source]¶

Quality-check the stimulus

This method is executed every time a new value is assigned to stim.

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced.

The user can define their own checks in implants that inherit from ProsthesisSystem.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).

earray¶: Electrode array

electrode_names¶: Return a list of all electrode names in the electrode array

electrode_objects¶: Return a list of all electrode objects in the array

electrodes¶

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the prosthesis system object, e.g. implant['A1'] or implant[0].

eye¶

Implanted eye

A ProsthesisSystem can be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such as AxonMapModel will treat left and right eyes differently (for example, adjusting the location of the optic disc).

Examples

Implant Argus II in a left eye:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(eye='LE')

n_electrodes¶

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim_cmap=False)[source]¶

Plot

Parameters:

annotate (bool, optional) – Whether to scale the axes view to the data
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

preprocess_stim(stim)[source]¶

Preprocess the stimulus

This methods is executed every time a new value is assigned to stim.

No preprocessing is performed by default, but the user can define their own method in implants that inherit from return stim ProsthesisSystem.

A custom method must return a Stimulus object with the correct number of electrodes for the implant.

Parameters:	stim (`Stimulus` source type) – A valid source type for the `Stimulus` object (e.g., scalar, NumPy array, pulse train).
Returns:	stim_out (`Stimulus` object)

stim¶

Stimulus

A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see Stimulus for a complete list).

A stimulus can be assigned either in the ProsthesisSystem constructor or later by assigning a value to stim.

Note

Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in earray.

Examples

Send a biphasic pulse (30uA, 0.45ms phase duration) to an implant made from a single DiskElectrode:

>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem
>>> from pulse2percept.stimuli import BiphasicPulse
>>> implant = ProsthesisSystem(DiskElectrode(0, 0, 0, 100))
>>> implant.stim = BiphasicPulse(30, 0.45)

Stimulate Electrode B7 in Argus II with 13 uA:

>>> from pulse2percept.implants import ArgusII
>>> implant = ArgusII(stim={'B7': 13})