pulse2percept.models.base¶
BaseModel
, Model
, NotBuiltError
, Percept
, SpatialModel
,
TemporalModel
Classes
BaseModel (**params) |
Abstract base class for all models |
Model ([spatial, temporal]) |
Computational model |
SpatialModel (**params) |
Abstract base class for all spatial models |
TemporalModel (**params) |
Abstract base class for all temporal models |
Exceptions
NotBuiltError |
Exception class used to raise if model is used before building |
-
class
pulse2percept.models.base.
BaseModel
(**params)[source]¶ Abstract base class for all models
Provides the following functionality:
- Pretty-print class attributes (via
_pprint_params
andPrettyPrint
) - Build a model (via
build
) and flip theis_built
switch - User-settable parameters must be listed in
get_default_params
- New class attributes can only be added in the constructor
(enforced via
Frozen
andFreezeError
).
-
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)
-
is_built
¶ A flag indicating whether the model has been built
- Pretty-print class attributes (via
-
class
pulse2percept.models.base.
Model
(spatial=None, temporal=None, **params)[source]¶ Computational model
To build your own model, you can mix and match spatial and temporal models at will.
For example, to create a model that combines the scoreboard model described in [Beyeler2019] with the temporal model cascade described in [Nanduri2012], use the following:
model = Model(spatial=ScoreboardSpatial(), temporal=Nanduri2012Temporal())
New in version 0.6.
Parameters: - spatial (
SpatialModel
or None) – blah - temporal (
TemporalModel
or None) – blah - **params – Additional keyword arguments(e.g.,
verbose=True
) to be passed to either the spatial model, the temporal model, or both.
-
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.
- spatial (
-
exception
pulse2percept.models.base.
NotBuiltError
[source]¶ Exception class used to raise if model is used before building
This class inherits from both ValueError and AttributeError to help with exception handling and backward compatibility.
-
name
¶ attribute name
-
obj
¶ object
-
with_traceback
()¶ Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
-
-
class
pulse2percept.models.base.
SpatialModel
(**params)[source]¶ Abstract base class for all spatial models
Provides basic functionality for all spatial models:
build
: builds the spatial grid used to calculate the percept. You can add your own_build
method (note the underscore) that performs additional expensive one-time calculations.predict_percept
: predicts the percepts based on an implant/stimulus. Don’t customize this method - implement your own_predict_spatial
instead (see below). A user must callbuild
before callingpredict_percept
.
To create your own spatial model, you must subclass
SpatialModel
and provide an implementation for:_predict_spatial
: This method should accept an ElectrodeArray as well as a Stimulus, and compute the brightness at all spatial coordinates ofself.grid
, returned as a 2D NumPy array (space x time).Note
The
_
in the method name indicates that this is a private method, meaning that it should not be called by the user. Instead, the user should callpredict_percept
, which in turn will call_predict_spatial
. The same logic applies tobuild
(called by the user; don’t touch) and_build
(called bybuild
; customize this instead).
In addition, you can customize the following:
__init__
: the constructor can be used to define additional parameters (note that you cannot add parameters on-the-fly)get_default_params
: all settable model parameters must be listed by this method_build
(optional): a way to add one-time computations to the build process
New in version 0.6.
Note
You will not be able to add more parameters outside the constructor; e.g.,
model.newparam = 1
will lead to aFreezeError
.-
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.base.
TemporalModel
(**params)[source]¶ Abstract base class for all temporal models
Provides basic functionality for all temporal models:
build
: builds the model in order to calculate the percept. You can add your own_build
method (note the underscore) that performs additional expensive one-time calculations.predict_percept
: predicts the percepts based on an implant/stimulus. You can add your own_predict_temporal
method to customize this step. A user must callbuild
before callingpredict_percept
.
To create your own temporal model, you must subclass
SpatialModel
and provide an implementation for:_predict_temporal
: a method that accepts either aStimulus
or aPercept
object and a list of time points at which to calculate the resulting percept, returned as a 2D NumPy array (space x time).
In addition, you can customize the following:
__init__
: the constructor can be used to define additional parameters (note that you cannot add parameters on-the-fly)get_default_params
: all settable model parameters must be listed by this method_build
(optional): a way to add one-time computations to the build process
New in version 0.6.
Note
You will not be able to add more parameters outside the constructor; e.g.,
model.newparam = 1
will lead to aFreezeError
.-
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: