retina

BaseModel(**kwargs) Abstract base class for all models of temporal sensitivity.
Grid([xlo, xhi, ylo, yhi, sampling, …]) Represent the retinal coordinate frame
Horsager2009(**kwargs) Model of temporal sensitivity (Horsager et al.
Nanduri2012(**kwargs) Model of temporal sensitivity (Nanduri et al.
TemporalModel(**kwargs) Latest edition of the temporal sensitivity model (experimental)
deg2micron(deg) Deprecated function. Use p2p.retina.dva2ret instead.
dva2ret(r_deg) Converts visual angles (deg) into retinal distances (um)
jansonius([num_cells, num_samples, center, …]) Implements the model of retinal axonal pathways by generating a matrix of (x,y) positions.
make_axon_map(xg, yg, jan_x, jan_y[, …]) Retinal axon map
micron2deg(micron) Deprecated function. Use p2p.retina.ret2dva instead.
ret2dva(r_um) Converts retinal distances (um) to visual angles (deg)

BaseModel

class pulse2percept.retina.BaseModel(**kwargs)[source]

Bases: object

Abstract base class for all models of temporal sensitivity.

This class provides a standard template for all models of temporal sensitivity.

Methods

model_cascade(in_arr, pt_list, layers, use_jit) Abstract base ganglion cell model
set_kwargs(warn_inexistent, **kwargs) Overwrite any given keyword arguments
__init__(**kwargs)[source]
model_cascade(in_arr, pt_list, layers, use_jit)[source]

Abstract base ganglion cell model

Parameters:

in_arr: array-like

A 2D array specifying the effective current values at a particular spatial location (pixel); one value per retinal layer and electrode. Dimensions: <#layers x #electrodes>

pt_list : list

List of pulse train ‘data’ containers. Dimensions: <#electrodes x #time points>

layers : list

List of retinal layers to simulate. Choose from: - ‘OFL’: optic fiber layer - ‘GCL’: ganglion cell layer - ‘INL’: inner nuclear layer

use_jit : bool

If True, applies just-in-time (JIT) compilation to expensive computations for additional speed-up (requires Numba).

set_kwargs(warn_inexistent, **kwargs)[source]

Overwrite any given keyword arguments

Parameters:

warn_inexistent : bool

If True, displays a warning message if a keyword is provided that is not recognized by the temporal model.

tsample = 5e-06

Grid

class pulse2percept.retina.Grid(xlo=-1000, xhi=1000, ylo=-1000, yhi=1000, sampling=25, axon_lambda=2.0, rot=0.0, datapath=’.’, save_data=True)[source]

Bases: object

Represent the retinal coordinate frame

Methods

current2effectivecurrent(cs) Converts a current spread map to an ‘effective’ current spread map, by passing the map through a mapping of axon streaks.
electrode_ecs(implant[, alpha, n]) Gather current spread and effective current spread for each electrode
__init__(xlo=-1000, xhi=1000, ylo=-1000, yhi=1000, sampling=25, axon_lambda=2.0, rot=0.0, datapath=’.’, save_data=True)[source]

Generates a spatial grid representing the retinal coordinate frame

This function generates the coordinate system for the retina and an axon map. As this can take a while, the function will first look for an already existing file in the directory datapath that was automatically created from an earlier call to this function, before it attempts to generate new grid from scratch.

Parameters:

xlo, xhi : float

Extent of the retinal coverage (microns) in horizontal dimension. Default: xlo=-1000, xhi=1000.

ylo, yhi : float

Extent of the retinal coverage (microns) in vertical dimension. Default: ylo=-1000, ylo=1000.

datapath : str

Relative path where to look for existing retina files, and where to store new files. Default: current directory.

save_data : bool

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

current2effectivecurrent(cs)[source]

Converts a current spread map to an ‘effective’ current spread map, by passing the map through a mapping of axon streaks.

Parameters:

cs : array

The 2D spread map in retinal space

Returns:

ecm : array

The effective current spread, a time-series of the same size as the current map, where each pixel is the dot product of the pixel values in ecm along the pixels in the list in axon_map, weighted by the weights axon map.

electrode_ecs(implant, alpha=14000, n=1.69)[source]

Gather current spread and effective current spread for each electrode within both the bipolar and the ganglion cell layer

Parameters:

implant : implants.ElectrodeArray

An implants.ElectrodeArray instance describing the implant.

alpha : float

Current spread parameter

n : float

Current spread parameter

Returns:

ecs : contains n arrays containing the the effective current

spread within various layers for each electrode in the array respectively.

See also

Electrode.current_spread

Horsager2009

class pulse2percept.retina.Horsager2009(**kwargs)[source]

Bases: pulse2percept.retina.BaseModel

Model of temporal sensitivity (Horsager et al. 2009)

This class implements the model of temporal sensitivty as described in: > A Horsager, SH Greenwald, JD Weiland, MS Humayun, RJ Greenberg, > MJ McMahon, GM Boynton, and I Fine (2009). Predicting visual sensitivity > in retinal prosthesis patients. Investigative Ophthalmology & Visual > Science, 50(4):1483.

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.

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

Methods

calc_layer_current(in_arr, pt_list, layers) Calculates the effective current map of a given layer
model_cascade(in_arr, pt_list, layers, use_jit) Horsager model cascade
set_kwargs(warn_inexistent, **kwargs) Overwrite any given keyword arguments
__init__(**kwargs)[source]
calc_layer_current(in_arr, pt_list, layers)[source]

Calculates the effective current map of a given layer

Parameters:

in_arr: array-like

A 2D array specifying the effective current values at a particular spatial location (pixel); one value per retinal layer and electrode. Dimensions: <#layers x #electrodes>

pt_list : list

List of pulse train ‘data’ containers. Dimensions: <#electrodes x #time points>

layers : list

List of retinal layers to simulate. Choose from: - ‘OFL’: optic fiber layer - ‘GCL’: ganglion cell layer

model_cascade(in_arr, pt_list, layers, use_jit)[source]

Horsager model cascade

Parameters:

in_arr: array-like

A 2D array specifying the effective current values at a particular spatial location (pixel); one value per retinal layer and electrode. Dimensions: <#layers x #electrodes>

pt_list : list

List of pulse train ‘data’ containers. Dimensions: <#electrodes x #time points>

layers : list

List of retinal layers to simulate. Choose from: - ‘OFL’: optic fiber layer - ‘GCL’: ganglion cell layer

use_jit : bool

If True, applies just-in-time (JIT) compilation to expensive computations for additional speed-up (requires Numba).

Nanduri2012

class pulse2percept.retina.Nanduri2012(**kwargs)[source]

Bases: pulse2percept.retina.BaseModel

Model of temporal sensitivity (Nanduri et al. 2012)

This class implements the model of temporal sensitivity as described in: > Nanduri, Fine, Horsager, Boynton, Humayun, Greenberg, Weiland (2012). > Frequency and Amplitude Modulation Have Different Effects on the Percepts > Elicited by Retinal Stimulation. Investigative Ophthalmology & Visual > Science January 2012, Vol.53, 205-214. doi:10.1167/iovs.11-8401.

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

asymptote : float, optional, default: 14.0

Asymptote of the logistic function used in the stationary nonlinearity stage.

slope : float, optional, default: 3.0

Slope of the logistic function in the stationary nonlinearity stage.

shift : float, optional, default: 16.0

Shift of the logistic function in the stationary nonlinearity stage.

Methods

calc_layer_current(in_arr, pt_list, layers) Calculates the effective current map of a given layer
model_cascade(in_arr, pt_list, layers, use_jit) Nanduri model cascade
set_kwargs(warn_inexistent, **kwargs) Overwrite any given keyword arguments
__init__(**kwargs)[source]
calc_layer_current(in_arr, pt_list, layers)[source]

Calculates the effective current map of a given layer

Parameters:

in_arr: array-like

A 2D array specifying the effective current values at a particular spatial location (pixel); one value per retinal layer and electrode. Dimensions: <#layers x #electrodes>

pt_list : list

List of pulse train ‘data’ containers. Dimensions: <#electrodes x #time points>

layers : list

List of retinal layers to simulate. Choose from: - ‘OFL’: optic fiber layer - ‘GCL’: ganglion cell layer

model_cascade(in_arr, pt_list, layers, use_jit)[source]

Nanduri model cascade

Parameters:

in_arr: array-like

A 2D array specifying the effective current values at a particular spatial location (pixel); one value per retinal layer and electrode. Dimensions: <#layers x #electrodes>

pt_list : list

List of pulse train ‘data’ containers. Dimensions: <#electrodes x #time points>

layers : list

List of retinal layers to simulate. Choose from: - ‘OFL’: optic fiber layer - ‘GCL’: ganglion cell layer

use_jit : bool

If True, applies just-in-time (JIT) compilation to expensive computations for additional speed-up (requires Numba).

TemporalModel

class pulse2percept.retina.TemporalModel(**kwargs)[source]

Bases: pulse2percept.retina.BaseModel

Latest edition of the temporal sensitivity model (experimental)

This class implements the latest version of the temporal sensitivity model (experimental). As such, the model might still change from version to version. For more stable implementations, please refer to other, published models (see p2p.retina.SUPPORTED_MODELS).

Parameters:

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

Sampling time step (seconds).

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

Time decay constant for the fast leaky integrater of the ganglion cell layer (GCL). This is only important in combination with epiretinal electrode arrays.

tau_inl : float, optional, default: 18.0 / 1000 seconds

Time decay constant for the fast leaky integrater of the inner nuclear layer (INL); i.e., bipolar cell layer. This is only important in combination with subretinal electrode arrays.

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

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

scale_ca : float, optional, default: 42.1

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

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

Time decay constant for the slow leaky integrator.

scale_slow : float, optional, default: 1150.0

Scaling factor applied to the output of the cascade, to make output values interpretable brightness values >= 0.

lweight : float, optional, default: 0.636

Relative weight applied to responses from bipolar cells (weight of ganglion cells is 1).

aweight : float, optional, default: 0.5

Relative weight applied to anodic charges (weight of cathodic charges is 1).

slope : float, optional, default: 3.0

Slope of the logistic function in the stationary nonlinearity stage.

shift : float, optional, default: 15.0

Shift of the logistic function in the stationary nonlinearity stage.

Methods

calc_layer_current(ecs_item, pt_list, layers) For a given pixel, calculates the effective current for each retinal
charge_accumulation(ecm) Calculates the charge accumulation
fast_response(stim, gamma, method[, use_jit]) Fast response function
model_cascade(ecs_item, pt_list, layers, use_jit) The Temporal Sensitivity model
set_kwargs(warn_inexistent, **kwargs) Overwrite any given keyword arguments
slow_response(stim) Slow response function
stationary_nonlinearity(stim) Stationary nonlinearity
__init__(**kwargs)[source]
calc_layer_current(ecs_item, pt_list, layers)[source]
For a given pixel, calculates the effective current for each retinal
layer over time

This function operates at a single-pixel level: It calculates the combined current from all electrodes through a spatial location over time. This calculation is performed per retinal layer.

Parameters:

ecs_item: array-like

A 2D array specifying the effective current values at a particular spatial location (pixel); one value per retinal layer and electrode. Dimensions: <#layers x #electrodes>

pt_list: list

A list of PulseTrain data containers. Dimensions: <#electrodes x #time points>

layers : list

List of retinal layers to simulate. Choose from: - ‘OFL’: optic fiber layer - ‘GCL’: ganglion cell layer - ‘INL’: inner nuclear layer

charge_accumulation(ecm)[source]

Calculates the charge accumulation

Charge accumulation is calculated on the effective input current ecm, as opposed to the output of the fast response stage.

Parameters:

ecm : array-like

A 2D array specifying the effective current values at a particular spatial location (pixel); one value per retinal layer, averaged over all electrodes through that pixel. Dimensions: <#layers x #time points>

fast_response(stim, gamma, method, use_jit=True)[source]

Fast response function

Convolve a stimulus stim with a temporal low-pass filter gamma.

Parameters:

stim : array

Temporal signal to process, stim(r,t) in Nanduri et al. (2012).

use_jit : bool, optional

If True (default), use numba just-in-time compilation.

usefft : bool, optional

If False (default), use sparseconv, else fftconvolve.

Returns:

Fast response, b2(r,t) in Nanduri et al. (2012).

Notes

The function utils.sparseconv can be much faster than np.convolve and signal.fftconvolve if stim is sparse and much longer than the convolution kernel. The output is not converted to a TimeSeries object for speedup.

model_cascade(ecs_item, pt_list, layers, use_jit)[source]

The Temporal Sensitivity model

This function applies the model of temporal sensitivity to a single retinal cell (i.e., a pixel). The model is inspired by Nanduri et al. (2012), with some extended functionality.

Parameters:

ecs_item: array-like

A 2D array specifying the effective current values at a particular spatial location (pixel); one value per retinal layer and electrode. Dimensions: <#layers x #electrodes>

pt_list: list

A list of PulseTrain data containers. Dimensions: <#electrodes x #time points>

layers : list

List of retinal layers to simulate. Choose from: - ‘OFL’: optic fiber layer - ‘GCL’: ganglion cell layer - ‘INL’: inner nuclear layer

use_jit : bool

If True, applies just-in-time (JIT) compilation to expensive computations for additional speed-up (requires Numba).

Returns:

Brightness response over time. In Nanduri et al. (2012), the

maximum value of this signal was used to represent the perceptual

brightness of a particular location in space, B(r).

slow_response(stim)[source]

Slow response function

Convolve a stimulus stim with a low-pass filter (3-stage gamma) with time constant self.tau_slow. This is Box 5 in Nanduri et al. (2012).

Parameters:

stim : array

Temporal signal to process, stim(r,t) in Nanduri et al. (2012)

Returns:

Slow response, b5(r,t) in Nanduri et al. (2012).

Notes

This is by far the most computationally involved part of the perceptual sensitivity model. Conversion to TimeSeries is avoided for the sake of speedup.

stationary_nonlinearity(stim)[source]

Stationary nonlinearity

Nonlinearly rescale a temporal signal stim across space and time, based on a sigmoidal function dependent on the maximum value of stim. This is Box 4 in Nanduri et al. (2012). The parameter values of the asymptote, slope, and shift of the logistic function are given by self.asymptote, self.slope, and self.shift, respectively.

Parameters:

stim : array

Temporal signal to process, stim(r,t) in Nanduri et al. (2012).

Returns:

Rescaled signal, b4(r,t) in Nanduri et al. (2012).

Notes

Conversion to TimeSeries is avoided for the sake of speedup.

deg2micron

pulse2percept.retina.deg2micron(deg)[source]

Deprecated function. Use p2p.retina.dva2ret instead.

Function deg2micron is deprecated since version 0.2, and will be removed in version 0.3. Use p2p.retina.dva2ret instead.

Transforms a distance from degrees to microns

Based on http://retina.anatomy.upenn.edu/~rob/lance/units_space.html

dva2ret

pulse2percept.retina.dva2ret(r_deg)[source]

Converts visual angles (deg) into retinal distances (um)

This function converts a retinal distancefrom the optic axis (um) into degrees of visual angle. Source: Eq. A5 in Watson (2014), J Vis 14(7):15, 1-17

jansonius

pulse2percept.retina.jansonius(num_cells=500, num_samples=801, center=array([15, 2]), rot=0.0, scale=1, bs=-1.9, bi=0.5, r0=4, max_samples=45, ang_range=60)[source]

Implements the model of retinal axonal pathways by generating a matrix of (x,y) positions.

Assumes that the fovea is at [0, 0]

Parameters:

num_cells : int

Number of axons (cells).

num_samples : int

Number of samples per axon (spatial resolution).

Center: 2 item array

The location of the optic disk in dva.

See:

Jansonius et al., 2009, A mathematical description of nerve fiber bundle

trajectories and their variability in the human retina, Vision Research

make_axon_map

pulse2percept.retina.make_axon_map(xg, yg, jan_x, jan_y, axon_lambda=1, min_weight=0.001)[source]

Retinal axon map

Generates a mapping of how each pixel in the retina space is affected by stimulation of underlying ganglion cell axons. Parameters ———- xg, yg : array

meshgrid of pixel locations in units of visual angle sp
axon_lambda : float
space constant for how effective stimulation (or ‘weight’) falls off with distance from the pixel back along the axon toward the optic disc (default 1 degree)
min_weight : float
minimum weight falloff. default .001
Returns:

axon_id : list

a list, for every pixel, of the index into the pixel in xg,yg space, along the underlying axonal pathway.

axon_weight : list

a list, for every pixel, of the axon weight into the pixel in xg,yg space

micron2deg

pulse2percept.retina.micron2deg(micron)[source]

Deprecated function. Use p2p.retina.ret2dva instead.

Function micron2deg is deprecated since version 0.2, and will be removed in version 0.3. Use p2p.retina.ret2dva instead.

Transforms a distance from microns to degrees

Based on http://retina.anatomy.upenn.edu/~rob/lance/units_space.html

ret2dva

pulse2percept.retina.ret2dva(r_um)[source]

Converts retinal distances (um) to visual angles (deg)

This function converts an eccentricity measurement on the retinal surface (in micrometers), measured from the optic axis, into degrees of visual angle. Source: Eq. A6 in Watson (2014), J Vis 14(7):15, 1-17