pulse2percept.implants.cortex

Cortical implants such as Orion, ICVP, and Neuralink

orion	Orion
cortivis	Cortivis
icvp	ICVP
neuralink	EllipsoidElectrode, LinearEdgeThread, NeuralinkThread

See also

• Basic Concepts > Visual Prostheses

class pulse2percept.implants.cortex.Orion(x=15000, y=0, z=0, rot=0, stim=None, preprocess=False, safe_mode=False)

Create a Orion array

This function creates a Orion array and places it on the visual cortex such that the center of the base of the array is at 3D location (x,y,z) given in microns, and the array is rotated by angle rot, given in degrees.

Orion contains 60 electrodes in a hex shaped grid inspired by Argus II.

Note

By default the implant is in right hemisphere, use negative x-values to shift it to left hemisphere

Parameters:

• x/y/z (double) – 3D location (um) of the center of the electrode array. z can either be a list with 35 entries or a scalar that is applied to all electrodes. May be given as unitful quantities (e.g. Orion(x=15 * mm)); see pulse2percept.units.

• rot (float) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.

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

• preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).

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

Examples

Create an Orion array, by default centered 15mm to the right of fovea in V1:

>>> from pulse2percept.implants.cortex import Orion
>>> Orion() 
Orion(earray=ElectrodeGrid, preprocess=False,
      safe_mode=False, shape=(10, 7), stim=None)

Get access to electrode ‘96’:

>>> orion = Orion()
>>> orion['96'] 
DiskElectrode(activated=True, name='96', r=1000.0,
              x=3450.0, y=-9640.928378532848, z=0.0)

property earray

Electrode array

property stim

Stimulus

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

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

Note

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

Examples

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

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

check_stim(stim)

Quality-check the stimulus

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

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. 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. An implant that asks for neither does not run either check, which is why a dimensionless stimulus may still be assigned to one – preprocess has already had its chance to turn it into current, and if it did not, no safety claim is being made about it either.

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

Parameters:

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

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 prosthesis system object, e.g. implant['A1'] or implant[0].

property eye

Implanted eye

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

Examples

Implant Argus II in a left eye:

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

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 earray.n_electrodes.

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

Plot

Parameters:

• annotate (bool, optional) – Whether to scale the axes view to the data

• autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant

• ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.

• stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

preprocess_stim(stim)

Preprocess the stimulus

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

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

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

Parameters:

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

Returns:

stim_out

Return type:

Stimulus object

property raster

Raster pattern

Most implants do not set this in their constructor, so the slot backing it may never have been written to; an unset raster means all electrodes may fire at once.

class pulse2percept.implants.cortex.Cortivis(x=20000, y=-5000, z=0, rot=0, stim=None, preprocess=False, safe_mode=False)

Create a Cortivis array

This function creates a Cortivis array and places it on the visual cortex such that the center of the base of the array is at 3D location (x,y,z) given in microns, and the array is rotated by angle rot, given in degrees.

Cortivis is a Utah electrode array containing 96 electrodes in a 10x10 array with 400 um spacing, and electrode diameter of 80 um at the base [Fernandez2017].

Note

By default the implant is in right hemisphere, use negative x-values to shift it to left hemisphere

Parameters:

• x/y/z (double) – 3D location (um) of the center of the electrode array. z can either be a list with 35 entries or a scalar that is applied to all electrodes. May be given as unitful quantities (e.g. Cortivis(x=20 * mm)); see pulse2percept.units.

• rot (float) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.

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

• preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).

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

Examples

Create an Cortivis array, by default centered 20mm to the right of fovea in V1:

>>> from pulse2percept.implants.cortex import Cortivis
>>> Cortivis() 
Cortivis(earray=ElectrodeGrid, preprocess=False,
     safe_mode=False, shape=(10, 10), stim=None)

Get access to electrode ‘11’:

>>> cortivis = Cortivis()
>>> cortivis['11'] 
DiskElectrode(activated=True, name='11', r=40.0, x=21400.0,
              y=-6000.0, z=-1500.0)

property earray

Electrode array

property stim

Stimulus

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

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

Note

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

Examples

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

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

check_stim(stim)

Quality-check the stimulus

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

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. 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. An implant that asks for neither does not run either check, which is why a dimensionless stimulus may still be assigned to one – preprocess has already had its chance to turn it into current, and if it did not, no safety claim is being made about it either.

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

Parameters:

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

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 prosthesis system object, e.g. implant['A1'] or implant[0].

property eye

Implanted eye

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

Examples

Implant Argus II in a left eye:

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

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 earray.n_electrodes.

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

Plot

Parameters:

• annotate (bool, optional) – Whether to scale the axes view to the data

• autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant

• ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.

• stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

preprocess_stim(stim)

Preprocess the stimulus

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

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

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

Parameters:

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

Returns:

stim_out

Return type:

Stimulus object

property raster

Raster pattern

Most implants do not set this in their constructor, so the slot backing it may never have been written to; an unset raster means all electrodes may fire at once.

class pulse2percept.implants.cortex.ICVP(x=15000, y=0, z=0, rot=0, stim=None, preprocess=False, safe_mode=False)

Create an ICVP array

This function creates a ICVP array and places it on the visual cortex such that the center of the base of the array is at 3D location (x,y,z) given in microns, and the array is rotated by angle rot, given in degrees.

ICVP (Intracortical Visual Prosthesis Project) is an electrode array containing 16 Parylene-insulated (and 2 uninsulated reference and counter) iridium shaft electrodes in a 4 column array with 400 um spacing [Troyk2003]. The electrodes have a diameter of 15 um at the laser cut. They are inserted either 650 um or 850 um into the cortex.

Note

By default the implant is in right hemisphere, use negative x-values to shift it to left hemisphere

Parameters:

• x/y/z (double) – 3D location (um) of the center of the electrode array. z can either be a list with 35 entries or a scalar that is applied to all electrodes. May be given as unitful quantities (e.g. ICVP(x=15 * mm)); see pulse2percept.units.

• rot (float) – Rotation angle of the array (deg). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.

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

• preprocess (bool or callable, optional) – Either True/False to indicate whether to execute the implant’s default preprocessing method whenever a new stimulus is assigned, or a custom function (callable).

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

Examples

Create an ICVP array, by default centered 15mm to the right of fovea in V1:

>>> from pulse2percept.implants.cortex import Orion
>>> ICVP() 
ICVP(earray=ElectrodeGrid, preprocess=False,
     safe_mode=False, shape=(5, 4), stim=None)

Get access to electrode ‘11’:

>>> icvp = ICVP()
>>> icvp['11'] 
DiskElectrode(activated=True, name='11', r=50.0,
              x=15173.205080756888, y=100.0, z=-650.0)

property earray

Electrode array

property stim

Stimulus

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

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

Note

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

Examples

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

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

check_stim(stim)

Quality-check the stimulus

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

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. 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. An implant that asks for neither does not run either check, which is why a dimensionless stimulus may still be assigned to one – preprocess has already had its chance to turn it into current, and if it did not, no safety claim is being made about it either.

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

Parameters:

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

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 prosthesis system object, e.g. implant['A1'] or implant[0].

property eye

Implanted eye

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

Examples

Implant Argus II in a left eye:

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

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 earray.n_electrodes.

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

Plot

Parameters:

• annotate (bool, optional) – Whether to scale the axes view to the data

• autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant

• ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.

• stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

preprocess_stim(stim)

Preprocess the stimulus

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

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

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

Parameters:

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

Returns:

stim_out

Return type:

Stimulus object

property raster

Raster pattern

Most implants do not set this in their constructor, so the slot backing it may never have been written to; an unset raster means all electrodes may fire at once.

class pulse2percept.implants.cortex.EllipsoidElectrode(x=0, y=0, z=0, rx=7, ry=7, rz=12, orient=array([0, 0, 1]), orient_mode='direction', name=None, activated=True)

plot3D(ax=None, **kwargs)

Plot the electrode in 3D space

Parameters:

ax (matplotlib.axes.Axes) – Axes to plot on. If None, a new figure and axes will be created.

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

class pulse2percept.implants.cortex.NeuralinkThread(earray, stim=None, eye='RE', preprocess=False, safe_mode=False, raster=None, max_current=None)

Base class for Neuralink threads

check_stim(stim)

Quality-check the stimulus

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

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. 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. An implant that asks for neither does not run either check, which is why a dimensionless stimulus may still be assigned to one – preprocess has already had its chance to turn it into current, and if it did not, no safety claim is being made about it either.

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

Parameters:

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

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 earray

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 prosthesis system object, e.g. implant['A1'] or implant[0].

property eye

Implanted eye

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

Examples

Implant Argus II in a left eye:

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

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 earray.n_electrodes.

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

Plot

Parameters:

• annotate (bool, optional) – Whether to scale the axes view to the data

• autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant

• ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.

• stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

preprocess_stim(stim)

Preprocess the stimulus

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

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

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

Parameters:

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

Returns:

stim_out

Return type:

Stimulus object

property raster

Raster pattern

Most implants do not set this in their constructor, so the slot backing it may never have been written to; an unset raster means all electrodes may fire at once.

property stim

Stimulus

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

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

Note

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

Examples

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

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

class pulse2percept.implants.cortex.LinearEdgeThread(x=0, y=0, z=0, orient=array([0, 0, 1]), orient_mode='direction', r=5, n_elecs=32, spacing=50, insertion_depth=0, electrode=<class 'pulse2percept.implants.cortex.neuralink.EllipsoidElectrode'>, stim=None, preprocess=False, safe_mode=False)

property earray

Electrode array

property stim

Stimulus

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

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

Note

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

Examples

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

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

Stimulate Electrode B7 in Argus II with 13 uA:

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

plot3D(ax=None, **kwargs)

Plot the thread in 3D space

Parameters:

ax (matplotlib.axes.Axes) – Axes to plot on. If None, a new figure and axes will be created.

check_stim(stim)

Quality-check the stimulus

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

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. 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. An implant that asks for neither does not run either check, which is why a dimensionless stimulus may still be assigned to one – preprocess has already had its chance to turn it into current, and if it did not, no safety claim is being made about it either.

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

Parameters:

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

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 prosthesis system object, e.g. implant['A1'] or implant[0].

property eye

Implanted eye

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

Examples

Implant Argus II in a left eye:

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

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 earray.n_electrodes.

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

Plot

Parameters:

• annotate (bool, optional) – Whether to scale the axes view to the data

• autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant

• ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.

• stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

preprocess_stim(stim)

Preprocess the stimulus

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

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

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

Parameters:

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

Returns:

stim_out

Return type:

Stimulus object

property raster

Raster pattern

Most implants do not set this in their constructor, so the slot backing it may never have been written to; an unset raster means all electrodes may fire at once.

class pulse2percept.implants.cortex.Neuralink(threads, stim=None, preprocess=False, safe_mode=False)

classmethod from_neuropythy(vfmap, locs=None, xrange=None, yrange=None, step=None, rand_insertion_angle=None, region='v1', Thread=<class 'pulse2percept.implants.cortex.neuralink.LinearEdgeThread'>)

Create a Neuralink implant [Musk2019] from a neuropythy visual field map.

The implant will be created by creating a NeuralinkThread for each visual field location specified either by locs or by xrange, yrange, and step. Each thread will be inserted perpendicular to the cortical surface at the corresponding location in cortex, with up to rand_insertion_angle degrees of azimuthal rotation.

Parameters:

• vfmap (p2p.topography.NeuropythyMap) – Visual field map to create implant from.

• locs (np.ndarray with shape (n, 2), optional) – Array of visual field locations (dva) to create threads at. Not needed if using xrange, yrange, and step.

• xrange (tuple of floats, optional) – Range of x and y coordinates (dva) to create threads at.

• yrange (tuple of floats, optional) – Range of x and y coordinates (dva) to create threads at.

• step (float or (x_step, y_step), optional) –

  Spacing (dva) between threads.

  Changed in version 0.10.0: Renamed from xystep, which suggested that one step size applies to both axes. The old name still works as a keyword argument, but is deprecated and will be removed in v0.11.0.

• rand_insertion_angle (float, optional) – If not none, insert threads at a random offset from perpendicular, with a maximum azimuthal rotation of rand_insertion_angle degrees. A plain rotation in degrees, not a unitful quantity: dva measures visual angle, which is a different thing.

• region (str, optional) – Region of cortex to create implant in.

• Thread (NeuralinkThread, optional) – Thread class to use for the implant. Must accept x, y, z, and orient parameters.

Returns:

Neuralink – Neuralink ensemble implant created from the visual field map.

Return type:

p2p.implants.Neuralink

Notes

• Thread locations are visual field coordinates, so they may be given as plain numbers of degrees or as unitful quantities (e.g. xrange=(-3 * dva, 3 * dva)). The thread geometry itself is in microns; see LinearEdgeThread. See pulse2percept.units.

classmethod from_cortical_map(implant_type, vfmap, locs=None, xrange=None, yrange=None, step=None, region='v1')

Override of parent class from cortical map method. Uses from_neuropythy instead of from_cortical_map if the provided vfmap is a NeuropythyMap.

Parameters:

• implant_type (p2p.implants.ProsthesisSystem) – Type of implant to create. Currently only NeuralinkThread is supported.

• vfmap (p2p.topography.CorticalMap) – Cortical map to create implant from.

• locs (np.ndarray with shape (n, 2), optional) – Array of visual field locations to create threads at. Not needed if using xrange, yrange, and step.

• xrange (tuple of floats, optional) – Range of x and y coordinates to create threads at.

• yrange (tuple of floats, optional) – Range of x and y coordinates to create threads at.

• step (float or (x_step, y_step), optional) –

  Spacing between threads.

  Changed in version 0.10.0: Renamed from xystep, which suggested that one step size applies to both axes. The old name still works as a keyword argument, but is deprecated and will be removed in v0.11.0.

• region (str, optional) – Region of cortex to create implant in.

Returns:

Neuralink – Neuralink ensemble implant created from the visual field map.

Return type:

p2p.implants.Neuralink

plot3D(ax=None, **kwargs)

Plot the implant in 3D space

Parameters:

ax (matplotlib.axes.Axes) – Axes to plot on. If None, a new figure and axes will be created.

check_stim(stim)

Quality-check the stimulus

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

If safe_mode is set to True, this function will only allow stimuli that are charge-balanced. 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. An implant that asks for neither does not run either check, which is why a dimensionless stimulus may still be assigned to one – preprocess has already had its chance to turn it into current, and if it did not, no safety claim is being made about it either.

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

Parameters:

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

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 earray

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 prosthesis system object, e.g. implant['A1'] or implant[0].

property eye

Implanted eye

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

Examples

Implant Argus II in a left eye:

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

classmethod from_coords(implant_type, locs=None, xrange=None, yrange=None, step=None)

Create an ensemble implant using physical (cortical or retinal) coordinates.

Parameters:

• implant_type (type) – The type of implant to create for the ensemble.

• locs (np.ndarray with shape (n, 2), optional) – Array of physical locations (um) to create implants at. Not needed if using xrange, yrange, and step.

• xrange (tuple of floats, optional) – Range of x and y coordinates (um) to create implants at. Required (together with step) if locs is not given.

• yrange (tuple of floats, optional) – Range of x and y coordinates (um) to create implants at. Required (together with step) if locs is not given.

• step (float or (x_step, y_step), optional) –

  Spacing (um) between implant centers.

  Changed in version 0.10.0: Renamed from xystep, which suggested that one step size applies to both axes. The old name still works as a keyword argument, but is deprecated and will be removed in v0.11.0.

Raises:

ValueError – If neither locs nor all three of xrange, yrange and step are given.

Notes

• Lengths may be given as plain numbers of microns or as unitful quantities (e.g. xrange=(-1 * mm, 1 * mm)). See pulse2percept.units.

Changed in version 0.10.0: The grid arguments no longer have defaults. They used to fall back on (-3, 3) and 1, which are the degrees of visual angle from_cortical_map() works in; here they are microns, so the default laid every implant out inside a 6 um square.

property implants

Dict of implants

property max_current

Total instantaneous current (uA) the stimulator can source

merge_stimuli()

Constructs the combined stimulus for all implants in self._implants

property n_electrodes

Number of electrodes in the array

This is equivalent to calling earray.n_electrodes.

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

Plot

Parameters:

• annotate (bool, optional) – Whether to scale the axes view to the data

• autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant

• ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.

• stim_cmap (bool, str, or matplotlib colormap, optional) – If not false, the fill color of the plotted electrodes will vary based on maximum stimulus amplitude on each electrode. The chosen colormap will be used if provided

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

preprocess_stim(stim)

Preprocess the stimulus

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

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

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

Parameters:

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

Returns:

stim_out

Return type:

Stimulus object

property raster

Raster pattern

Most implants do not set this in their constructor, so the slot backing it may never have been written to; an unset raster means all electrodes may fire at once.

property stim

Stimulus

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

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

Note

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

Examples

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

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

Stimulate Electrode B7 in Argus II with 13 uA:

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