pulse2percept.models.retina

Computational models of retinal stimulation

Phosphene and neural-response models for epiretinal, subretinal and suprachoroidal devices, plus the retinal spatial base class they share.

`base`	`RetinalSpatial`
`thompson2003`	`Thompson2003Model`, `Thompson2003Spatial` [Thompson2003]
`horsager2009`	`Horsager2009Model`, `Horsager2009Temporal` [Horsager2009]
`nanduri2012`	`Nanduri2012Model`, `Nanduri2012Spatial`, `Nanduri2012Temporal` [Nanduri2012]
`beyeler2019`	`AxonMapModel`, `AxonMapSpatial` [Beyeler2019]
`granley2021`	`BiphasicAxonMapModel`, `BiphasicAxonMapSpatial`, `BiphasicScoreboardModel`, `BiphasicScoreboardSpatial` [Granley2021]
`ho2018`	`Ho2018Model`, `Ho2018Spatial`, `Ho2018Temporal` [Ho2018]

See also

Basic Concepts > Computational Models

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

Note

Dimensionless image or video values are read as relative electrode drive, so an implant encoder is optional when only the spatial pattern matters. An encoder is required when physical amplitude, pulse timing, safety constraints, or a temporal or pulse-dependent model matters.

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)[source]

Predict a percept.

Parameters:

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

Returns:

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

property 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.retina.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, which must therefore be a RetinalImplant: the optic disc sits on the nasal side of the implanted eye, and a generic implant does not say which eye that is.

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 model

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

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.retina.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 cathodic-first 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.

Interphase duration is accepted but ignored: the effect models read only amplitude, frequency, and phase duration.

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.retina.ArgusII(thresholds=80 * p2p.units.uA)
model = p2p.models.retina.BiphasicAxonMapModel(implant=implant)
percept = model.predict_percept(p2p.stimuli.samples.logo_bvl())

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.retina.ArgusII(encoder=encoder)
model = p2p.models.retina.BiphasicAxonMapModel(implant=implant)
percept = model.predict_percept(p2p.stimuli.samples.logo_bvl())

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)[source]

Predict a percept.

Parameters:

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

Returns:

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

property 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.retina.BiphasicAxonMapSpatial(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] (spatial module only).

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

Stimuli must describe the cathodic-first 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). Amplitude may be given in multiples of perceptual threshold (xTh) or as current when a threshold calibration is available.

Encoded still images use the device-resolved amplitude, phase duration, and frequency; exact pulse-onset timing and interphase duration are 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.

When paired with a temporal model, this spatial prediction is treated as the peak percept and multiplied by a normalized temporal response.

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.

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

build(**build_params)[source]

Build the model

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

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

extra_stimulus_units = (xTh,): Amplitude may be given in multiples of perceptual threshold.

property eye

Eye used by the axon map.

Taken from the bound implant, which must therefore be a RetinalImplant: the optic disc sits on the nasal side of the implanted eye, and a generic implant does not say which eye that is.

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

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.

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

property implant

The prosthesis system whose geometry this model uses.

Rebinding invalidates the spatial build.

Added in version 0.11.0.

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

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

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

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.retina.BiphasicScoreboardModel(implant, *, bright_model=None, size_model=None, 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]

Biphasic scoreboard model.

Extends ScoreboardModel with the stimulus-dependent brightness and size scaling of [Granley2021], but without the axonal streak term of BiphasicAxonMapModel: phosphenes stay round and centered on the electrode.

Stimuli must describe the cathodic-first 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. Bare amplitudes and raw waveforms are rejected.

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

Interphase duration is accepted but ignored: the effect models read only amplitude, frequency, and phase duration.

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(x, y) = \sum_{e \in E} F_{\mathrm{bright}} \exp\left( -\frac{(x-x_e)^2 + (y-y_e)^2}{2 \rho^2 F_{\mathrm{size}}} \right),\]

so the effective spatial scale is \(\rho_{\mathrm{eff}} = \rho \sqrt{F_{\mathrm{size}}}\).

Note

The brightness and size functions are the empirical fits of [Granley2021] (Eqs. 4-5), but this focal combination – those fits without the axonal streak term – is not the model that paper validated. [Granley2021] assumes an epiretinal implant and treats axonal activation as part of phosphene shape, so here rho alone carries the apparent size. The underlying psychophysics ([Nanduri2012], [Weitz2015]) is likewise epiretinal.

Parameters:

implant (Implant) – Implant whose electrode geometry is modeled.
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.
rho (float or Quantity, optional) –
Baseline Gaussian spatial decay constant in microns, before F_size scaling. Larger values produce broader phosphenes.

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.
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. 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.
implant_rotation (float or Quantity, optional) – In-plane rotation (deg), positive counter-clockwise.
implant_depth (float or Quantity, optional) – Signed offset (um) along the normal of a 2D tissue map.
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.
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.
versionadded: (..) – 0.11.0:

Examples

A pulse train given in threshold multiples:

import pulse2percept as p2p

model = p2p.models.retina.BiphasicScoreboardModel(
    p2p.implants.retina.ArgusII())
train = p2p.stimuli.BiphasicPulseTrain(20, 2 * p2p.units.xTh, 0.45)
percept = model.predict_percept({'C5': train})

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

implant = p2p.implants.retina.ArgusII(thresholds=80 * p2p.units.uA)
model = p2p.models.retina.BiphasicScoreboardModel(implant=implant)
percept = model.predict_percept(p2p.stimuli.samples.logo_bvl())

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)[source]

Predict a percept.

Parameters:

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

Returns:

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

property 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.retina.BiphasicScoreboardSpatial(implant, *, bright_model=None, size_model=None, 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]

Biphasic scoreboard model (spatial module only).

Spatial component of BiphasicScoreboardModel, for pairing with a temporal model in a Model. The stimulus contract, effect models, spatial response, and validation caveat are described there. In a composite model this spatial prediction is treated as the peak percept and multiplied by a normalized temporal response.

Parameters:

implant (Implant) – Implant whose electrode geometry is modeled.
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.
rho (float or Quantity, optional) –
Baseline Gaussian spatial decay constant in microns, before F_size scaling. Larger values produce broader phosphenes.

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.
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. 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.
implant_rotation (float or Quantity, optional) – In-plane rotation (deg), positive counter-clockwise.
implant_depth (float or Quantity, optional) – Signed offset (um) along the normal of a 2D tissue map.
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.
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.
versionadded: (..) – 0.11.0:

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

build(**build_params)[source]

Build the model

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

extra_stimulus_units = (xTh,): Amplitude may be given in multiples of perceptual threshold.

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

property implant

The prosthesis system whose geometry this model uses.

Rebinding invalidates the spatial build.

Added in version 0.11.0.

property is_built: Return whether the grid matches the current retinal laterality

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

Added in version 0.11.0.

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

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

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.retina.Ho2018Model(implant, *, rho=None, xrange=(-15, 15), yrange=(-15, 15), step=0.25, grid_type='rect', min_current_spread=1e-08, visual_field_map=None, implant_position=(0, 0), implant_rotation=0, implant_depth=0, location_noise=None, ndim=None, n=6, tau1=51.3, tau2=137.1, p1=1.0, p2=0.3743, dt=0.005, reduce='last', thresh_percept=0, verbose=True, n_threads=None, n_jobs=None)[source]

Network-mediated photovoltaic response model of [Ho2018].

Ho2018Spatial turns an encoder’s optical schedule into one drive map per pulse period, spread over half the implant’s pixel pitch; Ho2018Temporal filters those into a transient, spatially localized percept.

implant = p2p.implants.retina.PRIMAPivotal()
model = p2p.models.retina.Ho2018Model(implant, xrange=(-3, 3),
                                      yrange=(-3, 3), step=0.05)
percept = model.predict_percept(image)

ScoreboardModel on the same encoder visualizes normalized optical drive; this model predicts a phenomenological retinal response.

Warning

This reconstructs the structure and timing of [Ho2018], not validated PRIMA percepts. It covers the pON center response of degenerate (RCS) rat retina only: no antagonistic surround, no pOFF pathway, a linear radiant-exposure activation law with no fitted irradiance, pulse-duration or frequency nonlinearity, no photovoltaic circuit or electric-field model, no electrode-retina distance effect, no wavelength or device-specific conversion efficiency, and no calibration to human brightness or contrast perception.

Added in version 0.11.0.

Parameters:

implant (Implant) – Photovoltaic implant whose pixel geometry is modeled.
rho (float or Quantity, optional) – Gaussian spatial decay constant in microns. None (default) uses half the implant’s median nearest-neighbor pitch, a pulse2percept convention rather than a measured spread; see Ho2018Spatial.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle.
step (float, (float, float), or Quantity, optional) – Grid spacing in degrees of visual angle.
grid_type ({'rect', 'hex'}, optional) – Sampling lattice used for the visual-field grid.
min_current_spread (float, optional) – Fraction of peak Gaussian spread below which a pixel may be skipped at a grid point.
visual_field_map (VisualFieldMap, optional) – Retinotopic map between visual-field and retinal coordinates.
implant_position ((x, y) or Quantity, optional) – Position of the device-local origin, in tissue coordinates or dva.
implant_rotation (float or Quantity, optional) – In-plane rotation (deg), positive counter-clockwise.
implant_depth (float or Quantity, optional) – Signed offset (um) along the normal of a 2D tissue map.
location_noise (float or None, optional) – Standard deviation of fixed pixel-specific phosphene offsets, in dva.
ndim (list of int, optional) – Dimensionalities of visual_field_map accepted by the model.
n (float, optional) – Order of both low-pass cascades.
tau1 (float or Quantity, optional) – Time constants (ms) of the fast and slow cascade.
tau2 (float or Quantity, optional) – Time constants (ms) of the fast and slow cascade.
p1 (float, optional) – Peak amplitudes of the fast and slow cascade.
p2 (float, optional) – Peak amplitudes of the fast and slow cascade.
dt (float or Quantity, optional) – Lattice (ms) output times must be multiples of.
reduce ({'last', 'peak'}, optional) – How automatically chosen output points summarize the preceding interval; see Ho2018Temporal.
thresh_percept (float, optional) – Brightness values below this threshold are set to zero. Applied to the returned percept only; the spatial stage passes drive on unthresholded.
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.

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)[source]

Predict a percept.

Parameters:

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

Returns:

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

property 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.retina.Ho2018Spatial(implant, *, rho=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]

Network-mediated spatial response of [Ho2018] (spatial module only).

Sums a circular Gaussian per illuminated pixel like ScoreboardSpatial, but driven by the encoder’s optical schedule rather than by normalized time-averaged drive. See Ho2018Model for the spatiotemporal model.

Each pulse period reduces to a radiant-exposure drive per pixel,

\[d_e = \frac{E_e \, T_e}{E_\mathrm{ref} \, T_\mathrm{ref}}, \qquad E_\mathrm{ref} = 9\ \mathrm{mW/mm}^2, \; T_\mathrm{ref} = 4\ \mathrm{ms},\]

for peak irradiance \(E_e\) and ON duration \(T_e\) of pixel \(e\) in that period, so the [Ho2018] reference pulse has \(d_e = 1\). Drives are summed over pixels,

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

giving one drive map per pulse period, on the schedule’s pulse-period clock. The waveform behind the schedule is never rendered.

Warning

The linear radiant-exposure law is a pulse2percept assumption, not a dose-response function reported by [Ho2018]. It reads no wavelength and no pixel design, so two devices delivering the same radiant exposure drive the retina identically. Irradiance, pulse duration, repetition rate and wavelength remain separately available on the stimulus.

Added in version 0.11.0.

Parameters:

implant (Implant) – Photovoltaic implant whose pixel geometry is modeled. Its encoder converts images and videos into an optical schedule.
rho (float or Quantity, optional) –
Gaussian spatial decay constant in microns. None (default) uses half the implant’s median nearest-neighbor pitch, resolved when the model is built, and raises if the implant has no pitch (fewer than two electrodes at distinct positions).

Important

rho = pitch / 2 is a pulse2percept convention: a spread on the scale of the device, so that neighboring pixels stay resolvable. It is neither a measured perceptual point-spread function nor the receptive-field size [Ho2018] reports. Electrode-retina distance (z) does not affect it, and nonzero z raises a warning.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle, or a retinal extent resolved through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle, or a retinal extent resolved through visual_field_map.
step (float, (float, float), or Quantity, optional) – Grid spacing in degrees of visual angle.
grid_type ({'rect', 'hex'}, optional) – Sampling lattice used for the visual-field grid.
thresh_percept (float, optional) – Drive values below this threshold are set to zero. Ho2018Model leaves this at 0 and thresholds the percept instead, since subthreshold drive still sums over pulses.
min_current_spread (float, optional) – Fraction of peak Gaussian spread below which a pixel 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.
n_gray (int or None, optional) – Number of gray levels in the returned drive map. Quantizing drive changes what a temporal stage integrates, so Ho2018Model does not expose it.
implant_position ((x, y) or Quantity, optional) – Position of the device-local origin, in tissue coordinates or dva.
implant_rotation (float or Quantity, optional) – In-plane rotation (deg), positive counter-clockwise.
implant_depth (float or Quantity, optional) – Signed offset (um) along the normal of a 2D tissue map.
location_noise (float or None, optional) – Standard deviation of fixed pixel-specific phosphene offsets, in dva.
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.

stimulus_unit = mW/mm^2[source]: An optical schedule, not injected current.

extra_stimulus_units = (): A normalized drive no longer carries the irradiance and ON duration the activation law requires.

get_default_params()[source]: Return all settable parameters of the spatial response.

build(**build_params)[source]

Build the model

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

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

property implant

The prosthesis system whose geometry this model uses.

Rebinding invalidates the spatial build.

Added in version 0.11.0.

property is_built: Return whether the grid matches the current retinal laterality

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

Added in version 0.11.0.

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

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

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

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

class pulse2percept.models.retina.Ho2018Temporal(*, n=6, tau1=51.3, tau2=137.1, p1=1.0, p2=0.3743, dt=0.005, thresh_percept=0, reduce='last', verbose=True, n_threads=None, n_jobs=None)[source]

Network-mediated temporal response of [Ho2018].

[Ho2018] summarizes photovoltaic spike-triggered-average time courses as a difference of two low-pass cascades [Chichilnisky2002]:

\[h(t) = p_1 \left(\frac{t}{\tau_1}\right)^{n} e^{-n\left(t/\tau_1 - 1\right)} - p_2 \left(\frac{t}{\tau_2}\right)^{n} e^{-n\left(t/\tau_2 - 1\right)}, \qquad t \geq 0.\]

Each term peaks at \(t = \tau_i\) with amplitude \(p_i\); \(\tau_1 < \tau_2\) makes the filter biphasic and band-pass.

Each input sample is one pulse period’s radiant-exposure drive, applied as an impulse at that sample time. For drives \(d_k\) at pulse onsets \(t_k\),

\[B(t) = \max\left[ g \sum_k d_k \, h(t - t_k), \; 0 \right],\]

with \(g\) normalizing \(h\) to unit peak, so one reference pulse (9 mW/mm^2 for 4 ms) peaks at a drive of 1. Evaluated in closed form at the requested output times; dt only fixes the lattice they lie on.

Rectification models the pON pathway: a negative excursion is a drop below the spontaneous firing rate, which Percept brightness cannot represent.

Input is network-response drive, not stimulation. In a Ho2018Model that is the percept Ho2018Spatial returns; used alone, this model also accepts a dimensionless normalized drive. Injected current and raw gray levels are refused.

Warning

The functional form and the timing landmarks come from [Ho2018], the coefficients do not: [Ho2018] publishes none. Given n=6, p1=1 and zero DC gain (\(p_1\tau_1 = p_2\tau_2\), which makes the filter purely transient), tau1, tau2 and p2 are the unique solution reproducing Table 1 of [Ho2018] – the per-cell RCS pON summary of a 50 +/- 3 ms first peak and a 94 +/- 5 ms first zero crossing. Averaged per retina the same paper reports 51 +/- 3 ms and 87 +/- 3 ms, and the 20 Hz white-noise stimulus sampled the time course only every 50 ms, so both landmarks are coarse.

Added in version 0.11.0.

Parameters:

n (float, optional) – Order of both cascades. The default 6 is a pulse2percept choice; any n >= 4 can reproduce the two landmarks.
tau1 (float or Quantity, optional) – Time constant (ms) of the fast, positive cascade.
tau2 (float or Quantity, optional) – Time constant (ms) of the slow, negative cascade.
p1 (float, optional) – Peak amplitude of the fast cascade.
p2 (float, optional) – Peak amplitude of the slow cascade.
dt (float or Quantity, optional) – Lattice (ms) output times must be multiples of.
thresh_percept (float, optional) – Brightness values below this threshold are set to zero.
reduce ({'last', 'peak'}, optional) – How automatically chosen output points summarize the preceding interval. 'last' is the value at the output instant, which this model computes exactly. 'peak' is approximated by sampling each interval eight times, and on a pulse train whose period is comparable to tau1 it can underestimate the true peak by tens of percent.
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.

stimulus_unit = dimensionless[source]: Normalized network drive, not injected current.

get_default_params()[source]: Return all settable parameters of the temporal response.

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

impulse_response(t)[source]

Return the unnormalized filter \(h(t)\).

Parameters:: t (array-like) – Time (ms) since the pulse. Negative times return zero.

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

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

class pulse2percept.models.retina.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)[source]

Predict a percept.

Parameters:

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

Returns:

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

property 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.retina.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.retina.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)[source]

Predict a percept.

Parameters:

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

Returns:

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

property 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.retina.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 model

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

property implant

The prosthesis system whose geometry this model uses.

Rebinding invalidates the spatial build.

Added in version 0.11.0.

property is_built: Return whether the grid matches the current retinal laterality

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

Added in version 0.11.0.

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

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

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.retina.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.retina.RetinalSpatial(implant, **params)[source]

Abstract base class for spatial models of retinal stimulation.

Adds to SpatialModel the behavior that is specific to simulating the retina:

a retinotopic visual_field_map by default ([Curcio1990]);
xrange and yrange may be given as a physical retinal extent, which is resolved through visual_field_map.

Parameters:

implant (Implant) – Implant whose electrode geometry is modeled.
xrange ((float, float) or Quantity, optional) – Horizontal visual-field extent in degrees of visual angle. A physical retinal extent is accepted as shorthand and is resolved along the horizontal retinal meridian through visual_field_map.
yrange ((float, float) or Quantity, optional) – Vertical visual-field extent in degrees of visual angle. A physical retinal extent is resolved along the vertical meridian.
visual_field_map (VisualFieldMap, optional) – Retinotopic map between visual-field and retinal coordinates.
**params (keyword arguments) – Any other parameter of SpatialModel.

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

property is_built: Return whether the grid matches the current retinal laterality

build(**build_params)[source]

Build the model

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

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

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

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

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

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

Plot the model

Parameters:

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

Added in version 0.11.0.

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

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.

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.retina.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. For photovoltaic implants, PhotovoltaicEncoder instead provides normalized optical drive. Scoreboard visualizes the stimulation pattern; it does not model photovoltaic conversion or the retinal response.

Note

For this spatial-only model, dimensionless image and video values are treated as relative electrode amplitudes, so an implant encoder is not required. Physical or pulse-dependent models still require encoded stimulation.

Warning

rho is fixed: this model does not predict pulse-dependent phosphene size. Doubling amplitude doubles brightness and leaves the phosphene exactly as wide, which is not what [Nanduri2012] reports. Use BiphasicScoreboardModel for pulse-dependent brightness and size.

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)[source]

Predict a percept.

Parameters:

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

Returns:

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

property 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.retina.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. For photovoltaic implants, PhotovoltaicEncoder instead provides normalized optical drive. Scoreboard visualizes the stimulation pattern; it does not model photovoltaic conversion or the retinal response.

Warning

rho is fixed: this model does not predict pulse-dependent phosphene size. Doubling amplitude doubles brightness and leaves the phosphene exactly as wide, which is not what [Nanduri2012] reports. Use BiphasicScoreboardSpatial for pulse-dependent brightness and size.

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

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 model

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: Return whether the grid matches the current retinal laterality

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

Added in version 0.11.0.

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

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

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.retina.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)[source]

Predict a percept.

Parameters:

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

Returns:

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

property 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.retina.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 model

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: Return whether the grid matches the current retinal laterality

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

Added in version 0.11.0.

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

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

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