pulse2percept.models.retina.granley2021

BiphasicAxonMapModel, BiphasicAxonMapSpatial, BiphasicScoreboardModel, BiphasicScoreboardSpatial [Granley2021]

Classes

BiphasicAxonMapModel(implant, *[, ...])	Biphasic axon-map model of [Granley2021].
BiphasicAxonMapSpatial(implant, *[, ...])	Biphasic axon-map model of [Granley2021] (spatial module only).
BiphasicScoreboardModel(implant, *[, ...])	Biphasic scoreboard model.
BiphasicScoreboardSpatial(implant, *[, ...])	Biphasic scoreboard model (spatial module only).
DefaultBrightModel(*[, a0, a1, a2, a3, a4])	Brightness scaling from [Granley2021].
DefaultSizeModel(rho, *[, a0, a1, a5, a6, ...])	Phosphene-size scaling from [Granley2021].
DefaultStreakModel(lam, *[, a7, a8, a9, ...])	Phosphene-streak scaling from [Granley2021].

class pulse2percept.models.retina.granley2021.DefaultBrightModel(*, a0=2.095, a1=0.054326, a2=0.1492147, a3=0.0163851, a4=0)

Brightness scaling from [Granley2021].

Implements the amplitude- and frequency-dependent factor in Eq. 4, using the phase-duration threshold correction from Eq. 3. Coefficients were fit to [Nanduri2012] and [Weitz2015].

The default brightness factor is

\[F_{\mathrm{bright}} = a_2 \tilde{a} + a_3 f + a_4,\]

where \(f\) is pulse frequency and \(\tilde{a}\) is threshold-scaled amplitude.

Parameters:

• a0 (float, optional) – Slope and intercept of the phase-duration threshold correction, a0 * pdur + a1.

• a1 (float, optional) – Slope and intercept of the phase-duration threshold correction, a0 * pdur + a1.

• a2 (float, optional) – Coefficient for threshold-scaled amplitude in Eq. 4.

• a3 (float, optional) – Coefficient for frequency in Eq. 4.

• a4 (float, optional) – Intercept in Eq. 4.

get_default_params()

Return a dict of user-settable parameters

scale_threshold(pdur)

Return the phase-duration threshold scaling from Eq. 3.

Uses the Argus II refit to [Horsager2009] data rather than the coefficients in the original publication.

predict_freq_amp(amp, freq)

Return the Eq. 4 brightness factor.

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

get_param_units()

Return storage units for physical parameters.

Subclasses should extend this mapping. Parameters not listed here take plain dimensionless values.

Added in version 0.10.0.

property is_built

A read-only flag indicating whether the model has been built

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.granley2021.DefaultSizeModel(rho, *, a0=2.095, a1=0.054326, a5=1.0812, a6=-0.35338, min_rho=10)

Phosphene-size scaling from [Granley2021].

Implements the size scaling of [Granley2021], using p2p’s Argus II phase-duration threshold refit (i.e., different from Eq. 5 in the published paper).

With threshold-scaled amplitude \(\tilde{a}\), the default size factor is

\[F_{\mathrm{size}} = \max\left( a_5 \tilde{a} + a_6,\, \frac{\mathrm{min\_rho}^2}{\rho^2} \right),\]

so that

\[\rho_{\mathrm{eff}} = \rho \sqrt{F_{\mathrm{size}}} \geq \mathrm{min\_rho}.\]

Parameters:

• rho (float or Quantity, optional) –

  Baseline Gaussian spatial decay away from the axon, in microns. Larger values produce broader phosphenes. The effective spatial spread is additionally modulated by amplitude and pulse duration according to [Granley2021].

  Important

  Electrode-retina distance (z) does not directly affect rho. Electrode-specific detection thresholds may capture its effect on stimulation sensitivity, but not on baseline spatial spread.

• min_rho (float or Quantity, optional) – Minimum effective rho, in microns. Prevents pulse-dependent size scaling from shrinking the spatial decay below this value.

• a0 (float, optional) – Slope and intercept of the phase-duration threshold correction, a0 * pdur + a1.

• a1 (float, optional) – Slope and intercept of the phase-duration threshold correction, a0 * pdur + a1.

• a5 (float, optional) – Coefficient for threshold-scaled amplitude in Eq. 5.

• a6 (float, optional) – Intercept in Eq. 5.

get_default_params()

Return a dict of user-settable parameters

get_param_units()

Return units used to store model parameters.

scale_threshold(pdur)

Return the phase-duration threshold scaling from Eq. 3.

Uses the Argus II refit to [Horsager2009] data rather than the coefficients in the original publication.

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

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.granley2021.DefaultStreakModel(lam, *, a7=0.54, a8=0.21, a9=1.56, min_lambda=10)

Phosphene-streak scaling from [Granley2021].

Implements the pulse-duration-dependent factor in Eq. 6. Coefficients were fit to [Weitz2015].

The default streak-length factor is

\[F_{\mathrm{streak}} = \max\left( a_9 - a_7 t^{a_8},\, \frac{\mathrm{min\_lambda}^2}{\lambda^2} \right),\]

where \(t\) is phase duration. Therefore

\[\lambda_{\mathrm{eff}} = \lambda \sqrt{F_{\mathrm{streak}}} \geq \mathrm{min\_lambda}.\]

Parameters:

• lam (float or Quantity, optional) – Baseline Gaussian decay along the axon, in microns. Larger values produce longer phosphene streaks. The effective decay is additionally modulated by pulse duration according to [Granley2021].

• min_lambda (float or Quantity, optional) – Minimum effective lam, in microns. Prevents pulse-dependent streak-length scaling from shrinking the axonal decay below this value.

• a7 (float, optional) – Regression coefficients in a9 - a7 * pdur ** a8.

• a8 (float, optional) – Regression coefficients in a9 - a7 * pdur ** a8.

• a9 (float, optional) – Regression coefficients in a9 - a7 * pdur ** a8.

get_default_params()

Return a dict of user-settable 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

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.granley2021.BiphasicAxonMapSpatial(implant, *, bright_model=None, size_model=None, streak_model=None, 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)

Biphasic axon-map model of [Granley2021] (spatial module only).

Extends AxonMapSpatial with the stimulus-dependent brightness, size, and streak-length scaling of [Granley2021]. The model returns one representative spatial percept for the full biphasic pulse train.

Stimuli must describe the cathodic-first pulse train they deliver, rather than only its samples: either retained BiphasicPulseTrain objects, or a still image encoded with the standard biphasic encoder pulse (see AmplitudeEncoder). Amplitude may be given in multiples of perceptual threshold (xTh) or as current when a threshold calibration is available.

Encoded still images use the device-resolved amplitude, phase duration, and frequency; exact pulse-onset timing and interphase duration are ignored. Videos are not supported.

Custom effect models must be callables with signature f(freq, amp, pdur). Their arguments are frequency, amplitude in multiples of threshold, and phase duration.

When paired with a temporal model, this spatial prediction is treated as the peak percept and multiplied by a normalized temporal response.

The spatial response is

\[I(r, \theta) = \max_{p \in R(\theta)} \sum_{e \in E} F_{\mathrm{bright}} \exp\left( -\frac{d_e^2}{2 \rho^2 F_{\mathrm{size}}} -\frac{d_{\mathrm{soma}}^2} {2 \lambda^2 F_{\mathrm{streak}}} \right),\]

where \(d_e\) is the distance from an axon segment to electrode \(e\), and \(d_{\mathrm{soma}}\) is the path length from that segment to the ganglion cell body. Thus the effective spatial scales are

\[\rho_{\mathrm{eff}} = \rho \sqrt{F_{\mathrm{size}}}, \qquad \lambda_{\mathrm{eff}} = \lambda \sqrt{F_{\mathrm{streak}}}.\]

Parameters:

• implant (Implant) –

  Implant whose electrode geometry and eye are modeled.

  Added in version 0.11.0.

• bright_model (callable, optional) – Maps (freq, amp, pdur) to a multiplicative brightness factor. Defaults to DefaultBrightModel.

• size_model (callable, optional) – Maps (freq, amp, pdur) to F_size, which scales rho ** 2. Defaults to DefaultSizeModel.

• streak_model (callable, optional) – Maps (freq, amp, pdur) to F_streak, which scales lam ** 2. Defaults to DefaultStreakModel.

• rho (float or Quantity, optional) – Gaussian decay constant for spread from an electrode to nearby axon segments, in microns. Larger values broaden the percept.

• 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. 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) – Fraction of peak current spread below which an electrode may be skipped at an axon segment. The cutoff is scaled by F_size. Set to 0 to disable.

• 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.

get_default_params()

Return a dictionary of default values for all model parameters

build(**build_params)

Build the model

Parameters:

**build_params (keyword arguments) – Declared model parameters to set before building.

Return type:

self

calc_axon_sensitivity(bundles)

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)

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)

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

extra_stimulus_units = (xTh,)

Amplitude may be given in multiples of perceptual threshold.

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.

find_closest_axon(bundles, xret=None, yret=None, return_index=False, return_segment=False)

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.

get_param_units()

Return units used to store model parameters.

grow_axon_bundles(n_bundles=None, prune=True)

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

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 axon map matches the implant’s current eye.

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', annotate=True, autoscale=True, ax=None, figsize=None, show_implant=False)

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

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.granley2021.BiphasicAxonMapModel(implant, *, bright_model=None, size_model=None, streak_model=None, 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)

Biphasic axon-map model of [Granley2021].

Extends AxonMapModel with the stimulus-dependent brightness, size, and streak-length scaling of [Granley2021]. The model returns one representative percept for the full biphasic pulse train.

Stimuli must describe the cathodic-first pulse train they deliver, rather than only its samples: either retained BiphasicPulseTrain objects, or a still image encoded with the standard biphasic encoder pulse (see AmplitudeEncoder). Give amplitude in multiples of perceptual threshold (xTh) or provide a threshold calibration for current-valued amplitudes. Threshold is the 50%-detection current for a train at the same frequency and 0.45 ms phase duration [Granley2021]; the model applies its own phase-duration correction.

Encoded still images use the device-resolved amplitude, phase duration, and frequency; exact pulse-onset timing is ignored. Videos are not supported.

Interphase duration is accepted but ignored: the effect models read only amplitude, frequency, and phase duration.

Custom effect models must be callables with signature f(freq, amp, pdur). Their arguments are frequency, amplitude in multiples of threshold, and phase duration.

The spatial response is

\[I(r, \theta) = \max_{p \in R(\theta)} \sum_{e \in E} F_{\mathrm{bright}} \exp\left( -\frac{d_e^2}{2 \rho^2 F_{\mathrm{size}}} -\frac{d_{\mathrm{soma}}^2} {2 \lambda^2 F_{\mathrm{streak}}} \right),\]

where \(d_e\) is the distance from an axon segment to electrode \(e\), and \(d_{\mathrm{soma}}\) is the path length from that segment to the ganglion cell body. Thus the effective spatial scales are

\[\rho_{\mathrm{eff}} = \rho \sqrt{F_{\mathrm{size}}}, \qquad \lambda_{\mathrm{eff}} = \lambda \sqrt{F_{\mathrm{streak}}}.\]

Parameters:

• implant (Implant) –

  Implant whose electrode geometry and eye are modeled.

  Added in version 0.11.0.

• bright_model (callable, optional) – Maps (freq, amp, pdur) to a multiplicative brightness factor. Defaults to DefaultBrightModel.

• size_model (callable, optional) – Maps (freq, amp, pdur) to F_size, which scales rho ** 2. Defaults to DefaultSizeModel.

• streak_model (callable, optional) – Maps (freq, amp, pdur) to F_streak, which scales lam ** 2. Defaults to DefaultStreakModel.

• rho (float or Quantity, optional) – Gaussian decay constant for spread from an electrode to nearby axon segments, in microns. Larger values broaden the percept.

• 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. 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) – Fraction of peak current spread below which an electrode may be skipped at an axon segment. The cutoff is scaled by F_size. Set to 0 to disable.

• 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.

Examples

A picture, a device that encodes it, and a participant’s measured threshold:

import pulse2percept as p2p

implant = p2p.implants.retina.ArgusII(thresholds=80 * p2p.units.uA)
model = p2p.models.retina.BiphasicAxonMapModel(implant=implant)
percept = model.predict_percept(p2p.stimuli.samples.logo_bvl())

An encoder that asks for threshold multiples in the first place needs no measured threshold:

encoder = p2p.stimuli.AmplitudeEncoder(
    amp_range=(0 * p2p.units.xTh, 3 * p2p.units.xTh))
implant = p2p.implants.retina.ArgusII(encoder=encoder)
model = p2p.models.retina.BiphasicAxonMapModel(implant=implant)
percept = model.predict_percept(p2p.stimuli.samples.logo_bvl())

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.

class pulse2percept.models.retina.granley2021.BiphasicScoreboardSpatial(implant, *, bright_model=None, size_model=None, 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)

Biphasic scoreboard model (spatial module only).

Spatial component of BiphasicScoreboardModel, for pairing with a temporal model in a Model. The stimulus contract, effect models, spatial response, and validation caveat are described there. In a composite model this spatial prediction is treated as the peak percept and multiplied by a normalized temporal response.

Parameters:

• implant (Implant) – Implant whose electrode geometry is modeled.

• bright_model (callable, optional) – Maps (freq, amp, pdur) to a multiplicative brightness factor. Defaults to DefaultBrightModel.

• size_model (callable, optional) – Maps (freq, amp, pdur) to F_size, which scales rho ** 2. Defaults to DefaultSizeModel.

• rho (float or Quantity, optional) –

  Baseline Gaussian spatial decay constant in microns, before F_size scaling. Larger values produce broader phosphenes.

  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.

• 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. The cutoff is scaled by F_size. Set to 0 to disable.

• 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.

• 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 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.

• 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.

• versionadded: (..) – 0.11.0:

get_default_params()

Return all settable scoreboard 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 = (xTh,)

Amplitude may be given in multiples of perceptual threshold.

get_param_units()

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)

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.granley2021.BiphasicScoreboardModel(implant, *, bright_model=None, size_model=None, 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)

Biphasic scoreboard model.

Extends ScoreboardModel with the stimulus-dependent brightness and size scaling of [Granley2021], but without the axonal streak term of BiphasicAxonMapModel: phosphenes stay round and centered on the electrode.

Stimuli must describe the cathodic-first pulse train they deliver, rather than only its samples: either retained BiphasicPulseTrain objects, or a still image encoded with the standard biphasic encoder pulse (see AmplitudeEncoder). Give amplitude in multiples of perceptual threshold (xTh) or provide a threshold calibration for current-valued amplitudes. Threshold is the 50%-detection current for a train at the same frequency and 0.45 ms phase duration [Granley2021]; the model applies its own phase-duration correction. Bare amplitudes and raw waveforms are rejected.

Encoded still images use the device-resolved amplitude, phase duration, and frequency; exact pulse-onset timing is ignored. Videos are not supported.

Interphase duration is accepted but ignored: the effect models read only amplitude, frequency, and phase duration.

Custom effect models must be callables with signature f(freq, amp, pdur). Their arguments are frequency, amplitude in multiples of threshold, and phase duration.

The spatial response is

\[I(x, y) = \sum_{e \in E} F_{\mathrm{bright}} \exp\left( -\frac{(x-x_e)^2 + (y-y_e)^2}{2 \rho^2 F_{\mathrm{size}}} \right),\]

so the effective spatial scale is \(\rho_{\mathrm{eff}} = \rho \sqrt{F_{\mathrm{size}}}\).

Note

The brightness and size functions are the empirical fits of [Granley2021] (Eqs. 4-5), but this focal combination – those fits without the axonal streak term – is not the model that paper validated. [Granley2021] assumes an epiretinal implant and treats axonal activation as part of phosphene shape, so here rho alone carries the apparent size. The underlying psychophysics ([Nanduri2012], [Weitz2015]) is likewise epiretinal.

Parameters:

• implant (Implant) – Implant whose electrode geometry is modeled.

• bright_model (callable, optional) – Maps (freq, amp, pdur) to a multiplicative brightness factor. Defaults to DefaultBrightModel.

• size_model (callable, optional) – Maps (freq, amp, pdur) to F_size, which scales rho ** 2. Defaults to DefaultSizeModel.

• rho (float or Quantity, optional) –

  Baseline Gaussian spatial decay constant in microns, before F_size scaling. Larger values produce broader phosphenes.

  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.

• 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. The cutoff is scaled by F_size. Set to 0 to disable.

• 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.

• 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 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.

• 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.

• versionadded: (..) – 0.11.0:

Examples

A pulse train given in threshold multiples:

import pulse2percept as p2p

model = p2p.models.retina.BiphasicScoreboardModel(
    p2p.implants.retina.ArgusII())
train = p2p.stimuli.BiphasicPulseTrain(20, 2 * p2p.units.xTh, 0.45)
percept = model.predict_percept({'C5': train})

A picture, a device that encodes it, and a participant’s measured threshold:

implant = p2p.implants.retina.ArgusII(thresholds=80 * p2p.units.uA)
model = p2p.models.retina.BiphasicScoreboardModel(implant=implant)
percept = model.predict_percept(p2p.stimuli.samples.logo_bvl())

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.