pulse2percept.models.cortex.base

CortexSpatial

Classes

CortexSpatial(implant, *[, regions, ...])

Abstract base class for cortical models

class pulse2percept.models.cortex.base.CortexSpatial(implant, *, regions=None, visual_field_map=None, **params)

Abstract base class for cortical models

This is an abstract class that cortical models can subclass to get cortical implementation of the following features.

• Updated default parameters for cortex

• Handling of multiple visual regions via regions property

• Plotting, including multiple visual regions, legends, vertical divide at longitudinal fissure, etc.

Parameters:

implantImplant

The implant whose stimulation this model predicts.

Added in version 0.11.0.

regionslist of str, optional

The regions to simulate. Options are any combination of ‘v1’, ‘v2’, ‘v3’. Default: [‘v1’].

rhodouble, optional

Exponential decay constant describing current spread size (microns).

min_current_spreadfloat, optional

An electrode is skipped at grid points where its Gaussian current spread has decayed below this fraction of its peak. The default (1e-8, about 6.1 rho away) drops the Gaussian times the stimulus amplitude, summed over the skipped electrodes, so the error at a point is bounded by min_current_spread times the summed amplitude across electrodes.

xrange(x_min, x_max), optional

A tuple indicating the range of x values to simulate (in degrees of visual angle). Negative x values lie left of fixation, positive x values right of it.

yrangetuple, (y_min, y_max), optional

A tuple indicating the range of y values to simulate (in degrees of visual angle). Negative y values lie below fixation, positive y values above it.

stepint, double, tuple, optional

Step size for the range of (x,y) values to simulate (in degrees of visual angle). For example, to create a grid with x values [0, 0.5, 1] use xrange=(0, 1) and step=0.5. Pass a tuple to give the x and y axes different step sizes.

grid_type{‘rect’, ‘hex’}, optional

Whether to simulate points on a rectangular or hexagonal grid

visual_field_mapVisualFieldMap, optional

An instance of a VisualFieldMap object that provides retinotopic mappings. By default, Polimeni2006Map is used.

n_grayint, optional

The number of gray levels to use. If an integer is given, k-means clustering is used to compress the color space of the percept into n_gray bins. If None, no compression is performed.

implant_position(x, y) or Quantity, optional

Position of the device-local origin, in tissue coordinates or dva.

Added in version 0.11.0.

implant_rotationfloat or Quantity, optional

In-plane rotation (deg), positive counter-clockwise.

Added in version 0.11.0.

implant_depthfloat or Quantity, optional

Signed offset (um) along the normal of a 2D tissue map.

Added in version 0.11.0.

location_noisefloat or None, optional

Standard deviation of fixed electrode-specific phosphene offsets, in dva. Requires an invertible 2D visual_field_map. None or 0 disables it. Location-dependent models may also change phosphene shape or size.

Added in version 0.11.0.

n_threadsint, optional

Number of CPU threads to use during parallelization using OpenMP. Defaults to max number of user CPU cores.

n_jobsint, optional

Alias for n_threads; None or -1 uses every core.

Important

Changing a model parameter outside the constructor (e.g., by directly setting model.xrange = (-10, 10)) invalidates the build, and the next predict_percept builds it again.

build(**build_params)

Build the spatial model.

Applies any supplied parameters, validates the implant, visual-field map and implant placement, builds the sampling grid, then runs _build.

Parameters:

**build_params (keyword arguments) – Declared model parameters to set before building.

Return type:

self

extra_stimulus_units = ()

Additional stimulus units accepted by this model

get_default_params()

Returns all settable parameters of the scoreboard model

get_param_units()

Return a dict of the units that parameters are stored in

property implant

The prosthesis system whose geometry this model uses.

Rebinding invalidates the spatial build.

Added in version 0.11.0.

property is_built

A read-only flag indicating whether the model has been built

property n_jobs

both names read and write the same value.

Type:

Number of OpenMP threads to use during parallelization. An alias for n_threads

predict_percept(source, t_percept=None)

Predict the spatial response.

Parameters:

• source (stimulus source) – Anything accepted by prepare_stim().

• t_percept (float or array-like, optional) – Output times in time_unit. If omitted, use the source time points. Unitful times are accepted.

Returns:

percept – Percept with shape Y x X x T, or None for an empty source.

Return type:

Percept or None

Notes

For an encoded image or video, a spatial-only model uses frame-level modulation rather than the delivered pulse train. In a composite Model with a temporal stage, the spatial stage receives the delivered train so the temporal model can integrate it.

Changed in version 0.11.0: Takes the stimulus source rather than an implant carrying a stimulus.

set_params(**params)

Set the parameters of this object

space_unit = um

The unit spatial coordinates are expressed in

stimulus_unit = uA

The unit stimulus values are expressed in

time_unit = ms

The unit time is expressed in

plot(use_dva=False, style=None, autoscale=True, ax=None, figsize=None, fc=None, show_implant=False, **kwargs)

Plot the model

Parameters:

• use_dva (bool, optional) – Plot points in visual field. If false, simulated points will be plotted in cortex

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

  Grid plotting style:

  • ’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

• 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 (matplotlib color, optional) – Face color for the grid cells. If None, will use the default matplotlib color cycle.

• show_implant (bool, optional) –

  Draw the implant at its model-side placement. Requires use_dva=False.

  Added in version 0.11.0.

• kwargs (dict, optional) – Additional keyword arguments are passed on to Grid2D.plot()

Returns:

ax – Returns the axis object of the plot

Return type:

matplotlib.axes.Axes