pulse2percept.models.cortex.base¶

CortexSpatial, ScoreboardSpatial, ScoreboardModel

Classes

`CortexSpatial`(**params)	Abstract base class for cortical models
`ScoreboardModel`(**params)	Cortical adaptation of scoreboard model from [Beyeler2019] (standalone model)
`ScoreboardSpatial`(**params)	Cortical adaptation of scoreboard model from [Beyeler2019]

class pulse2percept.models.cortex.base.CortexSpatial(**params)[source]¶

Abstract base class for cortical models

This is an abstract class that cortical models can subclass to get cortical implementation of the following features. 1) Updated default parameters for cortex 2) Handling of multiple visual regions via regions property 3) Plotting, including multiple visual regions, legends, vertical

divide at longitudinal fissure, etc.

regions : list of str, optional: The regions to simulate. Options are any combination of ‘v1’, ‘v2’, ‘v3’. Default: [‘v1’].
rho : double, 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.
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. 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.

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

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 :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
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

class pulse2percept.models.cortex.base.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.

has_space¶: Returns True if the model has a spatial component

has_time¶: Returns True if the model has a temporal component

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.base.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.

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.

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

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 :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
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