pulse2percept.models

Computational models of the prosthetic vision, such as phosphene and neural response models. Cortical models are in the cortex submodule.

`cortex`	Phosphene models for cortical implants
`base`	`BaseModel`, `Model`, `NotBuiltError`, `SpatialModel`, `TemporalModel`
`temporal`	`FadingTemporal`
`thompson2003`	`Thompson2003Model`, `Thompson2003Spatial` [Thompson2003]
`horsager2009`	`Horsager2009Model`, `Horsager2009Temporal [Horsager2009]
`nanduri2012`	`Nanduri2012Model`, `Nanduri2012Spatial`, `Nanduri2012Temporal` [Nanduri2012]
`beyeler2019`	`AxonMapModel`, `AxonMapSpatial` [Beyeler2019]
`granley2021`	`BiphasicAxonMapModel`, `BiphasicAxonMapSpatial` [Granley2021]

See also

Basic Concepts > Computational Models

class pulse2percept.models.AxonMapModel(**params)[source]

Axon map model of [Beyeler2019] (standalone model)

Implements the axon map model described in [Beyeler2019], where percepts are elongated along nerve fiber bundle trajectories of the retina.

Parameters:

lam (double, optional) –
Exponential decay constant along the axon(microns).

Changed in version 0.10.0: Renamed from axlambda, which reads poorly next to rho. The old name still works, but is deprecated and will be removed in v0.11.0.
rho (double, optional) – Exponential decay constant away from the axon(microns).
min_current_spread (float, optional) – An electrode is skipped at axon segments where its Gaussian current spread has decayed below this fraction of its peak. The default (1e-8, about 6.1 rho away) drops the Gaussian times the stimulus amplitude, summed over the skipped electrodes, so the error at a point is bounded by min_current_spread times the summed amplitude across electrodes.
eye ({'RE', LE'}, optional) – Eye for which to generate the axon map.
xrange ((x_min, x_max), optional) – A tuple indicating the range of x values to simulate (in degrees of visual angle). In a right eye, negative x values correspond to the temporal retina, and positive x values to the nasal retina. In a left eye, the opposite is true.
yrange ((y_min, y_max), optional) – A tuple indicating the range of y values to simulate (in degrees of visual angle). Negative y values correspond to the superior retina, and positive y values to the inferior retina.
step (int or double or tuple, optional) –
Step size for the range of (x,y) values to simulate (in degrees of visual angle). For example, to create a grid with x values [0, 0.5, 1] use xrange=(0, 1) and step=0.5. Pass a tuple to give the x and y axes different step sizes.

Changed in version 0.10.0: Renamed from xystep, which suggested that one step size applies to both axes. The old name still works, but is deprecated and will be removed in v0.11.0.
grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
vfmap (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides retinotopic mappings. By default, Watson2014Map is used.
n_gray (int, optional) – The number of gray levels to use. If an integer is given, k-means clustering is used to compress the color space of the percept into n_gray bins. If None, no compression is performed.
noise (float or int, optional) – Adds salt-and-pepper noise to each percept frame. An integer will be interpreted as the number of pixels to subject to noise in each frame. A float between 0 and 1 will be interpreted as a ratio of pixels to subject to noise in each frame.
loc_od ((x,y), optional) – Location of the optic disc in degrees of visual angle. Note that the optic disc in a left eye will be corrected to have a negative x coordinate.
loc_od – Location of the optic disc in degrees of visual angle. Note that the optic disc in a left eye will be corrected to have a negative x coordinate.
n_axons (int, optional) – Number of axons to generate.
axons_range ((min, max), optional) – The range of angles(in degrees) at which axons exit the optic disc. This corresponds to the range of $phi_0$ values used in [Jansonius2009].
n_ax_segments (int, optional) – Number of segments an axon is made of.
ax_segments_range ((min, max), optional) – Lower and upper bounds for the radial position values(polar coords) for each axon.
min_ax_sensitivity (float, optional) – Axon segments whose contribution to brightness is smaller than this value will be pruned to improve computational efficiency. Set to a value between 0 and 1.
axon_pickle (str, optional) – File name in which to store precomputed axon maps.
ignore_pickle (bool, optional) – A flag whether to ignore the pickle file in future calls to model.build().
n_threads (int, optional) – Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.
n_jobs (int, optional) – Alias for n_threads; None or -1 uses every core.
:: (.. important) – If you change important model parameters outside the constructor (e.g., by directly setting model.lam = 100), you will have to call model.build() again for your changes to take effect.

Notes

The axon map is not very accurate when the upper bound of ax_segments_range is greater than 90 deg.

predict_percept(implant, t_percept=None)[source]

Predict a percept

Important

You must call build before calling predict_percept.

Parameters:

implant (ProsthesisSystem) – A valid prosthesis system. A stimulus can be passed via stim().
t_percept (float or list of floats, optional) – The time points at which to output a percept, counted in this model’s time_unit (milliseconds, for every model p2p ships). If None, implant.stim.time is used. May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units.

Returns:

percept – A Percept object whose data container has dimensions Y x X x T. Will return None if implant.stim is None.

Return type:

Percept

build(**build_params)[source]

Build the model

Performs expensive one-time calculations, such as building the spatial grid used to predict a percept.

Parameters:: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params. Trying to add new class attributes outside of that will cause a FreezeError. Example: model.build(param1=val)
Return type:: self

find_threshold(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]

Find the threshold current for a certain stimulus

Estimates amp_th such that the output of model.predict_percept(stim(amp_th)) is approximately bright_th.

Parameters:

implant (ProsthesisSystem) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated until amp_th is found.
bright_th (float) – Model output (brightness) that’s considered “at threshold”.
amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search, counted in this model’s stimulus_unit (microamps, for every model p2p ships).
amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within amp_tol
bright_tol (float, optional) – Search will stop if model brightness is within bright_tol of bright_th
max_iter (int, optional) – Search will stop after max_iter iterations
t_percept (float or list of floats, optional) – The time points at which to output a percept, counted in this model’s time_unit (milliseconds, for every model p2p ships). If None, implant.stim.time is used. May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units.

Returns:

amp_th – Threshold current, in stimulus_unit, estimated so that the output of model.predict_percept(stim(amp_th)) is within bright_tol of bright_th.

Return type:

float

Notes

amp_range, amp_tol and t_percept may be given as unitful quantities; the answer comes back as a plain number of microamps. bright_th and bright_tol are model output, which is not a physical quantity and carries no unit. See pulse2percept.units.

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 is_built: Returns True if the build model has been called

set_params(params)[source]

Set model parameters

This is a convenience function to set parameters that might be part of the spatial model, the temporal model, or both.

Alternatively, you can set the parameter directly, e.g. model.spatial.verbose = True.

Note

If a parameter exists in both spatial and temporal models(e.g., verbose), both models will be updated.

Parameters:: params (dict) – A dictionary of parameters to set.

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

The unit time is expressed in

t_percept is read in, and the resulting Percept is written in, the unit of the last stage of the pipeline: the temporal model if there is one, the spatial model otherwise. The two need not agree – a spatial model counting in seconds hands its percept to a temporal model counting in milliseconds and the time axis is converted on the way across.

class pulse2percept.models.AxonMapSpatial(**params)[source]

Axon map model of [Beyeler2019] (spatial module only)

Implements the axon map model described in [Beyeler2019], where percepts are elongated along nerve fiber bundle trajectories of the retina.

Parameters:

lam (double, optional) –
Exponential decay constant along the axon(microns).

Changed in version 0.10.0: Renamed from axlambda, which reads poorly next to rho. The old name still works, but is deprecated and will be removed in v0.11.0.
rho (double, optional) – Exponential decay constant away from the axon(microns).
min_current_spread (float, optional) – An electrode is skipped at axon segments where its Gaussian current spread has decayed below this fraction of its peak. The default (1e-8, about 6.1 rho away) drops the Gaussian times the stimulus amplitude, summed over the skipped electrodes, so the error at a point is bounded by min_current_spread times the summed amplitude across electrodes.
eye ({'RE', LE'}, optional) – Eye for which to generate the axon map.
xrange ((x_min, x_max), optional) – A tuple indicating the range of x values to simulate (in degrees of visual angle). In a right eye, negative x values correspond to the temporal retina, and positive x values to the nasal retina. In a left eye, the opposite is true.
yrange ((y_min, y_max), optional) – A tuple indicating the range of y values to simulate (in degrees of visual angle). Negative y values correspond to the superior retina, and positive y values to the inferior retina.
step (int or double or tuple, optional) –
Step size for the range of (x,y) values to simulate (in degrees of visual angle). For example, to create a grid with x values [0, 0.5, 1] use xrange=(0, 1) and step=0.5. Pass a tuple to give the x and y axes different step sizes.

Changed in version 0.10.0: Renamed from xystep, which suggested that one step size applies to both axes. The old name still works, but is deprecated and will be removed in v0.11.0.
grid_type ({'rectangular', 'hexagonal'}, optional) – Whether to simulate points on a rectangular or hexagonal grid
vfmap (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides retinotopic mappings. By default, Watson2014Map is used.
n_gray (int, optional) – The number of gray levels to use. If an integer is given, k-means clustering is used to compress the color space of the percept into n_gray bins. If None, no compression is performed.
noise (float or int, optional) – Adds salt-and-pepper noise to each percept frame. An integer will be interpreted as the number of pixels to subject to noise in each frame. A float between 0 and 1 will be interpreted as a ratio of pixels to subject to noise in each frame.
loc_od ((x,y), optional) – Location of the optic disc in degrees of visual angle. Note that the optic disc in a left eye will be corrected to have a negative x coordinate.
loc_od – Location of the optic disc in degrees of visual angle. Note that the optic disc in a left eye will be corrected to have a negative x coordinate.
n_axons (int, optional) – Number of axons to generate.
axons_range ((min, max), optional) – The range of angles(in degrees) at which axons exit the optic disc. This corresponds to the range of $phi_0$ values used in [Jansonius2009].
n_ax_segments (int, optional) – Number of segments an axon is made of.
ax_segments_range ((min, max), optional) – Lower and upper bounds for the radial position values(polar coords) for each axon.
min_ax_sensitivity (float, optional) – Axon segments whose contribution to brightness is smaller than this value will be pruned to improve computational efficiency. Set to a value between 0 and 1.
axon_pickle (str, optional) – File name in which to store precomputed axon maps.
ignore_pickle (bool, optional) – A flag whether to ignore the pickle file in future calls to model.build().
n_threads (int, optional) – Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.
n_jobs (int, optional) – Alias for n_threads; None or -1 uses every core.
:: (.. important) – If you change important model parameters outside the constructor (e.g., by directly setting model.lam = 100), you will have to call model.build() again for your changes to take effect.

Notes

The axon map is not very accurate when the upper bound of ax_segments_range is greater than 90 deg.

axlambda[source]: lam used to be called axlambda. The old name still reads and writes lam, with a DeprecationWarning:

get_default_params()[source]: Return a dictionary of default values for all model parameters

get_param_units()[source]: Return a dict of the units that parameters are stored in

grow_axon_bundles(n_bundles=None, prune=True)[source]

Grow a number of axon bundles

This method generates the trajectory of a number of nerve fiber bundles based on the mathematical model described in [Beyeler2019], which is based on [Jansonius2009].

Bundles originate at the optic nerve head with initial angle phi0. The method generates n_bundles axon bundles whose phi0 values are linearly sampled from self.axons_range (polar coords). Each axon will consist of self.n_ax_segments segments that span self.ax_segments_range distance from the optic nerve head (polar coords).

Parameters:

n_bundles (int, optional) – Number of axon bundles to generate. If None, self.n_axons is used
prune (bool, optional) – If set to True, will remove axon segments that are outside the simulated area self.xrange, self.yrange for the sake of computational efficiency.

Returns:

bundles – A list of bundles, where every bundle is an Nx2 array consisting of the x,y coordinates of each axon segment (retinal coords, microns). Note that each bundle will most likely have a different N

Return type:

list of Nx2 arrays

find_closest_axon(bundles, xret=None, yret=None, return_index=False, return_segment=False)[source]

Finds the closest axon segment for a point on the retina

This function will search a number of nerve fiber bundles (bundles) and return the bundle that is closest to a particular point (or list of points) on the retinal surface (xret, yret).

Parameters:

bundles (list of Nx2 arrays) – A list of bundles, where every bundle is an Nx2 array consisting of the x,y coordinates of each axon segment (retinal coords, microns). Note that each bundle will most likely have a different N
xret (scalar or list of scalars) – The x,y location on the retina (in microns, where the fovea is the origin) for which to find the closests axon.
yret (scalar or list of scalars) – The x,y location on the retina (in microns, where the fovea is the origin) for which to find the closests axon.
return_index (bool, optional) – If True, the function will also return the index into bundles that represents the closest axon
return_segment (bool, optional) – If True, the function will also return the row index, within the closest bundle, of the segment nearest the point. The search already determines this, so asking for it here saves calc_axon_sensitivity() from working it out again.

Returns:

axon (Nx2 array or list of Nx2 arrays) – For each point in (xret, yret), returns an Nx2 array that represents the closest axon to that point. Each row in the array contains the x,y retinal coordinates (microns) of a particular axon segment.
idx_axon (scalar or list of scalars, optional) – If return_index is True, also returns the index in bundles of the closest axon (or list of closest axons).
idx_segment (scalar or list of scalars, optional) – If return_segment is True, also returns the row index of the closest segment within that axon.

calc_axon_sensitivity(bundles)[source]

Calculate the sensitivity of each axon segment to electrical current

This function combines the x,y coordinates of each bundle segment with a sensitivity value that depends on the distance of the segment to the cell body and self.lam.

The number of bundles must equal the number of points on self.grid`. The function will then assume that the i-th bundle passes through the i-th point on the grid. This is used to determine the bundle segment that is closest to the i-th point on the grid, and to cut off all segments that extend beyond the soma. This effectively transforms a bundle into an axon, where the first axon segment now corresponds with the i-th location of the grid.

After that, each axon segment gets a sensitivity value that depends on the distance of the segment to the soma (with decay rate self.lam). This is typically done during the build process, so that the only work left to do during run time is to multiply the sensitivity value with the current applied to each segment.

Parameters:: bundles (list of Nx2 arrays) – A list of bundles, where every bundle is an Nx2 array consisting of the x,y coordinates of each axon segment (retinal coords, microns). Note that each bundle will most likely have a different N
Returns:: axon_contrib – A list with one entry per point on self.grid. Each entry is a Nx3 array, where the first two columns contain the retinal coordinates of each axon segment (microns), and the third column contains the sensitivity of the segment to electrical current. The latter depends on self.lam. Note that each axon will most likely have a different N, since segments whose sensitivity falls below min_ax_sensitivity are trimmed.
Return type:: list of Nx3 arrays

calc_bundle_tangent(xc, yc)[source]

Calculates orientation of fiber bundle tangent at (xc, yc)

Parameters:

xc (float) – (x, y) retinal location of point at which to calculate bundle orientation in microns.
yc (float) – (x, y) retinal location of point at which to calculate bundle orientation in microns.

Returns:

tangent – An angle in radians

Return type:

scalar

calc_bundle_tangent_fast(xc, yc, bundles=None)[source]

Calculates orientation of fiber bundle tangent at (xc, yc) This function supports multiple queries (xc and yc can be arrays), without requiring growing the axon bundles again for each point (like calc_bundle_tangent). It uses a ckdtree, which will be slower for single points, but significantly faster for multiple points.

Parameters:

xc (array of floats) – (x, y) retinal location of point at which to calculate bundle orientation in microns.
yc (array of floats) – (x, y) retinal location of point at which to calculate bundle orientation in microns.

Returns:

tangent – Angles in radians

Return type:

array of floats

plot(use_dva=False, style='hull', annotate=True, autoscale=True, ax=None, figsize=None)[source]

Plot the axon map

Parameters:

use_dva (bool, optional) – Uses degrees of visual angle (dva) if True, else retinal 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.
annotate (bool, optional) – Flag whether to label the four retinal quadrants
autoscale (bool, optional) – Whether to adjust the x,y limits of the plot
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

build(**build_params)[source]

Build the model

Performs expensive one-time calculations, such as building the spatial grid used to predict a percept. You must call build before calling predict_percept.

Important

Don’t override this method if you are building your own model. Customize _build instead.

Parameters:: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params. Trying to add new class attributes outside of that will cause a FreezeError. Example: model.build(param1=val)

find_threshold(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100)[source]

Find the threshold current for a certain stimulus

Estimates amp_th such that the output of model.predict_percept(stim(amp_th)) is approximately bright_th.

Parameters:

implant (ProsthesisSystem) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated until amp_th is found.
bright_th (float) – Model output (brightness) that’s considered “at threshold”.
amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search, counted in this model’s stimulus_unit (microamps, for every model p2p ships).
amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within amp_tol, in stimulus_unit
bright_tol (float, optional) – Search will stop if model brightness is within bright_tol of bright_th
max_iter (int, optional) – Search will stop after max_iter iterations

Returns:

amp_th – Threshold current, in stimulus_unit, estimated so that the output of model.predict_percept(stim(amp_th)) is within bright_tol of bright_th.

Return type:

float

Notes

amp_range and amp_tol may be given as unitful quantities (e.g. amp_range=(0, 1 * mA)); the answer comes back as a plain number of microamps. bright_th and bright_tol are model output, which is not a physical quantity and carries no unit. See pulse2percept.units.

property is_built: A 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(implant, t_percept=None)[source]

Predict the spatial response

Important

Don’t override this method if you are creating your own model. Customize _predict_spatial instead.

Parameters:

implant (ProsthesisSystem) – A valid prosthesis system. A stimulus can be passed via stim().
t_percept (float or list of floats, optional) – The time points at which to output a percept, counted in this model’s time_unit (milliseconds, for every model p2p ships). If None, implant.stim.time is used. May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units.

Returns:

percept – A Percept object whose data container has dimensions Y x X x T, and whose time axis is labelled in time_unit. Will return None if implant.stim is None.

Return type:

Percept

set_params(**params)[source]: Set the parameters of this object

space_unit = um[source]: The unit spatial coordinates are expressed in

stimulus_unit = uA[source]: The unit stimulus values are expressed in

time_unit = ms[source]: The unit time is expressed in

xystep[source]: step used to be called xystep. The old name still reads and writes step, with a DeprecationWarning:

class pulse2percept.models.BaseModel(**params)[source]

Abstract base class for all models

Adds the build workflow on top of Parametrized, which supplies the parameter, pretty-printing, equality and deep-copy machinery:

Build a model (via build) and flip the is_built switch

Changed in version 0.10.0: Everything other than the build workflow moved to Parametrized.

stimulus_unit = uA[source]: The unit stimulus values are expressed in

space_unit = um[source]: The unit spatial coordinates are expressed in

time_unit = ms[source]: The unit time is expressed in

build(**build_params)[source]

Build the model

Every model must have a `build method, which is meant to perform all expensive one-time calculations. You must call build before calling predict_percept.

Important

Don’t override this method if you are building your own model. Customize _build instead.

Parameters:: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params. Trying to add new class attributes outside of that will cause a FreezeError. Example: model.build(param1=val)

property is_built: A flag indicating whether the model has been built

abstract get_default_params()[source]: Return a dict of user-settable parameters

get_param_units()[source]

Return a dict of the units that parameters are stored in

Maps a parameter name to the Unit that the implementation assumes it is expressed in. A Quantity assigned to such a parameter is checked against that unit and rescaled to it, so that

FadingTemporal(tau=100)
FadingTemporal(tau=100 * ms)
FadingTemporal(tau=0.1 * s)

all store the same float. Bare numbers keep their documented meaning and are passed through untouched.

Parameters absent from this dict take plain numbers: they are either dimensionless (thresh_percept) or empirical fit parameters whose dimension the implementation does not actually commit to. Declaring a unit is a statement about what the equations assume, so a parameter should only appear here when that is documented or unambiguous.

This dict is not restricted to the names in get_default_params: it describes every physical attribute this object normalizes. A constructor argument assigned straight to self – DefaultSizeModel takes rho that way – belongs here too, and is converted like any other.

Subclasses extend rather than replace it:

def get_param_units(self):
    return {**super().get_param_units(), 'dt': ms, 'tau': ms}

Added in version 0.10.0.

set_params(**params)[source]: Set the parameters of this object

class pulse2percept.models.FadingTemporal(**params)[source]

A generic temporal model for phosphene fading

Implements phosphene fading using a leaky integrator driven by the cathodic half of the stimulus:

\[\frac{dB}{dt} = \frac{\max(-A, 0) - B}{\tau}\]

where $A$ is the stimulus amplitude, $B$ is the perceived brightness, and $\tau$ is the exponential decay constant (tau).

The model makes the following assumptions:

Cathodic currents (negative amplitudes) increase perceived brightness
Anodic currents (positive amplitudes) do not, and are ignored
Brightness is bounded below by zero. What is reported is then thresholded, so an output value is either 0 or at least $\theta$ (thresh_percept, a nonnegative scalar)

Changed in version 0.10.0: The drive is now half-wave rectified, driven by the cathodic phase. A stimulus that is purely cathodic is unaffected.

Note

This is the simplest sensical temporal model, not a perceptually validated model of phosphene fading.

Parameters:

dt (float, optional) – Sampling time step of the simulation (ms)
tau (float, optional) –
Time decay constant for the exponential decay (ms). Larger values lead to slower decay. Brightness should decay to half its peak (“half-life”) after $\ln(2) \tau$ milliseconds.

It cannot be shorter than dt. The integrator steps explicitly, so a time constant of one step already carries brightness all the way to its drive; anything shorter overshoots and oscillates. tau also sets the rise, not just the decay, so raising it does not make a percept persist – it makes it dimmer, as $1/\tau$.
thresh_percept (float, optional) – Below threshold, the percept has brightness zero.
reduce ({'peak', 'last'}, optional) – How a percept time point summarizes the interval since the previous one, when predict_percept chooses the output times itself; see TemporalModel. This model tracks the peak inside the integrator, so it is exact at any output rate.
n_threads (int, optional) – Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.
versionadded: (..) – 0.7.1:

get_default_params()[source]: Return a dictionary of default values for all model parameters

get_param_units()[source]: Return a dict of the units that parameters are stored in

build(**build_params)[source]

Build the model

Every model must have a `build method, which is meant to perform all expensive one-time calculations. You must call build before calling predict_percept.

Important

Don’t override this method if you are building your own model. Customize _build instead.

Parameters:: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params. Trying to add new class attributes outside of that will cause a FreezeError. Example: model.build(param1=val)

find_threshold(stim, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]

Find the threshold current for a certain stimulus

Estimates amp_th such that the output of model.predict_percept(stim(amp_th)) is approximately bright_th.

Parameters:

stim (Stimulus) – The stimulus to use. Stimulus amplitude will be up and down regulated until amp_th is found.
bright_th (float) – Model output (brightness) that’s considered “at threshold”.
amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search, counted in this model’s stimulus_unit (microamps, for every model p2p ships).
amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within amp_tol, in stimulus_unit
bright_tol (float, optional) – Search will stop if model brightness is within bright_tol of bright_th
max_iter (int, optional) – Search will stop after max_iter iterations
t_percept (float or list of floats, optional) – The time points at which to output a percept, counted in this model’s time_unit (milliseconds, for every model p2p ships). If None, implant.stim.time is used. May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units.

Returns:

amp_th – Threshold current, in stimulus_unit, estimated so that the output of model.predict_percept(stim(amp_th)) is within bright_tol of bright_th.

Return type:

float

Notes

amp_range, amp_tol and t_percept may be given as unitful quantities; the answer comes back as a plain number of microamps. bright_th and bright_tol are model output, which is not a physical quantity and carries no unit. See pulse2percept.units.

property is_built: A 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

Important

Don’t override this method if you are creating your own model. Customize _predict_temporal instead.

Parameters:

stim (: py: class: ~pulse2percept.stimuli.Stimulus or) – : py: class: ~pulse2percept.models.Percept Either a Stimulus or a Percept object. The temporal model will be applied to each spatial location in the stimulus/percept.
t_percept (float or list of floats, optional) –
The time points at which to output a percept, counted in this model’s time_unit (milliseconds, for every model p2p ships). May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units. If None, the percept will be output once per frame of the video the stimulus was encoded from, or failing that once every 20 ms (50 Hz frame rate), starting at zero and stopping at the last frame boundary the stimulus reaches.

Note

A stimulus shorter than a single frame still gets one frame, whose time point therefore falls after the end of the stimulus. That is the only case in which the output runs past the stimulus, and it is what makes a brief pulse visible at all: reporting it only at t=0 would describe it before it had had any effect. Name t_percept to be reported at particular instants instead.

Returns:

percept – A Percept object whose data container has dimensions Y x X x T. Will return None if stim is None.

Return type:

Percept

Notes

If a list of time points is provided for t_percept, the values will automatically be sorted.
Naming t_percept asks for the brightness at those instants. Leaving it None asks the model to pick the output times, and reduce then says what each point reports about the interval leading up to it – the closing instant, or the peak reached over it.

The distinction matters because electrical stimulation is pulsatile. A 20 Hz train of 0.46 ms biphasic pulses drives brightness in sub-millisecond transients at a 1.8% duty cycle, so an instant sampled from it is almost always an instant between pulses. Worse, the sampling phase walks: against a 29.97 fps video the frame (33.37 ms) and the pulse period (50 ms) are incommensurate, so which electrodes a frame catches drifts from frame to frame. Under a raster, where each group pulses in its own slot, that shows up as groups appearing in the wrong order or not at all.

Changed in version 0.10.0: Output times chosen by the model can summarize their interval instead of sampling its final instant. See reduce.

set_params(**params)[source]: Set the parameters of this object

space_unit = um[source]: The unit spatial coordinates are expressed in

stimulus_unit = uA[source]: The unit stimulus values are expressed in

time_unit = ms[source]: The unit time is expressed in

class pulse2percept.models.Horsager2009Model(**params)[source]

[Horsager2009] Standalone model

Implements the temporal response model described in [Horsager2009], which assumes that the temporal activation of retinal tissue is the output of a linear-nonlinear model cascade (see Fig.2 in the paper).

Note

Use this class if you want a standalone model. Use Horsager2009Temporal if you want to combine the temporal model with a spatial model.

Parameters:

dt (float, optional) – Sampling time step (ms)
tau1 (float, optional) – Time decay constant for the fast leaky integrater.
tau2 (float, optional) – Time decay constant for the charge accumulation.
tau3 (float, optional) – Time decay constant for the slow leaky integrator.
eps (float, optional) – Scaling factor applied to charge accumulation. Common values at threshold: 0.00225, suprathreshold: 0.00873. Power nonlinearity (exponent of the half-wave rectification). Common values at threshold: 3.43, suprathreshold: 0.83.
thresh_percept (float, optional) – Below threshold, the percept has brightness zero.
n_threads (int, optional) – Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.

build(**build_params)[source]

Build the model

Performs expensive one-time calculations, such as building the spatial grid used to predict a percept.

Parameters:: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params. Trying to add new class attributes outside of that will cause a FreezeError. Example: model.build(param1=val)
Return type:: self

find_threshold(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]

Find the threshold current for a certain stimulus

Estimates amp_th such that the output of model.predict_percept(stim(amp_th)) is approximately bright_th.

Parameters:

implant (ProsthesisSystem) – The implant and its stimulus to use. Stimulus amplitude will be up and down regulated until amp_th is found.
bright_th (float) – Model output (brightness) that’s considered “at threshold”.
amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search, counted in this model’s stimulus_unit (microamps, for every model p2p ships).
amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within amp_tol
bright_tol (float, optional) – Search will stop if model brightness is within bright_tol of bright_th
max_iter (int, optional) – Search will stop after max_iter iterations
t_percept (float or list of floats, optional) – The time points at which to output a percept, counted in this model’s time_unit (milliseconds, for every model p2p ships). If None, implant.stim.time is used. May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units.

Returns:

amp_th – Threshold current, in stimulus_unit, estimated so that the output of model.predict_percept(stim(amp_th)) is within bright_tol of bright_th.

Return type:

float

Notes

amp_range, amp_tol and t_percept may be given as unitful quantities; the answer comes back as a plain number of microamps. bright_th and bright_tol are model output, which is not a physical quantity and carries no unit. See pulse2percept.units.

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 is_built: Returns True if the build model has been called

predict_percept(implant, t_percept=None)[source]

Predict a percept

Important

You must call build before calling predict_percept.

Parameters:

implant (ProsthesisSystem) – A valid prosthesis system. A stimulus can be passed via stim().
t_percept (float or list of floats, optional) – The time points at which to output a percept, counted in this model’s time_unit (milliseconds, for every model p2p ships). If None, implant.stim.time is used. May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units.

Returns:

percept – A Percept object whose data container has dimensions Y x X x T. Will return None if implant.stim is None.

Return type:

Percept

set_params(params)[source]

Set model parameters

This is a convenience function to set parameters that might be part of the spatial model, the temporal model, or both.

Alternatively, you can set the parameter directly, e.g. model.spatial.verbose = True.

Note

If a parameter exists in both spatial and temporal models(e.g., verbose), both models will be updated.

Parameters:: params (dict) – A dictionary of parameters to set.

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

The unit time is expressed in

t_percept is read in, and the resulting Percept is written in, the unit of the last stage of the pipeline: the temporal model if there is one, the spatial model otherwise. The two need not agree – a spatial model counting in seconds hands its percept to a temporal model counting in milliseconds and the time axis is converted on the way across.

class pulse2percept.models.Horsager2009Temporal(**params)[source]

Temporal model of [Horsager2009]

Implements the temporal response model described in [Horsager2009], which assumes that the temporal activation of retinal tissue is the output of a linear-nonlinear model cascade (see Fig.2 in the paper).

Note

Use this class if you want to combine the temporal model with a spatial model. Use Horsager2009Model if you want a a standalone model.

Parameters:

dt (float, optional) – Sampling time step (ms)
tau1 (float, optional) – Time decay constant for the fast leaky integrater.
tau2 (float, optional) – Time decay constant for the charge accumulation.
tau3 (float, optional) – Time decay constant for the slow leaky integrator.
eps (float, optional) – Scaling factor applied to charge accumulation. Common values at threshold: 2.25, suprathreshold: 8.73.
beta (float, optional) – Power nonlinearity (exponent of the half-wave rectification). Common values at threshold: 3.43, suprathreshold: 0.83.
thresh_percept (float, optional) – Below threshold, the percept has brightness zero.
n_threads (int, optional) – Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.

get_default_params()[source]: Return a dictionary of default values for all model parameters

get_param_units()[source]: Return a dict of the units that parameters are stored in

build(**build_params)[source]

Build the model

Every model must have a `build method, which is meant to perform all expensive one-time calculations. You must call build before calling predict_percept.

Important

Don’t override this method if you are building your own model. Customize _build instead.

Parameters:: build_params (additional parameters to set) – You can overwrite parameters that are listed in get_default_params. Trying to add new class attributes outside of that will cause a FreezeError. Example: model.build(param1=val)

find_threshold(stim, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100, t_percept=None)[source]

Find the threshold current for a certain stimulus

Estimates amp_th such that the output of model.predict_percept(stim(amp_th)) is approximately bright_th.

Parameters:

stim (Stimulus) – The stimulus to use. Stimulus amplitude will be up and down regulated until amp_th is found.
bright_th (float) – Model output (brightness) that’s considered “at threshold”.
amp_range ((amp_lo, amp_hi), optional) – Range of amplitudes to search, counted in this model’s stimulus_unit (microamps, for every model p2p ships).
amp_tol (float, optional) – Search will stop if candidate range of amplitudes is within amp_tol, in stimulus_unit
bright_tol (float, optional) – Search will stop if model brightness is within bright_tol of bright_th
max_iter (int, optional) – Search will stop after max_iter iterations
t_percept (float or list of floats, optional) – The time points at which to output a percept, counted in this model’s time_unit (milliseconds, for every model p2p ships). If None, implant.stim.time is used. May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units.

Returns:

amp_th – Threshold current, in stimulus_unit, estimated so that the output of model.predict_percept(stim(amp_th)) is within bright_tol of bright_th.

Return type:

float

Notes

amp_range, amp_tol and t_percept may be given as unitful quantities; the answer comes back as a plain number of microamps. bright_th and bright_tol are model output, which is not a physical quantity and carries no unit. See pulse2percept.units.

property is_built: A 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

Important

Don’t override this method if you are creating your own model. Customize _predict_temporal instead.

Parameters:

stim (: py: class: ~pulse2percept.stimuli.Stimulus or) – : py: class: ~pulse2percept.models.Percept Either a Stimulus or a Percept object. The temporal model will be applied to each spatial location in the stimulus/percept.
t_percept (float or list of floats, optional) –
The time points at which to output a percept, counted in this model’s time_unit (milliseconds, for every model p2p ships). May be given as a unitful quantity (e.g. [0, 20] * ms); see pulse2percept.units. If None, the percept will be output once per frame of the video the stimulus was encoded from, or failing that once every 20 ms (50 Hz frame rate), starting at zero and stopping at the last frame boundary the stimulus reaches.

Note

A stimulus shorter than a single frame still gets one frame, whose time point therefore falls after the end of the stimulus. That is the only case in which the output runs past the stimulus, and it is what makes a brief pulse visible at all: reporting it only at t=0 would describe it before it had had any effect. Name t_percept to be reported at particular instants instead.

Returns:

percept – A Percept object whose data container has dimensions Y x X x T. Will return None if stim is None.

Return type:

Percept

Notes

If a list of time points is provided for t_percept, the values will automatically be sorted.
Naming t_percept asks for the brightness at those instants. Leaving it None asks the model to pick the output times, and reduce then says what each point reports about the interval leading up to it – the closing instant, or the peak reached over it.

The distinction matters because electrical stimulation is pulsatile. A 20 Hz train of 0.46 ms biphasic pulses drives brightness in sub-millisecond transients at a 1.8% duty cycle, so an instant sampled from it is almost always an instant between pulses. Worse, the sampling phase walks: against a 29.97 fps video the frame (33.37 ms) and the pulse period (50 ms) are incommensurate, so which electrodes a frame catches drifts from frame to frame. Under a raster, where each group pulses in its own slot, that shows up as groups appearing in the wrong order or not at all.

Changed in version 0.10.0: Output times chosen by the model can summarize their interval instead of sampling its final instant. See reduce.

set_params(**params)[source]: Set the parameters of this object

space_unit = um[source]: The unit spatial coordinates are expressed in

stimulus_unit = uA[source]: The unit stimulus values are expressed in

time_unit = ms[source]: The unit time is expressed in

class pulse2percept.models.Model(spatial=None, temporal=None, **params)[source]

Computational model

To build your own model, you can mix and match spatial and temporal models at will.

For example, to create a model that combines the scoreboard model described in [Beyeler2019] with the temporal model cascade described in [Nanduri2012], use the following:

model = Model(spatial=ScoreboardSpatial(),
              temporal=Nanduri2012Temporal())