pulse2percept.models.nanduri2012

Nanduri2012Model, Nanduri2012Spatial, Nanduri2012Temporal [Nanduri2012]

Classes

`Nanduri2012Model`(**params)	[Nanduri2012] Model
`Nanduri2012Spatial`(**params)	Spatial response model of [Nanduri2012]
`Nanduri2012Temporal`(**params)	Temporal model of [Nanduri2012]

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

Spatial response model of [Nanduri2012]

Implements the spatial response model described in [Nanduri2012], which assumes that the spatial activation of retinal tissue is equivalent to the “current spread” \(I\), described as a function of distance \(r\) from the center of the stimulating electrode:

\[\begin{split}I(r) = \begin{cases} \frac{\verb!atten_a!}{\verb!atten_a! + (r-a)^\verb!atten_n!} & r > a \\ 1 & r \leq a \end{cases}\end{split}\]

where \(a\) is the radius of the electrode (see Eq.2 in the paper).

Note

Use this class if you just want the spatial response model. Use Nanduri2012Model if you want both the spatial and temporal model.

Parameters:

atten_a (float, optional) – Nominator of the attentuation function
atten_n (float32, optional) – Exponent of the attenuation function’s denominator
vfmap (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides retinotopic mappings. By default, Curcio1990Map 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.
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.

get_default_params()[source]: Returns all settable parameters of the Nanduri model

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

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.

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

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

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

Plot the model

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

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes

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.nanduri2012.Nanduri2012Temporal(**params)[source]

Temporal model of [Nanduri2012]

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

Note

Use this class if you just want the temporal response model. Use Nanduri2012Model if you want both the spatial and temporal 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.
asymptote (float, optional) – Asymptote of the logistic function used in the stationary nonlinearity stage.
slope (float, optional) – Slope of the logistic function in the stationary nonlinearity stage.
shift (float, optional) – Shift of the logistic function in the stationary nonlinearity stage.
scale_out (float32, optional) – A scaling factor applied to the output of the model
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.
n_jobs (int, optional) – Alias for n_threads; None or -1 uses every core.

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.nanduri2012.Nanduri2012Model(**params)[source]

[Nanduri2012] Model

Implements the model described in [Nanduri2012], where percepts are circular and their brightness evolves over time.

The model combines two parts:

Nanduri2012Spatial is used to calculate the spatial activation function, which is assumed to be equivalent to the “current spread” described as a function of distance from the center of the stimulating electrode (see Eq.2 in the paper).
Nanduri2012Temporal is used to calculate the temporal activation function, which is assumed to be the output of a linear-nonlinear cascade model (see Fig.6 in the paper).

Parameters:

atten_a (float, optional) – Nominator of the attentuation function (Eq.2 in the paper)
atten_n (float32, optional) – Exponent of the attenuation function’s denominator (Eq.2 in the paper)
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.
asymptote (float, optional) – Asymptote of the logistic function used in the stationary nonlinearity stage.
slope (float, optional) – Slope of the logistic function in the stationary nonlinearity stage.
shift (float, optional) – Shift of the logistic function in the stationary nonlinearity stage.
scale_out (float32, optional) – A scaling factor applied to the output of the model
thresh_percept (float, optional) – Below threshold, the percept has brightness zero.
vfmap (VisualFieldMap, optional) – An instance of a VisualFieldMap object that provides retinotopic mappings. By default, Curcio1990Map 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.
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.