pulse2percept.models.retina.beyeler2019

AxonMapModel, AxonMapSpatial [Beyeler2019]

Classes

`AxonMapModel`(implant, *[, rho, lam, xrange, ...])	Axon map model of [Beyeler2019].
`AxonMapSpatial`(implant, *[, rho, lam, ...])	Axon map model of [Beyeler2019] (spatial module only).
`ScoreboardModel`(implant, *[, rho, xrange, ...])	Scoreboard model of [Beyeler2019].
`ScoreboardSpatial`(implant, *[, rho, xrange, ...])	Scoreboard model of [Beyeler2019] (spatial module only).

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