pulse2percept.implants.cortex.neuralink

EllipsoidElectrode, LinearEdgeThread, NeuralinkThread

Classes

`EllipsoidElectrode`([x, y, z, rx, ry, rz, ...])
`LinearEdgeThread`([x, y, z, orient, ...])
`Neuralink`(threads[, preprocess, safe_mode, ...])
`NeuralinkThread`(electrode_array[, ...])	Base class for Neuralink threads

class pulse2percept.implants.cortex.neuralink.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)[source]

plot3d(ax=None, **kwargs)[source]

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[source]: 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)[source]

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)[source]

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.neuralink.NeuralinkThread(electrode_array, preprocess=False, safe_mode=False, encoder=None, raster=None, max_current=None, thresholds=None, scene_input_frame=None)[source]

Base class for Neuralink threads

placement = 'intracortical': 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.

check_stim(stim)[source]

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.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)[source]

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)[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)[source]

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[source]: Unit used by prepared stimuli. Defaults to electrical current.

technology = None: Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

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

Added in version 0.10.0.

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

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

property electrode_array: Electrode array

plot3d(ax=None, **kwargs)[source]

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)[source]

Quality-check the stimulus

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

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

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

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

Parameters:

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

Raises:

DimensionMismatchError – If an electrical check was requested and stim is not measured in units of current.
.. versionchanged: – 0.10.0: The electrical checks verify that the stimulus really is electrical, instead of reading whatever numbers it holds as microamps.

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

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

property electrodes

Return all electrode names and objects in the electrode array

Internally, electrodes are stored in an ordered dictionary. You can iterate over different electrodes in the array as follows:

for name, electrode in implant.electrodes.items():
    print(name, electrode)

You can access an individual electrode by indexing directly into the implant, e.g. implant['A1'] or implant[0], and ask how many there are with len(implant).

property encoder

Stimulus encoder used for image or video input.

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

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

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

property max_current: Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

placement = 'intracortical': 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)[source]

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)[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)[source]

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[source]: Unit used by prepared stimuli. Defaults to electrical current.

technology = None: Stimulation technology, e.g. 'photovoltaic'. .. versionadded:: 0.11.0

property thresholds

Perceptual threshold current (uA) for each electrode.

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

Added in version 0.10.0.

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

class pulse2percept.implants.cortex.neuralink.Neuralink(threads, preprocess=False, safe_mode=False, hemisphere=None)[source]

placement = 'intracortical': 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.

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

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:

visual_field_map (p2p.topography.cortex.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.
rand_insertion_angle (float or Quantity, optional) – If not none, insert threads at a random offset from perpendicular, with a maximum azimuthal rotation of rand_insertion_angle degrees.
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_visual_field_map(implant_type, visual_field_map, locs=None, xrange=None, yrange=None, step=None, region=None)[source]

Override of the generic ensemble factory.

A NeuropythyMap is handed to from_neuropythy(), which inserts each thread along the cortical surface normal; any other 2D cortical map goes through the generic implementation.

Only a CorticalMap is accepted. The generic factory takes any 2D map, but the tissue coordinates a retinal map returns are also microns, so placing threads by one would produce a valid-looking implant sitting nowhere in cortex.

Added in version 0.11.0: Replaces from_cortical_map.

Parameters:

implant_type (p2p.implants.Implant) – Type of implant to create. Currently only NeuralinkThread is supported.
visual_field_map (p2p.topography.cortex.CorticalMap) – Cortical visual field map to create the 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.
region (str, optional) – Region of cortex to create implant in. Required unless the map has exactly one region.

Returns:

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

Return type:

p2p.implants.Neuralink

check_stim(stim)[source]

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

classmethod from_coords(implant_type, locs=None, xrange=None, yrange=None, step=None)[source]

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.

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_visual_field_map() works in; here they are microns, so the default laid every implant out inside a 6 um square.

property hemisphere

Implanted hemisphere

‘left’, ‘right’, or None if unspecified. Metadata: thread coordinates and the model’s implant_position place the implant, not this attribute.

Added in version 0.11.0.

property implants: Dict of implants

property max_current: Total instantaneous current (uA) the stimulator can source

property n_electrodes

Number of electrodes in the array

This is equivalent to calling electrode_array.n_electrodes.

plot(annotate=False, autoscale=True, ax=None, stim=None, stim_cmap=False)[source]

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)[source]

Prepare stimulation for an ensemble implant.

source may address the combined electrode array directly, or be a dict keyed by constituent implant keys. Per-implant sources are prepared by each constituent implant, merged, then passed through ensemble-level preprocessing and safety checks. Missing implant keys contribute zeros.

Changed in version 0.11.0: Replaces merge_stimuli and the stimuli previously stored on constituent implants.

Parameters:: source (dict or Stimulus source type) – One source for the whole ensemble, or {implant_key: source}.
Returns:: stim – Merged stimulation for the ensemble.
Return type:: Stimulus or None

Examples

>>> import numpy as np
>>> from pulse2percept.implants import EnsembleImplant
>>> from pulse2percept.implants.cortex import Orion
>>> ensemble = EnsembleImplant.from_coords(
...     Orion, locs=np.array([(0, 0), (-35000, 0)]))
>>> ensemble.prepare_stim({0: np.ones(60),
...                        1: 2 * np.ones(60)}).data.shape
(120, 1)

preprocess_stim(stim)[source]

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[source]: 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.

plot3d(ax=None, **kwargs)[source]

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.