pulse2percept.topography.retina

Retinal visual field maps

base	RetinalMap
curcio1990	Curcio1990Map
montesano2020	Montesano2020Map
watson2014	Watson2014Map, Watson2014DisplaceMap

class pulse2percept.topography.retina.Curcio1990Map(**params)

Converts between visual angle and retinal eccentricity [Curcio1990]

dva_to_ret(xdva, ydva)

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

Assumes that one degree of visual angle is equal to 280 um on the retina [Curcio1990].

ret_to_dva(xret, yret)

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

Assumes that one degree of visual angle is equal to 280 um on the retina [Curcio1990]

from_dva()

Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).

get_default_params()

Required to inherit from Parametrized

get_param_units()

Return storage units for physical parameters.

Subclasses should extend this mapping. Parameters not listed here take plain dimensionless values.

Added in version 0.10.0.

set_params(**params)

Set the parameters of this object

tissue_unit = um

The unit of the tissue side of the map

to_dva()

Returns a dict containing the region(s) that this visuotopy maps from, and the corresponding inverse mapping function(s). This transform is optional for most models.

visual_unit = dva

The unit of the visual field side of the map

class pulse2percept.topography.retina.Montesano2020Map(**params)

Converts between visual angle and retinal eccentricity using two-dimensional RGC displacement [Montesano2020]

Retinal ganglion cell (RGC) bodies are displaced centrifugally from the receptive fields (RFs) they serve. The displacement depends on meridian as well as eccentricity. This map applies the [Montesano2020] field in degrees of visual angle (dva), then converts the displaced location to microns with Watson2014Map.

Displacement is radial: the visual-field polar angle is preserved. The anatomical meridian only selects which profile applies. The zone reaches 14.10 dva temporally and superiorly, 10.52 dva inferiorly, 9.54 dva nasally. Beyond 15 dva the map is the identity.

Added in version 0.11.0.

Parameters:

eye ({'right', 'left'}, optional) – Retinal laterality. Nasal retina is the positive-x visual field in a right eye, the negative-x one in a left eye; positive y is inferior retina in both. Case-insensitive on input; stored lowercase. Defaults to 'right'.

Notes

• An independent reconstruction of [Montesano2020] as opposed to a port of the original code. The implementation was validated against that paper’s published figures and E2v fits, and cross-checked against the visualFields implementation by the same group, which it matches to 0.07 dva inside the displacement zone. See tools/generate_montesano2020_map.py.

• This is based on population anatomy [Curcio1990] and not to be interpreted as a subject-specific eye.

property eye

Eye whose nasal/temporal anatomy is used

get_default_params()

Required to inherit from Parametrized

dva_to_ret(xdva, ydva, coords='cart')

Converts dva to retinal coords

Displaces RF to soma in the visual field, then converts to microns with Eq. A5 of [Watson2014].

Parameters:

• xdva (double or array-like) – x,y coordinates in dva

• ydva (double or array-like) – x,y coordinates in dva

• coords ({'cart', 'polar'}) – Whether to return the result in Cartesian or polar coordinates

Returns:

xret, yret – Corresponding x,y coordinates in microns

Return type:

double or array-like

from_dva()

Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).

get_param_units()

Return storage units for physical parameters.

Subclasses should extend this mapping. Parameters not listed here take plain dimensionless values.

Added in version 0.10.0.

ret_to_dva(xret, yret, coords='cart')

Converts retinal coords to dva

Inverts dva_to_ret(). Eq. A5 of [Watson2014] is inverted numerically, so this does not reproduce Watson2014Map.ret_to_dva(), which evaluates Eq. A6.

Parameters:

• xret (double or array-like) – x,y coordinates in microns

• yret (double or array-like) – x,y coordinates in microns

• coords ({'cart', 'polar'}) – Whether to return the result in Cartesian or polar coordinates

Returns:

xdva, ydva – Corresponding x,y coordinates in dva

Return type:

double or array-like

set_params(**params)

Set the parameters of this object

tissue_unit = um

The unit of the tissue side of the map

to_dva()

Returns a dict containing the region(s) that this visuotopy maps from, and the corresponding inverse mapping function(s). This transform is optional for most models.

visual_unit = dva

The unit of the visual field side of the map

class pulse2percept.topography.retina.RetinalMap(**params)

Template class for retinal visual field maps, which only have 1 region.

from_dva()

Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).

to_dva()

Returns a dict containing the region(s) that this visuotopy maps from, and the corresponding inverse mapping function(s). This transform is optional for most models.

abstractmethod dva_to_ret(x, y)

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

ret_to_dva(x, y)

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

get_default_params()

Required to inherit from Parametrized

get_param_units()

Return storage units for physical parameters.

Subclasses should extend this mapping. Parameters not listed here take plain dimensionless values.

Added in version 0.10.0.

set_params(**params)

Set the parameters of this object

tissue_unit = um

The unit of the tissue side of the map

visual_unit = dva

The unit of the visual field side of the map

class pulse2percept.topography.retina.Watson2014DisplaceMap(**kwargs)

Converts between visual angle and retinal eccentricity using RGC displacement [Watson2014]

Deprecated since version 0.11.0: Use Montesano2020Map, a two-dimensional displacement field.

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

[Watson2014] fits Eq. 5 separately for the nasal and temporal meridian. Specify eye as either 'left' or 'right' for the proper assignment (one is the horizontal mirror of the other). Points on the vertical meridian (x == 0) use the nasal fit, which is a backward-compatible tie-break rather than an anatomical claim.

Each fit applies throughout its retinal hemifield, so a point 45 deg above the horizon is displaced like one on the horizon at the same eccentricity. Kept for reproducing earlier results; ret_to_dva raises NotImplementedError.

Parameters:

eye ({'right', 'left'}, optional) –

Eye whose nasal/temporal displacement functions are used. Case-insensitive on input; stored lowercase. Defaults to 'right'.

Added in version 0.11.0.

property eye

Eye whose nasal and temporal displacement functions are used

get_default_params()

Required to inherit from Parametrized

watson_displacement(r, meridian='temporal')

Ganglion cell displacement function

Implements the ganglion cell displacement function described in Eq. 5 of [Watson2014].

Parameters:

• r (double|array-like) – Eccentricity in degrees of visual angle (dva)

• meridian ('temporal' or 'nasal') – Meridian whose fit to apply, elementwise if array-like. Which meridian a visual-field location falls on depends on the eye, but this function does not: it only evaluates the requested fit.

Returns:

• The displacement in dva experienced by ganglion cells at eccentricity

• r.

dva_to_ret(xdva, ydva)

Converts dva to retinal coords

Parameters:

• xdva (double or array-like) – x,y coordinates in dva

• ydva (double or array-like) – x,y coordinates in dva

Returns:

xret, yret – Corresponding x,y coordinates in microns

Return type:

double or array-like

from_dva()

Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).

get_param_units()

Return storage units for physical parameters.

Subclasses should extend this mapping. Parameters not listed here take plain dimensionless values.

Added in version 0.10.0.

ret_to_dva(xret, yret)

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:

• x_um (double or array-like) – Original x and y coordinates on the retina (microns)

• y_um (double or array-like) – Original x and y coordinates on the retina (microns)

• coords ({'cart', 'polar'}) – Whether to return the result in Cartesian or polar coordinates

Returns:

x_dva, y_dva – Transformed x and y coordinates (degrees of visual angle, dva)

Return type:

double or array-like

set_params(**params)

Set the parameters of this object

tissue_unit = um

The unit of the tissue side of the map

to_dva()

Returns a dict containing the region(s) that this visuotopy maps from, and the corresponding inverse mapping function(s). This transform is optional for most models.

visual_unit = dva

The unit of the visual field side of the map

class pulse2percept.topography.retina.Watson2014Map(**params)

Converts between visual angle and retinal eccentricity [Watson2014]

ret_to_dva(x_um, y_um, coords='cart')

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:

• x_um (double or array-like) – Original x and y coordinates on the retina (microns)

• y_um (double or array-like) – Original x and y coordinates on the retina (microns)

• coords ({'cart', 'polar'}) – Whether to return the result in Cartesian or polar coordinates

Returns:

x_dva, y_dva – Transformed x and y coordinates (degrees of visual angle, dva)

Return type:

double or array-like

dva_to_ret(x_deg, y_deg, coords='cart')

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:

• x_dva (double or array-like) – Original x and y coordinates (degrees of visual angle, dva)

• y_dva (double or array-like) – Original x and y coordinates (degrees of visual angle, dva)

• coords ({'cart', 'polar'}) – Whether to return the result in Cartesian or polar coordinates

Returns:

x_ret, y_ret – Transformed x and y coordinates on the retina (microns)

Return type:

double or array-like

from_dva()

Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).

get_default_params()

Required to inherit from Parametrized

get_param_units()

Return storage units for physical parameters.

Subclasses should extend this mapping. Parameters not listed here take plain dimensionless values.

Added in version 0.10.0.

set_params(**params)

Set the parameters of this object

tissue_unit = um

The unit of the tissue side of the map

to_dva()

Returns a dict containing the region(s) that this visuotopy maps from, and the corresponding inverse mapping function(s). This transform is optional for most models.

visual_unit = dva

The unit of the visual field side of the map