retina

BaseModel(**kwargs) Abstract base class for all models of temporal sensitivity.
Grid([x_range, y_range, eye, 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)
axon_contribution(axon_dist, current_spread) Determines the contribution of a single axon to the current map
axon_dist_from_soma(axon, xg, yg[, tree]) Calculates the distance to soma for every axon segment
dva2ret(r_deg) Converts visual angles (deg) into retinal distances (um)
find_closest_axon(pos_xy, axon_bundles) Finds the closest axon to a 2D point
jansonius([num_cells, num_samples, center, …]) Deprecated function. Use p2p.retina.jansonius2009 instead.
jansonius2009(phi0[, n_rho, rho_range, eye, …]) Grows a single axon bundle based on the model by Jansonius et al.
make_axon_map(xg, yg, jan_x, jan_y[, …]) Deprecated function.
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(x_range=(-1000.0, 1000.0), y_range=(-1000.0, 1000.0), eye=’RE’, sampling=25, 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’, contribution_rule=’max’, decay_const=2.0, powermean_exp=None, datapath=’.’, save_data=True, engine=’joblib’, scheduler=’threading’, n_jobs=-1)[source]

Bases: object

Represent the retinal coordinate frame

Methods

current2effectivecurrent(current_spread) 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__(x_range=(-1000.0, 1000.0), y_range=(-1000.0, 1000.0), eye=’RE’, sampling=25, 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’, contribution_rule=’max’, decay_const=2.0, powermean_exp=None, datapath=’.’, save_data=True, engine=’joblib’, scheduler=’threading’, n_jobs=-1)[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:

x_range : (xlo, xhi), optional, default: xlo=-1000, xhi=1000

Extent of the retinal coverage (microns) in horizontal dimension.

y_range : (ylo, yhi), optional, default: ylo=-1000, ylo=1000

Extent of the retinal coverage (microns) in vertical dimension.

eye : {‘LE’, ‘RE’}, optional, default: ‘RE’

Which eye to simulate (left/right). The optic disc is at (15, 2) deg in a right eye, and at (-15, 2) deg in a left eye.

sampling : float, optional, default: 25

Spatial sampling step (microns) for the grid.

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.0, 2.0)

Location of the center of the optic disc(x, y) in Cartesian coordinates.

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 Figure 2 in Jeng, Tang, Molnar, Desai, and Fried (2011). The sodium channel band shapes the response to electric stimulation in retinal ganglion cells. J Neural Eng 8 (036022).

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

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: None

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, optional, default: current directory

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

save_data : bool, optional, default: True

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.

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

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.

current2effectivecurrent(current_spread)[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) 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)[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>

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 < #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_TEMPORAL_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.

axon_contribution

pulse2percept.retina.axon_contribution(axon_dist, current_spread, sensitivity_rule=’decay’, contribution_rule=’max’, min_contribution=0.01, decay_const=2.0, powermean_exp=None)[source]

Determines the contribution of a single axon to the current map

This function determines the contribution of a single axon to the current map based on a sensitivity rule (i.e., how the activation threshold of the axon differs as a function of distance from the soma), and an contribution rule (i.e., how the different activation thresholds along the axon are combined to determine the axon contribution).

Parameters:

axon_dist : tuple (indices, distances)

A tuple containing a list of coordinates (indices into the retinal coordinates mesh grid) and distances for each axon segment.

current_spread : 2D array

A 2D current spread map that must have the same dimensions as the xg, yg meshgrid.

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 Figure 2 in Jeng, Tang, Molnar, Desai, and Fried (2011). The sodium channel band shapes the response to electric stimulation in retinal ganglion cells. J Neural Eng 8 (036022).

contribution_rule : {‘max’, ‘sum’, ‘power-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).

min_contribution : float, optional, default: 0.01

Current contributions below this value will not be counted.

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: None

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

axon_dist_from_soma

pulse2percept.retina.axon_dist_from_soma(axon, xg, yg, tree=None)[source]

Calculates the distance to soma for every axon segment

For every segment of an axon, this function calculates the distance to the soma. The 2D coordinates of the axon are snapped to the grid using a nearest-neighbor tree structure.

Parameters:

axon: Nx2 array

A single axon, where axon[0, :] contains the (x, y) coordinates of the location closest to the soma, and all subsequent rows move the axon away from the soma towards the optic disc.

xg, yg: array

meshgrid of pixel locations in units of visual angle sp

tree : spat.cKDTree class instance, optional, default: train on xg, yg

A kd-tree trained on xg, yg for quick nearest-neighbor lookup.

Returns:

idx_cs : list

Axon segment locations snapped to the grid, returned as a list of indices into the flat xg, yg meshgrid.

dist : list

Axon segment distances to the soma

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

find_closest_axon

pulse2percept.retina.find_closest_axon(pos_xy, axon_bundles)[source]

Finds the closest axon to a 2D point

This function finds the axon bundle closest to a 2D point pos_xy on the retina, and returns an axon that originates in pos_xy and projects to the optic disc.

Parameters:

pos_xy: (x, y)

2D Cartesian coordinates of a location on the retina.

axon_bundles: list of Nx2 arrays

List of two - dimensional arrays containing the(x, y) coordinates of each axon bundle. The first row of each axon bundle is assumed to be closest to the optic disc, and subsequent row indices move the axon away from the optic disc.

Returns:

axon: Nx2 array

A single axon, where axon[0, :] contains the (x, y) coordinates of the location closest to pos_xy, and all subsequent rows move the axon closer to the optic disc.

Notes

The order of axonal segments in the output argument axon is reversed with respect to the axonal segments in the input argument axon_bundles.

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]

Deprecated function. Use p2p.retina.jansonius2009 instead.

Function jansonius is deprecated since version 0.3, and will be removed in version 0.4. Use p2p.retina.jansonius2009 instead.

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

jansonius2009

pulse2percept.retina.jansonius2009(phi0, n_rho=801, rho_range=(4.0, 45.0), eye=’RE’, loc_od=(15.5, 1.5), beta_sup=-1.9, beta_inf=0.5)[source]

Grows a single axon bundle based on the model by Jansonius et al. (2009)

This function generates the trajectory of a single nerve fiber bundle based on the mathematical model described in [R14].

Parameters:

phi0: float

Angular position of the axon at its starting point(polar coordinates, degrees). 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).

beta_sup: float, optional, default: -1.9

Scalar value for the superior retina(see Eq. 5, eta_s in the paper).

beta_inf: float, optional, default: 0.5

Scalar value for the inferior retina(see Eq. 6, eta_i in the paper.)

Returns:

ax_pos: Nx2 array

Returns a two - dimensional array of axonal positions, where ax_pos[0, :] contains the(x, y) coordinates of the axon segment closest to the optic disc, and aubsequent row indices move the axon away from the optic disc. Number of rows is at most n_rho, but might be smaller if the axon crosses the meridian.

Notes

The study did not include axons with phi0 in [-60, 60] deg.

[R14]N. M. Jansionus, J. Nevalainen, B. Selig, L.M. Zangwill, P.A. Sample, W. M. Budde, J. B. Jonas, W. A. Lagrèze, P. J. Airaksinen, R. Vonthein, L. A. Levin, J. Paetzold, and U. Schieferd, “A mathematical description of nerve fiber bundle trajectories and their variability in the human retina. Vision Research 49:2157-2163, 2009.

make_axon_map

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

Deprecated function.

Function make_axon_map is deprecated since version 0.3, and will be removed in version 0.4.

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

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