pulse2percept.models.retina.ho2018

Ho2018Model, Ho2018Spatial, Ho2018Temporal [Ho2018]

Module Attributes

`REF_IRRADIANCE`	Peak irradiance (mW/mm^2) of the [Ho2018] white-noise condition, which the activation law normalizes against.
`REF_PULSE_DUR`	ON duration (ms) of the [Ho2018] white-noise condition.

Classes

`Ho2018Model`(implant, *[, rho, xrange, ...])	Network-mediated photovoltaic response model of [Ho2018].
`Ho2018Spatial`(implant, *[, rho, xrange, ...])	Network-mediated spatial response of [Ho2018] (spatial module only).
`Ho2018Temporal`(*[, n, tau1, tau2, p1, p2, ...])	Network-mediated temporal response of [Ho2018].

pulse2percept.models.retina.ho2018.REF_IRRADIANCE = 9.0: Peak irradiance (mW/mm^2) of the [Ho2018] white-noise condition, which the activation law normalizes against.

pulse2percept.models.retina.ho2018.REF_PULSE_DUR = 4.0: ON duration (ms) of the [Ho2018] white-noise condition.

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