pulse2percept.models

Computational models of the prosthetic vision, such as phosphene and neural response models. Cortical models are in the cortex submodule.

`cortex`	Phosphene models for cortical implants
`base`	`BaseModel`, `Model`, `SpatialModel`, `TemporalModel`
`temporal`	`FadingTemporal`, `AlphaTemporal`
`thompson2003`	`Thompson2003Model`, `Thompson2003Spatial` [Thompson2003]
`horsager2009`	`Horsager2009Model`, `Horsager2009Temporal` [Horsager2009]
`nanduri2012`	`Nanduri2012Model`, `Nanduri2012Spatial`, `Nanduri2012Temporal` [Nanduri2012]
`beyeler2019`	`AxonMapModel`, `AxonMapSpatial` [Beyeler2019]
`granley2021`	`BiphasicAxonMapModel`, `BiphasicAxonMapSpatial` [Granley2021]

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.AxonMapModel(implant, *, rho=300, lam=500, xrange=(-15, 15), yrange=(-15, 15), step=0.25, grid_type='rect', thresh_percept=0, min_current_spread=1e-08, visual_field_map=None, n_gray=None, implant_position=(0, 0), implant_rotation=0, implant_depth=0, location_noise=None, loc_od=(15.5, 1.5), n_axons=1000, axons_range=(-180, 180), n_ax_segments=500, ax_segments_range=(0, 50), min_ax_sensitivity=0.001, meridian_blend=1, axon_pickle='axons.pickle', ignore_pickle=False, verbose=True, ndim=None, n_threads=None, n_jobs=None)[source]

Axon map model of [Beyeler2019].

Models percepts as activation spread along retinal nerve fiber bundle trajectories. Use AxonMapSpatial to combine this spatial model with a temporal model.

The spatial response extends the scoreboard model by allowing activation to spread along retinal nerve fiber bundles [Beyeler2019]. For an axon segment, the contribution of electrode \(e\) is proportional to

\[a_e \exp\left( -\frac{d_e^2}{2\rho^2} -\frac{d_{\mathrm{soma}}^2}{2\lambda^2} \right),\]

where \(d_e\) is the distance from the segment to electrode \(e\), and \(d_{\mathrm{soma}}\) is the path length along the axon from that segment to the ganglion cell body. Thus \(\rho\) controls spread away from the axon, whereas \(\lambda\) controls spread along it.

Important

rho and lam vary substantially across patients [Beyeler2019]. The defaults are representative values, not patient-specific estimates.

Parameters:

implant (Implant) –
Implant whose electrode geometry and eye are modeled.

Added in version 0.11.0.
rho (float or Quantity, optional) –
Gaussian spatial decay constant in microns. Larger values produce broader phosphenes. The same rho value applies to all electrodes.

Important

Electrode-retina distance (z) does not directly affect rho.
lam (float or Quantity, optional) –
Gaussian decay constant along the axon between stimulation site and soma, in microns. Larger values lengthen the percept.

Changed in version 0.10.0: Renamed from axlambda; axlambda was removed in 0.11.0.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle. May also be passed as retinal extent using physical units such as um. The correspondence is resolved through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle. May also be passed as retinal extent using physical units such as um. The correspondence is resolved through visual_field_map.
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 an axon segment. Set to 0 to disable the cutoff.
visual_field_map (VisualFieldMap, optional) – Retinotopic map between visual-field and retinal coordinates. Defaults to Watson2014Map.
n_gray (int or None, optional) – Number of gray levels in the returned percept. None disables gray-level quantization.
implant_position ((x, y) or Quantity, optional) –
Position of the device-local origin, in tissue coordinates or dva.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
In-plane rotation (deg), positive counter-clockwise.

Added in version 0.11.0.
implant_depth (float or Quantity, optional) –
Signed offset (um) along the normal of a 2D tissue map.

Added in version 0.11.0.
location_noise (float or None, optional) –
Standard deviation of fixed electrode-specific phosphene offsets, in dva. Requires an invertible 2D visual_field_map. None or 0 disables it. Location-dependent models may also change phosphene shape or size.

Added in version 0.11.0.
loc_od ((float, float) or Quantity, optional) – Optic-disc location in degrees of visual angle. Its horizontal sign is set from the bound implant’s eye.
n_axons (int, optional) – Number of nerve fiber bundles generated.
axons_range ((float, float) or Quantity, optional) – Range of initial bundle angles phi0 in the Jansonius model.
n_ax_segments (int, optional) – Number of radial samples used to generate each bundle.
ax_segments_range ((float, float), optional) – Radial-coordinate range used to generate each bundle in the Jansonius model.
min_ax_sensitivity (float, optional) – Minimum relative axon sensitivity retained during precomputation.
meridian_blend (float or Quantity, optional) –
Gaussian standard deviation for blending across the horizontal meridian, in degrees of visual angle. Set to 0 to disable.

Added in version 0.10.0.
axon_pickle (str, optional) – File used to cache generated axon bundles.
ignore_pickle (bool, optional) – If True, regenerate axon bundles instead of loading axon_pickle.
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

ax_segments_range values above 90 are outside the range for which this axon-map construction is considered reliable.

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

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

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

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

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

Plot the spatial model.

Parameters and return value are those of plot().

predict_percept(source, t_percept=None, gaze=None, vmax=None, vmin=0)[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) or (n_frames, 2), 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. Gaze always moves the percept across the scene; it moves the scene across the electrodes too unless the implant’s scene_input_frame is 'head'.
vmax (float, optional) – Percept brightness mapped to white when composing a scene with a scotoma. Required for scotoma composition.
vmin (float, optional) – Percept brightness mapped to black for scotoma composition.

Returns:

percept (Percept or None) – Brightness percept for ordinary prediction. For a scene with a scotoma, returns an RGB percept on the scene pixel grid.
.. versionchanged:: 0.11.0 – source is now the presented stimulus or scene rather than an implant carrying a stimulus.

property space_unit

The unit spatial coordinates are expressed in

The temporal model never sees a coordinate.

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

class pulse2percept.models.AxonMapSpatial(implant, *, rho=300, lam=500, xrange=(-15, 15), yrange=(-15, 15), step=0.25, grid_type='rect', thresh_percept=0, min_current_spread=1e-08, visual_field_map=None, n_gray=None, implant_position=(0, 0), implant_rotation=0, implant_depth=0, location_noise=None, loc_od=(15.5, 1.5), n_axons=1000, axons_range=(-180, 180), n_ax_segments=500, ax_segments_range=(0, 50), min_ax_sensitivity=0.001, meridian_blend=1, axon_pickle='axons.pickle', ignore_pickle=False, verbose=True, ndim=None, n_threads=None, n_jobs=None)[source]

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

Models percepts as activation spread along retinal nerve fiber bundle trajectories. Use AxonMapModel for a standalone model.

The spatial response extends the scoreboard model by allowing activation to spread along retinal nerve fiber bundles [Beyeler2019]. For an axon segment, the contribution of electrode \(e\) is proportional to

\[a_e \exp\left( -\frac{d_e^2}{2\rho^2} -\frac{d_{\mathrm{soma}}^2}{2\lambda^2} \right),\]

where \(d_e\) is the distance from the segment to electrode \(e\), and \(d_{\mathrm{soma}}\) is the path length along the axon from that segment to the ganglion cell body. Thus \(\rho\) controls spread away from the axon, whereas \(\lambda\) controls spread along it.

Important

rho and lam vary substantially across patients [Beyeler2019]. The defaults are representative values, not patient-specific estimates.

Parameters:

implant (Implant) –
Implant whose electrode geometry and eye are modeled.

Added in version 0.11.0.
rho (float or Quantity, optional) –
Gaussian spatial decay constant in microns. Larger values produce broader phosphenes. The same rho value applies to all electrodes.

Important

Electrode-retina distance (z) does not directly affect rho.
lam (float or Quantity, optional) –
Gaussian decay constant along the axon between stimulation site and soma, in microns. Larger values lengthen the percept.

Changed in version 0.10.0: Renamed from axlambda; axlambda was removed in 0.11.0.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle. May also be passed as retinal extent using physical units such as um. The correspondence is resolved through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle. May also be passed as retinal extent using physical units such as um. The correspondence is resolved through visual_field_map.
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 an axon segment. Set to 0 to disable the cutoff.
visual_field_map (VisualFieldMap, optional) – Retinotopic map between visual-field and retinal coordinates. Defaults to Watson2014Map.
n_gray (int or None, optional) – Number of gray levels in the returned percept. None disables gray-level quantization.
implant_position ((x, y) or Quantity, optional) –
Position of the device-local origin, in tissue coordinates or dva.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
In-plane rotation (deg), positive counter-clockwise.

Added in version 0.11.0.
implant_depth (float or Quantity, optional) –
Signed offset (um) along the normal of a 2D tissue map.

Added in version 0.11.0.
location_noise (float or None, optional) –
Standard deviation of fixed electrode-specific phosphene offsets, in dva. Requires an invertible 2D visual_field_map. None or 0 disables it. Location-dependent models may also change phosphene shape or size.

Added in version 0.11.0.
loc_od ((float, float) or Quantity, optional) – Optic-disc location in degrees of visual angle. Its horizontal sign is set from the bound implant’s eye.
n_axons (int, optional) – Number of nerve fiber bundles generated.
axons_range ((float, float) or Quantity, optional) – Range of initial bundle angles phi0 in the Jansonius model.
n_ax_segments (int, optional) – Number of radial samples used to generate each bundle.
ax_segments_range ((float, float), optional) – Radial-coordinate range used to generate each bundle in the Jansonius model.
min_ax_sensitivity (float, optional) – Minimum relative axon sensitivity retained during precomputation.
meridian_blend (float or Quantity, optional) –
Gaussian standard deviation for blending across the horizontal meridian, in degrees of visual angle. Set to 0 to disable.

Added in version 0.10.0.
axon_pickle (str, optional) – File used to cache generated axon bundles.
ignore_pickle (bool, optional) – If True, regenerate axon bundles instead of loading axon_pickle.
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

ax_segments_range values above 90 are outside the range for which this axon-map construction is considered reliable.

property eye

Eye used by the axon map.

Taken from the bound implant.

Changed in version 0.11.0: eye is no longer a separate model parameter.

property is_built: Return whether the axon map matches the implant’s current eye.

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

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

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

Generate nerve fiber bundles from the Jansonius model.

Parameters:

n_bundles (int, optional) – Number of bundles. Defaults to n_axons.
prune (bool, optional) – If True, discard bundles and segments outside the simulated visual field.

Returns:

bundles – Bundle coordinates on the retina in microns.

Return type:

list of (N, 2) ndarrays

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

Find the nearest nerve fiber bundle for one or more retinal points.

Parameters:

bundles (list of (N, 2) ndarrays) – Bundle coordinates in microns.
xret (array_like, optional) – Retinal coordinates in microns. Defaults to the model grid.
yret (array_like, optional) – Retinal coordinates in microns. Defaults to the model grid.
return_index (bool, optional) – Also return the index of the nearest bundle.
return_segment (bool, optional) – Also return the index of the nearest segment within that bundle.

Returns:

axon (ndarray or list of ndarrays) – Nearest bundle for each query point.
idx_axon (int or ndarray, optional) – Returned when return_index is True.
idx_segment (int or ndarray, optional) – Returned when return_segment is True.

calc_axon_sensitivity(bundles)[source]

Calculate sensitivity along the axon associated with each grid point.

bundles[i] is assumed to pass through grid point i. Segments beyond the soma are removed, and sensitivity decays with distance from the soma according to lam.

Parameters:: bundles (list of (N, 2) ndarrays) – One retinal bundle per grid point, in microns.
Returns:: axon_contrib – Retinal x, y, and relative sensitivity for each retained segment.
Return type:: list of (N, 3) ndarrays

calc_bundle_tangent(xc, yc)[source]

Calculate the local nerve fiber bundle orientation.

Parameters:

xc (float) – Retinal coordinates in microns.
yc (float) – Retinal coordinates in microns.

Returns:

tangent – Bundle orientation in radians, restricted to [-pi/2, pi/2].

Return type:

float

calc_bundle_tangent_fast(xc, yc, bundles=None)[source]

Calculate local bundle orientation for multiple retinal points.

Reuses a KD-tree search over bundles and is intended for vectorized queries.

Parameters:

xc (array_like) – Retinal coordinates in microns.
yc (array_like) – Retinal coordinates in microns.
bundles (list of (N, 2) ndarrays, optional) – Precomputed bundles. Generated if omitted.

Returns:

tangent – Bundle orientations in radians, shaped like xc.

Return type:

ndarray

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

Plot the axon map.

Parameters:

use_dva (bool, optional) – Plot in degrees of visual angle instead of retinal microns.
style ({'hull', 'scatter', 'cell'}, optional) – Grid plotting style.
annotate (bool, optional) – Label retinal quadrants.
autoscale (bool, optional) – Set axis limits to include the simulated region.
ax (matplotlib.axes.Axes, optional) – Axes to draw on. Defaults to the current axes.
figsize ((float, float), optional) – Figure size 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 – Axes containing the plot.

Return type:

matplotlib.axes.Axes

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

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

property implant

The prosthesis system whose geometry this model uses.

Rebinding invalidates the spatial build.

Added in version 0.11.0.

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

set_params(**params)[source]

Set the parameters of this model

visual_field_map is applied before the other parameters, so that a retinal extent given for xrange/yrange in the same call is resolved through the map the caller asked for. See _visual_field_map_first.

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.Horsager2009Model(*, dt=0.005, tau1=0.42, tau2=45.25, tau3=26.25, eps=2.25, beta=3.43, thresh_percept=0, reduce='last', verbose=True, n_threads=None, n_jobs=None)[source]

Standalone temporal model of [Horsager2009].

Uses Horsager2009Temporal without a spatial component. See that class for the model equations. Use Horsager2009Temporal instead when combining the temporal cascade with a spatial model.

Parameters:

dt (float or Quantity, optional) – Simulation time step, in milliseconds. Default: 0.005 ms.
tau1 (float or Quantity, optional) – Time constant of the fast response, in milliseconds. Default: 0.42 ms.
tau2 (float or Quantity, optional) – Time constant of the filtered charge accumulation, in milliseconds. Default: 45.25 ms.
tau3 (float or Quantity, optional) – Time constant of each final leaky-integrator stage, in milliseconds. Default: 26.25 ms.
eps (float, optional) – Strength of the subtractive charge-accumulation pathway. Default: 2.25. [Horsager2009] also reports 8.73 for the suprathreshold fit.
beta (float, optional) – Exponent of the rectifying power nonlinearity. Default: 3.43. [Horsager2009] also reports 0.83 for the suprathreshold fit.
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. Default: 'last'.
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.

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

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

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

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

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

Plot the spatial model.

Parameters and return value are those of plot().

predict_percept(source, t_percept=None, gaze=None, vmax=None, vmin=0)[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) or (n_frames, 2), 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. Gaze always moves the percept across the scene; it moves the scene across the electrodes too unless the implant’s scene_input_frame is 'head'.
vmax (float, optional) – Percept brightness mapped to white when composing a scene with a scotoma. Required for scotoma composition.
vmin (float, optional) – Percept brightness mapped to black for scotoma composition.

Returns:

percept (Percept or None) – Brightness percept for ordinary prediction. For a scene with a scotoma, returns an RGB percept on the scene pixel grid.
.. versionchanged:: 0.11.0 – source is now the presented stimulus or scene rather than an implant carrying a stimulus.

property space_unit

The unit spatial coordinates are expressed in

The temporal model never sees a coordinate.

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

class pulse2percept.models.Horsager2009Temporal(*, dt=0.005, tau1=0.42, tau2=45.25, tau3=26.25, eps=2.25, beta=3.43, thresh_percept=0, reduce='last', verbose=True, n_threads=None, n_jobs=None)[source]

Temporal model of [Horsager2009].

Implements the linear-nonlinear cascade from Fig. 2 of [Horsager2009]. With stimulus current \(A(t)\), the fast pathway and charge accumulation are

\[ \begin{align}\begin{aligned}\begin{split}\tau_1 \frac{dR_1}{dt} &= -A(t) - R_1(t), \\\end{split}\\\begin{split}\frac{dC}{dt} &= \max[A(t), 0], \\\end{split}\\\tau_2 \frac{dR_2}{dt} &= C(t) - R_2(t).\end{aligned}\end{align} \]

Thus negative current drives the fast response, while positive current contributes to accumulated charge. The two pathways combine through a rectifying power nonlinearity,

\[R_3(t) = \left[ \max\left( R_1(t) - \epsilon_{\mathrm{ms}} R_2(t), 0 \right) \right]^\beta,\]

where \(\epsilon_{\mathrm{ms}} = \epsilon / 1000\) because p2p integrates time in milliseconds while the original parameterization used microseconds.

The result passes through three identical slow leaky integrators,

\[ \begin{align}\begin{aligned}\begin{split}\tau_3 \frac{dR_{4a}}{dt} &= R_3 - R_{4a}, \\\end{split}\\\begin{split}\tau_3 \frac{dR_{4b}}{dt} &= R_{4a} - R_{4b}, \\\end{split}\\\tau_3 \frac{dB}{dt} &= R_{4b} - B,\end{aligned}\end{align} \]

and \(B(t)\) is the predicted brightness.

Use this class to combine the temporal model with a spatial model. Use Horsager2009Model for the standalone temporal model.

Parameters:

dt (float or Quantity, optional) – Simulation time step, in milliseconds. Default: 0.005 ms.
tau1 (float or Quantity, optional) – Time constant of the fast response \(R_1\), in milliseconds. Default: 0.42 ms.
tau2 (float or Quantity, optional) – Time constant of the filtered charge accumulation \(R_2\), in milliseconds. Default: 45.25 ms.
tau3 (float or Quantity, optional) – Time constant of each of the three final leaky-integrator stages, in milliseconds. Default: 26.25 ms.
eps (float, optional) – Strength of the subtractive charge-accumulation pathway. The public value retains the original microsecond parameterization and is divided by 1000 internally for millisecond integration. Default: 2.25. [Horsager2009] also reports 8.73 for the suprathreshold fit.
beta (float, optional) – Exponent of the rectifying power nonlinearity. Default: 3.43. [Horsager2009] also reports 0.83 for the suprathreshold fit.
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. 'last' reports brightness at the output instant; 'peak' approximates the interval peak by subsampling. Explicit t_percept values always request those instants. Default: 'last'.
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.

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, vmax=None, vmin=0)[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) or (n_frames, 2), 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. Gaze always moves the percept across the scene; it moves the scene across the electrodes too unless the implant’s scene_input_frame is 'head'.
vmax (float, optional) – Percept brightness mapped to white when composing a scene with a scotoma. Required for scotoma composition.
vmin (float, optional) – Percept brightness mapped to black for scotoma composition.

Returns:

percept (Percept or None) – Brightness percept for ordinary prediction. For a scene with a scotoma, returns an RGB percept on the scene pixel grid.
.. versionchanged:: 0.11.0 – source is now the presented stimulus or scene rather than an implant carrying a stimulus.

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.Nanduri2012Model(implant, *, atten_a=14000, atten_n=1.69, xrange=(-15, 15), yrange=(-15, 15), step=0.25, grid_type='rect', min_current_spread=1e-08, visual_field_map=None, n_gray=None, implant_position=(0, 0), implant_rotation=0, implant_depth=0, location_noise=None, ndim=None, dt=0.005, tau1=0.42, tau2=45.25, tau3=26.25, eps=8.73, asymptote=14.0, slope=3.0, shift=16.0, scale_out=1.0, reduce='last', thresh_percept=0, verbose=True, n_threads=None, n_jobs=None)[source]

Combined spatial-temporal model of [Nanduri2012].

Combines Nanduri2012Spatial with Nanduri2012Temporal. See those classes for the spatial current-spread equation and temporal cascade.

Parameters:

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

Added in version 0.11.0.
atten_a (float, optional) – Spatial attenuation scale. Default: 14000.
atten_n (float, optional) – Exponent controlling spatial attenuation. Default: 1.69.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle. A physical retinal extent may instead be resolved through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle. A physical retinal extent may instead be resolved through visual_field_map.
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.
visual_field_map (VisualFieldMap, optional) – Retinotopic map between visual-field and retinal coordinates. Defaults to Curcio1990Map.
n_gray (int or None, optional) – Number of gray levels in the returned percept. None disables gray-level quantization.
implant_position ((x, y) or Quantity, optional) –
Where the implant’s local (0, 0) origin sits. A bare pair or a length is a tissue position in microns; (6, -2) * dva is a visual field location, resolved through visual_field_map.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
Angle (deg) the implant is rotated by in the tissue plane, positive counter-clockwise, about its own local origin.

Added in version 0.11.0.
implant_depth (float or Quantity, optional) –
Signed offset (um) along the tissue plane’s normal, carried by the electrodes’ local z. Requires a 2D visual_field_map.

Added in version 0.11.0.
location_noise (float or None, optional) –
Standard deviation of fixed electrode-specific phosphene offsets, in dva. Requires an invertible 2D visual_field_map. None or 0 disables it. Location-dependent models may also change phosphene shape or size.

Added in version 0.11.0.
min_current_spread (float, optional) – Inherited Gaussian current-spread cutoff. Not used by the Nanduri spatial model.
dt (float or Quantity, optional) – Simulation time step, in milliseconds. Default: 0.005 ms.
tau1 (float or Quantity, optional) – Fast-response time constant, in milliseconds. Default: 0.42 ms.
tau2 (float or Quantity, optional) – Charge-accumulation time constant, in milliseconds. Default: 45.25 ms.
tau3 (float or Quantity, optional) – Time constant of the final three-stage low-pass cascade, in milliseconds. Default: 26.25 ms.
eps (float, optional) – Strength of the subtractive charge-accumulation pathway. Default: 8.73.
asymptote (float, optional) – Upper asymptote of the logistic peak-response nonlinearity. Default: 14.
slope (float, optional) – Scale parameter of the logistic nonlinearity. Default: 3.
shift (float, optional) – Midpoint of the logistic nonlinearity. Default: 16.
scale_out (float, optional) – Multiplicative scaling applied to final brightness. Default: 1.
thresh_percept (float, optional) – Brightness values below this threshold are set to zero. Default: 0.
reduce ({'peak', 'last'}, optional) – Temporal interval reduction used for automatically selected output times. Default: 'last'.
verbose (bool, optional) – Whether to print status messages. Default: True.
ndim (list of int, optional) – Dimensionalities of visual_field_map accepted by the spatial 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.

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

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

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

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

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

Plot the spatial model.

Parameters and return value are those of plot().

predict_percept(source, t_percept=None, gaze=None, vmax=None, vmin=0)[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) or (n_frames, 2), 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. Gaze always moves the percept across the scene; it moves the scene across the electrodes too unless the implant’s scene_input_frame is 'head'.
vmax (float, optional) – Percept brightness mapped to white when composing a scene with a scotoma. Required for scotoma composition.
vmin (float, optional) – Percept brightness mapped to black for scotoma composition.

Returns:

percept (Percept or None) – Brightness percept for ordinary prediction. For a scene with a scotoma, returns an RGB percept on the scene pixel grid.
.. versionchanged:: 0.11.0 – source is now the presented stimulus or scene rather than an implant carrying a stimulus.

property space_unit

The unit spatial coordinates are expressed in

The temporal model never sees a coordinate.

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

class pulse2percept.models.Nanduri2012Spatial(implant, *, atten_a=14000, atten_n=1.69, xrange=(-15, 15), yrange=(-15, 15), step=0.25, grid_type='rect', thresh_percept=0, min_current_spread=1e-08, visual_field_map=None, n_gray=None, implant_position=(0, 0), implant_rotation=0, implant_depth=0, location_noise=None, verbose=True, ndim=None, n_threads=None, n_jobs=None)[source]

Spatial response model of [Nanduri2012].

Models retinal activation as the sum of current spread from disk electrodes. For electrode \(e\), define the lateral distance from its center

\[s_e(x,y) = \sqrt{(x-x_e)^2 + (y-y_e)^2}\]

and the distance to the nearest point on the electrode disk

\[d_e(x,y) = \sqrt{ z_e^2 + \max\left[s_e(x,y)-a_e,\,0\right]^2 },\]

where \(a_e\) is electrode radius and \(z_e\) is electrode-retina distance. The spatial response is

\[I(x,y,t) = \sum_{e \in E} A_e(t) \frac{\mathrm{atten\_a}} {\mathrm{atten\_a} + d_e(x,y)^{\mathrm{atten\_n}}}.\]

Thus activation is uniform beneath an electrode when \(z_e=0\) and decays with distance from its edge. This is the p2p implementation of the current-spread model in Eq. 2 of [Nanduri2012], extended to include the electrode z coordinate.

Only DiskElectrode arrays are supported because the model depends explicitly on electrode radius.

Use this class for the spatial component alone. Use Nanduri2012Model for the combined spatial-temporal model.

Parameters:

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

Added in version 0.11.0.
atten_a (float, optional) – Attenuation scale in Eq. 2. Current spread falls to half its maximum when \(d = \mathrm{atten\_a}^{1/\mathrm{atten\_n}}\). Distances are evaluated in microns. Default: 14000.
atten_n (float, optional) – Exponent controlling the falloff of current spread with distance. Larger values produce a steeper tail. Default: 1.69.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle. A physical retinal extent may instead be resolved through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle. A physical retinal extent may instead be resolved through visual_field_map.
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) – Inherited Gaussian current-spread cutoff. This parameter is not used by Nanduri2012Spatial.
visual_field_map (VisualFieldMap, optional) – Retinotopic map between visual-field and retinal coordinates. Defaults to Curcio1990Map.
n_gray (int or None, optional) – Number of gray levels in the returned percept. None disables gray-level quantization.
implant_position ((x, y) or Quantity, optional) –
Where the implant’s local (0, 0) origin sits. A bare pair or a length is a tissue position in microns; (6, -2) * dva is a visual field location, resolved through visual_field_map.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
Angle (deg) the implant is rotated by in the tissue plane, positive counter-clockwise, about its own local origin.

Added in version 0.11.0.
implant_depth (float or Quantity, optional) –
Signed offset (um) along the tissue plane’s normal, carried by the electrodes’ local z. Requires a 2D visual_field_map.

Added in version 0.11.0.
location_noise (float or None, optional) –
Standard deviation of fixed electrode-specific phosphene offsets, in dva. Requires an invertible 2D visual_field_map. None or 0 disables it. Location-dependent models may also change phosphene shape or size.

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.

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

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

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

get_param_units()[source]

Return a dict of the units that parameters are stored in

xrange and yrange additionally accept a retinal extent, which is not a unit conversion and so does not appear here; see _retinal_range_to_dva.

property implant

The prosthesis system whose geometry this model uses.

Rebinding invalidates the spatial build.

Added in version 0.11.0.

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

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 retinal coordinates (microns)
style ({'hull', 'scatter', 'cell'}, optional) –
Grid plotting style:
- ’hull’: Show the convex hull of the grid (that is, the outline of the smallest convex set that contains all grid points).
- ’scatter’: Scatter plot all grid points
- ’cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a high-resolution grid.
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
figsize ((float, float), optional) – Desired (width, height) of the figure in inches
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

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.

set_params(**params)[source]

Set the parameters of this model

visual_field_map is applied before the other parameters, so that a retinal extent given for xrange/yrange in the same call is resolved through the map the caller asked for. See _visual_field_map_first.

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.Nanduri2012Temporal(*, dt=0.005, tau1=0.42, tau2=45.25, tau3=26.25, eps=8.73, asymptote=14.0, slope=3.0, shift=16.0, scale_out=1.0, thresh_percept=0, reduce='last', verbose=True, n_threads=None, n_jobs=None)[source]

Temporal response model of [Nanduri2012].

Implements the linear-nonlinear cascade in Fig. 6 of [Nanduri2012]. With stimulus amplitude \(A(t)\), the fast response and charge accumulation are

\[ \begin{align}\begin{aligned}\begin{split}\tau_1 \frac{dR_1}{dt} &= A(t) - R_1(t), \\\end{split}\\\begin{split}\frac{dC}{dt} &= \max[A(t), 0], \\\end{split}\\\tau_2 \frac{dR_2}{dt} &= C(t) - R_2(t).\end{aligned}\end{align} \]

The two pathways are combined by half-wave rectification,

\[R_3(t) = \max\left[ R_1(t) - \epsilon_{\mathrm{ms}} R_2(t),\,0 \right],\]

where \(\epsilon_{\mathrm{ms}} = \epsilon / 1000\) because p2p integrates time in milliseconds while the original parameterization used microseconds.

A logistic nonlinearity sets the peak response. Let

\[R_{3,\max} = \max_t R_3(t)\]

and

\[g = \frac{\mathrm{asymptote}}{R_{3,\max}} \sigma\left( \frac{R_{3,\max} - \mathrm{shift}}{\mathrm{slope}} \right),\]

where \(\sigma(u)=1/(1+e^{-u})\). The entire \(R_3(t)\) trace is multiplied by this gain, so the scaled peak equals the logistic response.

The result then passes through three identical slow leaky integrators,

\[ \begin{align}\begin{aligned}\begin{split}\tau_3 \frac{dR_{4a}}{dt} &= gR_3 - R_{4a}, \\\end{split}\\\begin{split}\tau_3 \frac{dR_{4b}}{dt} &= R_{4a} - R_{4b}, \\\end{split}\\\tau_3 \frac{dB}{dt} &= R_{4b} - B,\end{aligned}\end{align} \]

and the predicted brightness is scale_out \(\times B(t)\).

Positive current drives the model. Use this class for the temporal component alone. Use Nanduri2012Model for the combined spatial-temporal model.

Parameters:

dt (float or Quantity, optional) – Simulation time step, in milliseconds. Default: 0.005 ms.
tau1 (float or Quantity, optional) – Time constant of the fast response \(R_1\), in milliseconds. Default: 0.42 ms.
tau2 (float or Quantity, optional) – Time constant of the filtered charge accumulation \(R_2\), in milliseconds. Default: 45.25 ms.
tau3 (float or Quantity, optional) – Time constant of each of the three final leaky-integrator stages, in milliseconds. Default: 26.25 ms.
eps (float, optional) – Strength of the subtractive charge-accumulation pathway. The public value retains the original microsecond parameterization and is divided by 1000 internally for millisecond integration. Default: 8.73.
asymptote (float, optional) – Upper asymptote of the logistic peak-response nonlinearity. Default: 14.
slope (float, optional) – Scale parameter controlling the steepness of the logistic nonlinearity. Default: 3.
shift (float, optional) – Midpoint of the logistic nonlinearity along \(R_{3,\max}\). Default: 16.
scale_out (float, optional) – Multiplicative scaling applied to the final brightness. Default: 1.
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. 'last' reports brightness at the output instant; 'peak' approximates the interval peak by subsampling. Explicit t_percept values always request those instants. Default: 'last'.
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.

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.BiphasicAxonMapModel(implant, *, bright_model=None, size_model=None, streak_model=None, rho=300, lam=500, xrange=(-15, 15), yrange=(-15, 15), step=0.25, grid_type='rect', thresh_percept=0, min_current_spread=1e-08, visual_field_map=None, n_gray=None, implant_position=(0, 0), implant_rotation=0, implant_depth=0, location_noise=None, loc_od=(15.5, 1.5), n_axons=1000, axons_range=(-180, 180), n_ax_segments=500, ax_segments_range=(0, 50), min_ax_sensitivity=0.001, meridian_blend=1, axon_pickle='axons.pickle', ignore_pickle=False, verbose=True, ndim=None, n_threads=None, n_jobs=None)[source]

Biphasic axon-map model of [Granley2021].

Extends AxonMapModel with the stimulus-dependent brightness, size, and streak-length scaling of [Granley2021]. The model returns one representative percept for the full biphasic pulse train.

Stimuli must describe the pulse train they deliver, rather than only its samples: either retained BiphasicPulseTrain objects, or a still image encoded with the standard biphasic encoder pulse (see AmplitudeEncoder). Give amplitude in multiples of perceptual threshold (xTh) or provide a threshold calibration for current-valued amplitudes. Threshold is the 50%-detection current for a train at the same frequency and 0.45 ms phase duration [Granley2021]; the model applies its own phase-duration correction.

Encoded still images use the device-resolved amplitude, phase duration, and frequency; exact pulse-onset timing is ignored. Videos are not supported.

Custom effect models must be callables with signature f(freq, amp, pdur). Their arguments are frequency, amplitude in multiples of threshold, and phase duration.

The spatial response is

\[I(r, \theta) = \max_{p \in R(\theta)} \sum_{e \in E} F_{\mathrm{bright}} \exp\left( -\frac{d_e^2}{2 \rho^2 F_{\mathrm{size}}} -\frac{d_{\mathrm{soma}}^2} {2 \lambda^2 F_{\mathrm{streak}}} \right),\]

where \(d_e\) is the distance from an axon segment to electrode \(e\), and \(d_{\mathrm{soma}}\) is the path length from that segment to the ganglion cell body. Thus the effective spatial scales are

\[\rho_{\mathrm{eff}} = \rho \sqrt{F_{\mathrm{size}}}, \qquad \lambda_{\mathrm{eff}} = \lambda \sqrt{F_{\mathrm{streak}}}.\]

Parameters:

implant (Implant) –
Implant whose electrode geometry and eye are modeled.

Added in version 0.11.0.
bright_model (callable, optional) – Maps (freq, amp, pdur) to a multiplicative brightness factor. Defaults to DefaultBrightModel.
size_model (callable, optional) – Maps (freq, amp, pdur) to F_size, which scales rho ** 2. Defaults to DefaultSizeModel.
streak_model (callable, optional) – Maps (freq, amp, pdur) to F_streak, which scales lam ** 2. Defaults to DefaultStreakModel.
rho (float or Quantity, optional) – Gaussian decay constant for spread from an electrode to nearby axon segments, in microns. Larger values broaden the percept.
lam (float or Quantity, optional) –
Gaussian decay constant along the axon between stimulation site and soma, in microns. Larger values lengthen the percept.

Changed in version 0.10.0: Renamed from axlambda; axlambda was removed in 0.11.0.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle. A physical retinal extent may instead be resolved through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle. A physical retinal extent may instead be resolved through visual_field_map.
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 current spread below which an electrode may be skipped at an axon segment. The cutoff is scaled by F_size. Set to 0 to disable.
visual_field_map (VisualFieldMap, optional) – Retinotopic map between visual-field and retinal coordinates. Defaults to Watson2014Map.
n_gray (int or None, optional) – Number of gray levels in the returned percept. None disables gray-level quantization.
implant_position ((x, y) or Quantity, optional) –
Position of the device-local origin, in tissue coordinates or dva.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
In-plane rotation (deg), positive counter-clockwise.

Added in version 0.11.0.
implant_depth (float or Quantity, optional) –
Signed offset (um) along the normal of a 2D tissue map.

Added in version 0.11.0.
location_noise (float or None, optional) –
Standard deviation of fixed electrode-specific phosphene offsets, in dva. Requires an invertible 2D visual_field_map. None or 0 disables it. Location-dependent models may also change phosphene shape or size.

Added in version 0.11.0.
loc_od ((float, float) or Quantity, optional) – Optic-disc location in degrees of visual angle. Its horizontal sign is set from the bound implant’s eye.
n_axons (int, optional) – Number of nerve fiber bundles generated.
axons_range ((float, float) or Quantity, optional) – Range of initial bundle angles phi0 in the Jansonius model.
n_ax_segments (int, optional) – Number of radial samples used to generate each bundle.
ax_segments_range ((float, float), optional) – Radial-coordinate range used to generate each bundle in the Jansonius model.
min_ax_sensitivity (float, optional) – Minimum relative axon sensitivity retained during precomputation.
meridian_blend (float or Quantity, optional) –
Gaussian standard deviation for blending across the horizontal meridian, in degrees of visual angle. Set to 0 to disable.

Added in version 0.10.0.
axon_pickle (str, optional) – File used to cache generated axon bundles.
ignore_pickle (bool, optional) – If True, regenerate axon bundles instead of loading axon_pickle.
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

ax_segments_range values above 90 are outside the range for which this axon-map construction is considered reliable.

Examples

A picture, a device that encodes it, and a participant’s measured threshold:

import pulse2percept as p2p

implant = p2p.implants.ArgusII(thresholds=80 * p2p.units.uA)
model = p2p.models.BiphasicAxonMapModel(implant=implant)
percept = model.predict_percept(p2p.stimuli.LogoBVL())

An encoder that asks for threshold multiples in the first place needs no measured threshold:

encoder = p2p.stimuli.AmplitudeEncoder(
    amp_range=(0 * p2p.units.xTh, 3 * p2p.units.xTh))
implant = p2p.implants.ArgusII(encoder=encoder)
model = p2p.models.BiphasicAxonMapModel(implant=implant)
percept = model.predict_percept(p2p.stimuli.LogoBVL())

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

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

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

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

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

Plot the spatial model.

Parameters and return value are those of plot().

predict_percept(source, t_percept=None, gaze=None, vmax=None, vmin=0)[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) or (n_frames, 2), 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. Gaze always moves the percept across the scene; it moves the scene across the electrodes too unless the implant’s scene_input_frame is 'head'.
vmax (float, optional) – Percept brightness mapped to white when composing a scene with a scotoma. Required for scotoma composition.
vmin (float, optional) – Percept brightness mapped to black for scotoma composition.

Returns:

percept (Percept or None) – Brightness percept for ordinary prediction. For a scene with a scotoma, returns an RGB percept on the scene pixel grid.
.. versionchanged:: 0.11.0 – source is now the presented stimulus or scene rather than an implant carrying a stimulus.

property space_unit

The unit spatial coordinates are expressed in

The temporal model never sees a coordinate.

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

class pulse2percept.models.ScoreboardModel(implant, *, rho=100, xrange=(-15, 15), yrange=(-15, 15), step=0.25, grid_type='rect', thresh_percept=0, min_current_spread=1e-08, visual_field_map=None, n_gray=None, implant_position=(0, 0), implant_rotation=0, implant_depth=0, location_noise=None, verbose=True, ndim=None, n_threads=None, n_jobs=None)[source]

Scoreboard model of [Beyeler2019].

Models each electrode’s percept as a circular Gaussian. Use ScoreboardSpatial to combine this spatial model with a temporal model.

The spatial response is modeled as a Gaussian centered on each electrode:

\[I(x, y) = \sum_{e \in E} a_e \exp\left( -\frac{(x-x_e)^2 + (y-y_e)^2}{2\rho^2} \right),\]

where \(a_e\) is the drive at site \(e\), and \(\rho\) controls the spatial spread of activation. Larger values of \(\rho\) produce broader phosphenes.

For current-driven implants, \(a_e\) is current amplitude. PRIMAEncoder instead provides normalized optical drive. In that case, Scoreboard visualizes the stimulation pattern; it does not model the retinal response.

Parameters:

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

Added in version 0.11.0.
rho (float or Quantity, optional) –
Gaussian spatial decay constant in microns. Larger values produce broader phosphenes. The same rho value applies to all electrodes.

Important

Electrode-retina distance (z) does not directly affect rho.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle. May also be passed as retinal extent using physical units such as um. The correspondence is resolved through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle. May also be passed as retinal extent using physical units such as um. The correspondence is resolved through visual_field_map.
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) – Retinotopic map between visual-field and retinal coordinates. Defaults to Watson2014Map.
n_gray (int or None, optional) – Number of gray levels in the returned percept. None disables gray-level quantization.
implant_position ((x, y) or Quantity, optional) –
Position of the device-local origin, in tissue coordinates or dva.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
In-plane rotation (deg), positive counter-clockwise.

Added in version 0.11.0.
implant_depth (float or Quantity, optional) –
Signed offset (um) along the normal of a 2D tissue map.

Added in version 0.11.0.
location_noise (float or None, optional) –
Standard deviation of fixed electrode-specific phosphene offsets, in dva. Requires an invertible 2D visual_field_map. None or 0 disables it. Location-dependent models may also change phosphene shape or size.

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.

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

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

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

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

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

Plot the spatial model.

Parameters and return value are those of plot().

predict_percept(source, t_percept=None, gaze=None, vmax=None, vmin=0)[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) or (n_frames, 2), 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. Gaze always moves the percept across the scene; it moves the scene across the electrodes too unless the implant’s scene_input_frame is 'head'.
vmax (float, optional) – Percept brightness mapped to white when composing a scene with a scotoma. Required for scotoma composition.
vmin (float, optional) – Percept brightness mapped to black for scotoma composition.

Returns:

percept (Percept or None) – Brightness percept for ordinary prediction. For a scene with a scotoma, returns an RGB percept on the scene pixel grid.
.. versionchanged:: 0.11.0 – source is now the presented stimulus or scene rather than an implant carrying a stimulus.

property space_unit

The unit spatial coordinates are expressed in

The temporal model never sees a coordinate.

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

class pulse2percept.models.ScoreboardSpatial(implant, *, rho=100, xrange=(-15, 15), yrange=(-15, 15), step=0.25, grid_type='rect', thresh_percept=0, min_current_spread=1e-08, visual_field_map=None, n_gray=None, implant_position=(0, 0), implant_rotation=0, implant_depth=0, location_noise=None, verbose=True, ndim=None, n_threads=None, n_jobs=None)[source]

Scoreboard model of [Beyeler2019] (spatial module only).

Models each electrode’s percept as a circular Gaussian. Use ScoreboardModel for a standalone model.

The spatial response is modeled as a Gaussian centered on each electrode:

\[I(x, y) = \sum_{e \in E} a_e \exp\left( -\frac{(x-x_e)^2 + (y-y_e)^2}{2\rho^2} \right),\]

where \(a_e\) is the drive at site \(e\), and \(\rho\) controls the spatial spread of activation. Larger values of \(\rho\) produce broader phosphenes.

For current-driven implants, \(a_e\) is current amplitude. PRIMAEncoder instead provides normalized optical drive. In that case, Scoreboard visualizes the stimulation pattern; it does not model the retinal response.

Parameters:

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

Added in version 0.11.0.
rho (float or Quantity, optional) –
Gaussian spatial decay constant in microns. Larger values produce broader phosphenes. The same rho value applies to all electrodes.

Important

Electrode-retina distance (z) does not directly affect rho.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle. May also be passed as retinal extent using physical units such as um. The correspondence is resolved through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle. May also be passed as retinal extent using physical units such as um. The correspondence is resolved through visual_field_map.
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) – Retinotopic map between visual-field and retinal coordinates. Defaults to Watson2014Map.
n_gray (int or None, optional) – Number of gray levels in the returned percept. None disables gray-level quantization.
implant_position ((x, y) or Quantity, optional) –
Position of the device-local origin, in tissue coordinates or dva.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
In-plane rotation (deg), positive counter-clockwise.

Added in version 0.11.0.
implant_depth (float or Quantity, optional) –
Signed offset (um) along the normal of a 2D tissue map.

Added in version 0.11.0.
location_noise (float or None, optional) –
Standard deviation of fixed electrode-specific phosphene offsets, in dva. Requires an invertible 2D visual_field_map. None or 0 disables it. Location-dependent models may also change phosphene shape or size.

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.

extra_stimulus_units = (dimensionless,): Also accepts encoded normalized optical drive from PRIMAEncoder.

get_default_params()[source]: Return all settable scoreboard parameters.

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

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

property implant

The prosthesis system whose geometry this model uses.

Rebinding invalidates the spatial build.

Added in version 0.11.0.

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

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 retinal coordinates (microns)
style ({'hull', 'scatter', 'cell'}, optional) –
Grid plotting style:
- ’hull’: Show the convex hull of the grid (that is, the outline of the smallest convex set that contains all grid points).
- ’scatter’: Scatter plot all grid points
- ’cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a high-resolution grid.
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
figsize ((float, float), optional) – Desired (width, height) of the figure in inches
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

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.

set_params(**params)[source]

Set the parameters of this model

visual_field_map is applied before the other parameters, so that a retinal extent given for xrange/yrange in the same call is resolved through the map the caller asked for. See _visual_field_map_first.

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.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. On retinal maps, a physical retinal extent may be given instead and is resolved through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle. On retinal maps, a physical retinal extent may be given instead and is resolved through visual_field_map.
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) – Retinotopic map between visual-field and tissue coordinates.
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 and yrange always describe the simulated visual field and are stored in degrees of visual angle. A retinal length is only shorthand for selecting that extent through visual_field_map; the resulting grid is still uniformly sampled in visual angle. step therefore only accepts angular spacing.

Added in version 0.6.

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.

set_params(**params)[source]

Set the parameters of this model

visual_field_map is applied before the other parameters, so that a retinal extent given for xrange/yrange in the same call is resolved through the map the caller asked for. See _visual_field_map_first.

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

xrange and yrange additionally accept a retinal extent, which is not a unit conversion and so does not appear here; see _retinal_range_to_dva.

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 retinal coordinates (microns)
style ({'hull', 'scatter', 'cell'}, optional) –
Grid plotting style:
- ’hull’: Show the convex hull of the grid (that is, the outline of the smallest convex set that contains all grid points).
- ’scatter’: Scatter plot all grid points
- ’cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a high-resolution grid.
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
figsize ((float, float), optional) – Desired (width, height) of the figure in inches
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

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

class pulse2percept.models.Thompson2003Model(implant, *, radius=None, dropout=None, xrange=(-15, 15), yrange=(-15, 15), step=0.25, grid_type='rect', thresh_percept=0, min_current_spread=1e-08, visual_field_map=None, n_gray=None, implant_position=(0, 0), implant_rotation=0, implant_depth=0, location_noise=None, verbose=True, ndim=None, n_threads=None, n_jobs=None)[source]

Standalone spatial model of [Thompson2003].

Uses Thompson2003Spatial without a temporal component. See that class for the top-hat disk equation and dropout model.

Parameters:

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

Added in version 0.11.0.
radius (float, Quantity, or None, optional) – Radius of each circular phosphene, in microns. If None, uses 0.45 * implant.electrode_array.spacing. Default: None.
dropout (int, float, or None, optional) – Number or fraction of electrodes randomly omitted from each stimulus frame. None disables dropout.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle. A physical retinal extent may instead be resolved through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle. A physical retinal extent may instead be resolved through visual_field_map.
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) – Inherited Gaussian current-spread cutoff. Not used by the Thompson spatial model.
visual_field_map (VisualFieldMap, optional) – Retinotopic map between visual-field and retinal coordinates. Defaults to Curcio1990Map.
n_gray (int or None, optional) – Number of gray levels in the returned percept. None disables gray-level quantization.
implant_position ((x, y) or Quantity, optional) –
Position of the device-local origin, in tissue coordinates or dva.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
In-plane rotation (deg), positive counter-clockwise.

Added in version 0.11.0.
implant_depth (float or Quantity, optional) –
Signed offset (um) along the normal of a 2D tissue map.

Added in version 0.11.0.
location_noise (float or None, optional) –
Standard deviation of fixed electrode-specific phosphene offsets, in dva. Requires an invertible 2D visual_field_map. None or 0 disables it. Location-dependent models may also change phosphene shape or size.

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 spatial model.
n_threads (int, optional) – Inherited OpenMP thread count. The Thompson spatial kernel does not currently use this parameter.
n_jobs (int or None, optional) – Alias for n_threads. The Thompson spatial kernel does not currently use this parameter.

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

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

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

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

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

Plot the spatial model.

Parameters and return value are those of plot().

predict_percept(source, t_percept=None, gaze=None, vmax=None, vmin=0)[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) or (n_frames, 2), 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. Gaze always moves the percept across the scene; it moves the scene across the electrodes too unless the implant’s scene_input_frame is 'head'.
vmax (float, optional) – Percept brightness mapped to white when composing a scene with a scotoma. Required for scotoma composition.
vmin (float, optional) – Percept brightness mapped to black for scotoma composition.

Returns:

percept (Percept or None) – Brightness percept for ordinary prediction. For a scene with a scotoma, returns an RGB percept on the scene pixel grid.
.. versionchanged:: 0.11.0 – source is now the presented stimulus or scene rather than an implant carrying a stimulus.

property space_unit

The unit spatial coordinates are expressed in

The temporal model never sees a coordinate.

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

class pulse2percept.models.Thompson2003Spatial(implant, *, radius=None, dropout=None, xrange=(-15, 15), yrange=(-15, 15), step=0.25, grid_type='rect', thresh_percept=0, min_current_spread=1e-08, visual_field_map=None, n_gray=None, implant_position=(0, 0), implant_rotation=0, implant_depth=0, location_noise=None, verbose=True, ndim=None, n_threads=None, n_jobs=None)[source]

Spatial model of [Thompson2003].

Models each electrode as a circular phosphene with uniform brightness inside a fixed radius and zero contribution outside. For electrode \(e\), let

\[r_e(x,y) = \sqrt{(x-x_e)^2 + (y-y_e)^2}.\]

The spatial response is

\[I(x,y,t) = \sum_{e \in E} [1-D_e(t)]\,A_e(t)\, \mathbf{1}\left[r_e(x,y) < R\right],\]

where \(A_e(t)\) is stimulus amplitude, \(R\) is radius, \(D_e(t)\) is 1 for a dropped electrode and 0 otherwise, and \(\mathbf{1}\) is the indicator function. Contributions from overlapping disks add linearly.

Dropout is resampled independently for each stimulus frame. Electrode z coordinates are ignored.

Use this class to combine the spatial model with a temporal model. Use Thompson2003Model for the standalone spatial model.

Parameters:

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

Added in version 0.11.0.
radius (float, Quantity, or None, optional) – Radius of each circular phosphene, in microns. If None, uses 0.45 * implant.electrode_array.spacing, giving a disk diameter equal to 90% of the electrode spacing. The electrode array must provide a spacing attribute. Default: None.
dropout (int, float, or None, optional) – Number or fraction of electrodes randomly omitted from each stimulus frame. An integer gives the number of dropped electrodes; a float in [0, 1] gives their fraction. None disables dropout.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle. A physical retinal extent may instead be resolved through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle. A physical retinal extent may instead be resolved through visual_field_map.
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) – Inherited Gaussian current-spread cutoff. This parameter is not used by Thompson2003Spatial.
visual_field_map (VisualFieldMap, optional) – Retinotopic map between visual-field and retinal coordinates. Defaults to Curcio1990Map.
n_gray (int or None, optional) – Number of gray levels in the returned percept. None disables gray-level quantization.
implant_position ((x, y) or Quantity, optional) –
Position of the device-local origin, in tissue coordinates or dva.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
In-plane rotation (deg), positive counter-clockwise.

Added in version 0.11.0.
implant_depth (float or Quantity, optional) –
Signed offset (um) along the normal of a 2D tissue map.

Added in version 0.11.0.
location_noise (float or None, optional) –
Standard deviation of fixed electrode-specific phosphene offsets, in dva. Requires an invertible 2D visual_field_map. None or 0 disables it. Location-dependent models may also change phosphene shape or size.

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) – Inherited OpenMP thread count. The Thompson spatial kernel does not currently use this parameter.
n_jobs (int or None, optional) – Alias for n_threads. The Thompson spatial kernel does not currently use this parameter.

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

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

property implant

The prosthesis system whose geometry this model uses.

Rebinding invalidates the spatial build.

Added in version 0.11.0.

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

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 retinal coordinates (microns)
style ({'hull', 'scatter', 'cell'}, optional) –
Grid plotting style:
- ’hull’: Show the convex hull of the grid (that is, the outline of the smallest convex set that contains all grid points).
- ’scatter’: Scatter plot all grid points
- ’cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a high-resolution grid.
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant
ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object.
figsize ((float, float), optional) – Desired (width, height) of the figure in inches
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

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.

set_params(**params)[source]

Set the parameters of this model

visual_field_map is applied before the other parameters, so that a retinal extent given for xrange/yrange in the same call is resolved through the map the caller asked for. See _visual_field_map_first.

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