pulse2percept.models.nanduri2012¶
Nanduri2012Model
, Nanduri2012Spatial
, Nanduri2012Temporal
[Nanduri2012]
Classes
Nanduri2012Model (**params) |
[Nanduri2012] Model |
Nanduri2012Spatial (**params) |
Spatial response model of [Nanduri2012] |
Nanduri2012Temporal (**params) |
Temporal model of [Nanduri2012] |
-
class
pulse2percept.models.nanduri2012.
Nanduri2012Model
(**params)[source]¶ [Nanduri2012] Model
Implements the model described in [Nanduri2012], where percepts are circular and their brightness evolves over time.
The model combines two parts:
Nanduri2012Spatial
is used to calculate the spatial activation function, which is assumed to be equivalent to the “current spread” described as a function of distance from the center of the stimulating electrode (see Eq.2 in the paper).Nanduri2012Temporal
is used to calculate the temporal activation function, which is assumed to be the output of a linear-nonlinear cascade model (see Fig.6 in the paper).
Parameters: - atten_a (float, optional) – Nominator of the attentuation function (Eq.2 in the paper)
- atten_n (float32, optional) – Exponent of the attenuation function’s denominator (Eq.2 in the paper)
- dt (float, optional) – Sampling time step (ms)
- tau1 (float, optional) – Time decay constant for the fast leaky integrater.
- tau2 (float, optional) – Time decay constant for the charge accumulation.
- tau3 (float, optional) – Time decay constant for the slow leaky integrator.
- eps (float, optional) – Scaling factor applied to charge accumulation.
- asymptote (float, optional) – Asymptote of the logistic function used in the stationary nonlinearity stage.
- slope (float, optional) – Slope of the logistic function in the stationary nonlinearity stage.
- shift (float, optional) – Shift of the logistic function in the stationary nonlinearity stage.
- scale_out (float32, optional) – A scaling factor applied to the output of the model
- thresh_percept (float, optional) – Below threshold, the percept has brightness zero.
- 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. - 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.
-
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.nanduri2012.
Nanduri2012Spatial
(**params)[source]¶ Spatial response model of [Nanduri2012]
Implements the spatial response model described in [Nanduri2012], which assumes that the spatial activation of retinal tissue is equivalent to the “current spread” \(I\), described as a function of distance \(r\) from the center of the stimulating electrode:
\[\begin{split}I(r) = \begin{cases} \frac{\verb!atten_a!}{\verb!atten_a! + (r-a)^\verb!atten_n!} & r > a \\ 1 & r \leq a \end{cases}\end{split}\]where \(a\) is the radius of the electrode (see Eq.2 in the paper).
Note
Use this class if you just want the spatial response model. Use
Nanduri2012Model
if you want both the spatial and temporal model.Parameters: - atten_a (float, optional) – Nominator of the attentuation function
- atten_n (float32, optional) – Exponent of the attenuation function’s denominator
- 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. - 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.
-
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 (
-
class
pulse2percept.models.nanduri2012.
Nanduri2012Temporal
(**params)[source]¶ Temporal model of [Nanduri2012]
Implements the temporal response model described in [Nanduri2012], which assumes that the temporal activation of retinal tissue is the output of a linear-nonlinear model cascade (see Fig.6 in the paper).
Note
Use this class if you just want the temporal response model. Use
Nanduri2012Model
if you want both the spatial and temporal model.Parameters: - dt (float, optional) – Sampling time step (ms)
- tau1 (float, optional) – Time decay constant for the fast leaky integrater.
- tau2 (float, optional) – Time decay constant for the charge accumulation.
- tau3 (float, optional) – Time decay constant for the slow leaky integrator.
- eps (float, optional) – Scaling factor applied to charge accumulation.
- asymptote (float, optional) – Asymptote of the logistic function used in the stationary nonlinearity stage.
- slope (float, optional) – Slope of the logistic function in the stationary nonlinearity stage.
- shift (float, optional) – Shift of the logistic function in the stationary nonlinearity stage.
- scale_out (float32, optional) – A scaling factor applied to the output of the model
- thresh_percept (float, optional) – Below threshold, the percept has brightness zero.
- n_threads (int, optional) – Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.
-
build
(**build_params)[source]¶ Build the model
Every model must have a
`build
method, which is meant to perform all expensive one-time calculations. You must callbuild
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
(stim, 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: - stim (
Stimulus
) – The 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
.- stim (
-
is_built
¶ A flag indicating whether the model has been built
-
predict_percept
(stim, t_percept=None)[source]¶ Predict the temporal response
Important
Don’t override this method if you are creating your own model. Customize
_predict_temporal
instead.Parameters: - stim (: py: class:
~pulse2percept.stimuli.Stimulus
or) – : py: class:~pulse2percept.models.Percept
Either a Stimulus or a Percept object. The temporal model will be applied to each spatial location in the stimulus/percept. - t_percept (float or list of floats, optional) –
The time points at which to output a percept (ms). If None, the percept will be output once very 20 ms (50 Hz frame rate).
Note
If your stimulus is shorter than 20 ms, you should specify the desired time points manually.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifstim
is None.Notes
- If a list of time points is provided for
t_percept
, the values will automatically be sorted.
- stim (: py: class: