pulse2percept.models

Computational models of prosthetic vision

The root namespace holds only anatomy-neutral model machinery: the abstract base classes a model is assembled from, and temporal models that are not tied to a particular stimulation site. Models of a specific target live in the subpackage for the tissue they stimulate — retina and cortex.

Changed in version 0.11.0: Retinal models are no longer exported here; import them from models.retina.

`base`	`BaseModel`, `Model`, `SpatialModel`, `TemporalModel`
`temporal`	`FadingTemporal`, `AlphaTemporal`
`retina`	Computational models of retinal stimulation
`cortex`	Phosphene models for cortical implants

See also

Basic Concepts > Computational Models

class pulse2percept.models.AlphaTemporal(*, tau=100, dt=0.005, thresh_percept=0, reduce='peak', verbose=True, n_threads=None, n_jobs=None)[source]

Generic alpha-shaped temporal model.

Cathodic current is half-wave rectified into

\[D(t) = \max[-A(t), 0].\]

Two identical first-order stages are then cascaded:

\[\tau \frac{dx}{dt} = D(t) - x(t),\]

\[\tau \frac{dB}{dt} = x(t) - B(t).\]

For a unit-area impulse, the continuous-time impulse response is

\[h(t) = \frac{t}{\tau^2} e^{-t/\tau}, \qquad t \geq 0,\]

which rises from zero, peaks at \(t=\tau\), and then decays. Anodic current does not drive brightness.

The model is evaluated with the explicit-Euler recurrences

\[x_{k+1} = x_k + \frac{\Delta t}{\tau}\left(D_k - x_k\right),\]

\[B_{k+1} = B_k + \frac{\Delta t}{\tau}\left(x_k - B_k\right),\]

with \(\Delta t =\) dt. The implementation requires \(\tau \geq \Delta t\).

This is a generic temporal response model, not a perceptually validated fit.

Parameters:

dt (float or Quantity, optional) – Simulation time step, in milliseconds. Default: 0.005 ms.
tau (float or Quantity, optional) – Time constant of both stages, in milliseconds. Larger values delay and broaden the response. Must be at least dt. Default: 100 ms.
thresh_percept (float, optional) – Brightness values below this threshold are set to zero. Default: 0.
reduce ({'peak', 'last'}, optional) – How automatically chosen output points summarize the preceding interval. 'peak' reports the maximum brightness reached; 'last' reports brightness at the output instant. Explicit t_percept values always request those instants. Default: 'peak'.
verbose (bool, optional) – Whether to print status messages. Default: True.
n_threads (int, optional) – Number of OpenMP threads. Defaults to all available CPU cores.
n_jobs (int or None, optional) – Alias for n_threads. None and -1 use all available CPU cores.
versionadded: (..) – 0.10.0:

get_default_params()[source]: Return default model parameters.

get_param_units()[source]: Return units used to store model parameters.

build(**build_params)[source]

Build the model.

Runs expensive one-time setup after applying any supplied model parameters. predict_percept builds automatically when needed.

Parameters:: **build_params (keyword arguments) – Declared model parameters to set before building.
Return type:: self

Notes

Subclasses should override _build, not this method.

extra_stimulus_units = (): Additional stimulus units accepted by this model

property is_built: A read-only flag indicating whether the model has been built

property n_jobs

both names read and write the same value.

Type:: Number of OpenMP threads to use during parallelization. An alias for n_threads

predict_percept(stim, t_percept=None)[source]

Predict the temporal response.

Parameters:

stim (Stimulus or Percept) – Time-varying input. The temporal model is applied independently at each spatial location.
t_percept (float or array-like, optional) – Output times in time_unit. Unitful times are accepted. If omitted, encoded video frame times are used when available; otherwise output is sampled every 20 ms, with at least one frame for a shorter stimulus.

Returns:

percept – Percept with shape Y x X x T, or None if stim is None.

Return type:

Percept or None

Notes

Explicit t_percept values sample brightness at those instants. Otherwise reduce determines whether each output interval reports its endpoint or peak. Requested times are sorted and must lie on the dt grid.

Changed in version 0.10.0: Automatically selected output times may summarize intervals via reduce.

set_params(**params)[source]: Set the parameters of this object

space_unit = um[source]: The unit spatial coordinates are expressed in

stimulus_unit = uA[source]: The unit stimulus values are expressed in

time_unit = ms[source]: The unit time is expressed in

class pulse2percept.models.BaseModel(**params)[source]

Abstract base class for computational models.

Adds build state to Parametrized. Changing a declared model parameter invalidates the build; prediction rebuilds automatically when needed.

Changed in version 0.11.0: predict_percept builds automatically after construction or a parameter change.

stimulus_unit = uA[source]: The unit stimulus values are expressed in

extra_stimulus_units = (): Additional stimulus units accepted by this model

space_unit = um[source]: The unit spatial coordinates are expressed in

time_unit = ms[source]: The unit time is expressed in

build(**build_params)[source]

Build the model.

Runs expensive one-time setup after applying any supplied model parameters. predict_percept builds automatically when needed.

Parameters:: **build_params (keyword arguments) – Declared model parameters to set before building.
Return type:: self

Notes

Subclasses should override _build, not this method.

property is_built: A read-only flag indicating whether the model has been built

abstractmethod get_default_params()[source]: Return a dict of user-settable parameters

get_param_units()[source]

Return storage units for physical parameters.

Subclasses should extend this mapping. Parameters not listed here take plain dimensionless values.

Added in version 0.10.0.

set_params(**params)[source]: Set the parameters of this object

class pulse2percept.models.FadingTemporal(*, tau=100, dt=0.005, thresh_percept=0, reduce='peak', verbose=True, n_threads=None, n_jobs=None)[source]

Generic temporal model for phosphene fading.

Cathodic current is half-wave rectified into the drive

\[D(t) = \max[-A(t), 0],\]

where \(A(t)\) is stimulus amplitude. Brightness follows a first-order leaky integrator,

\[\tau \frac{dB}{dt} = D(t) - B(t).\]

For constant drive \(D\), the continuous-time response is

\[B(t) = D + [B(0) - D] e^{-t/\tau}.\]

Thus \(\tau\) controls both rise and decay. Larger values produce slower responses and lower peaks for brief pulses. Anodic current does not drive brightness.

The model is evaluated with the explicit-Euler recurrence

\[B_{k+1} = B_k + \frac{\Delta t}{\tau}\left(D_k - B_k\right),\]

with \(\Delta t =\) dt. The implementation requires \(\tau \geq \Delta t\), so the discrete-time pole \(1-\Delta t/\tau\) is nonnegative.

This is a generic temporal response model, not a perceptually validated fit.

Parameters:

dt (float or Quantity, optional) – Simulation time step, in milliseconds. Default: 0.005 ms.
tau (float or Quantity, optional) – Leaky-integrator time constant, in milliseconds. Larger values slow both rise and decay and reduce the peak response to brief pulses. Must be at least dt. Default: 100 ms.
thresh_percept (float, optional) – Brightness values below this threshold are set to zero. Default: 0.
reduce ({'peak', 'last'}, optional) – How automatically chosen output points summarize the preceding interval. 'peak' reports the maximum brightness reached; 'last' reports brightness at the output instant. Explicit t_percept values always request those instants. Default: 'peak'.
verbose (bool, optional) – Whether to print status messages. Default: True.
n_threads (int, optional) – Number of OpenMP threads. Defaults to all available CPU cores.
n_jobs (int or None, optional) – Alias for n_threads. None and -1 use all available CPU cores.
versionchanged: (..) – 0.10.0: The drive is half-wave rectified, so only cathodic current increases brightness.
versionadded: (..) – 0.7.1:

get_default_params()[source]: Return default model parameters.

get_param_units()[source]: Return units used to store model parameters.

build(**build_params)[source]

Build the model.

Runs expensive one-time setup after applying any supplied model parameters. predict_percept builds automatically when needed.

Parameters:: **build_params (keyword arguments) – Declared model parameters to set before building.
Return type:: self

Notes

Subclasses should override _build, not this method.

extra_stimulus_units = (): Additional stimulus units accepted by this model

property is_built: A read-only flag indicating whether the model has been built

property n_jobs

both names read and write the same value.

Type:: Number of OpenMP threads to use during parallelization. An alias for n_threads

predict_percept(stim, t_percept=None)[source]

Predict the temporal response.

Parameters:

stim (Stimulus or Percept) – Time-varying input. The temporal model is applied independently at each spatial location.
t_percept (float or array-like, optional) – Output times in time_unit. Unitful times are accepted. If omitted, encoded video frame times are used when available; otherwise output is sampled every 20 ms, with at least one frame for a shorter stimulus.

Returns:

percept – Percept with shape Y x X x T, or None if stim is None.

Return type:

Percept or None

Notes

Explicit t_percept values sample brightness at those instants. Otherwise reduce determines whether each output interval reports its endpoint or peak. Requested times are sorted and must lie on the dt grid.

Changed in version 0.10.0: Automatically selected output times may summarize intervals via reduce.

set_params(**params)[source]: Set the parameters of this object

space_unit = um[source]: The unit spatial coordinates are expressed in

stimulus_unit = uA[source]: The unit stimulus values are expressed in

time_unit = ms[source]: The unit time is expressed in

class pulse2percept.models.Model(spatial=None, temporal=None)[source]

Composite computational model.

Combines a spatial model with a temporal model. Both are given as already constructed instances, and at least one is required.

model = Model(ScoreboardSpatial(ArgusII()), Nanduri2012Temporal())

Model does not forward component parameters. Access them through model.spatial or model.temporal, as model.spatial.rho and model.temporal.tau.

Parameters:

spatial (SpatialModel, optional) – Spatial model instance, already bound to its implant.
temporal (TemporalModel, optional) – Temporal model instance.
versionadded: (..) – 0.6:
versionchanged: (..) – 0.11.0: Takes component instances only, requires at least one of them, and no longer forwards component parameters.

property stimulus_unit

The unit stimulus values are expressed in

The stimulus goes to the spatial model if there is one, and straight to the temporal model otherwise.

property extra_stimulus_units: Additional stimulus units accepted by the active component

property space_unit

The unit spatial coordinates are expressed in

The temporal model never sees a coordinate.

property time_unit

Time unit used by the final model stage.

t_percept and the returned percept use the temporal model’s unit when present, otherwise the spatial model’s unit.

property implant

The implant the spatial model is bound to.

Returns None for temporal-only models. Assignment forwards to model.spatial.implant and invalidates the spatial build.

Added in version 0.11.0.

build()[source]

Build all model components.

Unlike prediction-time auto-building, this rebuilds every component. To set parameters while building, call the component’s build method, e.g. model.spatial.build(rho=250).

Return type:: self

plot(*args, **kwargs)[source]

Plot the spatial model.

Parameters and return value are those of plot().

predict_percept(source, t_percept=None, gaze=None)[source]

Predict a percept.

Parameters:

source (stimulus source or Scene) – What is presented to the device: anything accepted by prepare_stim(), or a visual scene.
t_percept (float or array-like, optional) – Output times in time_unit. Unitful times are accepted.
gaze ((x, y), (n_frames, 2), or Gaze, optional) – Scene location falling on the fovea, in degrees of visual angle, so that scene = eye-centered visual field + gaze. Requires source to be a scene. A Gaze is resolved against the scene’s frame times, not against t_percept. Gaze decides which part of the scene reaches the electrodes unless the implant’s scene_input_frame is 'head'; the percept itself stays on the model’s eye-centered grid either way.

Returns:

percept (Percept or None) – Perceived brightness on the model’s spatial grid, for a scene as for any other source. A scene’s scotoma describes residual native vision and does not enter the model response; draw the two together with plot() or render().
.. versionchanged:: 0.11.0 – source is now the presented stimulus or scene rather than an implant carrying a stimulus. Scene prediction returns the model percept; vmin and vmax moved to Scene.plot and Scene.render.

property has_space: Returns True if the model has a spatial component

property has_time: Returns True if the model has a temporal component

property is_built: Returns True if the build model has been called

class pulse2percept.models.SpatialModel(implant, **params)[source]

Abstract base class for spatial models.

Spatial models map electrode stimulation to brightness on a sampled visual-field grid. Subclasses implement _predict_spatial and may override _build for precomputation.

Parameters:

implant (Implant) –
Implant whose electrode geometry is modeled.

Added in version 0.11.0.
implant_position ((x, y) or Quantity, optional) –
Position of the device-local origin. A bare pair or length is a tissue position in microns; a dva position is resolved through a single-region visual_field_map. Placement is rigid and distinct from location_noise.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
In-plane rotation (deg), positive counter-clockwise about the device-local origin. Applied before implant_position.

Added in version 0.11.0.
implant_depth (float or Quantity, optional) –
Signed offset (um) along the tissue-plane normal; positive is away from the tissue. Only models that use electrode z respond to it.

Added in version 0.11.0.
note:: (..) – These parameters define a 2D tissue-plane pose. A 3D visual_field_map such as NeuropythyMap accepts only identity model-side placement; construct the implant directly in the map’s 3D frame instead.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle.
step (float, (float, float), or Quantity, optional) –
Grid spacing in degrees of visual angle. A pair specifies separate x and y spacing.

Changed in version 0.10.0: Renamed from xystep; xystep was removed in 0.11.0.
grid_type ({'rect', 'hex'}, optional) – Sampling lattice used for the visual-field grid.
thresh_percept (float, optional) – Brightness values below this threshold are set to zero.
min_current_spread (float, optional) – Fraction of peak Gaussian current spread below which an electrode may be skipped at a grid point. Set to 0 to disable the cutoff.
visual_field_map (VisualFieldMap, optional) – Map between visual-field and tissue coordinates. None until an anatomy-specific subclass such as RetinalSpatial supplies one; building without a map raises.
n_gray (int or None, optional) – Number of gray levels in the returned percept. None disables gray-level quantization.
location_noise (float or None, optional) –
Standard deviation of fixed electrode-specific phosphene offsets, in dva. Requires an invertible 2D visual_field_map. Moving the effective stimulation location may also change phosphene shape or size in location-dependent models. This phenomenological parameter is not empirically calibrated and does not model trial-to-trial or gaze effects.

Added in version 0.11.0.
verbose (bool, optional) – Whether to print status messages.
ndim (list of int, optional) – Dimensionalities of visual_field_map accepted by the model.
n_threads (int, optional) – Number of OpenMP threads.
n_jobs (int or None, optional) – Alias for n_threads. None and -1 use all available CPU cores.

Notes

xrange, yrange and step describe the simulated visual field and are stored in degrees of visual angle. This class is anatomy-neutral: it supplies no default visual_field_map and reads no physical length as a visual-field extent.

Added in version 0.6.

Changed in version 0.11.0: Retinal defaults and the physical-extent shorthand moved to RetinalSpatial.

property n_jobs: n_jobs is an alias for n_threads; see _n_jobs_alias.

property implant

The prosthesis system whose geometry this model uses.

Rebinding invalidates the spatial build.

Added in version 0.11.0.

get_default_params()[source]: Return a dictionary of default values for all model parameters

get_param_units()[source]: Return a dict of the units that parameters are stored in

build(**build_params)[source]

Build the spatial model.

Applies any supplied parameters, validates the implant, visual-field map and implant placement, builds the sampling grid, then runs _build.

Parameters:: **build_params (keyword arguments) – Declared model parameters to set before building.
Return type:: self

predict_percept(source, t_percept=None)[source]

Predict the spatial response.

Parameters:

source (stimulus source) – Anything accepted by prepare_stim().
t_percept (float or array-like, optional) – Output times in time_unit. If omitted, use the source time points. Unitful times are accepted.

Returns:

percept – Percept with shape Y x X x T, or None for an empty source.

Return type:

Percept or None

Notes

For an encoded image or video, a spatial-only model uses frame-level modulation rather than the delivered pulse train. In a composite Model with a temporal stage, the spatial stage receives the delivered train so the temporal model can integrate it.

Changed in version 0.11.0: Takes the stimulus source rather than an implant carrying a stimulus.

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

Plot the model

Parameters:

use_dva (bool, optional) – Uses degrees of visual angle (dva) if True, else tissue 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
show_implant (bool, optional) –
Draw the implant at its model-side placement. Requires use_dva=False.

Added in version 0.11.0.

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

extra_stimulus_units = (): Additional stimulus units accepted by this model

property is_built: A read-only flag indicating whether the model has been built

set_params(**params)[source]: Set the parameters of this object

space_unit = um[source]: The unit spatial coordinates are expressed in

stimulus_unit = uA[source]: The unit stimulus values are expressed in

time_unit = ms[source]: The unit time is expressed in

class pulse2percept.models.TemporalModel(**params)[source]

Abstract base class for temporal models.

Temporal models map a time-varying stimulus or percept to brightness over time. Subclasses implement _predict_temporal and may override _build for precomputation.

Parameters:

dt (float or Quantity, optional) – Simulation time step. Plain values are interpreted as milliseconds.
thresh_percept (float, optional) – Brightness values below this threshold are set to zero.
reduce ({'last', 'peak'}, optional) – How automatically selected output intervals are summarized. 'last' reports brightness at the interval endpoint; 'peak' reports the maximum brightness reached in the interval. Explicit t_percept values always request those exact instants.
verbose (bool, optional) – Whether to print status messages.
n_threads (int, optional) – Number of OpenMP threads.
n_jobs (int or None, optional) – Alias for n_threads. None and -1 use all available CPU cores.

Notes

Models with _reduces_intervals = True compute 'peak' within the integrator. Other temporal models approximate it by subsampling each output interval.

Added in version 0.6.

Changed in version 0.10.0: Added reduce.

property n_jobs: n_jobs is an alias for n_threads; see _n_jobs_alias.

get_default_params()[source]: Return default model parameters.

get_param_units()[source]: Return a dict of the units that parameters are stored in

predict_percept(stim, t_percept=None)[source]

Predict the temporal response.

Parameters:

stim (Stimulus or Percept) – Time-varying input. The temporal model is applied independently at each spatial location.
t_percept (float or array-like, optional) – Output times in time_unit. Unitful times are accepted. If omitted, encoded video frame times are used when available; otherwise output is sampled every 20 ms, with at least one frame for a shorter stimulus.

Returns:

percept – Percept with shape Y x X x T, or None if stim is None.

Return type:

Percept or None

Notes

Explicit t_percept values sample brightness at those instants. Otherwise reduce determines whether each output interval reports its endpoint or peak. Requested times are sorted and must lie on the dt grid.

Changed in version 0.10.0: Automatically selected output times may summarize intervals via reduce.

build(**build_params)[source]

Build the model.

Runs expensive one-time setup after applying any supplied model parameters. predict_percept builds automatically when needed.

Parameters:: **build_params (keyword arguments) – Declared model parameters to set before building.
Return type:: self

Notes

Subclasses should override _build, not this method.

extra_stimulus_units = (): Additional stimulus units accepted by this model

property is_built: A read-only flag indicating whether the model has been built

set_params(**params)[source]: Set the parameters of this object

space_unit = um[source]: The unit spatial coordinates are expressed in

stimulus_unit = uA[source]: The unit stimulus values are expressed in

time_unit = ms[source]: The unit time is expressed in