# pulse2percept.models.beyeler2019¶

Classes

 AxonMapModel(**params) Axon map model of [Beyeler2019] (standalone model) AxonMapSpatial(**params) Axon map model of [Beyeler2019] (spatial module only) ScoreboardModel(**params) Scoreboard model of [Beyeler2019] (standalone model) ScoreboardSpatial(**params) Scoreboard model of [Beyeler2019] (spatial module only)
class pulse2percept.models.beyeler2019.AxonMapModel(**params)[source]

Axon map model of [Beyeler2019] (standalone model)

Implements the axon map model described in [Beyeler2019], where percepts are elongated along nerve fiber bundle trajectories of the retina.

Parameters: axlambda (double, optional) – Exponential decay constant along the axon(microns). rho (double, optional) – Exponential decay constant away from the axon(microns). eye ({'RE', LE'}, optional) – Eye for which to generate the axon map. xrange ((x_min, x_max), optional) – A tuple indicating the range of x values to simulate (in degrees of visual angle). In a right eye, negative x values correspond to the temporal retina, and positive x values to the nasal retina. In a left eye, the opposite is true. yrange (tuple, (y_min, y_max)) – A tuple indicating the range of y values to simulate (in degrees of visual angle). Negative y values correspond to the superior retina, and positive y values to the inferior retina. xystep (int, double, tuple) – Step size for the range of (x,y) values to simulate (in degrees of visual angle). For example, to create a grid with x values [0, 0.5, 1] use x_range=(0, 1) and xystep=0.5. grid_type ({'rectangular', 'hexagonal'}) – Whether to simulate points on a rectangular or hexagonal grid loc_od (loc_od,) – Location of the optic disc in degrees of visual angle. Note that the optic disc in a left eye will be corrected to have a negative x coordinate. n_axons (int, optional) – Number of axons to generate. axons_range ((min, max), optional) – The range of angles(in degrees) at which axons exit the optic disc. This corresponds to the range of $phi_0$ values used in [Jansonius2009]. n_ax_segments (int, optional) – Number of segments an axon is made of. ax_segments_range ((min, max), optional) – Lower and upper bounds for the radial position values(polar coords) for each axon. min_ax_sensitivity (float, optional) – Axon segments whose contribution to brightness is smaller than this value will be pruned to improve computational efficiency. Set to a value between 0 and 1. axon_pickle (str, optional) – File name in which to store precomputed axon maps. ignore_pickle (bool, optional) – A flag whether to ignore the pickle file in future calls to model.build().

Notes

• The axon map is not very accurate when the upper bound of ax_segments_range is greater than 90 deg.
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) 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. 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. 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.beyeler2019.AxonMapSpatial(**params)[source]

Axon map model of [Beyeler2019] (spatial module only)

Implements the axon map model described in [Beyeler2019], where percepts are elongated along nerve fiber bundle trajectories of the retina.

Parameters: axlambda (double, optional) – Exponential decay constant along the axon(microns). rho (double, optional) – Exponential decay constant away from the axon(microns). eye ({'RE', LE'}, optional) – Eye for which to generate the axon map. xrange ((x_min, x_max), optional) – A tuple indicating the range of x values to simulate (in degrees of visual angle). In a right eye, negative x values correspond to the temporal retina, and positive x values to the nasal retina. In a left eye, the opposite is true. yrange (tuple, (y_min, y_max)) – A tuple indicating the range of y values to simulate (in degrees of visual angle). Negative y values correspond to the superior retina, and positive y values to the inferior retina. xystep (int, double, tuple) – Step size for the range of (x,y) values to simulate (in degrees of visual angle). For example, to create a grid with x values [0, 0.5, 1] use x_range=(0, 1) and xystep=0.5. grid_type ({'rectangular', 'hexagonal'}) – Whether to simulate points on a rectangular or hexagonal grid loc_od (loc_od,) – Location of the optic disc in degrees of visual angle. Note that the optic disc in a left eye will be corrected to have a negative x coordinate. n_axons (int, optional) – Number of axons to generate. axons_range ((min, max), optional) – The range of angles(in degrees) at which axons exit the optic disc. This corresponds to the range of $phi_0$ values used in [Jansonius2009]. n_ax_segments (int, optional) – Number of segments an axon is made of. ax_segments_range ((min, max), optional) – Lower and upper bounds for the radial position values(polar coords) for each axon. min_ax_sensitivity (float, optional) – Axon segments whose contribution to brightness is smaller than this value will be pruned to improve computational efficiency. Set to a value between 0 and 1. axon_pickle (str, optional) – File name in which to store precomputed axon maps. ignore_pickle (bool, optional) – A flag whether to ignore the pickle file in future calls to model.build().

Notes

• The axon map is not very accurate when the upper bound of ax_segments_range is greater than 90 deg.
build(**build_params)[source]

Build the model

Performs expensive one-time calculations, such as building the spatial grid used to predict a percept. 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)
calc_axon_sensitivity(bundles)[source]

Calculate the sensitivity of each axon segment to electrical current

This function combines the x,y coordinates of each bundle segment with a sensitivity value that depends on the distance of the segment to the cell body and self.axlambda.

The number of bundles must equal the number of points on self.grid. The function will then assume that the i-th bundle passes through the i-th point on the grid. This is used to determine the bundle segment that is closest to the i-th point on the grid, and to cut off all segments that extend beyond the soma. This effectively transforms a bundle into an axon, where the first axon segment now corresponds with the i-th location of the grid.

After that, each axon segment gets a sensitivity value that depends on the distance of the segment to the soma (with decay rate self.axlambda). This is typically done during the build process, so that the only work left to do during run time is to multiply the sensitivity value with the current applied to each segment.

Parameters: bundles (list of Nx2 arrays) – A list of bundles, where every bundle is an Nx2 array consisting of the x,y coordinates of each axon segment (retinal coords, microns). Note that each bundle will most likely have a different N axon_contrib (list of Nx3 arrays) – A list of axon segments and sensitivity values. Each entry in the list is a Nx3 array, where the first two columns contain the retinal coordinates of each axon segment (microns), and the third column contains the sensitivity of the segment to electrical current. The latter depends on self.axlambda.
calc_bundle_tangent(xc, yc)[source]

Calculates orientation of fiber bundle tangent at (xc, yc)

Parameters: yc (xc,) – (x, y) retinal location of point at which to calculate bundle orientation in microns. tangent (scalar) – An angle in radians
static dva2ret(xdva)[source]

Convert degrees of visual angle (dva) into retinal coords (um)

The axon map model converts degrees of visual angle into a retinal distance from the optic axis (um) using Eq. A5 in [Watson2014].

find_closest_axon(bundles, xret=None, yret=None, return_index=False)[source]

Finds the closest axon segment for a point on the retina

This function will search a number of nerve fiber bundles (bundles) and return the bundle that is closest to a particular point (or list of points) on the retinal surface (xret, yret).

Parameters: bundles (list of Nx2 arrays) – A list of bundles, where every bundle is an Nx2 array consisting of the x,y coordinates of each axon segment (retinal coords, microns). Note that each bundle will most likely have a different N yret (xret,) – The x,y location on the retina (in microns, where the fovea is the origin) for which to find the closests axon. return_index (bool, optional) – If True, the function will also return the index into bundles that represents the closest axon axon (Nx2 array or list of Nx2 arrays) – For each point in (xret, yret), returns an Nx2 array that represents the closest axon to that point. Each row in the array contains the x,y retinal coordinates (microns) of a particular axon segment. idx_axon (scalar or list of scalars, optional) – If return_index is True, also returns the index in bundles of the closest axon (or list of closest axons).
find_threshold(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100)[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 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

grow_axon_bundles(n_bundles=None, prune=True)[source]

Grow a number of axon bundles

This method generates the trajectory of a number of nerve fiber bundles based on the mathematical model described in [Beyeler2019], which is based on [Jansonius2009].

Bundles originate at the optic nerve head with initial angle phi0. The method generates n_bundles axon bundles whose phi0 values are linearly sampled from self.axons_range (polar coords). Each axon will consist of self.n_ax_segments segments that span self.ax_segments_range distance from the optic nerve head (polar coords).

Parameters: n_bundles (int, optional) – Number of axon bundles to generate. If None, self.n_axons is used prune (bool, optional) – If set to True, will remove axon segments that are outside the simulated area self.xrange, self.yrange for the sake of computational efficiency. bundles (list of Nx2 arrays) – A list of bundles, where every bundle is an Nx2 array consisting of the x,y coordinates of each axon segment (retinal coords, microns). Note that each bundle will most likely have a different N
is_built

A flag indicating whether the model has been built

plot(use_dva=False, annotate=True, autoscale=True, ax=None)[source]

Plot the axon map

Parameters: use_dva (bool, optional) – Uses degrees of visual angle (dva) if True, else retinal coordinates (microns) annotate (bool, optional) – Flag whether to label the four retinal quadrants autoscale (bool, optional) – Whether to adjust the x,y limits of the plot ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object
predict_percept(implant, t_percept=None)[source]

Predict the spatial response

Important

Don’t override this method if you are creating your own model. Customize _predict_spatial instead.

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. percept (Percept) – A Percept object whose data container has dimensions Y x X x T. Will return None if implant.stim is None.
static ret2dva(xret)[source]

Convert retinal corods (um) to degrees of visual angle (dva)

The axon map model converts an eccentricity measurement on the retinal surface(in micrometers), measured from the optic axis, into degrees of visual angle using Eq. A6 in [Watson2014].

set_params(**params)[source]

Set the parameters of this model

class pulse2percept.models.beyeler2019.ScoreboardModel(**params)[source]

Scoreboard model of [Beyeler2019] (standalone model)

Implements the scoreboard model described in [Beyeler2019], where all percepts are Gaussian blobs.

Note

Use this class if you want a standalone model. Use ScoreboardSpatial if you want to combine the spatial model with a temporal model.

Parameters: rho (double, optional) – Exponential decay constant describing phosphene size (microns). x_range ((x_min, x_max), optional) – A tuple indicating the range of x values to simulate (in degrees of visual angle). In a right eye, negative x values correspond to the temporal retina, and positive x values to the nasal retina. In a left eye, the opposite is true. y_range (tuple, (y_min, y_max)) – A tuple indicating the range of y values to simulate (in degrees of visual angle). Negative y values correspond to the superior retina, and positive y values to the inferior retina. xystep (int, double, tuple) – Step size for the range of (x,y) values to simulate (in degrees of visual angle). For example, to create a grid with x values [0, 0.5, 1] use x_range=(0, 1) and xystep=0.5. grid_type ({'rectangular', 'hexagonal'}) – Whether to simulate points on a rectangular or hexagonal grid
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) 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. 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. 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.beyeler2019.ScoreboardSpatial(**params)[source]

Scoreboard model of [Beyeler2019] (spatial module only)

Implements the scoreboard model described in [Beyeler2019], where all percepts are Gaussian blobs.

Note

Use this class if you want to combine the spatial model with a temporal model. Use ScoreboardModel if you want a a standalone model.

Parameters: rho (double, optional) – Exponential decay constant describing phosphene size (microns). x_range ((x_min, x_max), optional) – A tuple indicating the range of x values to simulate (in degrees of visual angle). In a right eye, negative x values correspond to the temporal retina, and positive x values to the nasal retina. In a left eye, the opposite is true. y_range (tuple, (y_min, y_max)) – A tuple indicating the range of y values to simulate (in degrees of visual angle). Negative y values correspond to the superior retina, and positive y values to the inferior retina. xystep (int, double, tuple) – Step size for the range of (x,y) values to simulate (in degrees of visual angle). For example, to create a grid with x values [0, 0.5, 1] use x_range=(0, 1) and xystep=0.5. grid_type ({'rectangular', 'hexagonal'}) – Whether to simulate points on a rectangular or hexagonal grid important :: (.) – If you change important model parameters outside the constructor (e.g., by directly setting model.axlambda = 100), you will have to call model.build() again for your changes to take effect.
build(**build_params)[source]

Build the model

Performs expensive one-time calculations, such as building the spatial grid used to predict a percept. 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)
static dva2ret(xdva)[source]

Convert degrees of visual angle (dva) into retinal coords (um)

find_threshold(implant, bright_th, amp_range=(0, 999), amp_tol=1, bright_tol=0.1, max_iter=100)[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 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]

Returns all settable parameters of the scoreboard model

is_built

A flag indicating whether the model has been built

plot(use_dva=False, autoscale=True, ax=None)[source]

Plot the model

Parameters: use_dva (bool, optional) – Uses degrees of visual angle (dva) if True, else retinal coordinates (microns) autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant ax (matplotlib.axes._subplots.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object. ax (matplotlib.axes.Axes) – Returns the axis object of the plot
predict_percept(implant, t_percept=None)[source]

Predict the spatial response

Important

Don’t override this method if you are creating your own model. Customize _predict_spatial instead.

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. percept (Percept) – A Percept object whose data container has dimensions Y x X x T. Will return None if implant.stim is None.
static ret2dva(xret)[source]

Convert retinal corods (um) to degrees of visual angle (dva)

set_params`(**params)[source]

Set the parameters of this model