pulse2percept.topography¶
Visual field maps, retinotopy, and visuotopy
base |
Grid2D , VisualFieldMap |
retina |
RetinalMap , Curcio1990Map , Watson2014Map , Watson2014DisplaceMap |
cortex |
CorticalMap , Polimeni2006Map |
neuropythy |
-
class
pulse2percept.topography.
CorticalMap
(**params)[source]¶ Template class for V1/V2/V3 visuotopic maps
-
build
(**build_params)[source]¶ Build the model
Every model must have a
`build
method, which is meant to perform all expensive one-time calculations. You must callbuild
before callingpredict_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 aFreezeError
. Example:model.build(param1=val)
-
from_dva
()[source]¶ Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).
-
is_built
¶ A flag indicating whether the model has been built
-
-
class
pulse2percept.topography.
Curcio1990Map
(**params)[source]¶ Converts between visual angle and retinal eccentricity [Curcio1990]
-
build
(**build_params)[source]¶ Build the model
Every model must have a
`build
method, which is meant to perform all expensive one-time calculations. You must callbuild
before callingpredict_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 aFreezeError
. Example:model.build(param1=val)
-
dva_to_ret
(xdva, ydva)[source]¶ 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].
-
from_dva
()[source]¶ Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).
-
is_built
¶ A flag indicating whether the model has been built
-
ret_to_dva
(xret, yret)[source]¶ 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]
-
-
class
pulse2percept.topography.
Grid2D
(x_range, y_range, step=1, grid_type='rectangular')[source]¶ 2D spatial grid
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.
New in version 0.6.
Parameters: - x_range ((x_min, x_max)) – A tuple indicating the range of x values (includes end points)
- y_range (tuple, (y_min, y_max)) – A tuple indicating the range of y values (includes end points)
- step (int, double, tuple) – Step size. 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).
- grid_type ({'rectangular', 'hexagonal'}) – The grid type
Notes
- The grid uses Cartesian indexing (
indexing='xy'
for NumPy’smeshgrid
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.
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
-
plot
(style='hull', autoscale=True, zorder=None, ax=None, figsize=None, fc=None, use_dva=False, legend=False, surface=None)[source]¶ 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)
- style ({'hull', 'scatter', 'cell'}, optional) –
-
plot3D
(style='scatter', ax=None, surface='midgray', color_by='region', **kwargs)[source]¶ 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)[source]¶ 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].
-
build
(**build_params)[source]¶ Build the model
Every model must have a
`build
method, which is meant to perform all expensive one-time calculations. You must callbuild
before callingpredict_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 aFreezeError
. Example:model.build(param1=val)
-
dva_to_ret
(xdva, ydva)[source]¶ 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
-
from_dva
()[source]¶ Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).
-
is_built
¶ A flag indicating whether the model has been built
-
ret_to_dva
(xret, yret)[source]¶ 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: - y_um (x_um,) – 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 (double or array-like) – Transformed x and y coordinates (degrees of visual angle, dva)
-
to_dva
()[source]¶ 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.
-
watson_displacement
(r, meridian='temporal')[source]¶ 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
.
-
-
class
pulse2percept.topography.
Watson2014Map
(**params)[source]¶ Converts between visual angle and retinal eccentricity [Watson2014]
-
build
(**build_params)[source]¶ Build the model
Every model must have a
`build
method, which is meant to perform all expensive one-time calculations. You must callbuild
before callingpredict_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 aFreezeError
. Example:model.build(param1=val)
-
dva_to_ret
(x_deg, y_deg, coords='cart')[source]¶ 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: - y_dva (x_dva,) – 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 (double or array-like) – Transformed x and y coordinates on the retina (microns)
-
from_dva
()[source]¶ Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).
-
is_built
¶ A flag indicating whether the model has been built
-
ret_to_dva
(x_um, y_um, coords='cart')[source]¶ 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: - y_um (x_um,) – 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 (double or array-like) – Transformed x and y coordinates (degrees of visual angle, dva)
-
-
class
pulse2percept.topography.
Polimeni2006Map
(**params)[source]¶ Polimeni visual mapping
-
build
(**build_params)[source]¶ Build the model
Every model must have a
`build
method, which is meant to perform all expensive one-time calculations. You must callbuild
before callingpredict_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 aFreezeError
. Example:model.build(param1=val)
-
from_dva
()[source]¶ Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).
-
is_built
¶ A flag indicating whether the model has been built
-
-
class
pulse2percept.topography.
NeuropythyMap
(subject, cache_dir=None, **params)[source]¶ -
build
(**build_params)[source]¶ Build the model
Every model must have a
`build
method, which is meant to perform all expensive one-time calculations. You must callbuild
before callingpredict_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 aFreezeError
. Example:model.build(param1=val)
-
cortex_to_dva
(xc, yc, zc)[source]¶ Gives the visual field position(s) of the cortex point(s)
(xc,yc,zc)
.Parameters: yc, zc (xc,) – The x, y, and z-coordinate(s) of the cortex point(s) to look up (in mm). Returns: x, y (array_like) – The x and y-coordinate(s) of the visual field point(s) (in dva).
-
dva_to_cortex
(x, y, region='v1', hemi=None, surface='midgray')[source]¶ Gives the cortex position(s) of the visual field point(s)
(x,y)
.Parameters: - y (x,) – 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')[source]¶ Gives the 3D cortex position(s) of the visual field point(s)
(x,y)
in v1.Parameters: - y (x,) – 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')[source]¶ Gives the 3D cortex position(s) of the visual field point(s)
(x,y)
in v2.Parameters: - y (x,) – 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')[source]¶ Gives the 3D cortex position(s) of the visual field point(s)
(x,y)
in v3.Parameters: - y (x,) – 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’.
-
from_dva
()[source]¶ Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).
-
is_built
¶ A flag indicating whether the model has been built
-
load_meshes
(subject)[source]¶ Predicts retinotopy and loads submeshes for the given subject. Adapted from code courtesy of Noah Benson
-
to_dva
()[source]¶ 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.
-
v1_to_dva
(xv1, yv1, zv1)[source]¶ 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: yv1, zv1 (xv1,) – The x, y, and z-coordinate(s) of the v1 point(s) to look up (in mm). Returns: x, y (array_like) – The x and y-coordinate(s) of the visual field point(s) (in dva).
-
v2_to_dva
(xv2, yv2, zv2)[source]¶ 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: yv2, zv2 (xv2,) – The x, y, and z-coordinate(s) of the v2 point(s) to look up (in mm). Returns: x, y (array_like) – The x and y-coordinate(s) of the visual field point(s) (in dva).
-
v3_to_dva
(xv3, yv3, zv3)[source]¶ 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: yv3, zv3 (xv3,) – The x, y, and z-coordinate(s) of the v3 point(s) to look up (in mm). Returns: x, y (array_like) – The x and y-coordinate(s) of the visual field point(s) (in dva).
-