pulse2percept.models.thompson2003

Thompson2003Model, Thompson2003Spatial [Thompson2003]

Classes

Thompson2003Model(**params)	Scoreboard model of [Thompson2003] (standalone model)
Thompson2003Spatial(**params)	Scoreboard model of [Thompson2003] (spatial module only)

class pulse2percept.models.thompson2003.Thompson2003Model(**params)

Scoreboard model of [Thompson2003] (standalone model)

Implements the scoreboard model described in [Thompson2003], where all percepts are circular disks of a given size, and a fraction of electrodes may randomly drop out.

Note

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

radius : double, optional

Disk radius describing phosphene size (microns). If None, disk diameter is chosen as the electrode-to-electrode spacing (works only for implants with a shape attribute) with a 5% gap.

dropout : int or float, optional

If an int, number of electrodes to randomly drop out every frame. If a float between 0 and 1, the fraction of electrodes to randomly drop out every frame.

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

retinotopy : VisualFieldMap, optional

An instance of a VisualFieldMap object that provides ret2dva and dva2ret methods. By default, Watson2014Map 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.

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

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)

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.thompson2003.Thompson2003Spatial(**params)

Scoreboard model of [Thompson2003] (spatial module only)

Implements the scoreboard model described in [Thompson2003], where all percepts are circular disks of a given size, and a fraction of electrodes may randomly drop out.

Note

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

Parameters:

• radius (double, optional) – Disk radius describing phosphene size (microns). If None, disk diameter is chosen as the electrode-to-electrode spacing (works only for implants with a shape attribute) with a 5% gap.
• dropout (int or float, optional) – If an int, number of electrodes to randomly drop out every frame. If a float between 0 and 1, the fraction of electrodes to randomly drop out every frame.
• 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
• retinotopy (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides ret2dva and dva2ret methods. By default, Curcio1990Map 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.
• 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. 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 (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()

Returns all settable parameters of the model

is_built

A flag indicating whether the model has been built

plot(use_dva=False, style='hull', autoscale=True, ax=None, figsize=None)

Plot the model

Parameters:

• use_dva (bool, optional) – Uses degrees of visual angle (dva) if True, else retinal coordinates (microns)
• 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

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

Set the parameters of this model