pulse2percept.plotting

Figures and animations that combine multiple pulse2percept objects.

Individual objects retain their own plot() and play() methods; this package only holds views that no single object owns.

`comparison`	`plot_stimulus_percept()`,
`argus`	`plot_argus_phosphenes()`, `plot_argus_simulated_phosphenes()`

pulse2percept.plotting.play_stimulus_percept(stim, percept, fps=None, axes=None, figsize=None, titles=('Stimulus', 'Percept'), repeat=True, annotate_time=True, colorbar=True, fmt='png', vmin=None, vmax=None)[source]

Animate a stimulus next to the percept it produced

Both panels run off a single clock. The percept’s time axis is authoritative: every displayed percept frame is paired with the source frame that is up at the same physical time (zero-order hold), so a source and a percept sampled at different rates stay in register, and a still image stays put. fps resamples the whole presentation, exactly as in play().

Added in version 0.11.0.

Parameters:

stim (ImageStimulus or) – VideoStimulus The image or video that went into the model, not the electrical stimulus an encoder made of it.
percept (Percept) – The percept the model predicted. Must have a time axis.
fps (float, optional) – Display frame rate in Hz. If None, use the percept’s recorded timing. May also be given as a unitful frequency (e.g., 30 * Hz).
axes (list of two matplotlib.axes.Axes, optional) – Axes to animate in, stimulus first. If None, a new figure is created.
figsize ((width, height), optional) – Size of that new figure (in inches). Ignored if axes is given.
titles ((str, str), optional) – Titles for the two panels.
repeat (bool, optional) – Whether to repeat the animation.
annotate_time (bool, optional) – Whether to show the current time above the two panels.
colorbar (bool, optional) – Whether to show a brightness colorbar next to the percept. An RGB percept never gets one.
fmt ({'png', 'jpg'}, optional) – Image format used to encode animation frames. ‘jpg’ keeps notebooks and doc pages smaller, which matters most for a video source; ‘png’ keeps the frames pixel-exact.
vmin (float, optional) – Brightness limits for the percept. 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.
vmax (float, optional) – Brightness limits for the percept. 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.

Returns:

ani – The animation.

Return type:

HTMLAnimation

Notes

Neither stimulus nor percept is resampled: the source keeps its own frames, and fps only controls which of them are shown when.

pulse2percept.plotting.plot_argus_phosphenes(data, argus=None, scale=1.0, axon_map=None, show_fovea=True, ax=None, implant_position=None, implant_rotation=None)[source]

Plots phosphenes centered over the corresponding electrodes

Added in version 0.7.

Parameters:

data (pd.DataFrame) – The Beyeler2019 dataset, a subset thereof, or a DataFrame with identical organization (i.e., must contain columns ‘subject’, ‘image’, ‘xrange’, and ‘yrange’).
argus (ArgusI or) – ArgusII Either an Argus I or Argus II implant. If None, the data must contain an “implant_type_str” column naming the device, either “ArgusI” or “ArgusII”. Where it was implanted comes from implant_position and implant_rotation below.
scale (float) – Scaling factor to apply to the phosphenes
axon_map (AxonMapModel) – An instance of the axon map model to use for visualization.
show_fovea (bool) – Whether to indicate the location of the fovea with a square
ax (axis) – Matplotlib axis
implant_position ((x, y) or Quantity, optional) –
Position of the device-local origin on the retina (um). Defaults to the dataset’s “implant_x”/”implant_y” columns where present, else 0.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
Array rotation (deg), positive counter-clockwise. Defaults to the dataset’s “implant_rot” column where present, else 0.

Added in version 0.11.0.

pulse2percept.plotting.plot_argus_simulated_phosphenes(percepts, argus, scale=1.0, axon_map=None, show_fovea=True, ax=None, implant_position=None, implant_rotation=None)[source]

Plots simulated phosphenes centered over the corresponding electrodes

Added in version 0.7.

Parameters:

percepts (Percept) – A Percept object containing multiple frames, where each frame is the percept produced by activating a single electrode.
argus (ArgusI or) – ArgusII Either an Argus I or Argus II implant
scale (float) – Scaling factor to apply to the phosphenes
axon_map (AxonMapModel) – An instance of the axon map model to use for visualization.
show_fovea (bool) – Whether to indicate the location of the fovea with a square
ax (axis) – Matplotlib axis
implant_position ((x, y) or Quantity, optional) –
Position of the device-local origin on the retina (um). Defaults to 0.

Added in version 0.11.0.
implant_rotation (float or Quantity, optional) –
Array rotation (deg), positive counter-clockwise. Defaults to 0.

Added in version 0.11.0.

pulse2percept.plotting.plot_stimulus_percept(stim, percept, axes=None, figsize=None, titles=('Stimulus', 'Percept'), stim_kwargs=None, percept_kwargs=None)[source]

Plot an image next to the percept it produced

Draws stim and percept side by side, each with its own plot method. A video has no single frame that stands for the whole sequence, and neither does the percept it produced, so use play_stimulus_percept() for those.

Added in version 0.11.0.

Parameters:

stim (ImageStimulus) – The image that went into the model, not the electrical stimulus an encoder made of it.
percept (Percept) – The percept the model predicted.
axes (list of two matplotlib.axes.Axes, optional) – Axes to draw into, stimulus first. If None, a new figure is created.
figsize ((width, height), optional) – Size of that new figure (in inches). Ignored if axes is given.
titles ((str, str), optional) – Titles for the two panels.
stim_kwargs (dict, optional) – Passed on to the stimulus’ and the percept’s plot method.
percept_kwargs (dict, optional) – Passed on to the stimulus’ and the percept’s plot method.

Returns:

axes – The two Axes that were drawn into.

Return type:

np.ndarray of matplotlib.axes.Axes

Examples

>>> import matplotlib
>>> matplotlib.use('Agg')
>>> import pulse2percept as p2p
>>> stim = p2p.stimuli.samples.logo_ucsb(resize=(24, 32))
>>> model = p2p.models.retina.ScoreboardModel(
...     p2p.implants.retina.ArgusII(), xrange=(-4, 4), yrange=(-4, 4),
...     step=0.5)
>>> percept = model.predict_percept(stim)
>>> axes = p2p.plotting.plot_stimulus_percept(stim, percept)
>>> [ax.get_title() for ax in axes]
['Stimulus', 'Percept']