pulse2percept.topography

Visual field maps, retinotopy, and visuotopy

base	Grid2D, VisualFieldMap
retina	RetinalMap, Curcio1990Map, Watson2014Map, Watson2014DisplaceMap
cortex	CorticalMap, Polimeni2006Map
neuropythy	NeuropythyMap

class pulse2percept.topography.CorticalMap(**params)

Template class for V1/V2/V3 visuotopic maps

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.

get_default_params()

Required to inherit from Parametrized

get_param_units()

Return a dict of the units that parameters are stored in

abstract dva_to_v1(x, y)

Convert degrees visual angle (dva) to V1 coordinates (um)

dva_to_v2(x, y)

Abstract Method: Convert degrees visual angle (dva) to V2 coordinates (um)

dva_to_v3(x, y)

Abstract Method: Convert degrees visual angle (dva) to V3 coordinates (um)

v1_to_dva(x, y)

Convert V1 coordinates (um) to degrees visual angle (dva)

v2_to_dva(x, y)

Convert V2 coordinates (um) to degrees visual angle (dva)

v3_to_dva(x, y)

Convert V3 coordinates (um) to degrees visual angle (dva)

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.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 a dict of the units that parameters are stored in

Maps a parameter name to the Unit that the implementation assumes it is expressed in. A Quantity assigned to such a parameter is checked against that unit and rescaled to it, so that

FadingTemporal(tau=100)
FadingTemporal(tau=100 * ms)
FadingTemporal(tau=0.1 * s)

all store the same float. Bare numbers keep their documented meaning and are passed through untouched.

Parameters absent from this dict take plain numbers: they are either dimensionless (thresh_percept) or empirical fit parameters whose dimension the implementation does not actually commit to. Declaring a unit is a statement about what the equations assume, so a parameter should only appear here when that is documented or unambiguous.

This dict is not restricted to the names in get_default_params: it describes every physical attribute this object normalizes. A constructor argument assigned straight to self – DefaultSizeModel takes rho that way – belongs here too, and is converted like any other.

Subclasses extend rather than replace it:

def get_param_units(self):
    return {**super().get_param_units(), 'dt': ms, 'tau': ms}

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.Grid2D(x_range, y_range, step=1, grid_type='rectangular')

2D grid of visual field coordinates

This class generates and stores 2D mesh grids of coordinates across different regions (visual field, retina, cortex). The grid is uniform in visual field, and transformed with a retinotopic mapping to obtain the grid in other regions.

Its own coordinates are therefore degrees of visual angle: they are what build() hands to a visual field map, and what grid.x and grid.y report. A grid of physical coordinates is a different thing and is not this class; see _rectangular_mesh().

Added in version 0.6.

Parameters:

• x_range ((x_min, x_max)) – A tuple indicating the range of x values in dva (includes end points)

• y_range (tuple, (y_min, y_max)) – A tuple indicating the range of y values in dva (includes end points)

• step (int, double, tuple) –

  Step size (dva). If int or double, the same step will apply to both x and y ranges. If a tuple, it is interpreted as (x_step, y_step).

  This is a target spacing rather than an exact one: both end points of a range are always included, so a range that is not a whole multiple of step is sampled at the nearest spacing that reaches both. Grid2D((0, 1), (0, 0), step=0.3) gives four points spaced 0.333 apart, not three spaced 0.3 with the last one short.

• grid_type ({'rectangular', 'hexagonal'}) – The grid type

Notes

• The grid uses Cartesian indexing (indexing='xy' for NumPy’s meshgrid function). This implies that the grid’s shape will be (number of y coordinates) x (number of x coordinates).

• If a range is zero, the step size is irrelevant.

• x_range, y_range and step may be given as plain numbers of degrees or as unitful quantities (e.g. step=0.5 * dva), and are stored as plain numbers. See pulse2percept.units.

Changed in version 0.10.0: The visual field contract is explicit: the three range arguments are degrees of visual angle, and a quantity in any other dimension raises.

Examples

You can iterate through a grid as if it were a list. Notice, the grid is indexed in (x, y) order, starting in the upper left of the grid (following image convention)

>>> grid = Grid2D((0, 1), (2, 3))
>>> for x, y in grid:
...     print(x, y)
0.0 3.0
1.0 3.0
0.0 2.0
1.0 2.0

visual_unit = dva

The unit this grid’s own coordinates are in. A grid is uniform in the visual field, and a visual field map turns it into tissue coordinates.

plot(style='hull', autoscale=True, zorder=None, ax=None, figsize=None, fc=None, use_dva=False, legend=False, surface=None)

Plot the extension of the grid

Parameters:

• style ({'hull', 'scatter', 'cell'}, optional) –

  • ‘hull’: Show the convex hull of the grid (that is, the outline of the smallest convex set that contains all grid points).

  • ’scatter’: Scatter plot all grid points

  • ’cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a high-resolution grid.

• autoscale (bool, optional) – Whether to adjust the x,y limits of the plot to fit the implant

• zorder (int, optional) – The Matplotlib zorder at which to plot the grid

• 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

• figsize ((float, float), optional) – Desired (width, height) of the figure in inches

• fc (str or valid matplotlib color, optional) – Facecolor, or edge color if style=scatter, of the plotted region Defaults to gray

• use_dva (bool, optional) – Whether dva or transformed points should be plotted. If True, will not apply any transformations, and if False, will apply all transformations in self.vfmap

• legend (bool, optional) – Whether to add a plot legend. The legend is always added if there are 2 or more regions. This only applies if there is 1 region.

• surface (str, optional) – Name of the surface to plot (only for vfmaps that accept a surface argument)

plot3D(style='scatter', ax=None, surface='midgray', color_by='region', **kwargs)

Plots grid points in 3D space. Note, you must have a 3D visual field map to use this method. :param style:

• ‘scatter’: Scatter plot all grid points

• ‘cell’: Show the outline of each grid cell as a polygon. Note that this can be costly for a high-resolution grid.

Parameters:

• 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

• surface (str, optional) – Name of the cortical surface to plot (only with neuropythy vfmap)

• color_by (str, optional) – What to color the points by. Options are ‘region’ (default), ‘eccentricity’, or ‘angle’

• kwargs (dict) – Additional keyword arguments to pass to plt.figure() (figsize) or ax.scatter() or ax.plot_trisurf()

class pulse2percept.topography.Watson2014DisplaceMap(**params)

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

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

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

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

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

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 a dict of the units that parameters are stored in

Maps a parameter name to the Unit that the implementation assumes it is expressed in. A Quantity assigned to such a parameter is checked against that unit and rescaled to it, so that

FadingTemporal(tau=100)
FadingTemporal(tau=100 * ms)
FadingTemporal(tau=0.1 * s)

all store the same float. Bare numbers keep their documented meaning and are passed through untouched.

Parameters absent from this dict take plain numbers: they are either dimensionless (thresh_percept) or empirical fit parameters whose dimension the implementation does not actually commit to. Declaring a unit is a statement about what the equations assume, so a parameter should only appear here when that is documented or unambiguous.

This dict is not restricted to the names in get_default_params: it describes every physical attribute this object normalizes. A constructor argument assigned straight to self – DefaultSizeModel takes rho that way – belongs here too, and is converted like any other.

Subclasses extend rather than replace it:

def get_param_units(self):
    return {**super().get_param_units(), 'dt': ms, 'tau': ms}

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.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 a dict of the units that parameters are stored in

Maps a parameter name to the Unit that the implementation assumes it is expressed in. A Quantity assigned to such a parameter is checked against that unit and rescaled to it, so that

FadingTemporal(tau=100)
FadingTemporal(tau=100 * ms)
FadingTemporal(tau=0.1 * s)

all store the same float. Bare numbers keep their documented meaning and are passed through untouched.

Parameters absent from this dict take plain numbers: they are either dimensionless (thresh_percept) or empirical fit parameters whose dimension the implementation does not actually commit to. Declaring a unit is a statement about what the equations assume, so a parameter should only appear here when that is documented or unambiguous.

This dict is not restricted to the names in get_default_params: it describes every physical attribute this object normalizes. A constructor argument assigned straight to self – DefaultSizeModel takes rho that way – belongs here too, and is converted like any other.

Subclasses extend rather than replace it:

def get_param_units(self):
    return {**super().get_param_units(), 'dt': ms, 'tau': ms}

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.Polimeni2006Map(**params)

Polimeni visual mapping

get_default_params()

Required to inherit from Parametrized

get_param_units()

Return a dict of the units that parameters are stored in

dva_to_v1(x, y)

Convert degrees visual angle (dva) to V1 coordinates (um)

dva_to_v2(x, y)

Abstract Method: Convert degrees visual angle (dva) to V2 coordinates (um)

dva_to_v3(x, y)

Abstract Method: Convert degrees visual angle (dva) to V3 coordinates (um)

v1_to_dva(x, y)

Convert V1 coordinates (um) to degrees visual angle (dva)

v2_to_dva(x, y)

Convert V2 coordinates (um) to degrees visual angle (dva)

v3_to_dva(x, y)

Convert V3 coordinates (um) to degrees visual angle (dva)

from_dva()

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

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.NeuropythyMap(subject='fsaverage', cache_dir=None, **params)

get_default_params()

Required to inherit from Parametrized

get_param_units()

Return a dict of the units that parameters are stored in

load_meshes(subject)

Predicts retinotopy and loads submeshes for the given subject. Adapted from code courtesy of Noah Benson

dva_to_cortex(x, y, region='v1', hemi=None, surface='midgray')

Gives the cortex position(s) of the visual field point(s) (x,y).

Parameters:

• x (float or array_like) – The x and y-coordinate(s) of the visual field point(s) to look up (in dva).

• y (float or array_like) – The x and y-coordinate(s) of the visual field point(s) to look up (in dva).

• region (str) – The visual field map to look up the point(s) in. Valid options are ‘v1’, ‘v2’, and ‘v3’. Default is ‘v1’.

• hemi (str) – The hemisphere to look up the point(s) in. Valid options are ‘lh’ and ‘rh’.

• surface (str) – The surface to look up the point(s) on. Default is ‘midgray’. Other common options include ‘pial’ and ‘white’.

Returns:

• cortex_pts (array_like) – cortical addresses of the visual field points (cortical addresses provide the face containing a point and the barycentric coordinates of the point within that face).

• Adapted from code courtesy of Noah Benson

dva_to_v1(x, y, surface='midgray')

Gives the 3D cortex position(s) of the visual field point(s) (x,y) in v1.

Parameters:

• x (float or array_like) – The x and y-coordinate(s) of the visual field point(s) to look up (in dva).

• y (float or array_like) – The x and y-coordinate(s) of the visual field point(s) to look up (in dva).

• surface (str) – The surface to look up the point(s) on. Default is ‘midgray’. Other common options include ‘pial’ and ‘white’.

dva_to_v2(x, y, surface='midgray')

Gives the 3D cortex position(s) of the visual field point(s) (x,y) in v2.

Parameters:

• x (float or array_like) – The x and y-coordinate(s) of the visual field point(s) to look up (in dva).

• y (float or array_like) – The x and y-coordinate(s) of the visual field point(s) to look up (in dva).

• surface (str) – The surface to look up the point(s) on. Default is ‘midgray’. Other common options include ‘pial’ and ‘white’.

dva_to_v3(x, y, surface='midgray')

Gives the 3D cortex position(s) of the visual field point(s) (x,y) in v3.

Parameters:

• x (float or array_like) – The x and y-coordinate(s) of the visual field point(s) to look up (in dva).

• y (float or array_like) – The x and y-coordinate(s) of the visual field point(s) to look up (in dva).

• surface (str) – The surface to look up the point(s) on. Default is ‘midgray’. Other common options include ‘pial’ and ‘white’.

cortex_to_dva(xc, yc, zc)

Gives the visual field position(s) of the cortex point(s) (xc,yc,zc).

Parameters:

• xc (float or array_like) – The x, y, and z-coordinate(s) of the cortex point(s) to look up (in um).

• yc (float or array_like) – The x, y, and z-coordinate(s) of the cortex point(s) to look up (in um).

• zc (float or array_like) – The x, y, and z-coordinate(s) of the cortex point(s) to look up (in um).

Returns:

x, y – The x and y-coordinate(s) of the visual field point(s) (in dva). Both have the same shape as the input. Points that cannot be mapped are NaN: either because the input was NaN, or because no mesh vertex lies within cort_nn_thresh of them.

Return type:

array_like

v1_to_dva(xv1, yv1, zv1)

Convert points in v1 to dva. Uses the mean of the 5 nearest neighbors in the cortical mesh, weighted by 1/distance, to interpolate dva. Any points that are more than self.cort_nn_thresh um from the nearest neighbor will be set to nan.

Parameters:

• xv1 (float or array_like) – The x, y, and z-coordinate(s) of the v1 point(s) to look up (in um).

• yv1 (float or array_like) – The x, y, and z-coordinate(s) of the v1 point(s) to look up (in um).

• zv1 (float or array_like) – The x, y, and z-coordinate(s) of the v1 point(s) to look up (in um).

Returns:

x, y – The x and y-coordinate(s) of the visual field point(s) (in dva).

Return type:

array_like

v2_to_dva(xv2, yv2, zv2)

Convert points in v2 to dva. Uses the mean of the 5 nearest neighbors in the cortical mesh, weighted by 1/distance, to interpolate dva. Any points that are more than self.cort_nn_thresh um from the nearest neighbor will be set to nan.

Parameters:

• xv2 (float or array_like) – The x, y, and z-coordinate(s) of the v2 point(s) to look up (in um).

• yv2 (float or array_like) – The x, y, and z-coordinate(s) of the v2 point(s) to look up (in um).

• zv2 (float or array_like) – The x, y, and z-coordinate(s) of the v2 point(s) to look up (in um).

Returns:

x, y – The x and y-coordinate(s) of the visual field point(s) (in dva).

Return type:

array_like

v3_to_dva(xv3, yv3, zv3)

Convert points in v3 to dva. Uses the mean of the 5 nearest neighbors in the cortical mesh, weighted by 1/distance, to interpolate dva. Any points that are more than self.cort_nn_thresh um from the nearest neighbor will be set to nan.

Parameters:

• xv3 (float or array_like) – The x, y, and z-coordinate(s) of the v3 point(s) to look up (in um).

• yv3 (float or array_like) – The x, y, and z-coordinate(s) of the v3 point(s) to look up (in um).

• zv3 (float or array_like) – The x, y, and z-coordinate(s) of the v3 point(s) to look up (in um).

Returns:

x, y – The x and y-coordinate(s) of the visual field point(s) (in dva).

Return type:

array_like

from_dva()

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

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