pulse2percept.implants¶
This module provides a number of visual prostheses.
base |
implants |
argus |
|
alpha |
Alpha IMS |
-
class
pulse2percept.implants.AlphaAMS(x=0, y=0, z=0, rot=0, eye='RE', stim=None)[source]¶ Alpha AMS
This function creates an AlphaAMS array and places it below the retina such that the center of the array is located at (x,y,z), given in microns, and the array is rotated by rotation angle
rot, given in radians.The array is oriented upright in the visual field, such that an array with center (0,0) has the top three rows lie in the lower retina (upper visual field), as shown below:
An electrode can be addressed by name, row/column index, or integer index (into the flattened array).
Note
Column order is reversed in a left-eye implant.
Parameters: - x (float) – x coordinate of the array center (um)
- y (float) – y coordinate of the array center (um)
- z (float || array_like) – Distance of the array to the retinal surface (um). Either a list with 60 entries or a scalar.
- rot (float) – Rotation angle of the array (rad). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
- eye ({'LE', 'RE'}, optional, default: 'RE') – Eye in which array is implanted.
Examples
Create an AlphaAMS array centered on the fovea, at 100um distance from the retina:
>>> from pulse2percept.implants import AlphaAMS >>> AlphaAMS(x=0, y=0, z=100, rot=0) # doctest: +NORMALIZE_WHITESPACE AlphaAMS(earray=pulse2percept.implants.base.ElectrodeGrid, eye='RE', shape=(40, 40), stim=None)
Get access to the third electrode in the top row (by name or by row/column index):
>>> alpha_ims = AlphaAMS(x=0, y=0, z=100, rot=0) >>> alpha_ims['A3'] DiskElectrode(r=15.0, x=-1225.0, y=-1365.0, z=100.0) >>> alpha_ims[0, 2] DiskElectrode(r=15.0, x=-1225.0, y=-1365.0, z=100.0)
-
check_stim(stim)[source]¶ Quality-check the stimulus
This method is executed every time a new value is assigned to
stim.No checks are performed by default, but the user can define their own checks in implants that inherit from
ProsthesisSystem.Parameters: stim ( Stimulussource type) – A valid source type for theStimulusobject (e.g., scalar, NumPy array, pulse train).
-
earray¶ Electrode array
-
eye¶ Implanted eye
A
ProsthesisSystemcan be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such asAxonMapModelwill 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')
-
items()[source]¶ Return all electrode names and objects in the electrode array
Internally, electrodes are stored in a dictionary in
earray.electrodes. For convenience, electrodes can also be accessed viaitems.Examples
Save the x-coordinates of all electrodes of Argus I in a dictionary:
>>> from pulse2percept.implants import ArgusI >>> xcoords = {} >>> for name, electrode in ArgusI().items(): ... xcoords[name] = electrode.x
-
n_electrodes¶ Number of electrodes in the array
This is equivalent to calling
earray.n_electrodes.
-
stim¶ Stimulus
A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see
Stimulusfor a complete list).A stimulus can be assigned either in the
ProsthesisSystemconstructor or later by assigning a value tostim.Note
Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in
earray.Examples
Send a biphasic pulse 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('cathodicfirst', 1e-4, 1e-6)
Stimulate Electrode B7 in Argus II with 13 uA:
>>> from pulse2percept.implants import ArgusII >>> implant = ArgusII(stim={'B7': 13})
-
class
pulse2percept.implants.AlphaIMS(x=0, y=0, z=0, rot=0, eye='RE', stim=None)[source]¶ Alpha IMS
This function creates an AlphaIMS array and places it on the retina such that the center of the array is located at (x,y,z), given in microns, and the array is rotated by rotation angle
rot, given in radians.The array is oriented upright in the visual field, such that an array with center (0,0) has the top three rows lie in the lower retina (upper visual field).
An electrode can be addressed by name, row/column index, or integer index (into the flattened array).
Note
Column order is reversed in a left-eye implant.
Parameters: - x (float) – x coordinate of the array center (um)
- y (float) – y coordinate of the array center (um)
- z (float or array_like) – Distance of the array to the retinal surface (um). Either a list with 60 entries or a scalar.
- rot (float) – Rotation angle of the array (rad). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
- eye ('LE' or 'RE', optional, default: 'RE') – Eye in which array is implanted.
Examples
Create an AlphaIMS array centered on the fovea, at 100um distance from the retina:
>>> from pulse2percept.implants import AlphaIMS >>> AlphaIMS(x=0, y=0, z=100, rot=0) # doctest: +NORMALIZE_WHITESPACE AlphaIMS(earray=pulse2percept.implants.base.ElectrodeGrid, eye='RE', shape=(37, 37), stim=None)
Get access to the third electrode in the top row (by name or by row/column index):
>>> alpha_ims = AlphaIMS(x=0, y=0, z=100, rot=0) >>> alpha_ims['A3'] DiskElectrode(r=50.0, x=-1152.0, y=-1296.0, z=100.0) >>> alpha_ims[0, 2] DiskElectrode(r=50.0, x=-1152.0, y=-1296.0, z=100.0)
-
check_stim(stim)[source]¶ Quality-check the stimulus
This method is executed every time a new value is assigned to
stim.No checks are performed by default, but the user can define their own checks in implants that inherit from
ProsthesisSystem.Parameters: stim ( Stimulussource type) – A valid source type for theStimulusobject (e.g., scalar, NumPy array, pulse train).
-
earray¶ Electrode array
-
eye¶ Implanted eye
A
ProsthesisSystemcan be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such asAxonMapModelwill 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')
-
items()[source]¶ Return all electrode names and objects in the electrode array
Internally, electrodes are stored in a dictionary in
earray.electrodes. For convenience, electrodes can also be accessed viaitems.Examples
Save the x-coordinates of all electrodes of Argus I in a dictionary:
>>> from pulse2percept.implants import ArgusI >>> xcoords = {} >>> for name, electrode in ArgusI().items(): ... xcoords[name] = electrode.x
-
n_electrodes¶ Number of electrodes in the array
This is equivalent to calling
earray.n_electrodes.
-
stim¶ Stimulus
A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see
Stimulusfor a complete list).A stimulus can be assigned either in the
ProsthesisSystemconstructor or later by assigning a value tostim.Note
Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in
earray.Examples
Send a biphasic pulse 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('cathodicfirst', 1e-4, 1e-6)
Stimulate Electrode B7 in Argus II with 13 uA:
>>> from pulse2percept.implants import ArgusII >>> implant = ArgusII(stim={'B7': 13})
-
class
pulse2percept.implants.ArgusI(x=0, y=0, z=0, rot=0, eye='RE', stim=None, use_legacy_names=False)[source]¶ Create an ArgusI array on the retina
This function creates an ArgusI array and places it on the retina such that the center of the array is located at 3D location (x,y,z), given in microns, and the array is rotated by rotation angle
rot, given in radians.The array is oriented in the visual field as shown in Fig. 1 of Horsager et al. (2009); that is, if placed in (0,0), the top two rows will lie in the lower retina (upper visual field):
-y A1 B1 C1 D1 260 520 260 520 ^ A2 B2 C2 D2 where electrode 520 260 520 260 | A3 B3 C3 D3 diameters are: 260 520 260 520 -->x A4 B4 C4 D4 520 260 520 260
Electrode order is: A1, B1, C1, D1, A2, B2, …, D4.
If
use_legacy_namesis True, electrode order is: L6, L2, M8, M4, …An electrode can be addressed by name, row/column index, or integer index (into the flattened array).
Note
Column order is reversed in a left-eye implant.
Parameters: - x (float, optional, default: 0) – x coordinate of the array center (um)
- y (float, optional, default: 0) – y coordinate of the array center (um)
- z (float || array_like, optional, default: 0) – Distance of the array to the retinal surface (um). Either a list with 16 entries or a scalar.
- rot (float, optional, default: 0) – Rotation angle of the array (rad). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
- eye ({'LE', 'RE'}, optional, default: 'RE') – Eye in which array is implanted.
Examples
Create an ArgusI array centered on the fovea, at 100um distance from the retina:
>>> from pulse2percept.implants import ArgusI >>> ArgusI(x=0, y=0, z=100, rot=0) # doctest: +NORMALIZE_WHITESPACE ArgusI(earray=pulse2percept.implants.base.ElectrodeGrid, eye='RE', shape=(4, 4), stim=None)
Get access to electrode ‘B1’, either by name or by row/column index:
>>> argus = ArgusI(x=0, y=0, z=100, rot=0) >>> argus['B1'] DiskElectrode(r=260.0, x=-400.0, y=-1200.0, z=100.0) >>> argus[0, 1] DiskElectrode(r=260.0, x=-400.0, y=-1200.0, z=100.0)
-
check_stim(stim)[source]¶ Quality-check the stimulus
This method is executed every time a new value is assigned to
stim.No checks are performed by default, but the user can define their own checks in implants that inherit from
ProsthesisSystem.Parameters: stim ( Stimulussource type) – A valid source type for theStimulusobject (e.g., scalar, NumPy array, pulse train).
-
earray¶ Electrode array
-
eye¶ Implanted eye
A
ProsthesisSystemcan be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such asAxonMapModelwill 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')
-
items()[source]¶ Return all electrode names and objects in the electrode array
Internally, electrodes are stored in a dictionary in
earray.electrodes. For convenience, electrodes can also be accessed viaitems.Examples
Save the x-coordinates of all electrodes of Argus I in a dictionary:
>>> from pulse2percept.implants import ArgusI >>> xcoords = {} >>> for name, electrode in ArgusI().items(): ... xcoords[name] = electrode.x
-
n_electrodes¶ Number of electrodes in the array
This is equivalent to calling
earray.n_electrodes.
-
stim¶ Stimulus
A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see
Stimulusfor a complete list).A stimulus can be assigned either in the
ProsthesisSystemconstructor or later by assigning a value tostim.Note
Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in
earray.Examples
Send a biphasic pulse 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('cathodicfirst', 1e-4, 1e-6)
Stimulate Electrode B7 in Argus II with 13 uA:
>>> from pulse2percept.implants import ArgusII >>> implant = ArgusII(stim={'B7': 13})
-
class
pulse2percept.implants.ArgusII(x=0, y=0, z=0, rot=0, eye='RE', stim=None)[source]¶ Create an ArgusII array on the retina
This function creates an ArgusII array and places it on the retina such that the center of the array is located at (x,y,z), given in microns, and the array is rotated by rotation angle
rot, given in radians.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 -y B1 B2 B3 B4 B5 B6 B7 B8 B9 B10 ^ C1 C2 C3 C4 C5 C6 C7 C8 C9 C10 | D1 D2 D3 D4 D5 D6 D7 D8 D9 D10 -->x E1 E2 E3 E4 E5 E6 E7 E8 E9 E10 F1 F2 F3 F4 F5 F6 F7 F8 F9 F10Electrode order is: A1, A2, …, A10, B1, B2, …, F10.
An electrode can be addressed by name, row/column index, or integer index (into the flattened array).
Note
Column order is reversed in a left-eye implant.
Parameters: - x (float) – x coordinate of the array center (um)
- y (float) – y coordinate of the array center (um)
- z (float || array_like) – Distance of the array to the retinal surface (um). Either a list with 60 entries or a scalar.
- rot (float) – Rotation angle of the array (rad). Positive values denote counter-clock-wise (CCW) rotations in the retinal coordinate system.
- eye ({'LE', 'RE'}, optional, default: 'RE') – Eye in which array is implanted.
Examples
Create an ArgusII array centered on the fovea, at 100um distance from the retina:
>>> from pulse2percept.implants import ArgusII >>> ArgusII(x=0, y=0, z=100, rot=0) # doctest: +NORMALIZE_WHITESPACE ArgusII(earray=pulse2percept.implants.base.ElectrodeGrid, eye='RE', shape=(6, 10), stim=None)
Get access to electrode ‘E7’, either by name or by row/column index:
>>> argus = ArgusII(x=0, y=0, z=100, rot=0) >>> argus['E7'] DiskElectrode(r=100.0, x=787.5, y=787.5, z=100.0) >>> argus[4, 6] DiskElectrode(r=100.0, x=787.5, y=787.5, z=100.0)
-
check_stim(stim)[source]¶ Quality-check the stimulus
This method is executed every time a new value is assigned to
stim.No checks are performed by default, but the user can define their own checks in implants that inherit from
ProsthesisSystem.Parameters: stim ( Stimulussource type) – A valid source type for theStimulusobject (e.g., scalar, NumPy array, pulse train).
-
earray¶ Electrode array
-
eye¶ Implanted eye
A
ProsthesisSystemcan be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such asAxonMapModelwill 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')
-
items()[source]¶ Return all electrode names and objects in the electrode array
Internally, electrodes are stored in a dictionary in
earray.electrodes. For convenience, electrodes can also be accessed viaitems.Examples
Save the x-coordinates of all electrodes of Argus I in a dictionary:
>>> from pulse2percept.implants import ArgusI >>> xcoords = {} >>> for name, electrode in ArgusI().items(): ... xcoords[name] = electrode.x
-
n_electrodes¶ Number of electrodes in the array
This is equivalent to calling
earray.n_electrodes.
-
stim¶ Stimulus
A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see
Stimulusfor a complete list).A stimulus can be assigned either in the
ProsthesisSystemconstructor or later by assigning a value tostim.Note
Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in
earray.Examples
Send a biphasic pulse 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('cathodicfirst', 1e-4, 1e-6)
Stimulate Electrode B7 in Argus II with 13 uA:
>>> from pulse2percept.implants import ArgusII >>> implant = ArgusII(stim={'B7': 13})
-
class
pulse2percept.implants.DiskElectrode(x, y, z, r)[source]¶ Circular disk electrode
Parameters: - y, z (x,) – 3D location that is the center of the disk electrode
- r (double) – Disk radius in the x,y plane
-
class
pulse2percept.implants.ElectrodeArray(electrodes)[source]¶ Electrode array
A collection of
Electrodeobjects.Parameters: electrodes (array-like) – Either a single Electrodeobject or a dict, list, or NumPy array thereof. The keys of the dict will serve as electrode names. Otherwise electrodes will be indexed 0..N.Examples
Electrode array made from a single DiskElectrode:
>>> from pulse2percept.implants import ElectrodeArray, DiskElectrode >>> earray = ElectrodeArray(DiskElectrode(0, 0, 0, 100)) >>> earray.electrodes # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS OrderedDict([(0, DiskElectrode(r=100..., x=0..., y=0..., z=0...))])
Electrode array made from a single DiskElectrode with name ‘A1’:
>>> from pulse2percept.implants import ElectrodeArray, DiskElectrode >>> earray = ElectrodeArray({'A1': DiskElectrode(0, 0, 0, 100)}) >>> earray.electrodes # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS OrderedDict([('A1', DiskElectrode(r=100..., x=0..., y=0..., z=0...))])
-
add_electrode(name, electrode)[source]¶ Add an electrode to the dictionary
Parameters: - name (int|str|...) – Electrode name or index
- electrode (implants.Electrode) – An Electrode object, such as a PointSource or a DiskElectrode.
-
-
class
pulse2percept.implants.ElectrodeGrid(shape, x=0, y=0, z=0, rot=0, r=10, spacing=None, names=('A', '1'))[source]¶ Rectangular grid of electrodes
Parameters: - shape ((rows, cols)) – A tuple containing the number of rows x columns in the grid
- y, z (x,) – 3D coordinates of the center of the grid
- rot (double) – Rotation of the grid in radians (positive angle: counter-clockwise rotation on the retinal surface)
- r (double) – Electrode radius in microns
- spacing (double) – Electrode-to-electrode spacing in microns. If None, 2x radius is chosen.
- names ((name_rows, name_cols), each of which either 'A' or '1') – Naming convention for rows and columns, respectively. If ‘A’, rows or columns will be labeled alphabetically. If ‘1’, rows or columns will be labeled numerically. Columns and rows may only be strings and integers. For example (‘1’, ‘A’) will number rows numerically and columns alphabetically.
- :param .. note::: For now, all electrodes will be
DiskElectrodeobjects.
Examples
An electrode grid with 2 rows and 4 columns, made of electrodes with 10um radius spaced 20um apart, centered at (10, 20)um, and located 500um away from the retinal surface, with names like this:
A1 A2 A3 A4 B1 B2 B3 B4>>> from pulse2percept.implants import ElectrodeGrid >>> ElectrodeGrid((2, 4), x=10, y=20, z=500, names=('A', '1')) # doctest: +NORMALIZE_WHITESPACE ElectrodeGrid(name_cols='1', name_rows='A', r=10, rot=0, shape=(2, 4), spacing=20.0, x=10, y=20, z=500)
There are three ways to access (e.g.) the last electrode in the grid, either by name (
grid['C3']), by row/column index (grid[2, 2]), or by index into the flattened array (grid[8]):>>> from pulse2percept.implants import ElectrodeGrid >>> grid = ElectrodeGrid((3, 3), names=('A', '1')) >>> grid['C3'] # doctest: +ELLIPSIS DiskElectrode(r=10..., x=20.0, y=20.0, z=0...) >>> grid['C3'] == grid[8] == grid[2, 2] True
You can also access multiple electrodes at the same time by passing a list of indices/names (it’s ok to mix-and-match):
>>> from pulse2percept.implants import ElectrodeGrid >>> grid = ElectrodeGrid((3, 3), names=('A', '1')) >>> grid[['A1', 1, (0, 2)]] # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS [DiskElectrode(r=10..., x=-20.0, y=-20.0, z=0...), DiskElectrode(r=10..., x=0.0, y=-20.0, z=0...), DiskElectrode(r=10..., x=20.0, y=-20.0, z=0...)]
Todo
- Allow user-specified electrode types (see issue #122).
-
add_electrode(name, electrode)[source]¶ Add an electrode to the dictionary
Parameters: - name (int|str|...) – Electrode name or index
- electrode (implants.Electrode) – An Electrode object, such as a PointSource or a DiskElectrode.
-
class
pulse2percept.implants.ProsthesisSystem(earray, stim=None, eye='RE')[source]¶ Visual prosthesis system
A visual prosthesis combines an electrode array and (optionally) a stimulus. This is the base class for prosthesis systems such as
ArgusIIandAlphaIMS.Parameters: - earray (
ElectrodeArrayor) –ElectrodeThe electrode array used to deliver electrical stimuli to the retina. - stim (
Stimulussource type) – A valid source type for theStimulusobject (e.g., scalar, NumPy array, pulse train). - eye ('LE' or 'RE') – A string indicating whether the system is implanted in the left (‘LE’) or right eye (‘RE’)
Examples
A system in the left eye made from a single
DiskElectrodewith radius r=100um sitting at x=200um, y=-50um, z=10um:>>> from pulse2percept.implants import DiskElectrode, ProsthesisSystem >>> implant = ProsthesisSystem(DiskElectrode(200, -50, 10, 100), eye='LE')
Note
A stimulus can also be assigned later (see
stim).-
check_stim(stim)[source]¶ Quality-check the stimulus
This method is executed every time a new value is assigned to
stim.No checks are performed by default, but the user can define their own checks in implants that inherit from
ProsthesisSystem.Parameters: stim ( Stimulussource type) – A valid source type for theStimulusobject (e.g., scalar, NumPy array, pulse train).
-
earray¶ Electrode array
-
eye¶ Implanted eye
A
ProsthesisSystemcan be implanted either in a left eye (‘LE’) or right eye (‘RE’). Models such asAxonMapModelwill 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')
-
items()[source]¶ Return all electrode names and objects in the electrode array
Internally, electrodes are stored in a dictionary in
earray.electrodes. For convenience, electrodes can also be accessed viaitems.Examples
Save the x-coordinates of all electrodes of Argus I in a dictionary:
>>> from pulse2percept.implants import ArgusI >>> xcoords = {} >>> for name, electrode in ArgusI().items(): ... xcoords[name] = electrode.x
-
n_electrodes¶ Number of electrodes in the array
This is equivalent to calling
earray.n_electrodes.
-
stim¶ Stimulus
A stimulus can be created from many source types, such as scalars, NumPy arrays, and dictionaries (see
Stimulusfor a complete list).A stimulus can be assigned either in the
ProsthesisSystemconstructor or later by assigning a value tostim.Note
Unless when using dictionary notation, the number of stimuli must equal the number of electrodes in
earray.Examples
Send a biphasic pulse 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('cathodicfirst', 1e-4, 1e-6)
Stimulate Electrode B7 in Argus II with 13 uA:
>>> from pulse2percept.implants import ArgusII >>> implant = ArgusII(stim={'B7': 13})
- earray (