pulse2percept.models.retina.horsager2009

Horsager2009Model, Horsager2009Temporal [Horsager2009]

Classes

Horsager2009Model(*[, dt, tau1, tau2, tau3, ...])	Standalone temporal model of [Horsager2009].
Horsager2009Temporal(*[, dt, tau1, tau2, ...])	Temporal model of [Horsager2009].

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

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

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

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

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.