pulse2percept.models.cortex

Phosphene models for cortical implants

`base`	`CortexSpatial`, `ScoreboardSpatial`, `ScoreboardModel`
`dynaphos`	`DynaphosModel`

Parameters:

regionslist of str, optional: The regions to simulate. Options are any combination of ‘v1’, ‘v2’, ‘v3’. Default: [‘v1’].
rhodouble, optional: Exponential decay constant describing current spread size (microns).
xrange(x_min, x_max), optional: A tuple indicating the range of x values to simulate (in degrees of visual angle). In a right eye, negative x values correspond to the temporal retina, and positive x values to the nasal retina. In a left eye, the opposite is true.
yrangetuple, (y_min, y_max), optional: A tuple indicating the range of y values to simulate (in degrees of visual angle). Negative y values correspond to the superior retina, and positive y values to the inferior retina.
xystepint, double, tuple, optional: Step size for the range of (x,y) values to simulate (in degrees of visual angle). For example, to create a grid with x values [0, 0.5, 1] use xrange=(0, 1) and xystep=0.5.
grid_type{‘rectangular’, ‘hexagonal’}, optional: Whether to simulate points on a rectangular or hexagonal grid
vfmapVisualFieldMap, optional: An instance of a VisualFieldMap object that provides retinotopic mappings. By default, Polimeni2006Map is used.
n_grayint, optional: The number of gray levels to use. If an integer is given, k-means clustering is used to compress the color space of the percept into n_gray bins. If None, no compression is performed.
noisefloat or int, optional: Adds salt-and-pepper noise to each percept frame. An integer will be interpreted as the number of pixels to subject to noise in each frame. A float between 0 and 1 will be interpreted as a ratio of pixels to subject to noise in each frame.
n_threadsint, optional: Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.

Important

If you change important model parameters outside the constructor (e.g., by directly setting model.xrange = (-10, 10)), you will have to call model.build() again for your changes to take effect.

get_default_params()[source]: Returns all settable parameters of the scoreboard model

plot(use_dva=False, style=None, autoscale=True, ax=None, figsize=None, fc=None, **kwargs)[source]

Plot the model

Parameters:

use_dva (bool, optional) – Plot points in visual field. If false, simulated points will be plotted in cortex
style ({'hull', 'scatter', 'cell'}, optional) –
Grid plotting style:
- ’hull’: Show the convex hull of the grid (that is, the outline of the smallest convex set that contains all grid points).
- ’scatter’: Scatter plot all grid points
- ’cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a high-resolution grid.
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.
figsize ((float, float), optional) – Desired (width, height) of the figure in inches
fc (matplotlib color, optional) – Face color for the grid cells. If None, will use the default matplotlib color cycle.
kwargs (dict, optional) – Additional keyword arguments are passed on to Grid2D.plot()

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

build(**build_params)[source]

Build the model

Performs expensive one-time calculations, such as building the spatial grid used to predict a percept. You must call build before calling predict_percept.

Important

Don’t override this method if you are building your own model. Customize _build instead.

Parameters:: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params. Trying to add new class attributes outside of that will cause a FreezeError. Example: model.build(param1=val)

find_threshold(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100)[source]

Find the threshold current for a certain stimulus

Estimates amp_th such that the output of model.predict_percept(stim(amp_th)) is approximately bright_th.

Parameters:

implant (ProsthesisSystem) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated until amp_th is found.
bright_th (float) – Model output (brightness) that’s considered “at threshold”.
amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within amp_tol
bright_tol (float, optional) – Search will stop if model brightness is within bright_tol of bright_th
max_iter (int, optional) – Search will stop after max_iter iterations

Returns:

amp_th (float) – Threshold current (uA), estimated so that the output of model.predict_percept(stim(amp_th)) is within bright_tol of bright_th.

property is_built: A flag indicating whether the model has been built

predict_percept(implant, t_percept=None)[source]

Predict the spatial response

Important

Don’t override this method if you are creating your own model. Customize _predict_spatial instead.

Parameters:

implant (ProsthesisSystem) – A valid prosthesis system. A stimulus can be passed via stim().
t_percept (float or list of floats, optional) – The time points at which to output a percept (ms). If None, implant.stim.time is used.

Returns:

percept (Percept) – A Percept object whose data container has dimensions Y x X x T. Will return None if implant.stim is None.

set_params(**params)[source]: Set the parameters of this model

class pulse2percept.models.cortex.DynaphosModel(**params)[source]

Adaptation of the Dynaphos model from [vanderGrinten2023]

The original and official implementation is available at https://github.com/neuralcodinglab/dynaphos.

Implements the Dynaphos model. Percepts from each electrode are Gaussian blobs, with the size dictated by a magnification factor M determined by the electrode’s position in the visual cortex.

Parameters:

dt (float, optional) – Sampling time step of the simulation (ms)
regions (list of str, optional) – The visual regions to simulate. Options are ‘v1’, ‘v2’, or ‘v3’. Default : [‘v1’]
rheobase (float, optional) – Rheobase current constant (uA)
tau_trace (float, optional) – Trace decay constant (ms)
kappa_trace (float, optional) – Stimulus input effect modifier constant for memory trace
excitability (float, optional) – Excitability constant for current spread (uA/mm^2)
tau_act (float, optional) – Activation decay constant (ms)
sig_slope (float, optional) – Slope of the sigmoidal brightness curve
a_thr (float, optional) – Activation threshold value, under which a phosphene is not generated
a50 (float, optional) – Activation value for which a phosphene reaches half of its maximum brightness
freq (float, optional) – Default stimulus frequency (Hz)
p_dur (float, optional) – Default stimulus pulse duration (ms)
xrange ((x_min, x_max), optional) – A tuple indicating the range of x values to simulate (in degrees of visual angle). Negative values correspond to the right hemisphere of visual cortex, and positive values correspond to the left hemisphere.
yrange ((y_min, y_max), optional) – A tuple indicating the range of y values to simulate (in degrees of visual angle).
xystep (int, double, tuple, optional) – Step size for the range of (x,y) values to simulate (in degrees of visual angle). For example, to create a grid with x values [0, 0.5, 1] use x_range=(0, 1) and xystep=0.5.
grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid.
vfmap (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides visual field mappings. By default, Polimeni2006Map is used.
n_gray (int, optional) – The number of gray levels to use. If an integer is given, k-means clustering is used to compress the color space of the percept into n_gray bins. If None, no compression is performed.
noise (float or int, optional) – Adds salt-and-pepper noise to each percept frame. An integer will be interpreted as the number of pixels to subject to noise in each frame. A float between 0 and 1 will be interpreted as a ratio of pixels to subject to noise in each frame.

Important

If you change important model parameters outside the constructor (e.g., by directly setting model.xrange = (-10, 10)), you will have to call model.build() again for your changes to take effect.

get_default_params()[source]: Returns all settable parameters of the Dynaphos model

build(**build_params)[source]

Build the model

Performs expensive one-time calculations, such as building the spatial grid used to predict a percept. You must call build before calling predict_percept.

Parameters:: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params. Trying to add new class attributes outside of that will cause a FreezeError. Example: model.build(param1=val)

predict_percept(implant, t_percept=None)[source]

Predict the spatiotemporal response

Parameters:

implant (ProsthesisSystem) – A valid prosthesis system. A stimulus can be passed via stim().
t_percept (float or list of floats, optional) – The time points at which to output a percept (ms). If None, implant.stim.time is used.

Returns:

percept (Percept) – A Percept object whose data container has dimensions Y x X x T. Will return None if implant.stim is None.

property is_built: A flag indicating whether the model has been built

plot(use_dva=False, style=None, autoscale=True, ax=None, figsize=None, fc=None)[source]

Plot the model :param use_dva: Plot points in visual field. If false, simulated points will be

plotted in cortex

Parameters:

style ({'hull', 'scatter', 'cell'}, optional) –
Grid plotting style:
- ’hull’: Show the convex hull of the grid (that is, the outline of the smallest convex set that contains all grid points).
- ’scatter’: Scatter plot all grid points
- ’cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a high-resolution grid.
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.
figsize ((float, float), optional) – Desired (width, height) of the figure in inches

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

set_params(**params)[source]: Set the parameters of this model

class pulse2percept.models.cortex.ScoreboardModel(**params)[source]

Cortical adaptation of scoreboard model from [Beyeler2019] (standalone model)

Implements the scoreboard model described in [Beyeler2019], where percepts from each electrode are Gaussian blobs. The percepts resulting from different cortical regions (e.g. v1/v2/v3) are added linearly. The rho parameter modulates phosphene size.

Note

Use this class if you want a standalone model. Use ScoreboardSpatial if you want to combine the spatial model with a temporal model.

Parameters:

rho (double, optional) – Exponential decay constant describing phosphene size (microns).
regions (list of str, optional) – The regions to simulate. Options are ‘v1’, ‘v2’, or ‘v3’. Default: [‘v1’]
xrange ((x_min, x_max), optional) – A tuple indicating the range of x values to simulate (in degrees of visual angle). In a right eye, negative x values correspond to the temporal retina, and positive x values to the nasal retina. In a left eye, the opposite is true.
yrange (tuple, (y_min, y_max), optional) – A tuple indicating the range of y values to simulate (in degrees of visual angle). Negative y values correspond to the superior retina, and positive y values to the inferior retina.
xystep (int, double, tuple, optional) – Step size for the range of (x,y) values to simulate (in degrees of visual angle). For example, to create a grid with x values [0, 0.5, 1] use xrange=(0, 1) and xystep=0.5.
grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
vfmap (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides retinotopic mappings. By default, Polimeni2006Map is used.
n_gray (int, optional) – The number of gray levels to use. If an integer is given, k-means clustering is used to compress the color space of the percept into n_gray bins. If None, no compression is performed.
noise (float or int, optional) – Adds salt-and-pepper noise to each percept frame. An integer will be interpreted as the number of pixels to subject to noise in each frame. A float between 0 and 1 will be interpreted as a ratio of pixels to subject to noise in each frame.
n_threads (int, optional) – Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.
:: (.. important) – If you change important model parameters outside the constructor (e.g., by directly setting model.xrange = (-10, 10)), you will have to call model.build() again for your changes to take effect.

build(**build_params)[source]

Build the model

Performs expensive one-time calculations, such as building the spatial grid used to predict a percept.

Parameters:: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params. Trying to add new class attributes outside of that will cause a FreezeError. Example: model.build(param1=val)
Returns:: self

find_threshold(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]

Find the threshold current for a certain stimulus

Estimates amp_th such that the output of model.predict_percept(stim(amp_th)) is approximately bright_th.

Parameters:

implant (ProsthesisSystem) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated until amp_th is found.
bright_th (float) – Model output (brightness) that’s considered “at threshold”.
amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within amp_tol
bright_tol (float, optional) – Search will stop if model brightness is within bright_tol of bright_th
max_iter (int, optional) – Search will stop after max_iter iterations
t_percept (float or list of floats, optional) – The time points at which to output a percept (ms). If None, implant.stim.time is used.

Returns:

amp_th (float) – Threshold current (uA), estimated so that the output of model.predict_percept(stim(amp_th)) is within bright_tol of bright_th.

property has_space: Returns True if the model has a spatial component

property has_time: Returns True if the model has a temporal component

property is_built: Returns True if the build model has been called

predict_percept(implant, t_percept=None)[source]

Predict a percept

Important

You must call build before calling predict_percept.

Parameters:

implant (ProsthesisSystem) – A valid prosthesis system. A stimulus can be passed via stim().
t_percept (float or list of floats, optional) – The time points at which to output a percept (ms). If None, implant.stim.time is used.

Returns:

percept (Percept) – A Percept object whose data container has dimensions Y x X x T. Will return None if implant.stim is None.

set_params(params)[source]

Set model parameters

This is a convenience function to set parameters that might be part of the spatial model, the temporal model, or both.

Alternatively, you can set the parameter directly, e.g. model.spatial.verbose = True.

Note

If a parameter exists in both spatial and temporal models(e.g., verbose), both models will be updated.

Parameters:: params (dict) – A dictionary of parameters to set.

class pulse2percept.models.cortex.ScoreboardSpatial(**params)[source]

Cortical adaptation of scoreboard model from [Beyeler2019]

Implements the scoreboard model described in [Beyeler2019], where percepts from each electrode are Gaussian blobs. The percepts resulting from different cortical regions (e.g. v1/v2/v3) are added linearly. The rho parameter modulates phosphene size.

Note

Use this class if you want to combine the spatial model with a temporal model. Use ScoreboardModel if you want a a standalone model.

Parameters:

rho (double, optional) – Exponential decay constant describing phosphene size (microns).
regions (list of str, optional) – The regions to simulate. Options are ‘v1’, ‘v2’, or ‘v3’. Default: [‘v1’]
xrange ((x_min, x_max), optional) – A tuple indicating the range of x values to simulate (in degrees of visual angle). In a right eye, negative x values correspond to the temporal retina, and positive x values to the nasal retina. In a left eye, the opposite is true.
yrange (tuple, (y_min, y_max), optional) – A tuple indicating the range of y values to simulate (in degrees of visual angle). Negative y values correspond to the superior retina, and positive y values to the inferior retina.
xystep (int, double, tuple, optional) – Step size for the range of (x,y) values to simulate (in degrees of visual angle). For example, to create a grid with x values [0, 0.5, 1] use xrange=(0, 1) and xystep=0.5.
grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
vfmap (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides retinotopic mappings. By default, Polimeni2006Map is used.
n_gray (int, optional) – The number of gray levels to use. If an integer is given, k-means clustering is used to compress the color space of the percept into n_gray bins. If None, no compression is performed.
noise (float or int, optional) – Adds salt-and-pepper noise to each percept frame. An integer will be interpreted as the number of pixels to subject to noise in each frame. A float between 0 and 1 will be interpreted as a ratio of pixels to subject to noise in each frame.
n_threads (int, optional) – Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.
:: (.. important) – If you change important model parameters outside the constructor (e.g., by directly setting model.xrange = (-10, 10)), you will have to call model.build() again for your changes to take effect.

get_default_params()[source]: Returns all settable parameters of the scoreboard model

build(**build_params)[source]

Build the model

Performs expensive one-time calculations, such as building the spatial grid used to predict a percept. You must call build before calling predict_percept.

Important

Don’t override this method if you are building your own model. Customize _build instead.

Parameters:: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params. Trying to add new class attributes outside of that will cause a FreezeError. Example: model.build(param1=val)

find_threshold(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100)[source]

Find the threshold current for a certain stimulus

Estimates amp_th such that the output of model.predict_percept(stim(amp_th)) is approximately bright_th.

Parameters:

implant (ProsthesisSystem) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated until amp_th is found.
bright_th (float) – Model output (brightness) that’s considered “at threshold”.
amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within amp_tol
bright_tol (float, optional) – Search will stop if model brightness is within bright_tol of bright_th
max_iter (int, optional) – Search will stop after max_iter iterations

Returns:

amp_th (float) – Threshold current (uA), estimated so that the output of model.predict_percept(stim(amp_th)) is within bright_tol of bright_th.

property is_built: A flag indicating whether the model has been built

plot(use_dva=False, style=None, autoscale=True, ax=None, figsize=None, fc=None, **kwargs)[source]

Plot the model

Parameters:

use_dva (bool, optional) – Plot points in visual field. If false, simulated points will be plotted in cortex
style ({'hull', 'scatter', 'cell'}, optional) –
Grid plotting style:
- ’hull’: Show the convex hull of the grid (that is, the outline of the smallest convex set that contains all grid points).
- ’scatter’: Scatter plot all grid points
- ’cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a high-resolution grid.
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.
figsize ((float, float), optional) – Desired (width, height) of the figure in inches
fc (matplotlib color, optional) – Face color for the grid cells. If None, will use the default matplotlib color cycle.
kwargs (dict, optional) – Additional keyword arguments are passed on to Grid2D.plot()

Returns:

ax (matplotlib.axes.Axes) – Returns the axis object of the plot

predict_percept(implant, t_percept=None)[source]

Predict the spatial response

Important

Don’t override this method if you are creating your own model. Customize _predict_spatial instead.

Parameters:

implant (ProsthesisSystem) – A valid prosthesis system. A stimulus can be passed via stim().
t_percept (float or list of floats, optional) – The time points at which to output a percept (ms). If None, implant.stim.time is used.

Returns:

percept (Percept) – A Percept object whose data container has dimensions Y x X x T. Will return None if implant.stim is None.

set_params(**params)[source]: Set the parameters of this model