pulse2percept.models.beyeler2019

AxonMapModel, AxonMapSpatial [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.
  • use_legacy_build (bool, optional) – If true, searches over axons instead of using KDTree. Build will likely be slower if True
  • 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)
Returns: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.
Returns:

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.
Returns:

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.
  • use_legacy_build (bool, optional) – If true, searches over axons instead of using KDTree. Build will likely be slower if True
  • 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_bundle_tangent(xc, yc)[source]

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

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

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

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

Finds the closest axon segment for every point (xret, yret)

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

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

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.
Returns:

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

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

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.
Returns:

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

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.
Returns:

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.
Returns:

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