pulse2percept.models¶

Computational models of the retina, such as phosphene and neural response models.

See also

Basic Concepts > Computational Models

class pulse2percept.models.AxonMapModel(**params)[source]¶

Axon map model of [Beyeler2019] (standalone model)

Implements the axon map model described in [Beyeler2019], where percepts are elongated along nerve fiber bundle trajectories of the retina.

Parameters:

axlambda (double, optional) – Exponential decay constant along the axon(microns).
rho (double, optional) – Exponential decay constant away from the axon(microns).
eye ({'RE', LE'}, optional) – Eye for which to generate the axon map.
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 ((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 or double or 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) and xystep=0.5.
grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
retinotopy (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides ret2dva and dva2ret methods. 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.
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.
loc_od (loc_od,) – Location of the optic disc in degrees of visual angle. Note that the optic disc in a left eye will be corrected to have a negative x coordinate.
n_axons (int, optional) – Number of axons to generate.
axons_range ((min, max), optional) – The range of angles(in degrees) at which axons exit the optic disc. This corresponds to the range of $phi_0$ values used in [Jansonius2009].
n_ax_segments (int, optional) – Number of segments an axon is made of.
ax_segments_range ((min, max), optional) – Lower and upper bounds for the radial position values(polar coords) for each axon.
min_ax_sensitivity (float, optional) – Axon segments whose contribution to brightness is smaller than this value will be pruned to improve computational efficiency. Set to a value between 0 and 1. If engine is jax, all other axons will be padded to the length enforced by this constraint.
engine (string, optional) – Engine to use for computation. Options are ‘serial’, ‘cython’, and ‘jax’. Defaults to ‘cython’
axon_pickle (str, optional) – File name in which to store precomputed axon maps.
ignore_pickle (bool, optional) – A flag whether to ignore the pickle file in future calls to model.build().
n_threads (int, optional) – Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.
important :: (.) – If you change important model parameters outside the constructor (e.g., by directly setting model.axlambda = 100), you will have to call model.build() again for your changes to take effect.

Notes

The axon map is not very accurate when the upper bound of ax_segments_range is greater than 90 deg.

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.

class pulse2percept.models.AxonMapSpatial(**params)[source]¶

Axon map model of [Beyeler2019] (spatial module only)

Implements the axon map model described in [Beyeler2019], where percepts are elongated along nerve fiber bundle trajectories of the retina.

Parameters:

axlambda (double, optional) – Exponential decay constant along the axon(microns).
rho (double, optional) – Exponential decay constant away from the axon(microns).
eye ({'RE', LE'}, optional) – Eye for which to generate the axon map.
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 ((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 or double or 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) and xystep=0.5.
grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
retinotopy (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides ret2dva and dva2ret methods. 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.
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.
loc_od (loc_od,) – Location of the optic disc in degrees of visual angle. Note that the optic disc in a left eye will be corrected to have a negative x coordinate.
n_axons (int, optional) – Number of axons to generate.
axons_range ((min, max), optional) – The range of angles(in degrees) at which axons exit the optic disc. This corresponds to the range of $phi_0$ values used in [Jansonius2009].
n_ax_segments (int, optional) – Number of segments an axon is made of.
ax_segments_range ((min, max), optional) – Lower and upper bounds for the radial position values(polar coords) for each axon.
min_ax_sensitivity (float, optional) – Axon segments whose contribution to brightness is smaller than this value will be pruned to improve computational efficiency. Set to a value between 0 and 1. If engine is jax, all other axons will be padded to the length enforced by this constraint.
engine (string, optional) – Engine to use for computation. Options are ‘serial’, ‘cython’, and ‘jax’. Defaults to ‘cython’
axon_pickle (str, optional) – File name in which to store precomputed axon maps.
ignore_pickle (bool, optional) – A flag whether to ignore the pickle file in future calls to model.build().
n_threads (int, optional) – Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.
important :: (.) – If you change important model parameters outside the constructor (e.g., by directly setting model.axlambda = 100), you will have to call model.build() again for your changes to take effect.

Notes

The axon map is not very accurate when the upper bound of ax_segments_range is greater than 90 deg.

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

calc_axon_sensitivity(bundles, pad=False)[source]¶

Calculate the sensitivity of each axon segment to electrical current

This function combines the x,y coordinates of each bundle segment with a sensitivity value that depends on the distance of the segment to the cell body and self.axlambda.

The number of bundles must equal the number of points on self.grid`. The function will then assume that the i-th bundle passes through the i-th point on the grid. This is used to determine the bundle segment that is closest to the i-th point on the grid, and to cut off all segments that extend beyond the soma. This effectively transforms a bundle into an axon, where the first axon segment now corresponds with the i-th location of the grid.

After that, each axon segment gets a sensitivity value that depends on the distance of the segment to the soma (with decay rate self.axlambda). This is typically done during the build process, so that the only work left to do during run time is to multiply the sensitivity value with the current applied to each segment.

If pad is True (set when engine is ‘jax’), axons are padded to all have the same length as the longest axon

Parameters: bundles (list of Nx2 arrays) – A list of bundles, where every bundle is an Nx2 array consisting of the x,y coordinates of each axon segment (retinal coords, microns). Note that each bundle will most likely have a different N

Returns: axon_contrib (numpy array with shape (n_points, axon_length, 3)) – An array of axon segments and sensitivity values. Each entry in the array is a Nx3 array, where the first two columns contain the retinal coordinates of each axon segment (microns), and the third column contains the sensitivity of the segment to electrical current. The latter depends on self.axlambda. axon_length is set to the maximum length of any axon after being trimmed due to min_sensitivity

calc_bundle_tangent(xc, yc)[source]¶

Calculates orientation of fiber bundle tangent at (xc, yc)

Parameters:	yc (xc,) – (x, y) retinal location of point at which to calculate bundle orientation in microns.
Returns:	tangent (scalar) – An angle in radians

find_closest_axon(bundles, xret=None, yret=None, return_index=False)[source]¶

Finds the closest axon segment for a point on the retina

This function will search a number of nerve fiber bundles (bundles) and return the bundle that is closest to a particular point (or list of points) on the retinal surface (xret, yret).

Parameters:

bundles (list of Nx2 arrays) – A list of bundles, where every bundle is an Nx2 array consisting of the x,y coordinates of each axon segment (retinal coords, microns). Note that each bundle will most likely have a different N
yret (xret,) – The x,y location on the retina (in microns, where the fovea is the origin) for which to find the closests axon.
return_index (bool, optional) – If True, the function will also return the index into bundles that represents the closest axon

Returns:

axon (Nx2 array or list of Nx2 arrays) – For each point in (xret, yret), returns an Nx2 array that represents the closest axon to that point. Each row in the array contains the x,y retinal coordinates (microns) of a particular axon segment.
idx_axon (scalar or list of scalars, optional) – If return_index is True, also returns the index in bundles of the closest axon (or list of closest axons).

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

grow_axon_bundles(n_bundles=None, prune=True)[source]¶

Grow a number of axon bundles

This method generates the trajectory of a number of nerve fiber bundles based on the mathematical model described in [Beyeler2019], which is based on [Jansonius2009].

Bundles originate at the optic nerve head with initial angle phi0. The method generates n_bundles axon bundles whose phi0 values are linearly sampled from self.axons_range (polar coords). Each axon will consist of self.n_ax_segments segments that span self.ax_segments_range distance from the optic nerve head (polar coords).

Parameters:	n_bundles (int, optional) – Number of axon bundles to generate. If None, `self.n_axons` is used prune (bool, optional) – If set to True, will remove axon segments that are outside the simulated area `self.xrange`, `self.yrange` for the sake of computational efficiency.
Returns:	bundles (list of Nx2 arrays) – A list of bundles, where every bundle is an Nx2 array consisting of the x,y coordinates of each axon segment (retinal coords, microns). Note that each bundle will most likely have a different N

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

plot(use_dva=False, style='hull', annotate=True, autoscale=True, ax=None, figsize=None)[source]¶

Plot the axon map

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.
annotate (bool, optional) – Flag whether to label the four retinal quadrants
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot
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

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.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.FadingTemporal(**params)[source]¶

A generic temporal model for phosphene fading

Implements phosphene fading using a leaky integrator:

\[\frac{dB}{dt} = -\frac{A+B}{\tau}\]

where $A$ is the stimulus amplitude, $B$ is the perceived brightness, and $\tau$ is the exponential decay constant (tau).

The model makes the following assumptions:

Cathodic currents (negative amplitudes) will increase perceived brightness
Anodic currents (positive amplitudes) will decrease brightness
Brightness is bounded in $[\theta, \infty]$, where $\theta$ (thresh_percept) is a nonnegative scalar

Parameters:

dt (float, optional) – Sampling time step of the simulation (ms)
tau (float, optional) – Time decay constant for the exponential decay (ms). Larger values lead to slower decay. Brightness should decay to half its peak (“half-life”) after $\ln(2) \tau$ milliseconds.
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.
versionadded: (.) – 0.7.1:

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.

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

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

class pulse2percept.models.Horsager2009Model(**params)[source]¶

[Horsager2009] Standalone model

Implements the temporal response model described in [Horsager2009], which assumes that the temporal activation of retinal tissue is the output of a linear-nonlinear model cascade (see Fig.2 in the paper).

Note

Use this class if you want a standalone model. Use Horsager2009Temporal if you want to combine the temporal model with a spatial 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. Common values at threshold: 0.00225, suprathreshold: 0.00873. Power nonlinearity (exponent of the half-wave rectification). Common values at threshold: 3.43, suprathreshold: 0.83.
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

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.

class pulse2percept.models.Horsager2009Temporal(**params)[source]¶

Temporal model of [Horsager2009]

Implements the temporal response model described in [Horsager2009], which assumes that the temporal activation of retinal tissue is the output of a linear-nonlinear model cascade (see Fig.2 in the paper).

Note

Use this class if you want to combine the temporal model with a spatial model. Use Horsager2009Model if you want a a standalone 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. Common values at threshold: 2.25, suprathreshold: 8.73.
beta (float, optional) – Power nonlinearity (exponent of the half-wave rectification). Common values at threshold: 3.43, suprathreshold: 0.83.
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 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.

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

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

class pulse2percept.models.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.

class pulse2percept.models.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.
retinotopy (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides ret2dva and dva2ret methods. 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 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.

class pulse2percept.models.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
retinotopy (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides ret2dva and dva2ret methods. 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 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]¶: Returns all settable parameters of the Nanduri model

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

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

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

class pulse2percept.models.BiphasicAxonMapModel(**params)[source]¶

BiphasicAxonMapModel of [Granley2021] (standalone model)

An AxonMapModel where phosphene brightness, size, and streak length scale according to amplitude, frequency, and pulse duration

All stimuli must be BiphasicPulseTrains.

This model is different than other spatial models in that it calculates one representative percept from all time steps of the stimulus.

Brightness, size, and streak length scaling are controlled by the parameters bright_model, size_model, and streak model respectively. By default, these are set to classes that implement Eqs 3-6 from Granley 2021. These models can be individually customized by setting the bright_model, size_model, or streak_model to any python callable with signature f(freq, amp, pdur)

Note

Using this model in combination with a temporal model is not currently supported and will give unexpected results

Parameters:

bright_model (callable, optional) – Model used to modulate percept brightness with amplitude, frequency, and pulse duration
size_model (callable, optional) – Model used to modulate percept size with amplitude, frequency, and pulse duration
streak_model (callable, optional) – Model used to modulate percept streak length with amplitude, frequency, and pulse duration
do_thresholding (boolean) – Use probabilistic sigmoid thresholding, default: False
**params (dict, optional) –
Arguments to be passed to AxonMapSpatial

axlambda: double, optional

Exponential decay constant along the axon(microns).

rho: double, optional

Exponential decay constant away from the axon(microns).

eye: {‘RE’, LE’}, optional

Eye for which to generate the axon map.

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)

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

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 x_range=(0, 1) and xystep=0.5.

grid_type : {‘rectangular’, ‘hexagonal’}

Whether to simulate points on a rectangular or hexagonal grid

retinotopy : VisualFieldMap, optional

An instance of a VisualFieldMap object that provides ret2dva and dva2ret methods. 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.

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.

loc_od, loc_od: (x,y), optional

Location of the optic disc in degrees of visual angle. Note that the optic disc in a left eye will be corrected to have a negative x coordinate.

n_axons: int, optional

Number of axons to generate.

axons_range: (min, max), optional

The range of angles(in degrees) at which axons exit the optic disc. This corresponds to the range of $phi_0$ values used in [Jansonius2009].

n_ax_segments: int, optional

Number of segments an axon is made of.

ax_segments_range: (min, max), optional

Lower and upper bounds for the radial position values(polar coords) for each axon.

min_ax_sensitivity: float, optional

Axon segments whose contribution to brightness is smaller than this value will be pruned to improve computational efficiency. Set to a value between 0 and 1.

axon_pickle: str, optional

File name in which to store precomputed axon maps.

ignore_pickle: bool, optional

A flag whether to ignore the pickle file in future calls to model.build().

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 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 Overrides base predict percept to keep desired time axes .. important:

You must call ``build`` before calling ``predict_percept``.

Note: The stimuli should use amplitude as a factor of threshold, NOT raw amplitude in microamps

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.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.ScoreboardModel(**params)[source]¶

Scoreboard model of [Beyeler2019] (standalone model)

Implements the scoreboard model described in [Beyeler2019], where all percepts are Gaussian blobs.

Note

Use this class if you want a standalone model. Use ScoreboardSpatial if you want to combine the spatial model with a temporal model.

Parameters:

rho (double, optional) – Exponential decay constant describing phosphene size (microns).
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) and xystep=0.5.
grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
retinotopy (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides ret2dva and dva2ret methods. 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.
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.
important :: (.) – If you change important model parameters outside the constructor (e.g., by directly setting model.xrange = (-10, 10)), you will have to call model.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 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.

class pulse2percept.models.ScoreboardSpatial(**params)[source]¶

Scoreboard model of [Beyeler2019] (spatial module only)

Implements the scoreboard model described in [Beyeler2019], where all percepts are Gaussian blobs.

Note

Use this class if you want to combine the spatial model with a temporal model. Use ScoreboardModel if you want a a standalone model.

Parameters:

rho (double, optional) – Exponential decay constant describing phosphene size (microns).
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) and xystep=0.5.
grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
retinotopy (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides ret2dva and dva2ret methods. 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.
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.
important :: (.) – If you change important model parameters outside the constructor (e.g., by directly setting model.xrange = (-10, 10)), you will have to call model.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 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]¶: Returns all settable parameters of the scoreboard model

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

See also

Basic Concepts > Computational Models > Building your own model

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.

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

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

class pulse2percept.models.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) and xystep=0.5.
grid_type : {‘rectangular’, ‘hexagonal’}, optional: Whether to simulate points on a rectangular or hexagonal grid
retinotopy : VisualFieldMap, optional: An instance of a VisualFieldMap object that provides ret2dva and dva2ret methods. 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 call model.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 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.

class pulse2percept.models.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) and xystep=0.5.
grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
retinotopy (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides ret2dva and dva2ret methods. 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 call model.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 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]¶: Returns all settable parameters of the model

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

`base`	`BaseModel`, `Model`, `NotBuiltError`, `Percept`, `SpatialModel`, `TemporalModel`
`temporal`	`FadingTemporal`
`thompson2003`	`Thompson2003Model`, `Thompson2003Spatial` [Thompson2003]
`horsager2009`	`Horsager2009Model`, `Horsager2009Temporal` [Horsager2009]
`nanduri2012`	`Nanduri2012Model`, `Nanduri2012Spatial`, `Nanduri2012Temporal` [Nanduri2012]
`beyeler2019`	`AxonMapModel`, `AxonMapSpatial` [Beyeler2019]
`granley2021`	`BiphasicAxonMapModel`