pulse2percept.models.temporal

FadingTemporal

Classes

FadingTemporal(**params)

A generic temporal model for phosphene fading

class pulse2percept.models.temporal.FadingTemporal(**params)

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

Return a dictionary of default values for all model parameters

get_param_units()

Return a dict of the units that parameters are stored in

build(**build_params)

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)

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)

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)

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