pulse2percept.percepts

Visual percepts and phosphenes.

The metrics module is documented but deliberately not imported here: measure() loads it on demand, so predicting a percept never pays for the measurement machinery. Import its classes from pulse2percept.percepts.metrics if you need them directly.

`base`	`Percept`
`metrics`	`FrameMetrics`,

class pulse2percept.percepts.Percept(data, space=None, time=None, metadata=None, n_gray=None, time_unit=ms)[source]

Visual percept in space and time.

Percepts are typically produced by computational models. A percept has one of two layouts, with time as the last axis in both:

(Y, X, T)     perceived brightness in arbitrary units
(Y, X, 3, T)  RGB intensities in [0, 1]

Models produce brightness percepts. RGB percepts exist to display a scene alongside a modeled percept. Their values are display intensities rather than brightness in arbitrary units, so they must be finite and lie in [0, 1]; anything else is rejected at construction. That is also why the operations defined on brightness reject them (see Notes).

Added in version 0.6.

Changed in version 0.11.0: Added RGB percepts.

Parameters:

data (3D or 4D array_like) – Percept data in (Y, X, T) or (Y, X, 3, T) dimensions. RGB data must be finite and lie in [0, 1].
space (Grid2D, optional) – Spatial coordinates of the percept. Without one, xdva and ydva are filled in with pixel indices, which are not degrees of visual angle; see Notes.
time (1D array_like, optional) – Time points corresponding to the frames. Bare values are expressed in time_unit; unitful values are converted to it.
metadata (dict, optional) – Additional percept metadata.
n_gray (int, optional) – Number of gray levels. If specified, k-means clustering is used to reduce the percept to n_gray levels. Not available for RGB.
time_unit (Unit, optional) –
Unit in which time is stored.

Added in version 0.10.0.

Notes

Spatial dimensions use standard NumPy indexing. When a time axis exists, values indexing the last dimension are interpreted as time points and may be interpolated; see Percept.__getitem__(). The RGB axis is not a spatial dimension: space still describes (Y, X), and a frame comes out as (Y, X) or (Y, X, 3).

n_gray, argmax, max, and the vmin/vmax display range are defined on perceived brightness and raise a ValueError for an RGB percept, which already carries its own display values. Reducing three channels to one number – to rank pixels or pick a brightest frame – would have to choose a color metric, and a metric the models never produced is a decision for the caller, not for this class. percept.data is always there for the plain numerical answer.

A percept built without a space still reports xdva and ydva: they are the pixel indices Data fills an omitted axis with, and they are indistinguishable from coordinates once stored. Code that needs real visual-field positions – placing a percept in a scene, say – must ask whether one was given rather than trust the numbers.

Examples

A one-frame RGB percept, and the frame it displays:

>>> import numpy as np
>>> from pulse2percept.percepts import Percept
>>> rgb = Percept(np.zeros((4, 6, 3, 1)))
>>> rgb.is_rgb
True
>>> rgb[..., 0].shape
(4, 6, 3)

property is_rgb: Whether this percept is RGB (Y, X, 3, T) rather than (Y, X, T)

Added in version 0.11.0.

property time_unit

Unit in which time is stored.

The property is read-only; use times() to request another unit.

Added in version 0.10.0.

property time_quantity: Time axis with its unit attached, or None.

Added in version 0.10.0.

times(unit=None)[source]

The time axis, expressed in unit

Added in version 0.10.0.

Parameters:: unit (Unit, optional) – The unit to express the time axis in. If None, time is returned as it is stored.
Returns:: times – An ordinary NumPy array, never a Quantity, or None if the percept has no time component.
Return type:: np.ndarray or None

Examples

>>> import numpy as np
>>> from pulse2percept.percepts import Percept
>>> from pulse2percept.units import s
>>> Percept(np.zeros((3, 3, 2)), time=[0, 20.0]).times(s)
array([0.  , 0.02])

argmax(axis=None)[source]

Return the indices of the maximum values along an axis

Parameters:: axis (None or 'frames') – Axis along which to operate. By default, the index of the brightest pixel is returned. Set axis='frames' to get the index of the brightest frame.
Returns:: argmax – Indices at which the maxima of percept.data along an axis occur. If axis is None, the result is a scalar value. If axis is ‘frames’, the result is the time of the brightest frame.
Return type:: ndarray or scalar
Raises:: ValueError – For an RGB percept, which has no brightest pixel or frame.

max(axis=None)[source]

Brightest pixel or frame

Parameters:: axis (None or 'frames') – Axis along which to operate. By default, the value of the brightest pixel is returned. Set axis='frames' to get the brightest frame.
Returns:: pmax – Maximum of percept.data. If axis is None, the result is a scalar value. If axis is ‘frames’, the result is the brightest frame.
Return type:: ndarray or scalar
Raises:: ValueError – For an RGB percept, which has no brightest pixel or frame.

measure(threshold=0.5)[source]

Measure the brightness and geometry of the phosphenes in a percept

Measures each frame of a brightness percept: its integrated and peak brightness, and the position, size and shape of its suprathreshold support. Results are computed on call and not cached, so a percept whose data changed measures anew.

See measure_percept() for the definitions, units, and the inputs it rejects.

Added in version 0.11.0.

Parameters:: threshold (float, optional) – Fraction of each frame’s own positive maximum at or above which a pixel belongs to the support. Must lie in (0, 1].
Returns:: metrics – One FrameMetrics per frame, plus the framewise arrays and the brightest frame.
Return type:: PerceptMetrics

rewind()[source]: Rewind the iterator

plot(kind='pcolor', ax=None, rings=False, meridians=False, grid_color='0.5', **kwargs)[source]

Plot the percept

For a spatial percept, will plot the perceived brightness across the x, y grid. For a temporal percept, will plot the evolution of perceived brightness over time. For a spatiotemporal percept, will plot the brightest frame. Use percept.play() to animate the percept across time points.

An RGB percept is drawn as RGB rather than through a colormap. It has no brightest frame to single out, so a multi-frame one raises; use play().

Parameters:

kind ({ 'pcolor', 'hex' }, optional) –
Kind of plot to draw:
- ’pcolor’: using Matplotlib’s pcolor. Additional parameters (e.g., vmin, vmax) can be passed as keyword arguments. By default, vmin is the drawn frame’s minimum and vmax the maximum brightness across the percept.
- ’hex’: using Matplotlib’s hexbin. Additional parameters (e.g., gridsize) can be passed as keyword arguments.
ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will either use the current axes (if exists) or create a new Axes object
rings (bool, float, or sequence, optional) – Eccentricity rings (dva) about the fovea at visual-field (0, 0). True draws 1.25, 2.5, 5, 10, 20, … dva, a number is a spacing, and a sequence is the eccentricities themselves. Automatic rings stop at the field edge nearest the fovea, or, for a field that excludes the fovea, span the eccentricities it covers.
meridians (bool, float, or sequence, optional) – Polar-angle meridians (geometric deg) from the fovea to the field edge: 0 is +x, 90 is +y, counterclockwise. True is every 45 deg, a number is a spacing from 0, and a sequence is the angles themselves.
grid_color (color, optional) – Matplotlib color of rings, meridians, and ring labels.
**kwargs – Other optional arguments passed down to the Matplotlib function

Returns:

ax – Returns the axes with the plot on it

Return type:

matplotlib.axes.Axes

Notes

Rings and meridians are display annotations. They require a percept built with space (ValueError otherwise), since pixel indices are not visual angle.

play(fps=None, repeat=True, annotate_time=True, ax=None, colorbar=True, fmt='png', vmin=None, vmax=None, rings=False, meridians=False, grid_color='0.5', title=None)[source]

Animate the percept in an interactive HTML player.

Parameters:

fps (float, optional) – Display frame rate in Hz. If None, use the percept’s recorded timing.
repeat (bool, optional) – Whether to repeat the animation.
annotate_time (bool, optional) – Whether to show the current time above each frame.
ax (matplotlib.axes.Axes, optional) – Axes on which to draw the animation.
colorbar (bool, optional) – Whether to show a colorbar. An RGB percept never gets one: it carries its own colors, and there is no one brightness scale to put next to them.
fmt ({'png', 'jpg'}, optional) –
Image format used to encode animation frames.

Added in version 0.10.0.
vmin (float, optional) –
Brightness limits. By default, vmin=0 and vmax is the maximum brightness across the percept. Not available for an RGB percept, whose values are shown as they are (clipped to [0, 1]).

Added in version 0.10.0.
vmax (float, optional) –
Brightness limits. By default, vmin=0 and vmax is the maximum brightness across the percept. Not available for an RGB percept, whose values are shown as they are (clipped to [0, 1]).

Added in version 0.10.0.
rings (optional) –
Visual-field grid about (0, 0), as in plot(), drawn as a static layer over every frame.

Added in version 0.11.0.
meridians (optional) –
Visual-field grid about (0, 0), as in plot(), drawn as a static layer over every frame.

Added in version 0.11.0.
grid_color (optional) –
Visual-field grid about (0, 0), as in plot(), drawn as a static layer over every frame.

Added in version 0.11.0.
title (str, optional) –
Figure title (fig.suptitle), shown independently of annotate_time.

Added in version 0.11.0.

Returns:

The animation.

Return type:

pulse2percept.utils.HTMLAnimation

Notes

fps controls display sampling, not interpolation. Use percept[..., t] to interpolate the percept at an arbitrary time.

Changed in version 0.10.0: Added support for irregular timing, fps display sampling, and vmin/vmax.

save(fname, shape=None, fps=None, vmin=None, vmax=None)[source]

Save the percept to an image or video file.

Parameters:

fname (str) – Output filename. The extension determines the file format.
shape ((height, width), optional) – Output size in pixels. Either dimension may be None to preserve the percept’s aspect ratio.
fps (float, optional) – Movie frame rate in Hz. If None, use the percept’s recorded timing.
vmin (float, optional) –
Brightness limits mapped to the file’s gray levels. Values outside this range are clipped. If either limit is given, the resolved range is stored so that Percept.load() can restore it. Not available for an RGB percept, whose values are written as they are (clipped to [0, 1]) and read back by load(..., as_gray=False).

Added in version 0.10.0.
vmax (float, optional) –
Brightness limits mapped to the file’s gray levels. Values outside this range are clipped. If either limit is given, the resolved range is stored so that Percept.load() can restore it. Not available for an RGB percept, whose values are written as they are (clipped to [0, 1]) and read back by load(..., as_gray=False).

Added in version 0.10.0.

Returns:

Path of the file that was written.

Return type:

str

Notes

If the output format cannot store the brightness range in metadata, save adds it to the filename.

Movie dimensions may be adjusted for codec compatibility.

Changed in version 0.10.0: Added vmin/vmax and return of the output filename.

classmethod load(fname, space=None, time=None, fps=None, vmin=None, vmax=None, as_gray=True)[source]

Load a percept from an image or video file.

Added in version 0.10.0.

Parameters:

fname (str) – File to load.
space (Grid2D, optional) – Spatial coordinates of the percept.
time (1D array_like, optional) – Frame times. Overrides fps and timing stored in the file.
fps (float, optional) – Frame rate in Hz. Overrides the frame rate stored in the file.
vmin (float, optional) – Brightness limits represented by the file. Explicit values override any range stored in the file metadata or filename.
vmax (float, optional) – Brightness limits represented by the file. Explicit values override any range stored in the file metadata or filename.
as_gray (bool, optional) –
Whether to convert a color file to a brightness percept. Pass False to load it as an RGB percept instead, keeping its three channels.

Added in version 0.11.0.

Returns:

Loaded percept.

Return type:

Percept

Notes

Color images are converted to grayscale unless as_gray=False. If the brightness range cannot be recovered, values remain on the encoded [0, 1] scale and a warning is issued.