pulse2percept.implants.retina

Retinal implants: Argus, Alpha, suprachoroidal, IMIE, and PRIMA arrays

base	RetinalImplant
argus	ArgusI, ArgusII
alpha	AlphaIMS, AlphaAMS
suprachoroidal	Suprachoroidal retinal prostheses by Bionic Vision Australia/Technologies
imie	IMIE
prima	PhotovoltaicPixel, PRIMAPivotal, Lorach2015Array, Ho2019FlatArray, Huang2021Array

See also

• Basic Concepts > Visual Prostheses

class pulse2percept.implants.retina.AlphaAMS(z=0, eye='right', preprocess=True, safe_mode=False)

Alpha-AMS

This class creates an Alpha-AMS array with 1600 photovoltaic pixels (each 30um in diameter) as described in [Stingl2017]. Electrode coordinates are device-local, centered on (0, 0).

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:

• z (float, list, or Quantity, optional) – Electrode height (um) above the array’s own plane: a scalar applies to every electrode, a list of 1600 entries gives each its own. May be given as unitful quantities (e.g. z=100 * um); see pulse2percept.units.

• eye ({'right', 'left'}, 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 stimulus is prepared, 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:

>>> from pulse2percept.implants.retina import AlphaAMS
>>> AlphaAMS()
AlphaAMS(electrode_array=ElectrodeGrid, eye='right', preprocess=True,
         safe_mode=False, shape=(40, 40))

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

>>> alpha_ims = AlphaAMS()
>>> alpha_ims['A3']
DiskElectrode(activated=True, name='A3', radius=15.0,
              x=-1225.0, y=-1365.0, z=0.0)
>>> alpha_ims[0, 2]
DiskElectrode(activated=True, name='A3', radius=15.0,
              x=-1225.0, y=-1365.0, z=0.0)

placement = 'subretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

property electrode_array

Electrode array

check_stim(stim)

Quality-check the stimulus

This method is executed every time a stimulus is prepared (see prepare_stim()).

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. If max_current is set, it will only allow stimuli whose total instantaneous current stays within it.

Both are questions about electricity, and neither can be answered about a stimulus that is not a current, so each raises a DimensionMismatchError on one. In the ordinary flow this cannot happen: prepare_stim() has already checked the stimulus against stimulus_unit. check_stim is public, though, and may be handed anything.

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

Parameters:

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

Raises:

• DimensionMismatchError – If an electrical check was requested and stim is not measured in units of current.

• .. versionchanged: – 0.10.0: The electrical checks verify that the stimulus really is electrical, instead of reading whatever numbers it holds as microamps.

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the device in its local coordinate frame.

Use model.plot(show_implant=True) to show model-side placement.

Parameters:

• annotate (bool, optional) – Whether to label electrodes.

• 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 (Stimulus source type, optional) –

  What is presented to the device. Prepared through prepare_stim(), so the colors show what the electrodes actually deliver. Required by stim_cmap.

  Added in version 0.11.0.

• 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 – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = uA

Unit used by prepared stimuli. Defaults to electrical current.

technology = None

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.AlphaIMS(z=0, eye='right', preprocess=True, safe_mode=False)

Alpha-IMS

This class creates an Alpha-IMS array with 1500 photovoltaic pixels (each 50um in diameter) as described in [Stingl2013]. Electrode coordinates are device-local, centered on (0, 0).

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:

• z (float, list, or Quantity, optional) – Electrode height (um) above the array’s own plane: a scalar applies to every electrode, a list of 1500 entries gives each its own. May be given as unitful quantities (e.g. z=100 * um); see pulse2percept.units.

• eye ({'right', 'left'}, 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 stimulus is prepared, 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:

>>> from pulse2percept.implants.retina import AlphaIMS
>>> AlphaIMS()
AlphaIMS(electrode_array=ElectrodeGrid, eye='right', preprocess=True,
         safe_mode=False, shape=(39, 39))

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

>>> alpha_ims = AlphaIMS()
>>> alpha_ims['A3']
SquareElectrode(activated=True, name='A3', side_length=50.0,
                x=-1224.0, y=-1368.0, z=0.0)
>>> alpha_ims[0, 2]
SquareElectrode(activated=True, name='A3', side_length=50.0,
                x=-1224.0, y=-1368.0, z=0.0)

placement = 'subretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

property electrode_array

Electrode array

check_stim(stim)

Quality-check the stimulus

This method is executed every time a stimulus is prepared (see prepare_stim()).

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. If max_current is set, it will only allow stimuli whose total instantaneous current stays within it.

Both are questions about electricity, and neither can be answered about a stimulus that is not a current, so each raises a DimensionMismatchError on one. In the ordinary flow this cannot happen: prepare_stim() has already checked the stimulus against stimulus_unit. check_stim is public, though, and may be handed anything.

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

Parameters:

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

Raises:

• DimensionMismatchError – If an electrical check was requested and stim is not measured in units of current.

• .. versionchanged: – 0.10.0: The electrical checks verify that the stimulus really is electrical, instead of reading whatever numbers it holds as microamps.

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the device in its local coordinate frame.

Use model.plot(show_implant=True) to show model-side placement.

Parameters:

• annotate (bool, optional) – Whether to label electrodes.

• 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 (Stimulus source type, optional) –

  What is presented to the device. Prepared through prepare_stim(), so the colors show what the electrodes actually deliver. Required by stim_cmap.

  Added in version 0.11.0.

• 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 – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = uA

Unit used by prepared stimuli. Defaults to electrical current.

technology = None

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.ArgusI(z=0, eye='right', preprocess=True, safe_mode=False, use_legacy_names=False)

Create an Argus I array

Electrode coordinates are device-local, centered on (0, 0).

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:

• z (float, list, or Quantity, optional) – Electrode height (um) above the array’s own plane: a scalar applies to every electrode, a list of 16 entries gives each its own. May be given as unitful quantities (e.g. z=100 * um); see pulse2percept.units.

• eye ({'right', 'left'}, 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 stimulus is prepared, 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:

>>> from pulse2percept.implants.retina import ArgusI
>>> ArgusI()
ArgusI(electrode_array=ElectrodeGrid, eye='right', preprocess=True,
       safe_mode=False, shape=(4, 4))

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

>>> argus = ArgusI()
>>> argus['B1']
DiskElectrode(activated=True, name='B1', radius=250.0,
              x=-400.0, y=-1200.0, z=0.0)
>>> argus[0, 1]
DiskElectrode(activated=True, name='B1', radius=250.0,
              x=-400.0, y=-1200.0, z=0.0)

placement = 'epiretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

property electrode_array

Electrode array

check_stim(stim)

Quality-check the stimulus

This method is executed every time a stimulus is prepared (see prepare_stim()).

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. If max_current is set, it will only allow stimuli whose total instantaneous current stays within it.

Both are questions about electricity, and neither can be answered about a stimulus that is not a current, so each raises a DimensionMismatchError on one. In the ordinary flow this cannot happen: prepare_stim() has already checked the stimulus against stimulus_unit. check_stim is public, though, and may be handed anything.

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

Parameters:

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

Raises:

• DimensionMismatchError – If an electrical check was requested and stim is not measured in units of current.

• .. versionchanged: – 0.10.0: The electrical checks verify that the stimulus really is electrical, instead of reading whatever numbers it holds as microamps.

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the device in its local coordinate frame.

Use model.plot(show_implant=True) to show model-side placement.

Parameters:

• annotate (bool, optional) – Whether to label electrodes.

• 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 (Stimulus source type, optional) –

  What is presented to the device. Prepared through prepare_stim(), so the colors show what the electrodes actually deliver. Required by stim_cmap.

  Added in version 0.11.0.

• 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 – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = uA

Unit used by prepared stimuli. Defaults to electrical current.

technology = None

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.ArgusII(z=0, eye='right', preprocess=True, safe_mode=False, encoder=<object object>, raster=<object object>, thresholds=None)

Create an Argus II array

Electrode coordinates are device-local, centered on (0, 0).

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:

• z (float, list, or Quantity, optional) – Electrode height (um) above the array’s own plane: a scalar applies to every electrode, a list of 60 entries gives each its own. May be given as unitful quantities (e.g. z=100 * um); see pulse2percept.units.

• eye ({'right', 'left'}, 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 stimulus is prepared, or a custom function (callable).

• safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

• encoder (ImplantEncoder, optional) –

  How the device turns a picture into stimulation. Defaults to a fresh AmplitudeEncoder at 6 Hz, which is the rate Argus II runs its video at. Pass encoder=None to switch automatic encoding off, so that an image or video input is refused rather than encoded.

  Added in version 0.10.0.

• raster (Raster, optional) –

  How the stimulator takes turns between electrodes. Defaults to a fresh SequentialRaster of six groups 2 ms apart, i.e. one row of ten electrodes at a time. Pass raster=None to drive every electrode at once.

  Added in version 0.10.0.

• thresholds (float, Quantity, or dict, optional) –

  Perceptual threshold current (uA) of the participant this device is modeling, used to calibrate threshold-relative (xTh) stimuli. A scalar applies to every electrode; a dict calibrates the named electrodes only. See thresholds.

  Added in version 0.11.0.

Examples

Create an Argus II array:

>>> from pulse2percept.implants.retina import ArgusII
>>> ArgusII()
ArgusII(electrode_array=ElectrodeGrid, encoder=AmplitudeEncoder,
        eye='right', preprocess=True, raster=SequentialRaster,
        safe_mode=False, shape=(6, 10))

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

>>> argus = ArgusII()
>>> argus['E7']
DiskElectrode(activated=True, name='E7', radius=112.5,
              x=862.5, y=862.5, z=0.0)
>>> argus[4, 6]
DiskElectrode(activated=True, name='E7', radius=112.5,
              x=862.5, y=862.5, z=0.0)

Because the device brings its own encoder, a picture can be presented directly and comes back as current:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

placement = 'epiretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

property electrode_array

Electrode array

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

check_stim(stim)

Quality-check the stimulus

This method is executed every time a stimulus is prepared (see prepare_stim()).

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. If max_current is set, it will only allow stimuli whose total instantaneous current stays within it.

Both are questions about electricity, and neither can be answered about a stimulus that is not a current, so each raises a DimensionMismatchError on one. In the ordinary flow this cannot happen: prepare_stim() has already checked the stimulus against stimulus_unit. check_stim is public, though, and may be handed anything.

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

Parameters:

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

Raises:

• DimensionMismatchError – If an electrical check was requested and stim is not measured in units of current.

• .. versionchanged: – 0.10.0: The electrical checks verify that the stimulus really is electrical, instead of reading whatever numbers it holds as microamps.

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the device in its local coordinate frame.

Use model.plot(show_implant=True) to show model-side placement.

Parameters:

• annotate (bool, optional) – Whether to label electrodes.

• 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 (Stimulus source type, optional) –

  What is presented to the device. Prepared through prepare_stim(), so the colors show what the electrodes actually deliver. Required by stim_cmap.

  Added in version 0.11.0.

• 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 – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = uA

Unit used by prepared stimuli. Defaults to electrical current.

technology = None

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

class pulse2percept.implants.retina.Suprachoroidal24(z=0, eye='right', preprocess=False, safe_mode=False)

First-generation 24-channel suprachoroidal retinal prosthesis

First-generation suprachoroidal system [Layton2014] developed by Bionic Vision Australia and later Bionic Vision Technologies. Electrode coordinates are device-local, centered on (0, 0).

“24” is the published channel count, not the number of physical electrodes. This model represents all 35 physical electrodes separately; hardware ganging of C21a-m is not applied automatically:

• 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 array’s own (0, 0) origin is assumed to lie between Electrodes C7, C8, C9, and C13.

Note

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

Added in version 0.6.

Parameters:

• z (float, list, or Quantity, optional) – Electrode height (um) above the array’s own plane: a scalar applies to every electrode, a list of 35 entries gives each its own. May be given as unitful quantities (e.g. z=100 * um); see pulse2percept.units.

• eye ({'right', 'left'}, 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 stimulus is prepared, or a custom function (callable).

• safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

placement = 'suprachoroidal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

property electrode_array

Electrode array

check_stim(stim)

Quality-check the stimulus

This method is executed every time a stimulus is prepared (see prepare_stim()).

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. If max_current is set, it will only allow stimuli whose total instantaneous current stays within it.

Both are questions about electricity, and neither can be answered about a stimulus that is not a current, so each raises a DimensionMismatchError on one. In the ordinary flow this cannot happen: prepare_stim() has already checked the stimulus against stimulus_unit. check_stim is public, though, and may be handed anything.

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

Parameters:

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

Raises:

• DimensionMismatchError – If an electrical check was requested and stim is not measured in units of current.

• .. versionchanged: – 0.10.0: The electrical checks verify that the stimulus really is electrical, instead of reading whatever numbers it holds as microamps.

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the device in its local coordinate frame.

Use model.plot(show_implant=True) to show model-side placement.

Parameters:

• annotate (bool, optional) – Whether to label electrodes.

• 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 (Stimulus source type, optional) –

  What is presented to the device. Prepared through prepare_stim(), so the colors show what the electrodes actually deliver. Required by stim_cmap.

  Added in version 0.11.0.

• 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 – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = uA

Unit used by prepared stimuli. Defaults to electrical current.

technology = None

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.Suprachoroidal44(z=0, eye='left', preprocess=False, safe_mode=False)

Second-generation 44-channel suprachoroidal retinal prosthesis

Second-generation suprachoroidal system [Petoe2021] developed by Bionic Vision Australia and Bionic Vision Technologies. The 44 channels are the 44 stimulating electrodes; the model adds 2 return electrodes (46 total).

The device-local origin lies at the center of electrodes D4, D5, C4 and E4.

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.

Added in version 0.8.

Parameters:

• z (float, list, or Quantity, optional) – Electrode height (um) above the array’s own plane: a scalar applies to every electrode, a list of 46 entries gives each its own. May be given as unitful quantities (e.g. z=100 * um); see pulse2percept.units.

• eye ({'right', 'left'}, 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 stimulus is prepared, or a custom function (callable).

• safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

placement = 'suprachoroidal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

property electrode_array

Electrode array

check_stim(stim)

Quality-check the stimulus

This method is executed every time a stimulus is prepared (see prepare_stim()).

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. If max_current is set, it will only allow stimuli whose total instantaneous current stays within it.

Both are questions about electricity, and neither can be answered about a stimulus that is not a current, so each raises a DimensionMismatchError on one. In the ordinary flow this cannot happen: prepare_stim() has already checked the stimulus against stimulus_unit. check_stim is public, though, and may be handed anything.

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

Parameters:

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

Raises:

• DimensionMismatchError – If an electrical check was requested and stim is not measured in units of current.

• .. versionchanged: – 0.10.0: The electrical checks verify that the stimulus really is electrical, instead of reading whatever numbers it holds as microamps.

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the device in its local coordinate frame.

Use model.plot(show_implant=True) to show model-side placement.

Parameters:

• annotate (bool, optional) – Whether to label electrodes.

• 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 (Stimulus source type, optional) –

  What is presented to the device. Prepared through prepare_stim(), so the colors show what the electrodes actually deliver. Required by stim_cmap.

  Added in version 0.11.0.

• 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 – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = uA

Unit used by prepared stimuli. Defaults to electrical current.

technology = None

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.Ho2019FlatArray(pixel_size, z=0, eye='right', preprocess=False, safe_mode=False, encoder=<object object>)

Create a flat photovoltaic array of [Ho2019]

Supports the F55 and F40 arrays on a 1 mm substrate:

pixel_size (um)	pixels	row spacing	active electrode
55 (F55)	250	47.6 um	14 um diameter
40 (F40)	502	34.6 um	10 um diameter

Added in version 0.11.0.

Parameters:

• pixel_size ({55, 40}) – Pixel width (um), which selects the device variant.

• z (float, list, or Quantity, optional) – Electrode height (um) above the array’s own plane: a scalar applies to every electrode, a list of them gives each its own. May be given as unitful quantities (e.g. z=100 * um); see pulse2percept.units.

• eye ({'right', 'left'}, 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 stimulus is prepared, or a custom function (callable).

• safe_mode (bool, optional) – Not supported: no optical operating envelope has been published for this array, and the PRIMA projector limits are specific to PRIMAPivotal.

• encoder (ImplantEncoder, optional) – Image/video encoder. Pass None to disable automatic encoding.

Notes

• Driven by pulsed near-infrared illumination: prepare_stim() returns irradiance (mW/mm^2). Photovoltaic conversion to tissue current is not modeled.

• The default encoder reproduces the 915 nm, 8 mW/mm^2, 4 ms, 40 Hz illumination of the [Ho2019] grating experiments. Gray levels set ON duration linearly, which is a pulse2percept simulation convention: the paper does not specify a natural-image grayscale transfer function.

• [Ho2019] also describes pillar arrays Pil55 and Pil40, which are not modeled here.

• The F55 layout is reconstructed from Fig. 2(a). The F40 outline is not published; its 502 pixels are taken as the nearest lattice sites to the substrate center.

• The 1 um isolation trenches are covered by the shared return electrode, so gap is 0.

placement = 'subretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

property electrode_array

Electrode array

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the implant and its 1 mm substrate.

Added in version 0.11.0.

property row_spacing

Distance (um) between adjacent pixel rows.

check_stim(stim)

Require finite, non-negative irradiance.

Charge balance does not apply to light and is not checked. With safe_mode, a subclass may additionally check its own documented optical operating envelope; arrays without one reject safe_mode rather than borrow another device’s limits.

Added in version 0.11.0.

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = mW/mm^2

The device is illuminated, not driven by a current source.

technology = 'photovoltaic'

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.Huang2021Array(pixel_size, z=0, eye='right', preprocess=False, safe_mode=False, encoder=<object object>)

Create a vertical-junction photovoltaic array of [Huang2021]

Supports four arrays on a 1.5 mm substrate. Only exposed pixels are modeled as electrodes:

pixel_size (um)	n_electrodes	fabricated pixels	active electrode
55	421	526	22 um diameter
40	821	1027	16 um diameter
30	1388	1735	12 um diameter
20	2806	3508	8 um diameter

Added in version 0.11.0.

Parameters:

• pixel_size ({55, 40, 30, 20}) – Pixel width (um), which selects the device variant.

• z (float, list, or Quantity, optional) – Electrode height (um) above the array’s own plane: a scalar applies to every electrode, a list of them gives each its own. May be given as unitful quantities (e.g. z=100 * um); see pulse2percept.units.

• eye ({'right', 'left'}, 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 stimulus is prepared, or a custom function (callable).

• safe_mode (bool, optional) –

  Not supported: no optical operating envelope has been published for this array, and the PRIMA projector limits are specific to PRIMAPivotal. True raises when a stimulus is checked.

  Changed in version 0.11.0: No longer applies the PRIMA projector envelope to this array.

• encoder (ImplantEncoder, optional) –

  Image/video encoder. Defaults to a PhotovoltaicEncoder configured for the illumination reported in [Huang2021] (880 nm, 4.7 mW/mm^2, 10 ms pulses at 2 Hz). Pass None to disable automatic encoding.

  Added in version 0.11.0.

Notes

• Driven by pulsed near-infrared illumination: prepare_stim() returns irradiance (mW/mm^2). Photovoltaic conversion to tissue current is not modeled.

• The default encoder reproduces the 880 nm, 10 ms, 2 Hz full-field stimulation of [Huang2021]. Gray levels set ON duration linearly (a p2p convention).

• n_total_pixels gives the fabricated pixel count; peripheral pixels covered by the common return are not modeled as electrodes.

• Exposed-pixel layouts are reconstructed from Fig. 7 of [Huang2021]. Three rim pixels of the 20 um array are inferred; one is ambiguous.

• Isolation trenches are covered by the shared return electrode, so gap is 0.

• The substrate is modeled as a 1.5 mm circle; the small die notch is omitted.

placement = 'subretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

property electrode_array

Electrode array

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the implant and its 1.5 mm substrate.

Added in version 0.11.0.

property row_spacing

Distance (um) between adjacent pixel rows.

check_stim(stim)

Require finite, non-negative irradiance.

Charge balance does not apply to light and is not checked. With safe_mode, a subclass may additionally check its own documented optical operating envelope; arrays without one reject safe_mode rather than borrow another device’s limits.

Added in version 0.11.0.

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = mW/mm^2

The device is illuminated, not driven by a current source.

technology = 'photovoltaic'

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.IMIE(z=0, eye='right', preprocess=True, safe_mode=False)

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:

• z (float, list, or Quantity, optional) – Electrode height (um) above the array’s own plane: a scalar applies to every electrode, a list of 35 entries gives each its own. May be given as unitful quantities (e.g. z=100 * um); see pulse2percept.units.

• eye ({'right', 'left'}, 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 stimulus is prepared, or a custom function (callable).

• safe_mode (bool, optional) – If safe mode is enabled, only charge-balanced stimuli are allowed.

placement = 'epiretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

property electrode_array

Electrode array

check_stim(stim)

Quality-check the stimulus

This method is executed every time a stimulus is prepared (see prepare_stim()).

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. If max_current is set, it will only allow stimuli whose total instantaneous current stays within it.

Both are questions about electricity, and neither can be answered about a stimulus that is not a current, so each raises a DimensionMismatchError on one. In the ordinary flow this cannot happen: prepare_stim() has already checked the stimulus against stimulus_unit. check_stim is public, though, and may be handed anything.

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

Parameters:

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

Raises:

• DimensionMismatchError – If an electrical check was requested and stim is not measured in units of current.

• .. versionchanged: – 0.10.0: The electrical checks verify that the stimulus really is electrical, instead of reading whatever numbers it holds as microamps.

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the device in its local coordinate frame.

Use model.plot(show_implant=True) to show model-side placement.

Parameters:

• annotate (bool, optional) – Whether to label electrodes.

• 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 (Stimulus source type, optional) –

  What is presented to the device. Prepared through prepare_stim(), so the colors show what the electrodes actually deliver. Required by stim_cmap.

  Added in version 0.11.0.

• 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 – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = uA

Unit used by prepared stimuli. Defaults to electrical current.

technology = None

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.Lorach2015Array(z=0, eye='right', preprocess=False, safe_mode=False, encoder=<object object>)

Create the 70 um photovoltaic array of [Lorach2015]

The array has 142 pixels, each 70 um wide on a 75 um hexagonal grid, with a 20 um active electrode, on a nominal 1 mm substrate.

Added in version 0.7.

Changed in version 0.11.0: Renamed from PRIMA75; that name was pulse2percept shorthand.

Parameters:

• z (float, list, or Quantity, optional) – Electrode height (um) above the array’s own plane: a scalar applies to every electrode, a list of 142 entries gives each its own. May be given as unitful quantities (e.g. z=100 * um); see pulse2percept.units.

• eye ({'right', 'left'}, 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 stimulus is prepared, or a custom function (callable).

• safe_mode (bool, optional) –

  Not supported: no optical operating envelope has been published for this array, and the PRIMA projector limits are specific to PRIMAPivotal. True raises when a stimulus is checked.

  Changed in version 0.11.0: No longer applies the PRIMA projector envelope to this array.

• encoder (ImplantEncoder, optional) –

  Image/video encoder. Defaults to a PhotovoltaicEncoder configured for the illumination reported in [Lorach2015] (915 nm, 4 mW/mm^2, 4 ms pulses at 40 Hz). Pass None to disable automatic encoding.

  Added in version 0.11.0.

Notes

• Driven by pulsed near-infrared illumination: prepare_stim() returns irradiance (mW/mm^2). Photovoltaic conversion to tissue current is not modeled.

• The default encoder reproduces the 915 nm, 4 mW/mm^2, 4 ms, 40 Hz illumination of the [Lorach2015] grating experiments. Gray levels set ON duration linearly, which is a pulse2percept simulation convention: the paper does not specify a natural-image grayscale transfer function.

• [Lorach2015] reports the 65 um row spacing as the “pixel pitch”.

• Seven rim pixels extend beyond the nominal 1 mm substrate and are clipped when plotted.

placement = 'subretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

property electrode_array

Electrode array

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the implant and its 1 mm substrate.

Added in version 0.11.0.

property row_spacing

Distance (um) between adjacent pixel rows.

check_stim(stim)

Require finite, non-negative irradiance.

Charge balance does not apply to light and is not checked. With safe_mode, a subclass may additionally check its own documented optical operating envelope; arrays without one reject safe_mode rather than borrow another device’s limits.

Added in version 0.11.0.

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = mW/mm^2

The device is illuminated, not driven by a current source.

technology = 'photovoltaic'

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.PhotovoltaicPixel(x, y, z, radius, apothem, name=None, activated=True, orientation='vertical', rot=0)

Photovoltaic pixel

A hexagonal pixel body with a circular active electrode at its center.

Added in version 0.7.

Parameters:

• x/y/z (double) – Location of the pixel (um) in the array’s own coordinate frame.

• radius (double) – Radius (um) of the active electrode.

• apothem (double) – Apothem (um) of the hexagonal pixel body.

• activated (bool) – To deactivate, set to False. Deactivated electrodes cannot receive stimuli.

• orientation ({'horizontal', 'vertical'}, optional) –

  Pixel orientation.

  Added in version 0.11.0.

• rot (double, optional) –

  Local pixel rotation (deg, positive counter-clockwise).

  Added in version 0.11.0.

Notes

• Lengths may be given as plain numbers of microns or as unitful quantities. See pulse2percept.units.

coordinate_unit = um

The unit electrode coordinates are stored in. Electrodes hold plain numbers, which is what every kernel downstream of them expects; this says what those numbers mean.

coordinates(unit=None)

3D position of the electrode

Added in version 0.10.0.

Parameters:

unit (Unit, optional) – Length unit to express the position in. If None, the position is returned as it is stored (microns).

Returns:

coords – An ordinary NumPy array [x, y, z], never a Quantity.

Return type:

(3,) np.ndarray

Examples

>>> from pulse2percept.implants import DiskElectrode
>>> from pulse2percept.units import mm
>>> DiskElectrode(1000, 0, 100, 200).coordinates(mm)
array([1. , 0. , 0.1])

plot(autoscale=False, ax=None)

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 – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

property width

Flat-to-flat width (um) of the hexagon

Added in version 0.11.0.

class pulse2percept.implants.retina.PRIMAPivotal(z=0, eye='right', preprocess=False, safe_mode=False, encoder=<object object>)

Create the PRIMA array used in the pivotal PRIMAvera trial

The implant has 378 photovoltaic pixels, each 100 um wide on a 100 um hexagonal grid, with a 28 um active electrode, on a 2 x 2 mm substrate [Holz2026]. The same configuration was used in the earlier first-in-human study [Palanker2020].

Added in version 0.7.

Changed in version 0.11.0: Pixel width corrected from 85 to 100 um; pixel centers are unchanged.

Changed in version 0.11.0: Renamed from PRIMA to distinguish this pivotal-trial configuration from future commercial hardware.

Parameters:

• z (float, list, or Quantity, optional) – Electrode height (um) above the array’s own plane: a scalar applies to every electrode, a list of 378 entries gives each its own. May be given as unitful quantities (e.g. z=100 * um); see pulse2percept.units.

• eye ({'right', 'left'}, 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 stimulus is prepared, or a custom function (callable).

• safe_mode (bool, optional) –

  Enforces the documented projector operating envelope: 880 nm illumination, irradiance <= 3.5 mW/mm^2, ON durations on the 0.7 ms grid and <= 9.8 ms, duty cycle <= 0.294, and frame rate <= 30 Hz. All 378 pixels may be illuminated simultaneously. This is not a biological safety limit or a demonstrated hardware maximum.

  Changed in version 0.11.0: Checks the optical envelope instead of electrical charge balance.

• encoder (ImplantEncoder, optional) –

  Image/video encoder. Defaults to PRIMAEncoder, which describes the pivotal-trial projector. Pass None to disable automatic encoding.

  Added in version 0.11.0.

Notes

• The active-electrode diameter was estimated from Fig. 1 of [Palanker2020].

• prepare_stim() returns optical irradiance (mW/mm^2). Photovoltaic conversion is not modeled.

• Gray levels map linearly onto the projector’s 0.7 ms duration grid. The clinical camera-to-pulse-duration transfer function is not published, so that mapping is a pulse2percept convention.

placement = 'subretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

family = 'PRIMA'

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

property electrode_array

Electrode array

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the implant and its 2 x 2 mm substrate.

Added in version 0.11.0.

property row_spacing

Distance (um) between adjacent pixel rows.

check_stim(stim)

Require finite, non-negative irradiance.

Charge balance does not apply to light and is not checked. With safe_mode, a subclass may additionally check its own documented optical operating envelope; arrays without one reject safe_mode rather than borrow another device’s limits.

Added in version 0.11.0.

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = mW/mm^2

The device is illuminated, not driven by a current source.

technology = 'photovoltaic'

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.RetinalImplant(electrode_array, eye='right', **kwargs)

Retinal prosthesis

A retinal prosthesis is an Implant that stimulates the retina, and therefore sits in one eye. This is the base class for devices such as ArgusII and AlphaIMS, and can be used directly to give a custom electrode array an eye.

Added in version 0.11.0.

Parameters:

• electrode_array (ElectrodeArray or) – Electrode The electrode array used to deliver electrical stimuli to the retina.

• eye ('left' or 'right', optional) – A string indicating whether the system is implanted in the left or right eye. Case-insensitive on input; stored lowercase.

• **kwargs – Keyword arguments accepted by Implant, such as preprocess, safe_mode, encoder, raster, max_current, thresholds and scene_input_frame.

Examples

Give a custom grid of electrodes a left eye:

>>> from pulse2percept.implants import ElectrodeGrid
>>> from pulse2percept.implants.retina import RetinalImplant
>>> implant = RetinalImplant(ElectrodeGrid((4, 4), 400), eye='left')
>>> implant.eye
'left'

check_stim(stim)

Quality-check the stimulus

This method is executed every time a stimulus is prepared (see prepare_stim()).

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. If max_current is set, it will only allow stimuli whose total instantaneous current stays within it.

Both are questions about electricity, and neither can be answered about a stimulus that is not a current, so each raises a DimensionMismatchError on one. In the ordinary flow this cannot happen: prepare_stim() has already checked the stimulus against stimulus_unit. check_stim is public, though, and may be handed anything.

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

Parameters:

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

Raises:

• DimensionMismatchError – If an electrical check was requested and stim is not measured in units of current.

• .. versionchanged: – 0.10.0: The electrical checks verify that the stimulus really is electrical, instead of reading whatever numbers it holds as microamps.

property electrode_array

Electrode array

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

placement = None

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the device in its local coordinate frame.

Use model.plot(show_implant=True) to show model-side placement.

Parameters:

• annotate (bool, optional) – Whether to label electrodes.

• 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 (Stimulus source type, optional) –

  What is presented to the device. Prepared through prepare_stim(), so the colors show what the electrodes actually deliver. Required by stim_cmap.

  Added in version 0.11.0.

• 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 – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = uA

Unit used by prepared stimuli. Defaults to electrical current.

technology = None

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

class pulse2percept.implants.retina.PRIMA(**kwargs)

Deprecated name for the pivotal-trial PRIMA array.

Deprecated since version 0.11.0: Use PRIMAPivotal instead.

check_stim(stim)

Require finite, non-negative irradiance.

Charge balance does not apply to light and is not checked. With safe_mode, a subclass may additionally check its own documented optical operating envelope; arrays without one reject safe_mode rather than borrow another device’s limits.

Added in version 0.11.0.

property electrode_array

Electrode array

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

family = 'PRIMA'

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

placement = 'subretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the implant and its 2 x 2 mm substrate.

Added in version 0.11.0.

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property row_spacing

Distance (um) between adjacent pixel rows.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = mW/mm^2

The device is illuminated, not driven by a current source.

technology = 'photovoltaic'

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.PRIMA75(**kwargs)

Deprecated name for the 70 um array of [Lorach2015].

Deprecated since version 0.11.0: Use Lorach2015Array instead.

check_stim(stim)

Require finite, non-negative irradiance.

Charge balance does not apply to light and is not checked. With safe_mode, a subclass may additionally check its own documented optical operating envelope; arrays without one reject safe_mode rather than borrow another device’s limits.

Added in version 0.11.0.

property electrode_array

Electrode array

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

placement = 'subretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the implant and its 1 mm substrate.

Added in version 0.11.0.

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property row_spacing

Distance (um) between adjacent pixel rows.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = mW/mm^2

The device is illuminated, not driven by a current source.

technology = 'photovoltaic'

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.PRIMA55(**kwargs)

Deprecated name for the F55 array of [Ho2019].

Deprecated since version 0.11.0: Use Ho2019FlatArray(55) instead.

check_stim(stim)

Require finite, non-negative irradiance.

Charge balance does not apply to light and is not checked. With safe_mode, a subclass may additionally check its own documented optical operating envelope; arrays without one reject safe_mode rather than borrow another device’s limits.

Added in version 0.11.0.

property electrode_array

Electrode array

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

placement = 'subretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the implant and its 1 mm substrate.

Added in version 0.11.0.

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property row_spacing

Distance (um) between adjacent pixel rows.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = mW/mm^2

The device is illuminated, not driven by a current source.

technology = 'photovoltaic'

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.

class pulse2percept.implants.retina.PRIMA40(**kwargs)

Deprecated name for the F40 array of [Ho2019].

Deprecated since version 0.11.0: Use Ho2019FlatArray(40) instead.

check_stim(stim)

Require finite, non-negative irradiance.

Charge balance does not apply to light and is not checked. With safe_mode, a subclass may additionally check its own documented optical operating envelope; arrays without one reject safe_mode rather than borrow another device’s limits.

Added in version 0.11.0.

property electrode_array

Electrode array

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 implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

Must be an ImplantEncoder. Model-aware encoders such as TraceEncoder are called directly instead. If None, dimensionless image/video stimuli are not encoded automatically.

Assigning an unbound encoder (encoder.implant is None) binds it to this implant. An encoder bound to a different implant is rejected with a ValueError.

property eye

Implanted eye

A RetinalImplant can be implanted either in a left eye (‘left’) or right eye (‘right’). 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.retina import ArgusII
>>> implant = ArgusII(eye='left')

family = None

Named device family, if applicable, e.g. 'PRIMA'. .. versionadded:: 0.11.0

property max_current

Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

placement = 'subretinal'

Where the device sits relative to the tissue it stimulates, where the literature is unambiguous about it; None where it is not, or where the class describes a family rather than a device.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)

Plot the implant and its 1 mm substrate.

Added in version 0.11.0.

prepare_stim(source)

Turn a source into stimulation the implant can deliver.

Preparation applies preprocessing, converts the source to a Stimulus, encodes dimensionless visual input when an encoder is present, reshapes it to the electrode array, removes deactivated electrodes, applies threshold calibration, and runs safety checks. The input is not modified and the result is not stored.

Prepared stimuli use the implant’s stimulus_unit (electrical current for most devices; irradiance for PRIMA).

Images and videos require an encoder unless preprocessing already converts them to the implant’s stimulus_unit.

Added in version 0.11.0: Replaces the stateful stim property.

Parameters:

source (Stimulus source type) – Any source accepted by Stimulus, including electrical stimulation and image or video input for the implant encoder.

Returns:

stim – Stimulation delivered by the implant, or None for an empty source.

Return type:

Stimulus or None

Examples

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

Argus II includes an encoder, so it can prepare an image directly:

>>> from pulse2percept.stimuli import samples
>>> ArgusII().prepare_stim(samples.logo_bvl()).unit
uA

preprocess_stim(stim)

Preprocess the stimulus

This method is executed every time a stimulus is prepared.

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

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

Return type:

Stimulus object

property raster

Raster pattern used to schedule stimulation across electrodes.

Assigning a raster binds it to this implant.

property row_spacing

Distance (um) between adjacent pixel rows.

property scene_input_frame

Coordinate frame used to register scene input.

'eye' means gaze changes which scene content reaches the implant; 'head' means scene input is fixed relative to the head.

Defaults to default_scene_input_frame. Setting to None restores that default.

Added in version 0.11.0.

stimulus_unit = mW/mm^2

The device is illuminated, not driven by a current source.

technology = 'photovoltaic'

Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

Assign a single current for the whole array, a per-electrode dict, or None to clear the calibration. Threshold-relative pulse trains are calibrated against whatever is in force at the moment prepare_stim() runs.

Added in version 0.10.0.

Changed in version 0.11.0: Changing thresholds affects the next stimulus prepared, rather than rewriting one the implant was holding.