pulse2percept.implants.argus

ArgusI, ArgusII

Classes

ArgusI([x, y, z, rot, eye, stim, ...])

Create an Argus I array on the retina

ArgusII([x, y, z, rot, eye, stim, ...])

Create an Argus II array on the retina
class pulse2percept.implants.argus.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)
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']
DiskElectrode(activated=True, name='B1', r=250.0, x=-400.0,
              y=-1200.0, z=100.0)
>>> argus[0, 1]
DiskElectrode(activated=True, name='B1', r=250.0, x=-400.0,
              y=-1200.0, z=100.0)
property earray

Electrode array

property 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})
property 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')
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).

property electrode_names

Return a list of all electrode names in the electrode array

property electrode_objects

Return a list of all electrode objects in the array

property 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].

property 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)

class pulse2percept.implants.argus.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)
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']
DiskElectrode(activated=True, name='E7', r=112.5, x=862.5,
              y=862.5, z=100.0)
>>> argus[4, 6]
DiskElectrode(activated=True, name='E7', r=112.5, x=862.5,
              y=862.5, z=100.0)
property earray

Electrode array

property 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})
property 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')
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).

property electrode_names

Return a list of all electrode names in the electrode array

property electrode_objects

Return a list of all electrode objects in the array

property 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].

property 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)