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)

Abstract base class for cortical models

This is an abstract class that cortical models can subclass to get cortical implementation of the following features.

• Updated default parameters for cortex

• Handling of multiple visual regions via regions property

• Plotting, including multiple visual regions, legends, vertical divide at longitudinal fissure, etc.

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

min_current_spreadfloat, optional

An electrode is skipped at grid points where its Gaussian current spread has decayed below this fraction of its peak. The default (1e-8, about 6.1 rho away) drops the Gaussian times the stimulus amplitude, summed over the skipped electrodes, so the error at a point is bounded by min_current_spread times the summed amplitude across electrodes.

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.

stepint, 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 step=0.5. Pass a tuple to give the x and y axes different step sizes.

Changed in version 0.10.0: Renamed from xystep, which suggested that one step size applies to both axes. The old name still works, but is deprecated and will be removed in v0.11.0.

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.

n_jobsint, optional

Alias for n_threads; None or -1 uses every core.

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()

Returns all settable parameters of the scoreboard model

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

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 – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

build(**build_params)

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)

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, counted in this model’s stimulus_unit (microamps, for every model p2p ships).

• amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within amp_tol, in stimulus_unit

• 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 – Threshold current, in stimulus_unit, estimated so that the output of model.predict_percept(stim(amp_th)) is within bright_tol of bright_th.

Return type:

float

Notes

• amp_range and amp_tol may be given as unitful quantities (e.g. amp_range=(0, 1 * mA)); the answer comes back as a plain number of microamps. bright_th and bright_tol are model output, which is not a physical quantity and carries no unit. See pulse2percept.units.

get_param_units()

Return a dict of the units that parameters are stored in

property is_built

A flag indicating whether the model has been built

property n_jobs

both names read and write the same value.

Type:

Number of OpenMP threads to use during parallelization. An alias for n_threads

predict_percept(implant, t_percept=None)

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, counted in this model’s time_unit (milliseconds, for every model p2p ships). If None, implant.stim.time is used. May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units.

Returns:

percept – A Percept object whose data container has dimensions Y x X x T, and whose time axis is labelled in time_unit. Will return None if implant.stim is None.

Return type:

Percept

set_params(**params)

Set the parameters of this object

space_unit = um

The unit spatial coordinates are expressed in

stimulus_unit = uA

The unit stimulus values are expressed in

time_unit = ms

The unit time is expressed in

xystep

step used to be called xystep. The old name still reads and writes step, with a DeprecationWarning:

class pulse2percept.models.cortex.base.ScoreboardSpatial(**params)

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

• min_current_spread (float, optional) – An electrode is skipped at grid points where its Gaussian current spread has decayed below this fraction of its peak. The default (1e-8, about 6.1 rho away) drops the Gaussian times the stimulus amplitude, summed over the skipped electrodes, so the error at a point is bounded by min_current_spread times the summed amplitude across electrodes.

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

• step (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 step=0.5. Pass a tuple to give the x and y axes different step sizes.

  Changed in version 0.10.0: Renamed from xystep, which suggested that one step size applies to both axes. The old name still works, but is deprecated and will be removed in v0.11.0.

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

• n_jobs (int, optional) – Alias for n_threads; None or -1 uses every core.

• :: (.. 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()

Returns all settable parameters of the scoreboard model

get_param_units()

Return a dict of the units that parameters are stored in

build(**build_params)

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)

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, counted in this model’s stimulus_unit (microamps, for every model p2p ships).

• amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within amp_tol, in stimulus_unit

• 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 – Threshold current, in stimulus_unit, estimated so that the output of model.predict_percept(stim(amp_th)) is within bright_tol of bright_th.

Return type:

float

Notes

• amp_range and amp_tol may be given as unitful quantities (e.g. amp_range=(0, 1 * mA)); the answer comes back as a plain number of microamps. bright_th and bright_tol are model output, which is not a physical quantity and carries no unit. See pulse2percept.units.

property is_built

A flag indicating whether the model has been built

property n_jobs

both names read and write the same value.

Type:

Number of OpenMP threads to use during parallelization. An alias for n_threads

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

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 – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

predict_percept(implant, t_percept=None)

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, counted in this model’s time_unit (milliseconds, for every model p2p ships). If None, implant.stim.time is used. May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units.

Returns:

percept – A Percept object whose data container has dimensions Y x X x T, and whose time axis is labelled in time_unit. Will return None if implant.stim is None.

Return type:

Percept

set_params(**params)

Set the parameters of this object

space_unit = um

The unit spatial coordinates are expressed in

stimulus_unit = uA

The unit stimulus values are expressed in

time_unit = ms

The unit time is expressed in

xystep

step used to be called xystep. The old name still reads and writes step, with a DeprecationWarning:

class pulse2percept.models.cortex.base.ScoreboardModel(**params)

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

• min_current_spread (float, optional) – An electrode is skipped at grid points where its Gaussian current spread has decayed below this fraction of its peak. The default (1e-8, about 6.1 rho away) drops the Gaussian times the stimulus amplitude, summed over the skipped electrodes, so the error at a point is bounded by min_current_spread times the summed amplitude across electrodes.

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

• step (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 step=0.5. Pass a tuple to give the x and y axes different step sizes.

  Changed in version 0.10.0: Renamed from xystep, which suggested that one step size applies to both axes. The old name still works, but is deprecated and will be removed in v0.11.0.

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

• n_jobs (int, optional) – Alias for n_threads; None or -1 uses every core.

• :: (.. 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)

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)

Return type:

self

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

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, counted in this model’s stimulus_unit (microamps, for every model p2p ships).

• 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, counted in this model’s time_unit (milliseconds, for every model p2p ships). If None, implant.stim.time is used. May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units.

Returns:

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

Return type:

float

Notes

• amp_range, amp_tol and t_percept may be given as unitful quantities; the answer comes back as a plain number of microamps. bright_th and bright_tol are model output, which is not a physical quantity and carries no unit. See pulse2percept.units.

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)

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, counted in this model’s time_unit (milliseconds, for every model p2p ships). If None, implant.stim.time is used. May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units.

Returns:

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

Return type:

Percept

set_params(params)

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.

property space_unit

The unit spatial coordinates are expressed in

The temporal model never sees a coordinate.

property stimulus_unit

The unit stimulus values are expressed in

The stimulus goes to the spatial model if there is one, and straight to the temporal model otherwise.

property time_unit

The unit time is expressed in

t_percept is read in, and the resulting Percept is written in, the unit of the last stage of the pipeline: the temporal model if there is one, the spatial model otherwise. The two need not agree – a spatial model counting in seconds hands its percept to a temporal model counting in milliseconds and the time axis is converted on the way across.