pulse2percept.models.temporal

FadingTemporal, AlphaTemporal

Classes

AlphaTemporal(*[, tau, dt, thresh_percept, ...])	Generic alpha-shaped temporal model.
FadingTemporal(*[, tau, dt, thresh_percept, ...])	Generic temporal model for phosphene fading.

class pulse2percept.models.temporal.FadingTemporal(*, tau=100, dt=0.005, thresh_percept=0, reduce='peak', verbose=True, n_threads=None, n_jobs=None)

Generic temporal model for phosphene fading.

Cathodic current is half-wave rectified into the drive

\[D(t) = \max[-A(t), 0],\]

where \(A(t)\) is stimulus amplitude. Brightness follows a first-order leaky integrator,

\[\tau \frac{dB}{dt} = D(t) - B(t).\]

For constant drive \(D\), the continuous-time response is

\[B(t) = D + [B(0) - D] e^{-t/\tau}.\]

Thus \(\tau\) controls both rise and decay. Larger values produce slower responses and lower peaks for brief pulses. Anodic current does not drive brightness.

The model is evaluated with the explicit-Euler recurrence

\[B_{k+1} = B_k + \frac{\Delta t}{\tau}\left(D_k - B_k\right),\]

with \(\Delta t =\) dt. The implementation requires \(\tau \geq \Delta t\), so the discrete-time pole \(1-\Delta t/\tau\) is nonnegative.

This is a generic temporal response model, not a perceptually validated fit.

Parameters:

• dt (float or Quantity, optional) – Simulation time step, in milliseconds. Default: 0.005 ms.

• tau (float or Quantity, optional) – Leaky-integrator time constant, in milliseconds. Larger values slow both rise and decay and reduce the peak response to brief pulses. Must be at least dt. Default: 100 ms.

• thresh_percept (float, optional) – Brightness values below this threshold are set to zero. Default: 0.

• reduce ({'peak', 'last'}, optional) – How automatically chosen output points summarize the preceding interval. 'peak' reports the maximum brightness reached; 'last' reports brightness at the output instant. Explicit t_percept values always request those instants. Default: 'peak'.

• verbose (bool, optional) – Whether to print status messages. Default: True.

• n_threads (int, optional) – Number of OpenMP threads. Defaults to all available CPU cores.

• n_jobs (int or None, optional) – Alias for n_threads. None and -1 use all available CPU cores.

• versionchanged: (..) – 0.10.0: The drive is half-wave rectified, so only cathodic current increases brightness.

• versionadded: (..) – 0.7.1:

get_default_params()

Return default model 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

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.

Parameters:

• stim (Stimulus or Percept) – Time-varying input. The temporal model is applied independently at each spatial location.

• t_percept (float or array-like, optional) – Output times in time_unit. Unitful times are accepted. If omitted, encoded video frame times are used when available; otherwise output is sampled every 20 ms, with at least one frame for a shorter stimulus.

Returns:

percept – Percept with shape Y x X x T, or None if stim is None.

Return type:

Percept or None

Notes

Explicit t_percept values sample brightness at those instants. Otherwise reduce determines whether each output interval reports its endpoint or peak. Requested times are sorted and must lie on the dt grid.

Changed in version 0.10.0: Automatically selected output times may summarize intervals via reduce.

set_params(**params)

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.temporal.AlphaTemporal(*, tau=100, dt=0.005, thresh_percept=0, reduce='peak', verbose=True, n_threads=None, n_jobs=None)

Generic alpha-shaped temporal model.

Cathodic current is half-wave rectified into

\[D(t) = \max[-A(t), 0].\]

Two identical first-order stages are then cascaded:

\[\tau \frac{dx}{dt} = D(t) - x(t),\]

\[\tau \frac{dB}{dt} = x(t) - B(t).\]

For a unit-area impulse, the continuous-time impulse response is

\[h(t) = \frac{t}{\tau^2} e^{-t/\tau}, \qquad t \geq 0,\]

which rises from zero, peaks at \(t=\tau\), and then decays. Anodic current does not drive brightness.

The model is evaluated with the explicit-Euler recurrences

\[x_{k+1} = x_k + \frac{\Delta t}{\tau}\left(D_k - x_k\right),\]

\[B_{k+1} = B_k + \frac{\Delta t}{\tau}\left(x_k - B_k\right),\]

with \(\Delta t =\) dt. The implementation requires \(\tau \geq \Delta t\).

This is a generic temporal response model, not a perceptually validated fit.

Parameters:

• dt (float or Quantity, optional) – Simulation time step, in milliseconds. Default: 0.005 ms.

• tau (float or Quantity, optional) – Time constant of both stages, in milliseconds. Larger values delay and broaden the response. Must be at least dt. Default: 100 ms.

• thresh_percept (float, optional) – Brightness values below this threshold are set to zero. Default: 0.

• reduce ({'peak', 'last'}, optional) – How automatically chosen output points summarize the preceding interval. 'peak' reports the maximum brightness reached; 'last' reports brightness at the output instant. Explicit t_percept values always request those instants. Default: 'peak'.

• verbose (bool, optional) – Whether to print status messages. Default: True.

• n_threads (int, optional) – Number of OpenMP threads. Defaults to all available CPU cores.

• n_jobs (int or None, optional) – Alias for n_threads. None and -1 use all available CPU cores.

• versionadded: (..) – 0.10.0:

get_default_params()

Return default model 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

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.

Parameters:

• stim (Stimulus or Percept) – Time-varying input. The temporal model is applied independently at each spatial location.

• t_percept (float or array-like, optional) – Output times in time_unit. Unitful times are accepted. If omitted, encoded video frame times are used when available; otherwise output is sampled every 20 ms, with at least one frame for a shorter stimulus.

Returns:

percept – Percept with shape Y x X x T, or None if stim is None.

Return type:

Percept or None

Notes

Explicit t_percept values sample brightness at those instants. Otherwise reduce determines whether each output interval reports its endpoint or peak. Requested times are sorted and must lie on the dt grid.

Changed in version 0.10.0: Automatically selected output times may summarize intervals via reduce.

set_params(**params)

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