pulse2percept.models

This module provides a number of computational models.

base
scoreboard
axon_map	This module implements several equations from [Beyeler2019].
watson2014	This module implements several equation from [Watson2014].

class pulse2percept.models.AxonMapModel(**kwargs)

Axon map model

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

Parameters:

• axlambda (double) – Exponential decay constant along the axon (microns).
• rho (double) – Exponential decay constant away from the axon (microns).

build(**build_params)

Build the model

Every model must have a `build method, which is meant to perform all expensive one-time calculations. You must call build before calling predict_percept.

You can override build in your own model (for a good example, see the AxonMapModel). You will want to make sure that:

• all build_params take effect,
• the flag _is_built is set,
• the method returns self.

One way to do this is to call the BaseModel’s build method from within your own model:

class MyModel(BaseModel):

def build(self, **build_params):

super(MyModel, self).build(self, **build_params) # Add your own code here…

Parameters:**build_params (Additional build parameters) – Additional build parameters passed as keyword arguments (e.g., model.build(engine='joblib')). Note that these must be listed in get_params; i.e., you can’t add any new parameters outside the constructor.

calc_bundle_tangent(xc, yc)

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.

find_closest_axon(bundles, xret=None, yret=None)

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

get_params()

Get a dictionary of all model parameters (don’t override!)

get_tissue_coords(xdva, ydva)

Converts dva to retinal coords

Parameters:ydva (xdva,) – x,y coordinates in dva Returns:xret, yret (double or array-like) – Corresponding x,y coordinates in microns

predict_percept(implant, t=None)

Predict a percept

Parameters:

• implant (ProsthesisSystem) – Stimulus can be passed via stim.
• fps (int, double) – Frames per second at which the percept should be rendered.
• n_frames (int) – If None, will simulate for the duration of the stimulus plus one frame (rounding up).

class pulse2percept.models.BaseModel(**kwargs)

Base model

The BaseModel class defines which methods and attributes a model must have. You can create your own model by adding a class that derives from BaseModel:

class MyModel(BaseModel):

The constructor is the only place where you can add new variables (i.e., class attributes). The signature of your own constructor should look like this:

def __init__(self, **kwargs):

meaning that all arguments are passed as keyword arguments. Also, make sure to call the BaseModel constructor first thing. So a complete example of a constructor could look like this:

class MyModel(BaseModel):

    def __init__(self, **kwargs):
        super(MyModel, self).__init__(self, **kwargs)
        self.newvar = 0

This is the only place where you can add new class attributes. Trying to set self.someothervar outside the constructor will raise an AttributeError. Of course, you can always set self.newvar = None in the constructor to make sure the variable exists, and then assign a new value in other class methods.

Note

Please note: If self.newvar already exists in the BaseModel class, the last line of the above code snippet would overwrite it.

To make the model complete (and compile), you will also need to fill in all methods marked with @abc.abstractmethod below. These include build and predict_percept. Have a look at the ScoreboardModel or AxonMapModel classes below to get an idea of how to write a complete model.

build(**build_params)

Build the model

Every model must have a `build method, which is meant to perform all expensive one-time calculations. You must call build before calling predict_percept.

You can override build in your own model (for a good example, see the AxonMapModel). You will want to make sure that:

• all build_params take effect,
• the flag _is_built is set,
• the method returns self.

One way to do this is to call the BaseModel’s build method from within your own model:

class MyModel(BaseModel):

def build(self, **build_params):

super(MyModel, self).build(self, **build_params) # Add your own code here…

Parameters:**build_params (Additional build parameters) – Additional build parameters passed as keyword arguments (e.g., model.build(engine='joblib')). Note that these must be listed in get_params; i.e., you can’t add any new parameters outside the constructor.

get_params()

Get a dictionary of all model parameters (don’t override!)

get_tissue_coords(xdva, ydva)

Convert dva into tissue coordinates

predict_percept(implant, t=None)

Predict a percept

Parameters:

• implant (ProsthesisSystem) – Stimulus can be passed via stim.
• fps (int, double) – Frames per second at which the percept should be rendered.
• n_frames (int) – If None, will simulate for the duration of the stimulus plus one frame (rounding up).

pulse2percept.models.dva2ret(r_deg)

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

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

Parameters:r_dva (double or array-like) – Eccentricity in degrees of visual angle (dva) Returns:r_um (double or array-like) – Eccentricity in microns

exception pulse2percept.models.NotBuiltError

Exception class used to raise if model is used before building

This class inherits from both ValueError and AttributeError to help with exception handling and backward compatibility.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

pulse2percept.models.ret2dva(r_um)

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 using Eq. A6 in [Watson2014].

Parameters:r_um (double or array-like) – Eccentricity in microns Returns:r_dva (double or array-like) – Eccentricity in degrees of visual angle (dva)

class pulse2percept.models.ScoreboardModel(**kwargs)

Scoreboard model

build(**build_params)

Build the model

Every model must have a `build method, which is meant to perform all expensive one-time calculations. You must call build before calling predict_percept.

You can override build in your own model (for a good example, see the AxonMapModel). You will want to make sure that:

• all build_params take effect,
• the flag _is_built is set,
• the method returns self.

One way to do this is to call the BaseModel’s build method from within your own model:

class MyModel(BaseModel):

def build(self, **build_params):

super(MyModel, self).build(self, **build_params) # Add your own code here…

Parameters:**build_params (Additional build parameters) – Additional build parameters passed as keyword arguments (e.g., model.build(engine='joblib')). Note that these must be listed in get_params; i.e., you can’t add any new parameters outside the constructor.

get_params()

Get a dictionary of all model parameters (don’t override!)

get_tissue_coords(xdva, ydva)

Converts dva to retinal coords

Parameters:ydva (xdva,) – x,y coordinates in dva Returns:xret, yret (double or array-like) – Corresponding x,y coordinates in microns

predict_percept(implant, t=None)

Predict a percept

Parameters:

• implant (ProsthesisSystem) – Stimulus can be passed via stim.
• fps (int, double) – Frames per second at which the percept should be rendered.
• n_frames (int) – If None, will simulate for the duration of the stimulus plus one frame (rounding up).

class pulse2percept.models.Watson2014ConversionMixin

Converts dva to retinal coords using [Watson2014]

Converts from eccentricity (defined as distance from a visual center) in degrees of visual angle (dva) to microns on the retina using Eqs. A5, A6 in [Watson2014].

get_tissue_coords(xdva, ydva)

Converts dva to retinal coords

Parameters:ydva (xdva,) – x,y coordinates in dva Returns:xret, yret (double or array-like) – Corresponding x,y coordinates in microns

class pulse2percept.models.Watson2014DisplacementMixin

Converts dva to ret coords with RGC displacement

Converts from eccentricity (defined as distance from a visual center) in degrees of visual angle (dva) to microns on the retina using Eqs. 5, A5, and A6 in [Watson2014].

In a central retinal zone, the retinal ganglion cell (RGC) bodies are displaced centrifugally some distance from the inner segments of the cones to which they are connected through the bipolar cells, and thus from their receptive field. The displacement function is described in Eq. 5 of [Watson2014].

get_tissue_coords(xdva, ydva)

Converts dva to retinal coords

Parameters:ydva (xdva,) – x,y coordinates in dva Returns:xret, yret (double or array-like) – Corresponding x,y coordinates in microns