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)[source]¶ 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)
andxystep=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,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 callmodel.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 aFreezeError
. 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 ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters: - implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_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
ofbright_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 withinbright_tol
ofbright_th
.- implant (
-
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 callingpredict_percept
.Parameters: - implant (
ProsthesisSystem
) – A valid prosthesis system. A stimulus can be passed viastim
. - 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 whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None.- implant (
-
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.thompson2003.
Thompson2003Spatial
(**params)[source]¶ 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)
andxystep=0.5
. - grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
- vfmap (
VisualFieldMap
, optional) – An instance of aVisualFieldMap
object that provides retinotopic mappings. 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 callmodel.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 callingpredict_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 aFreezeError
. 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 ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters: - implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_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
ofbright_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 withinbright_tol
ofbright_th
.- implant (
-
is_built
¶ A flag indicating whether the model has been built
-
plot
(use_dva=False, style='hull', autoscale=True, ax=None, figsize=None)[source]¶ 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)[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 viastim
. - 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 whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None.- implant (
- 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