pulse2percept.topography

Visual field maps, retinotopy, and visuotopy

The root namespace holds only anatomy-independent machinery: the coordinate grid a model simulates on, and the abstract map that turns visual field coordinates into tissue coordinates. Concrete maps live in the subpackage for the tissue they describe — retina and cortex.

Changed in version 0.11.0: Anatomy-specific maps are no longer exported here; import them from topography.retina or topography.cortex.

`base`	`Grid2D`, `VisualFieldMap`
`retina`	Retinal visual field maps
`cortex`	Cortical visual field maps

class pulse2percept.topography.Grid2D(x_range, y_range, step=1, grid_type='rect')[source]

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 ({'rect', 'hex'}) – Grid type (‘rect’: rectangular, ‘hex’: hexagonal).

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[source]: 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)[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.visual_field_map
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 visual_field_maps that accept a surface argument)

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.

Parameters:

style ({'scatter', 'cell'}, optional) –
- ‘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.
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 visual_field_map)
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.VisualFieldMap(**params)[source]

Base template class for a visual field map (retinotopy)

A visual field map is handed to a model so it knows how to convert between tissue and visual field coordinates. It is not itself a model: there is nothing to build and no percept to predict.

Changed in version 0.10.0: Derives from Parametrized rather than BaseModel.

Changed in version 0.10.0: Coordinates handed to a dva_to_* or *_to_dva method may carry units; see visual_unit and tissue_unit.

visual_unit = dva[source]: The unit of the visual field side of the map

get_param_units()[source]

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)[source]: Set the parameters of this object

tissue_unit = um[source]: The unit of the tissue side of the map

abstractmethod from_dva()[source]: Returns a dict containing the region(s) that this visuotopy maps to, and the corresponding mapping function(s).

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.

get_default_params()[source]: Required to inherit from Parametrized