pulse2percept.implants.base

Implant, GridImplant

Classes

GridImplant(shape, spacing[, x, y, z, rot, ...])	A prosthesis system whose electrodes form a regular grid
Implant(electrode_array[, preprocess, ...])	Visual prosthesis

class pulse2percept.implants.base.Implant(electrode_array, preprocess=False, safe_mode=False, encoder=None, raster=None, max_current=None, thresholds=None, scene_input_frame=None)

Visual prosthesis

A visual prosthesis describes an electrode array together with the input pipeline that turns what is presented to the device into the stimulation its electrodes deliver (see prepare_stim()). This is the base class for implants such as ArgusII and Orion.

The generic base carries no anatomical laterality. Use RetinalImplant (eye) or CorticalImplant (hemisphere) for a device with a stimulation target.

Added in version 0.6.

Changed in version 0.11.0: Renamed from ProsthesisSystem, which stays available as a deprecated alias until 0.12.0.

Changed in version 0.11.0: No longer takes eye, which moved to RetinalImplant.

Changed in version 0.11.0: An implant no longer stores a stimulus. implant.stim = source became delivered = implant.prepare_stim(source), and a model is given the source rather than the implant (see predict_percept()).

Parameters:

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

• 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. Charge balance is an electrical property and requires current units. Non-current-driven devices may override this check.

• encoder (ImplantEncoder, optional) –

  Maps image or video gray levels to device stimulation. If None, dimensionless visual input is rejected. An unbound encoder is bound to this implant (see encoder).

  Added in version 0.10.0.

  Changed in version 0.11.0: Accepts any ImplantEncoder, not only an electrical PulseEncoder.

• raster (Raster, optional) –

  How the stimulator takes turns between electrodes that it cannot drive at the same time. If None, every electrode may fire at once. Assigning one binds it to this implant (see bind()), and it is the raster the encoder schedules against.

  Added in version 0.10.0.

• max_current (float, optional) –

  The total current (uA) the stimulator can source at any one instant, summed over all electrodes. If given, preparing a stimulus that exceeds it raises. If None, no such check is performed.

  May be given as a plain number of microamps or as a unitful quantity (e.g. 0.1 * mA); see pulse2percept.units.

  Added in version 0.10.0.

• scene_input_frame ('eye' or 'head', optional) –

  How gaze registers a scene onto this system, overriding what the device class does, e.g. 'eye' for an Argus II run with eye tracking. See scene_input_frame.

  Added in version 0.11.0.

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

  Perceptual threshold current (uA) 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

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

>>> from pulse2percept.implants import DiskElectrode, Implant
>>> implant = Implant(DiskElectrode(200, -50, 10, 100))

stimulus_unit = uA

Unit used by prepared stimuli. Defaults to electrical current.

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.

technology = None

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

family = None

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

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.

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 max_current

Total instantaneous current (uA) the stimulator can source

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.

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

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

property electrode_array

Electrode array

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

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

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

class pulse2percept.implants.base.GridImplant(shape, spacing, x=0, y=0, z=0, rot=0, names=('A', '1'), grid_type='rect', orientation='horizontal', electrode_type=<class 'pulse2percept.implants.electrodes.PointSource'>, preprocess=False, safe_mode=False, encoder=None, raster=None, max_current=None, scene_input_frame=None, **electrode_params)

A prosthesis system whose electrodes form a regular grid

Convenience composition of an ElectrodeGrid and a Implant, for the common case where a custom implant is just a grid of electrodes:

implant = GridImplant(shape=(10, 10), spacing=500)

is the same thing as:

implant = Implant(ElectrodeGrid(shape=(10, 10), spacing=500))

Anatomy-neutral, like Implant: for a grid with a stimulation target, hand the ElectrodeGrid to RetinalImplant or CorticalImplant instead.

Added in version 0.11.0.

Parameters:

• shape ((rows, cols)) – The number of rows x columns in the grid.

• spacing (double or (x_spacing, y_spacing)) – Electrode-to-electrode spacing (um).

• x/y/z (double, optional) – Location (um) of the center of the grid in the implant’s own frame.

• rot (double, optional) – Rotation of the grid in degrees (positive angle: counter-clockwise).

• names ((name_rows, name_cols), optional) – Naming convention for rows and columns; see ElectrodeGrid.

• grid_type ({'rect', 'hex'}, optional) – Grid type (‘rect’: rectangular, ‘hex’: hexagonal).

• orientation ({'horizontal', 'vertical'}, optional) – Which way a hex grid staggers; see ElectrodeGrid.

• electrode_type (Electrode, optional) – A valid Electrode class.

• preprocess (bool or callable, optional) – Whether to preprocess a stimulus whenever one is prepared.

• safe_mode (bool, optional) – Whether to enforce charge balance.

• encoder (ImplantEncoder, optional) – How the device turns a picture into stimulation.

• raster (Raster, optional) – How the stimulator takes turns between electrodes.

• max_current (float, optional) – The total current (uA) the stimulator can source at any one instant.

• **electrode_params – Keyword arguments passed to the electrode_type constructor, such as radius for DiskElectrode; see ElectrodeGrid.

Examples

A 10x10 grid of point sources, 500um apart:

>>> from pulse2percept.implants import GridImplant
>>> from pulse2percept.units import um
>>> implant = GridImplant(shape=(10, 10), spacing=500 * um)
>>> implant.n_electrodes
100

A hex grid of 75um disk electrodes:

>>> from pulse2percept.implants import DiskElectrode, GridImplant
>>> from pulse2percept.units import um
>>> implant = GridImplant(shape=(20, 20), spacing=400 * um,
...                       grid_type='hex', electrode_type=DiskElectrode,
...                       radius=75 * um)
>>> implant['A1']
DiskElectrode(activated=True, name='A1', radius=75.0,
              x=-3700.0, y=-3290.89..., z=0...)

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.