pulse2percept.models.horsager2009

Horsager2009Model, Horsager2009Temporal [Horsager2009]

Classes

Horsager2009Model(**params) [Horsager2009] Standalone model
Horsager2009Temporal(**params) Temporal model of [Horsager2009]
class pulse2percept.models.horsager2009.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)
Returns: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 (uA).
  • 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 (ms). If None, implant.stim.time is used.
Returns:

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

has_space

Returns True if the model has a spatial component

has_time

Returns True if the model has a temporal component

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 (ms). If None, implant.stim.time is used.
Returns:

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

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.
class pulse2percept.models.horsager2009.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.
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 (uA).
  • 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 (ms). If None, implant.stim.time is used.
Returns:

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

get_default_params()[source]

Return a dictionary of default values for all model parameters

is_built

A flag indicating whether the model has been built

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 (ms). If None, the percept will be output once very 20 ms (50 Hz frame rate).

    Note

    If your stimulus is shorter than 20 ms, you should specify the desired time points manually.

Returns:

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

Notes

  • If a list of time points is provided for t_percept, the values will automatically be sorted.
set_params(**params)[source]

Set the parameters of this model