# pulse2percept.models.base¶

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


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

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

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)
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 of model.predict_percept(stim(amp_th)) is approximately bright_th.

Parameters: stim (Stimulus) – The 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. 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

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. percept (Percept) – A Percept object whose data container has dimensions Y x X x T. Will return None if stim is None.

Notes

• If a list of time points is provided for t_percept, the values will automatically be sorted.
set_params(**params)[source]

Set the parameters of this model