pulse2percept.models.retina.nanduri2012

Nanduri2012Model, Nanduri2012Spatial, Nanduri2012Temporal [Nanduri2012]

Classes

Nanduri2012Model(implant, *[, atten_a, ...])	Combined spatial-temporal model of [Nanduri2012].
Nanduri2012Spatial(implant, *[, atten_a, ...])	Spatial response model of [Nanduri2012].
Nanduri2012Temporal(*[, dt, tau1, tau2, ...])	Temporal response model of [Nanduri2012].

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

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

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

get_param_units()

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)

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

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

Return default model parameters.

get_param_units()

Return units used to store model parameters.

build(**build_params)

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)

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)

Set the parameters of this object

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

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

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.