pulse2percept.models.retina.thompson2003

Thompson2003Model, Thompson2003Spatial [Thompson2003]

Classes

Thompson2003Model(implant, *[, radius, ...])	Standalone spatial model of [Thompson2003].
Thompson2003Spatial(implant, *[, radius, ...])	Spatial model of [Thompson2003].

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

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

Return default model parameters.

get_param_units()

Return units used to store model parameters.

build(**build_params)

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)

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)

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)

Set the parameters of this model

space_unit = um

The unit spatial coordinates are expressed in

stimulus_unit = uA

The unit stimulus values are expressed in

time_unit = ms

The unit time is expressed in

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

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

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)

Plot the spatial model.

Parameters and return value are those of plot().

predict_percept(source, t_percept=None, gaze=None)

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.