pulse2percept

Simulation(implant[, engine, scheduler, …])

Methods

get_brightest_frame(percept) Returns the brightest frame of a percept

Simulation

class pulse2percept.Simulation(implant, engine=’joblib’, scheduler=’threading’, use_jit=True, n_jobs=-1)[source]

Bases: object

Methods

plot_fundus([stim, ax, n_axons, …]) Plot the implant on the retinal surface akin to a fundus photopgraph This function plots an electrode array on top of the axon streak map of the retina, akin to a fundus photograph.
pulse2percept(stim[, t_percept, tol, layers]) Transforms an input stimulus to a percept
set_ganglion_cell_layer(model, **kwargs) Sets parameters of the ganglion cell layer (GCL)
set_optic_fiber_layer([sampling, x_range, …]) Sets parameters of the optic fiber layer (OFL)
__init__(implant, engine=’joblib’, scheduler=’threading’, use_jit=True, n_jobs=-1)[source]

Generates a simulation framework

Parameters:

implant : implants.ElectrodeArray

An implants.ElectrodeArray object that describes the implant.

engine : str, optional, default: ‘joblib’

Which computational back end to use: - ‘serial’: Single-core computation - ‘joblib’: Parallelization via joblib (requires `pip install

joblib`)

  • ‘dask’: Parallelization via dask (requires pip install dask).

    Dask backend can be specified via threading.

scheduler : str, optional, default: ‘threading’

Which scheduler to use (irrelevant for ‘serial’ engine): - ‘threading’: a scheduler backed by a thread pool - ‘multiprocessing’: a scheduler backed by a process pool

use_jit : bool, optional, default: True

Whether to use just-in-time (JIT) compilation to speed up computation.

n_jobs : int, optional, default: -1

Number of cores (threads) to run the model on in parallel. Specify -1 to use as many cores as available.

plot_fundus(stim=None, ax=None, n_axons=100, upside_down=False, annotate=True)[source]

Plot the implant on the retinal surface akin to a fundus photopgraph This function plots an electrode array on top of the axon streak map of the retina, akin to a fundus photograph. A blue rectangle highlights the area of the retinal surface that is being simulated. If stim is passed, activated electrodes will be highlighted. Parameters ———- stim : utils.TimeSeries|list|dict, optional

An input stimulus, as passed to p2p.pulse2percept. If given, activated electrodes will be highlighted in the plot. Default: None
ax : matplotlib.axes._subplots.AxesSubplot, optional
A Matplotlib axes object. If None given, a new one will be created. Default: None
n_axons : int, optional, default: 100
Number of axons to plot.
upside_down : bool, optional, default: False
Flag whether to plot the retina upside-down, such that the upper half of the plot corresponds to the upper visual field. In general, inferior retina == upper visual field (and superior == lower).
annotate : bool, optional, default: True
Flag whether to annotate the four retinal quadrants (inferior/superior x temporal/nasal).
Returns:Returns a handle to the created figure (fig) and axes element (ax).
pulse2percept(stim, t_percept=None, tol=0.05, layers=[‘OFL’, ‘GCL’, ‘INL’])[source]

Transforms an input stimulus to a percept

Parameters:

stim : utils.TimeSeries|list|dict

There are several ways to specify an input stimulus:

  • For a single-electrode array, pass a single pulse train; i.e., a single utils.TimeSeries object.
  • For a multi-electrode array, pass a list of pulse trains; i.e., one pulse train per electrode.
  • For a multi-electrode array, specify all electrodes that should receive non-zero pulse trains by name.

t_percept : float, optional, default: inherit from stim object

The desired time sampling of the output (seconds).

tol : float, optional, default: 0.05

Ignore pixels whose effective current is smaller than a fraction tol of the max value.

layers : list, optional, default: [‘OFL’, ‘GCL’, ‘INL’]

A list of retina layers to simulate (order does not matter): - ‘OFL’: Includes the optic fiber layer in the simulation.

If omitted, the tissue activation map will not account for axon streaks.

  • ‘GCL’: Includes the ganglion cell layer in the simulation.

  • ‘INL’: Includes the inner nuclear layer in the simulation.

    If omitted, bipolar cell activity does not contribute to ganglion cell activity.

Returns:

A utils.TimeSeries object whose data container comprises the predicted

brightness over time at each retinal location (x, y), with the last

dimension of the container representing time (t).

Examples

Simulate a single-electrode array:

>>> import pulse2percept as p2p
>>> implant = p2p.implants.ElectrodeArray('subretinal', 0, 0, 0)
>>> stim = p2p.stimuli.PulseTrain(tsample=5e-6, freq=50, amp=20)
>>> sim = p2p.Simulation(implant)
>>> percept = sim.pulse2percept(stim)  

Simulate an Argus I array centered on the fovea, where a single electrode is being stimulated (‘C3’):

>>> import pulse2percept as p2p
>>> implant = p2p.implants.ArgusI()
>>> stim = {'C3': stimuli.PulseTrain(tsample=5e-6, freq=50,
...                                              amp=20)}
>>> sim = p2p.Simulation(implant)
>>> resp = sim.pulse2percept(stim, implant)  
set_ganglion_cell_layer(model, **kwargs)[source]

Sets parameters of the ganglion cell layer (GCL)

Select from pre-existing ganglion cell models or specify a custom one.

Parameters:

tsample : float, optional, default: 0.005 / 1000 seconds

Sampling time step (seconds).

tau1 : float, optional, default: 0.42 / 1000 seconds

Time decay constant for the fast leaky integrater of the ganglion cell layer (GCL).

tau2 : float, optional, default: 45.25 / 1000 seconds

Time decay constant for the charge accumulation, has values between 38 - 57 ms.

tau3 : float, optional, default: 26.25 / 1000 seconds

Time decay constant for the slow leaky integrator. Default: 26.25 / 1000 s.

eps : float, optional, default: 8.73

Scaling factor applied to charge accumulation (used to be called epsilon).

beta : float, optional, default: 3.43

Power nonlinearity applied after half-rectification. The original model used two different values, depending on whether an experiment is at threshold (`beta`=3.43) or above threshold (`beta`=0.83).

Notes

[R1]D. Nanduri, I. Fine, A. Horsager, G. M. Boynton, M. S. Humayun, R. Greenberg, J. D. Weiland, “Frequency and Amplitude Modulation Have Different Effects on the Percepts Elicited by Retinal Stimulation”, Investigative Ophthalmology & Visual Science 53, 205-214, 2012.
[R2]A. Horsager, S. H. Greenwald, J. D. Weiland, M. S. Humayun, R. J. Greenberg, M. J. McMahon, G. M. Boynton, and I. Fine, “Predicting visual sensitivity in retinal prosthesis patients”, Investigative Ophthalmology & Visual Science, 50(4):1483, 2009.
set_optic_fiber_layer(sampling=100, x_range=None, y_range=None, n_axons=501, phi_range=(-180.0, 180.0), n_rho=801, rho_range=(4.0, 45.0), loc_od=(15.5, 1.5), sensitivity_rule=’decay’, decay_const=1.0, contribution_rule=’max’, powermean_exp=None, datapath=’.’, save_data=True)[source]

Sets parameters of the optic fiber layer (OFL)

Parameters:

sampling : float, optional, default: 100 microns

Microns per grid cell.

x_range : (xlo, xhi)|None, default: None

Lower and upper bound of the retinal grid (microns) in horizontal dimension. Either a tuple (xlo, xhi) or None. If None, the generated grid will be just big enough to fit the implant.

y_range : (ylo, yhi)|None, default: None

Lower and upper bound of the retinal grid (microns) in vertical dimension. Either a tuple (ylo, yhi) or None. If None, the generated grid will be just big enough to fit the implant.

n_axons : int, optional, default: 501

The number of axons to generate. Their start orientations phi0 (in modified polar coordinates) will be sampled uniformly from phi_range.

phi_range : (lophi, hiphi), optional, default: (-180, 180)

Range of angular positions of axon fibers at their starting points (polar coordinates, degrees) to be sampled uniformly with n_axons samples. Must be within [-180, 180].

n_rho: int, optional, default: 801

Number of sampling points along the radial axis(polar coordinates).

rho_range: (rho_min, rho_max), optional, default: (4.0, 45.0)

Lower and upper bounds for the radial position values(polar coordinates).

loc_od: (x_od, y_od), optional, default: (15.5 1.5)

Location of the center of the optic disc (x, y) in Cartesian coordinates. In a right (left) eye, we should have x > 0 (x < 0).

sensitivity_rule : {‘decay’, ‘Jeng2011’}, optional, default: ‘decay’

This rule specifies how the activation of the axon differs as a function of distance from the soma. The following options are available: - ‘decay’:

Axon sensitivity decays exponentially with distance. Specify decay_const to change the steepness of the fall-off with distance.

  • ‘Jeng2011’:

    Axon sensitivity peaks near the sodium band (50um from the soma), then plateaus on the distal axon at roughly half of the peak sensitivity (see Fig. 2 in [R3]).

contribution_rule : {‘max’, ‘sum’, ‘mean’}, optional, default: ‘max’

This rule specifies how the activation thresholds across all axon segments are combined to determine the contribution of the axon to the current spread. The following options are available: - ‘max’:

The axon’s contribution to the current spread is equal to the max. sensitivity across all axon segments.

  • ‘sum’:

    The axon’s contribution to the current spread is equal to the sum sensitivity across all axon segments.

  • ‘mean’:

    The axon’s contribution to the current spread is equal to the mean sensitivity across all axon segments. Specify powermean_exp to change the exponent of the generalized (power) mean, calculated as np.mean(x ** powermean_exp) ** (1.0 / powermean_exp). Default is 1, which is equal to the arithmetic mean.

decay_const : float, optional, default: 2.0

When sensitivity_rule is set to ‘decay’, specifies the decay constant of the exponential fall-off.

powermean_exp : float, optional, default: 1.0

When sensitivity_rule is set to ‘mean’, specifies the exponent of the generalized (power) mean function. The power mean is calculated as np.mean(x ** powermean_exp) ** (1.0 / powermean_exp).

datapath : str, default: current directory

Relative path where to look for existing retina files, and where to store new retina files.

save_data : bool, default: True

Flag whether to save the data to a new retina file (True) or not (False). The file name is automatically generated from all specified input arguments.

Notes

[R3]J. Jeng, S. Tang, A. Molnar, N. J. Desai, and S. I. Fried, “The sodium channel band shapes the response to electric stimulation in retinal ganglion cells”, J Neural Eng 8 (036022), 2011.

get_brightest_frame

pulse2percept.get_brightest_frame(percept)[source]

Returns the brightest frame of a percept

This function returns the frame of a percept (brightness over time) that contains the brightest pixel.

Parameters:

percept : TimeSeries

The brightness movie as a TimeSeries object.