pulse2percept.models¶
Computational models of the retina, such as phosphene and neural response 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)
andxystep=0.5
.  grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
 retinotopy (
VisualFieldMap
, optional) – An instance of aVisualFieldMap
object that providesret2dva
anddva2ret
methods. By default,Watson2014Map
is used.  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 callmodel.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 onetime calculations, such as building the spatial grid used to predict a percept.
Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)
Returns: self

find_threshold
(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. implant (

has_space
¶ Returns True if the model has a spatial component

has_time
¶ Returns True if the model has a temporal component

is_built
¶ Returns True if the
build
model has been called

predict_percept
(implant, t_percept=None)[source]¶ Predict a percept
Important
You must call
build
before callingpredict_percept
.Parameters:  implant (
ProsthesisSystem
) – A valid prosthesis system. A stimulus can be passed viastim
.  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None. implant (

set_params
(params)[source]¶ Set model parameters
This is a convenience function to set parameters that might be part of the spatial model, the temporal model, or both.
Alternatively, you can set the parameter directly, e.g.
model.spatial.verbose = True
.Note
If a parameter exists in both spatial and temporal models(e.g.,
verbose
), both models will be updated.Parameters: params (dict) – A dictionary of parameters to set.

class
pulse2percept.models.
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)
andxystep=0.5
.  grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
 retinotopy (
VisualFieldMap
, optional) – An instance of aVisualFieldMap
object that providesret2dva
anddva2ret
methods. By default,Watson2014Map
is used.  n_gray (int, optional) – The number of gray levels to use. If an integer is given, kmeans
clustering is used to compress the color space of the percept into
n_gray
bins. If None, no compression is performed.  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 callmodel.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 onetime calculations, such as building the spatial grid used to predict a percept. You must call
build
before callingpredict_percept
.Important
Don’t override this method if you are building your own model. Customize
_build
instead.Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)

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 onself.grid`
. The function will then assume that the ith bundle passes through the ith point on the grid. This is used to determine the bundle segment that is closest to the ith 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 ith 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 inbundles
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 ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. implant (

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 generatesn_bundles
axon bundles whosephi0
values are linearly sampled fromself.axons_range
(polar coords). Each axon will consist ofself.n_ax_segments
segments that spanself.ax_segments_range
distance from the optic nerve head (polar coords).Parameters: 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 highresolution 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 viastim
.  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None. implant (

class
pulse2percept.models.
BaseModel
(**params)[source]¶ Abstract base class for all models
Provides the following functionality:
 Prettyprint class attributes (via
_pprint_params
andPrettyPrint
)  Build a model (via
build
) and flip theis_built
switch  Usersettable parameters must be listed in
get_default_params
 New class attributes can only be added in the constructor
(enforced via
Frozen
andFreezeError
).

build
(**build_params)[source]¶ Build the model
Every model must have a
`build
method, which is meant to perform all expensive onetime calculations. You must callbuild
before callingpredict_percept
.Important
Don’t override this method if you are building your own model. Customize
_build
instead.Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)

is_built
¶ A flag indicating whether the model has been built
 Prettyprint class attributes (via

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 (“halflife”) 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 onetime calculations. You must callbuild
before callingpredict_percept
.Important
Don’t override this method if you are building your own model. Customize
_build
instead.Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)

find_threshold
(stim, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  stim (
Stimulus
) – The stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. stim (

is_built
¶ A flag indicating whether the model has been built

predict_percept
(stim, t_percept=None)[source]¶ Predict the temporal response
Important
Don’t override this method if you are creating your own model. Customize
_predict_temporal
instead.Parameters:  stim (: py: class:
~pulse2percept.stimuli.Stimulus
or) – : py: class:~pulse2percept.models.Percept
Either a Stimulus or a Percept object. The temporal model will be applied to each spatial location in the stimulus/percept.  t_percept (float or list of floats, optional) –
The time points at which to output a percept (ms). If None, the percept will be output once very 20 ms (50 Hz frame rate).
Note
If your stimulus is shorter than 20 ms, you should specify the desired time points manually.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifstim
is None.Notes
 If a list of time points is provided for
t_percept
, the values will automatically be sorted.
 stim (: py: class:

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 linearnonlinear 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 halfwave 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 onetime calculations, such as building the spatial grid used to predict a percept.
Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)
Returns: self

find_threshold
(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. implant (

has_space
¶ Returns True if the model has a spatial component

has_time
¶ Returns True if the model has a temporal component

is_built
¶ Returns True if the
build
model has been called

predict_percept
(implant, t_percept=None)[source]¶ Predict a percept
Important
You must call
build
before callingpredict_percept
.Parameters:  implant (
ProsthesisSystem
) – A valid prosthesis system. A stimulus can be passed viastim
.  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None. implant (

set_params
(params)[source]¶ Set model parameters
This is a convenience function to set parameters that might be part of the spatial model, the temporal model, or both.
Alternatively, you can set the parameter directly, e.g.
model.spatial.verbose = True
.Note
If a parameter exists in both spatial and temporal models(e.g.,
verbose
), both models will be updated.Parameters: params (dict) – A dictionary of parameters to set.

class
pulse2percept.models.
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 linearnonlinear 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 halfwave 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 onetime calculations. You must callbuild
before callingpredict_percept
.Important
Don’t override this method if you are building your own model. Customize
_build
instead.Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)

find_threshold
(stim, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  stim (
Stimulus
) – The stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. stim (

is_built
¶ A flag indicating whether the model has been built

predict_percept
(stim, t_percept=None)[source]¶ Predict the temporal response
Important
Don’t override this method if you are creating your own model. Customize
_predict_temporal
instead.Parameters:  stim (: py: class:
~pulse2percept.stimuli.Stimulus
or) – : py: class:~pulse2percept.models.Percept
Either a Stimulus or a Percept object. The temporal model will be applied to each spatial location in the stimulus/percept.  t_percept (float or list of floats, optional) –
The time points at which to output a percept (ms). If None, the percept will be output once very 20 ms (50 Hz frame rate).
Note
If your stimulus is shorter than 20 ms, you should specify the desired time points manually.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifstim
is None.Notes
 If a list of time points is provided for
t_percept
, the values will automatically be sorted.
 stim (: py: class:

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())
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 onetime calculations, such as building the spatial grid used to predict a percept.
Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)
Returns: self

find_threshold
(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. implant (

has_space
¶ Returns True if the model has a spatial component

has_time
¶ Returns True if the model has a temporal component

is_built
¶ Returns True if the
build
model has been called

predict_percept
(implant, t_percept=None)[source]¶ Predict a percept
Important
You must call
build
before callingpredict_percept
.Parameters:  implant (
ProsthesisSystem
) – A valid prosthesis system. A stimulus can be passed viastim
.  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None. implant (

set_params
(params)[source]¶ Set model parameters
This is a convenience function to set parameters that might be part of the spatial model, the temporal model, or both.
Alternatively, you can set the parameter directly, e.g.
model.spatial.verbose = True
.Note
If a parameter exists in both spatial and temporal models(e.g.,
verbose
), both models will be updated.Parameters: params (dict) – A dictionary of parameters to set.
 spatial (

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 linearnonlinear 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 aVisualFieldMap
object that providesret2dva
anddva2ret
methods. By default,Curcio1990Map
is used.  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 onetime calculations, such as building the spatial grid used to predict a percept.
Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)
Returns: self

find_threshold
(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. implant (

has_space
¶ Returns True if the model has a spatial component

has_time
¶ Returns True if the model has a temporal component

is_built
¶ Returns True if the
build
model has been called

predict_percept
(implant, t_percept=None)[source]¶ Predict a percept
Important
You must call
build
before callingpredict_percept
.Parameters:  implant (
ProsthesisSystem
) – A valid prosthesis system. A stimulus can be passed viastim
.  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None. implant (

set_params
(params)[source]¶ Set model parameters
This is a convenience function to set parameters that might be part of the spatial model, the temporal model, or both.
Alternatively, you can set the parameter directly, e.g.
model.spatial.verbose = True
.Note
If a parameter exists in both spatial and temporal models(e.g.,
verbose
), both models will be updated.Parameters: params (dict) – A dictionary of parameters to set.

class
pulse2percept.models.
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! + (ra)^\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 aVisualFieldMap
object that providesret2dva
anddva2ret
methods. By default,Curcio1990Map
is used.  n_gray (int, optional) – The number of gray levels to use. If an integer is given, kmeans
clustering is used to compress the color space of the percept into
n_gray
bins. If None, no compression is performed.  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 onetime calculations, such as building the spatial grid used to predict a percept. You must call
build
before callingpredict_percept
.Important
Don’t override this method if you are building your own model. Customize
_build
instead.Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)

find_threshold
(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. implant (

is_built
¶ A flag indicating whether the model has been built

plot
(use_dva=False, style='hull', autoscale=True, ax=None, figsize=None)[source]¶ Plot the model
Parameters:  use_dva (bool, optional) – Uses degrees of visual angle (dva) if True, else retinal coordinates (microns)
 style ({'hull', 'scatter', 'cell'}, optional) –
Grid plotting style:
 ’hull’: Show the convex hull of the grid (that is, the outline of the smallest convex set that contains all grid points).
 ’scatter’: Scatter plot all grid points
 ’cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a highresolution grid.
 autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
 ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
 figsize ((float, float), optional) – Desired (width, height) of the figure in inches
Returns: ax (
matplotlib.axes.Axes
) – Returns the axis object of the plot

predict_percept
(implant, t_percept=None)[source]¶ Predict the spatial response
Important
Don’t override this method if you are creating your own model. Customize
_predict_spatial
instead.Parameters:  implant (
ProsthesisSystem
) – A valid prosthesis system. A stimulus can be passed viastim
.  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None. implant (

class
pulse2percept.models.
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 linearnonlinear 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 onetime calculations. You must callbuild
before callingpredict_percept
.Important
Don’t override this method if you are building your own model. Customize
_build
instead.Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)

find_threshold
(stim, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  stim (
Stimulus
) – The stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. stim (

is_built
¶ A flag indicating whether the model has been built

predict_percept
(stim, t_percept=None)[source]¶ Predict the temporal response
Important
Don’t override this method if you are creating your own model. Customize
_predict_temporal
instead.Parameters:  stim (: py: class:
~pulse2percept.stimuli.Stimulus
or) – : py: class:~pulse2percept.models.Percept
Either a Stimulus or a Percept object. The temporal model will be applied to each spatial location in the stimulus/percept.  t_percept (float or list of floats, optional) –
The time points at which to output a percept (ms). If None, the percept will be output once very 20 ms (50 Hz frame rate).
Note
If your stimulus is shorter than 20 ms, you should specify the desired time points manually.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifstim
is None.Notes
 If a list of time points is provided for
t_percept
, the values will automatically be sorted.
 stim (: py: class:

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 36 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
 n_gray : int, optional
 The number of gray levels to use. If an integer is given, kmeans
clustering is used to compress the color space of the percept into
n_gray
bins. If None, no compression is performed.  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)
andxystep=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 providesret2dva
anddva2ret
methods. By default,Watson2014Map
is used.  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 onetime calculations, such as building the spatial grid used to predict a percept.
Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)
Returns: self

find_threshold
(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. implant (

has_space
¶ Returns True if the model has a spatial component

has_time
¶ Returns True if the model has a temporal component

is_built
¶ Returns True if the
build
model has been called

predict_percept
(implant, t_percept=None)[source]¶ Predict a percept 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 viastim
.  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None. implant (

set_params
(params)[source]¶ Set model parameters
This is a convenience function to set parameters that might be part of the spatial model, the temporal model, or both.
Alternatively, you can set the parameter directly, e.g.
model.spatial.verbose = True
.Note
If a parameter exists in both spatial and temporal models(e.g.,
verbose
), both models will be updated.Parameters: params (dict) – A dictionary of parameters to set.

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)
andxystep=0.5
.  grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
 retinotopy (
VisualFieldMap
, optional) – An instance of aVisualFieldMap
object that providesret2dva
anddva2ret
methods. By default,Watson2014Map
is used.  n_gray (int, optional) – The number of gray levels to use. If an integer is given, kmeans
clustering is used to compress the color space of the percept into
n_gray
bins. If None, no compression is performed.  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 callmodel.build()
again for your changes to take effect.
build
(**build_params)[source]¶ Build the model
Performs expensive onetime calculations, such as building the spatial grid used to predict a percept.
Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)
Returns: self

find_threshold
(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. implant (

has_space
¶ Returns True if the model has a spatial component

has_time
¶ Returns True if the model has a temporal component

is_built
¶ Returns True if the
build
model has been called

predict_percept
(implant, t_percept=None)[source]¶ Predict a percept
Important
You must call
build
before callingpredict_percept
.Parameters:  implant (
ProsthesisSystem
) – A valid prosthesis system. A stimulus can be passed viastim
.  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None. implant (

set_params
(params)[source]¶ Set model parameters
This is a convenience function to set parameters that might be part of the spatial model, the temporal model, or both.
Alternatively, you can set the parameter directly, e.g.
model.spatial.verbose = True
.Note
If a parameter exists in both spatial and temporal models(e.g.,
verbose
), both models will be updated.Parameters: params (dict) – A dictionary of parameters to set.

class
pulse2percept.models.
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)
andxystep=0.5
.  grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
 retinotopy (
VisualFieldMap
, optional) – An instance of aVisualFieldMap
object that providesret2dva
anddva2ret
methods. By default,Watson2014Map
is used.  n_gray (int, optional) – The number of gray levels to use. If an integer is given, kmeans
clustering is used to compress the color space of the percept into
n_gray
bins. If None, no compression is performed.  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 callmodel.build()
again for your changes to take effect.
build
(**build_params)[source]¶ Build the model
Performs expensive onetime calculations, such as building the spatial grid used to predict a percept. You must call
build
before callingpredict_percept
.Important
Don’t override this method if you are building your own model. Customize
_build
instead.Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)

find_threshold
(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. implant (

is_built
¶ A flag indicating whether the model has been built

plot
(use_dva=False, style='hull', autoscale=True, ax=None, figsize=None)[source]¶ Plot the model
Parameters:  use_dva (bool, optional) – Uses degrees of visual angle (dva) if True, else retinal coordinates (microns)
 style ({'hull', 'scatter', 'cell'}, optional) –
Grid plotting style:
 ’hull’: Show the convex hull of the grid (that is, the outline of the smallest convex set that contains all grid points).
 ’scatter’: Scatter plot all grid points
 ’cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a highresolution grid.
 autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
 ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
 figsize ((float, float), optional) – Desired (width, height) of the figure in inches
Returns: ax (
matplotlib.axes.Axes
) – Returns the axis object of the plot

predict_percept
(implant, t_percept=None)[source]¶ Predict the spatial response
Important
Don’t override this method if you are creating your own model. Customize
_predict_spatial
instead.Parameters:  implant (
ProsthesisSystem
) – A valid prosthesis system. A stimulus can be passed viastim
.  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None. implant (

class
pulse2percept.models.
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 onetime calculations.predict_percept
: predicts the percepts based on an implant/stimulus. Don’t customize this method  implement your own_predict_spatial
instead (see below). A user must callbuild
before callingpredict_percept
.
To create your own spatial model, you must subclass
SpatialModel
and provide an implementation for:_predict_spatial
: This method should accept an ElectrodeArray as well as a Stimulus, and compute the brightness at all spatial coordinates ofself.grid
, returned as a 2D NumPy array (space x time).Note
The
_
in the method name indicates that this is a private method, meaning that it should not be called by the user. Instead, the user should callpredict_percept
, which in turn will call_predict_spatial
. The same logic applies tobuild
(called by the user; don’t touch) and_build
(called bybuild
; customize this instead).
In addition, you can customize the following:
__init__
: the constructor can be used to define additional parameters (note that you cannot add parameters onthefly)get_default_params
: all settable model parameters must be listed by this method_build
(optional): a way to add onetime computations to the build process
New in version 0.6.
Note
You will not be able to add more parameters outside the constructor; e.g.,
model.newparam = 1
will lead to aFreezeError
.
build
(**build_params)[source]¶ Build the model
Performs expensive onetime calculations, such as building the spatial grid used to predict a percept. You must call
build
before callingpredict_percept
.Important
Don’t override this method if you are building your own model. Customize
_build
instead.Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)

find_threshold
(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  implant (
ProsthesisSystem
) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. implant (

is_built
¶ A flag indicating whether the model has been built

plot
(use_dva=False, style='hull', autoscale=True, ax=None, figsize=None)[source]¶ Plot the model
Parameters:  use_dva (bool, optional) – Uses degrees of visual angle (dva) if True, else retinal coordinates (microns)
 style ({'hull', 'scatter', 'cell'}, optional) –
Grid plotting style:
 ’hull’: Show the convex hull of the grid (that is, the outline of the smallest convex set that contains all grid points).
 ’scatter’: Scatter plot all grid points
 ’cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a highresolution grid.
 autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
 ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
 figsize ((float, float), optional) – Desired (width, height) of the figure in inches
Returns: ax (
matplotlib.axes.Axes
) – Returns the axis object of the plot

predict_percept
(implant, t_percept=None)[source]¶ Predict the spatial response
Important
Don’t override this method if you are creating your own model. Customize
_predict_spatial
instead.Parameters:  implant (
ProsthesisSystem
) – A valid prosthesis system. A stimulus can be passed viastim
.  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifimplant.stim
is None. implant (

class
pulse2percept.models.
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 onetime calculations.predict_percept
: predicts the percepts based on an implant/stimulus. You can add your own_predict_temporal
method to customize this step. A user must callbuild
before callingpredict_percept
.
To create your own temporal model, you must subclass
SpatialModel
and provide an implementation for:_predict_temporal
: a method that accepts either aStimulus
or aPercept
object and a list of time points at which to calculate the resulting percept, returned as a 2D NumPy array (space x time).
In addition, you can customize the following:
__init__
: the constructor can be used to define additional parameters (note that you cannot add parameters onthefly)get_default_params
: all settable model parameters must be listed by this method_build
(optional): a way to add onetime computations to the build process
New in version 0.6.
Note
You will not be able to add more parameters outside the constructor; e.g.,
model.newparam = 1
will lead to aFreezeError
.
build
(**build_params)[source]¶ Build the model
Every model must have a
`build
method, which is meant to perform all expensive onetime calculations. You must callbuild
before callingpredict_percept
.Important
Don’t override this method if you are building your own model. Customize
_build
instead.Parameters: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params
. Trying to add new class attributes outside of that will cause aFreezeError
. Example:model.build(param1=val)

find_threshold
(stim, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]¶ Find the threshold current for a certain stimulus
Estimates
amp_th
such that the output ofmodel.predict_percept(stim(amp_th))
is approximatelybright_th
.Parameters:  stim (
Stimulus
) – The stimulus to use. Stimulus amplitude will be up and down regulated untilamp_th
is found.  bright_th (float) – Model output (brightness) that’s considered “at threshold”.
 amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search (uA).
 amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within
amp_tol
 bright_tol (float, optional) – Search will stop if model brightness is within
bright_tol
ofbright_th
 max_iter (int, optional) – Search will stop after
max_iter
iterations  t_percept (float or list of floats, optional) – The time points at which to output a percept (ms).
If None,
implant.stim.time
is used.
Returns: amp_th (float) – Threshold current (uA), estimated so that the output of
model.predict_percept(stim(amp_th))
is withinbright_tol
ofbright_th
. stim (

is_built
¶ A flag indicating whether the model has been built

predict_percept
(stim, t_percept=None)[source]¶ Predict the temporal response
Important
Don’t override this method if you are creating your own model. Customize
_predict_temporal
instead.Parameters:  stim (: py: class:
~pulse2percept.stimuli.Stimulus
or) – : py: class:~pulse2percept.models.Percept
Either a Stimulus or a Percept object. The temporal model will be applied to each spatial location in the stimulus/percept.  t_percept (float or list of floats, optional) –
The time points at which to output a percept (ms). If None, the percept will be output once very 20 ms (50 Hz frame rate).
Note
If your stimulus is shorter than 20 ms, you should specify the desired time points manually.
Returns: percept (
Percept
) – A Percept object whosedata
container has dimensions Y x X x T. Will return None ifstim
is None.Notes
 If a list of time points is provided for
t_percept
, the values will automatically be sorted.
 stim (: py: class: