pulse2percept.implants.electrode_arrays

ElectrodeArray, ElectrodeGrid

Classes

`ElectrodeArray`(electrodes)	Electrode array
`ElectrodeGrid`(shape, spacing[, x, y, z, ...])	2D grid of electrodes

class pulse2percept.implants.electrode_arrays.ElectrodeArray(electrodes)[source]

Electrode array

A collection of Electrode objects.

Parameters:

electrodes (array-like) –

Either a single Electrode object 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.

Note

If you pass multiple electrodes in a dictionary, the keys of the dictionary will automatically be sorted. Thus the original order of electrodes might not be preserved.

Examples

Electrode array made from a single DiskElectrode:

>>> from pulse2percept.implants import ElectrodeArray, DiskElectrode
>>> electrode_array = ElectrodeArray(DiskElectrode(0, 0, 0, 100))
>>> electrode_array.electrodes
OrderedDict([(0,
              DiskElectrode(activated=True, name=None, radius=100...,
              x=0..., y=0..., z=0...))])

Electrode array made from a single DiskElectrode with name ‘A1’:

>>> from pulse2percept.implants import ElectrodeArray, DiskElectrode
>>> electrode_array = ElectrodeArray({'A1': DiskElectrode(0, 0, 0, 100)})
>>> electrode_array.electrodes
OrderedDict([('A1',
              DiskElectrode(activated=True, name=None, radius=100...,
              x=0..., y=0..., z=0...))])

coordinate_unit = um[source]: The unit electrode coordinates are stored in, i.e. what the plain numbers returned by coordinates() mean by default.

coordinates(unit=None, electrodes=None)[source]

Positions of the electrodes in the array

The one place to ask an implant where its electrodes are. Code that needs the coordinates in a particular unit says so here, instead of reading electrode.x and knowing that electrodes happen to store microns.

Added in version 0.10.0.

Parameters:

unit (Unit, optional) – Length unit to express the coordinates in. If None, they are returned as they are stored (microns).
electrodes (optional) – Which electrodes to return, either by name, index into the flattened array, or a (row, col) pair on an ElectrodeGrid. Everything else is treated as a collection.

Returns:

coords – One [x, y, z] row per electrode

Return type:

(n_electrodes, 3) np.ndarray

Examples

>>> from pulse2percept.implants.retina import ArgusII
>>> from pulse2percept.units import mm
>>> ArgusII().electrode_array.coordinates(mm)[0]
array([-2.5875, -1.4375,  0.    ])
>>> ArgusII().electrode_array.coordinates(electrodes=['F10', 'A1'])
array([[ 2587.5,  1437.5,     0. ],
       [-2587.5, -1437.5,     0. ]])

add_electrode(name, electrode)[source]

Add an electrode to the array

Parameters:

name (int|str|...) – Electrode name or index
electrode (implants.Electrode) – An Electrode object, such as a PointSource or a DiskElectrode.

remove_electrode(name)[source]

Remove an electrode from the array

Parameter

name: int|str|…: Electrode name or index

plot(annotate=False, autoscale=True, ax=None, color_stim=None, cmap='OrRd')[source]

Plot the electrode array in its own coordinate frame

Parameters:

annotate (bool, optional) – Flag whether to label electrodes in the implant.
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.
color_stim (pulse2percept.stimuli.Stimulus, or None) – If provided, colors the electrode_array based on the stimulus amplitudes. A multi-patch electrode (e.g., PhotovoltaicPixel) colors only its last patch; earlier patches are structural.
cmap (str) – Matplotlib colormap to use for stimulus coloring.

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

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 electrode_array.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the electrode array object, e.g. electrode_array['A1'] or electrode_array[0].

property electrode_names: Return a list of all electrode names in the array

property electrode_objects: Return a list of all electrode objects in the array

class pulse2percept.implants.electrode_arrays.ElectrodeGrid(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'>, **electrode_params)[source]

2D grid of electrodes

Parameters:

shape ((rows, cols)) – A tuple containing the number of rows x columns in the grid
spacing (double or (x_spacing, y_spacing)) – Electrode-to-electrode spacing in microns. Must be either a tuple specifying the spacing in x and y directions or a float (assuming the same spacing in x and y). If a tuple is specified for a horizontal hex grid, x_spacing will define the electrode-to-electrode distance, and y_spacing will define the vertical distance between adjacent hexagon centers. In a vertical hex grid, the order is reversed.
grid_type ({'rect', 'hex'}, optional) –
Grid type (‘rect’: rectangular, ‘hex’: hexagonal).

Changed in version 0.11.0: Renamed from type.
orientation ({'horizontal', 'vertical'}, optional) – Hex-grid orientation. 'horizontal' staggers alternate rows; 'vertical' staggers alternate columns. Hexagonal electrode bodies follow the grid orientation.
x/y/z (double) – Location (um) of the center of the grid within the array it belongs to. z is height above the array plane.
rot (double, optional) – Rotation of the grid in degrees (positive angle: counter-clockwise). A plain angle, not a unitful one: dva means visual angle, which is a different thing.
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: A-Z, AA-AZ, BA-BZ, CA-CZ, etc. ‘-A’ will reverse the order. If ‘1’, rows or columns will be labeled numerically. ‘-1’ will reverse. Letters will always precede numbers in electrode names. For example (‘1’, ‘A’) will number rows numerically and columns alphabetically; first row: ‘A1’, ‘B1’, ‘C1’, NOT ‘1A’, ‘1B’, ‘1C’.

The default, ('A', '1'), is the same convention that names the pixels of an ImageStimulus, and is generated by the same implementation. The other combinations exist to reproduce the naming of specific published implants and are not otherwise recommended.

Alternatively, pass a list or NumPy array with one name per electrode to name them all explicitly. On a grid with exactly two electrodes the two readings collide, and only something that could be a scheme is read as one: names=('A', '1') gives ‘A1’, ‘A2’, whereas names=('C1', '4') names the two electrodes ‘C1’ and ‘4’. Pass a list (names=['A', '1']) to name two electrodes ‘A’ and ‘1’.

Changed in version 0.10.0: On a grid with exactly two electrodes, ('A', '1') now yields ‘A1’, ‘A2’ (was: ‘A’, ‘1’), consistent with every other shape.
electrode_type (Electrode, optional) –
A valid Electrode class. By default, PointSource is used.

Changed in version 0.11.0: Renamed from etype.
**electrode_params – Keyword arguments passed to the electrode_type constructor, such as radius for DiskElectrode. They are forwarded unchanged, except that radius may be given per electrode (see below).

Notes

z and radius may be given per electrode, as a list or array with one entry per grid position. Every other electrode parameter is one value shared by all electrodes.
spacing, x, y, z and radius may be given as plain numbers of microns or as unitful quantities, and may be mixed freely: spacing=(0.5 * mm, 600 * um) and z=[0 * um, 0.1 * mm, ...] both work. Any other electrode keyword is normalized by the electrode class it is passed to. See pulse2percept.units.

Examples

A hexagonal electrode grid with 3 rows and 4 columns, made of disk 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 C1 C2 C3 C4

>>> from pulse2percept.implants import ElectrodeGrid, DiskElectrode
>>> ElectrodeGrid((3, 4), 20, x=10, y=20, z=500, names=('A', '1'),
...               radius=10, grid_type='hex',
...               electrode_type=DiskElectrode)
...
ElectrodeGrid(grid_type='hex', rot=0, shape=(3, 4), spacing=20)

A rectangular electrode grid with 2 rows and 4 columns, made of disk 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, DiskElectrode
>>> ElectrodeGrid((2, 4), 20, x=10, y=20, z=500, names=('A', '1'),
...               radius=10, grid_type='rect',
...               electrode_type=DiskElectrode)
...
ElectrodeGrid(grid_type='rect', rot=0, shape=(2, 4), spacing=20)

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), 20, names=('A', '1'))
>>> grid['C3']
PointSource(activated=True, name='C3', x=20..., y=20...,
            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, DiskElectrode
>>> grid = ElectrodeGrid((3, 3), 20, electrode_type=DiskElectrode,
...                      radius=10)
>>> grid[['A1', 1, (0, 2)]]
[DiskElectrode(activated=True, name='A1', radius=10..., x=-20.0,
               y=-20.0, z=0...),
 DiskElectrode(activated=True, name='A2', radius=10..., x=0.0,
               y=-20.0, z=0...),
 DiskElectrode(activated=True, name='A3', radius=10..., x=20.0,
               y=-20.0, z=0...)]

add_electrode(name, electrode)[source]

Add an electrode to the array

Parameters:

name (int|str|...) – Electrode name or index
electrode (implants.Electrode) – An Electrode object, such as a PointSource or a DiskElectrode.

coordinate_unit = um[source]: The unit electrode coordinates are stored in, i.e. what the plain numbers returned by coordinates() mean by default.

coordinates(unit=None, electrodes=None)[source]

Positions of the electrodes in the array

The one place to ask an implant where its electrodes are. Code that needs the coordinates in a particular unit says so here, instead of reading electrode.x and knowing that electrodes happen to store microns.

Added in version 0.10.0.

Parameters:

unit (Unit, optional) – Length unit to express the coordinates in. If None, they are returned as they are stored (microns).
electrodes (optional) – Which electrodes to return, either by name, index into the flattened array, or a (row, col) pair on an ElectrodeGrid. Everything else is treated as a collection.

Returns:

coords – One [x, y, z] row per electrode

Return type:

(n_electrodes, 3) np.ndarray

Examples

>>> from pulse2percept.implants.retina import ArgusII
>>> from pulse2percept.units import mm
>>> ArgusII().electrode_array.coordinates(mm)[0]
array([-2.5875, -1.4375,  0.    ])
>>> ArgusII().electrode_array.coordinates(electrodes=['F10', 'A1'])
array([[ 2587.5,  1437.5,     0. ],
       [-2587.5, -1437.5,     0. ]])

property electrode_names: Return a list of all electrode names in the 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 electrode_array.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the electrode array object, e.g. electrode_array['A1'] or electrode_array[0].

plot(annotate=False, autoscale=True, ax=None, color_stim=None, cmap='OrRd')[source]

Plot the electrode array in its own coordinate frame

Parameters:

annotate (bool, optional) – Flag whether to label electrodes in the implant.
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.
color_stim (pulse2percept.stimuli.Stimulus, or None) – If provided, colors the electrode_array based on the stimulus amplitudes. A multi-patch electrode (e.g., PhotovoltaicPixel) colors only its last patch; earlier patches are structural.
cmap (str) – Matplotlib colormap to use for stimulus coloring.

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

remove_electrode(name)[source]

Remove an electrode from the array

Parameter

name: int|str|…: Electrode name or index