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 and PrettyPrint)
Build a model (via build) and flip the is_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 and FreezeError).

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

get_default_params()[source]¶: Return a dict of user-settable model parameters

is_built¶: A flag indicating whether the model has been built

set_params(**params)[source]¶: Set the parameters of this model

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

See also

Basic Concepts > Computational Models > Building your own model

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 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)[source]¶

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)[source]¶

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

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.

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 call build before calling predict_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 of self.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 call predict_percept, which in turn will call _predict_spatial. The same logic applies to build (called by the user; don’t touch) and _build (called by build; 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 a FreezeError.

See also

Basic Concepts > Computational Models > Building your own model

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 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)[source]¶

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()[source]¶: Return a dictionary of default values for all model parameters

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 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)[source]¶: Set the parameters of this model

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 call build before calling predict_percept.

To create your own temporal model, you must subclass SpatialModel and provide an implementation for:

_predict_temporal: a method that accepts either a Stimulus or a Percept 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 a FreezeError.