pulse2percept.percepts.base

Percept

Classes

Percept(data[, space, time, metadata, ...])

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

Visual percept

A visual percept in space and time (optional). Typically the output of a computational model.

Added in version 0.6.

Parameters:

  • data (3D NumPy array) – A NumPy array specifying the percept in (Y, X, T) dimensions

  • space (Grid2D, optional) – A grid object specifying the (x,y) coordinates in space

  • time (1D array, optional) – A list of time points, expressed in time_unit. May be given as a unitful quantity (e.g. [0, 0.01] * s), which is converted into time_unit rather than changing it.

  • metadata (dict, optional) – Additional stimulus metadata can be stored in a dictionary.

  • n_gray (int, 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.

  • noise (float or int, optional) – Adds salt-and-pepper noise to each percept frame. An integer will be interpreted as the number of pixels to subject to noise in each frame. A float between 0 and 1 will be interpreted as a ratio of pixels to subject to noise in each frame.

  • time_unit (Unit, optional) –

    The unit time is stored in. Bare numbers passed as time are assumed to already be expressed in this unit; unitful ones are converted into it. A model-created percept records the model’s own time_unit here, which is what lets its time axis cross into another model correctly.

    Added in version 0.10.0.

Notes

Changed in version 0.10.0: The time axis is unit-aware (see time_unit above). data is not: a percept is perceived brightness in arbitrary units, which is model output rather than a physical quantity.

Examples

A time axis given in seconds is stored in the percept’s own unit, so these two are the same percept:

>>> import numpy as np
>>> from pulse2percept.percepts import Percept
>>> from pulse2percept.units import s
>>> data = np.zeros((3, 3, 2))
>>> Percept(data, time=[0.0, 10.0]).time
array([ 0., 10.])
>>> Percept(data, time=[0, 0.01] * s).time
array([ 0., 10.])
property time_unit

The unit time is expressed in

Milliseconds unless the percept was built with a different time_unit. Read-only: the stored numbers mean what they meant when they were written down. Ask for another unit with times().

Added in version 0.10.0.

property time_quantity

The 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

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

rewind()[source]

Rewind the iterator

plot(kind='pcolor', ax=None, **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.

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.

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

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

play(fps=None, repeat=True, annotate_time=True, ax=None, colorbar=True, fmt='png')[source]

Animate the percept as HTML with JavaScript

The percept will be played in an interactive player in IPython or Jupyter Notebook.

Parameters:

  • fps (float or None) – If None, uses the percept’s time axis. Not supported for non-homogeneous time axis.

  • repeat (bool, optional) – Whether the animation should repeat when the sequence of frames is completed.

  • annotate_time (bool, optional) – If True, the time of the frame will be shown as t = X in the title of the panel, in the percept’s time_unit.

  • ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object

  • colorbar ({True, False}) – Whether to show the colorbar

  • fmt ({'png', 'jpg'}, optional) –

    The image format used to embed the frames. A percept is scalar, so ‘png’ ships it as a palettized image of one byte per pixel, which is already compact; ‘jpg’ roughly halves that again, but a phosphene is exactly the kind of high-contrast blob against black that JPEG rings around. Prefer ‘jpg’ only if size matters more than pixel-exact frames.

    Added in version 0.10.0.

Returns:

ani – A Matplotlib animation object that will play the percept frame-by-frame.

Return type:

pulse2percept.utils.HTMLAnimation

Notes

Changed in version 0.10.0: The HTML player is now generated by HTMLAnimation, which renders the figure once and ships all frames as a single sprite sheet. This is roughly two orders of magnitude faster than Matplotlib’s to_jshtml and produces much smaller notebooks and doc pages.

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

Save the percept as an MP4 or GIF

Parameters:

  • fname (str) – The filename to be created, with the file extension indicating the file type. Percepts with time=None can be saved as images (e.g., ‘.jpg’, ‘.png’, ‘.gif’). Multi-frame percepts can be saved as movies (e.g., ‘.mp4’, ‘.avi’, ‘.mov’) or ‘.gif’.

  • shape ((height, width) or None, optional) – The desired width x height of the resulting image/video. Use (h, None) to use a specified height and automatically infer the width from the percept’s aspect ratio. Analogously, use (None, w) to use a specified width. If shape is None, width will be set to 320px and height will be inferred accordingly.

  • fps (float or None) – If None, uses the percept’s time axis. Not supported for non-homogeneous time axis.

Notes

  • shape will be adjusted so that width and height are multiples

    of 16 to ensure compatibility with most codecs and players.