api

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

Methods

get_brightest_frame(percept) Returns the brightest frame of a percept

Simulation

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

Bases: object

Methods

plot_fundus([stim, ax]) Plot the implant on the retinal surface akin to a fundus photopgraph
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, …]) Sets parameters of the optic fiber layer (OFL)
__init__(implant, engine=’joblib’, scheduler=’threading’, use_jit=True, num_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.

num_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)[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

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

set_optic_fiber_layer(sampling=100, axon_lambda=2, rot_deg=0, x_range=None, y_range=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.

axon_lambda : float, optional, default: 2

Constant that determines fall-off with axonal distance.

rot_deg : float, optional, default: 0

Rotation angle (deg).

x_range : list|None, default: None

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

y_range : list|None, default: None

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

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.

get_brightest_frame

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