pulse2percept.stimuli

Common electrical stimuli, such as charge-balanced square-wave pulse trains.

`base`	`Stimulus`, `ImageStimulus`
`pulses`	`MonophasicPulse`, `BiphasicPulse`, `AsymmetricBiphasicPulse`
`pulse_trains`	`PulseTrain`, `BiphasicPulseTrain`, `AsymmetricBiphasicPulseTrain`
`images`	`ImageStimulus`, `LogoBVL`, `LogoUCSB`, `SnellenChart`
`videos`	`VideoStimulus`, `BostonTrain`, `GirlPool`
`psychophysics`	`BarStimulus`, `GratingStimulus`

See also

Basic Concepts > Electrical Stimuli

class pulse2percept.stimuli.AsymmetricBiphasicPulse(amp1, amp2, phase_dur1, phase_dur2, interphase_dur=0, delay_dur=0, stim_dur=None, cathodic_first=True, electrode=None)[source]

Asymmetric biphasic pulse

A simple stimulus consisting of a single biphasic pulse: a cathodic and an anodic phase, optionally separated by an interphase gap. The two pulse phases can have different amplitudes and duration (“asymmetric”).

Added in version 0.6.

Parameters:

amp1 (float) – Current amplitude (uA) of the first and second pulse phases. Negative currents: cathodic, positive: anodic. The signs will be converted automatically depending on cathodic_first.
amp2 (float) – Current amplitude (uA) of the first and second pulse phases. Negative currents: cathodic, positive: anodic. The signs will be converted automatically depending on cathodic_first.
phase_dur1 (float) – Duration (ms) of the first and second pulse phases.
phase_dur2 (float) – Duration (ms) of the first and second pulse phases.
interphase_dur (float, optional, default: 0) – Duration (ms) of the gap between cathodic and anodic phases.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the first pulse phase after delay_dur ms.
stim_dur (float, optional, default:) – 2*phase_dur+interphase_dur+delay_dur Total stimulus duration (ms). Zeros will be inserted at the end of the stimulus to make the stimulus last stim_dur ms overall.
cathodic_first (bool, optional, default: True) – If True, will deliver the cathodic pulse phase before the anodic one.
electrode ({ int | string }, optional, default: 0) – Optionally, you can provide your own electrode name.

Notes

The order of the two phases is given by the cathodic_first flag.
The sign of amp will be automatically adjusted depending on the cathodic_first flag.
A pulse will be considered “charge-balanced” if its net current is smaller than 10 picoamps.

Examples

An asymmetric cathodic-first pulse (first phase: -40uA, 1ms; second phase: 10uA, 4ms; 1ms interphase-gap) delivered after 2ms and embedded in a stimulus that lasts 15ms overall:

>>> from pulse2percept.stimuli import AsymmetricBiphasicPulse
>>> pulse = AsymmetricBiphasicPulse(-40, 10, 1, 4, interphase_dur=1,
...                                 delay_dur=2, stim_dur=15)

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

property shape: Data container shape

property time: Time steps A list of time steps, corresponding to the columns in the data container.

class pulse2percept.stimuli.AsymmetricBiphasicPulseTrain(freq, amp1, amp2, phase_dur1, phase_dur2, interphase_dur=0, delay_dur=0, n_pulses=None, stim_dur=1000.0, cathodic_first=True, electrode=None, metadata=None)[source]

Asymmetric biphasic pulse

A simple stimulus consisting of a single biphasic pulse: a cathodic and an anodic phase, optionally separated by an interphase gap. The two pulse phases can have different amplitudes and duration (“asymmetric”). The order of the two phases is given by the cathodic_first flag.

Added in version 0.6.

Parameters:

freq (float) – Pulse train frequency (Hz).
amp1 (float) – Current amplitude (uA) of the first and second pulse phases. Negative currents: cathodic, positive: anodic. The signs will be converted automatically depending on cathodic_first.
amp2 (float) – Current amplitude (uA) of the first and second pulse phases. Negative currents: cathodic, positive: anodic. The signs will be converted automatically depending on cathodic_first.
phase_dur1 (float) – Duration (ms) of the first and second pulse phases.
phase_dur2 (float) – Duration (ms) of the first and second pulse phases.
interphase_dur (float, optional, default: 0) – Duration (ms) of the gap between cathodic and anodic phases.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the first pulse phase after delay_dur ms.
n_pulses (int) – Number of pulses requested in the pulse train. If None, the entire stimulation window (stim_dur) is filled.
stim_dur (float, optional, default: 1000 ms) – Total stimulus duration (ms). Zeros will be inserted at the end of the stimulus to make the the stimulus last stim_dur ms overall.
cathodic_first (bool, optional, default: True) – If True, will deliver the cathodic pulse phase before the anodic one.
electrode ({ int | string }, optional, default: 0) – Optionally, you can provide your own electrode name.
metadata (dict) – A dictionary of meta-data

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

property shape: Data container shape

property time: Time steps A list of time steps, corresponding to the columns in the data container.

class pulse2percept.stimuli.BarStimulus(shape, direction=0, speed=0.1, bar_width=1, edge_width=3, px_btw_bars=None, start_pos=0, contrast=1, time=None, mask=None, electrodes=None, metadata=None)[source]

Drifting bar

A drifting bar stimulus.

Added in version 0.7.

Parameters:

shape ((height, width)) – A tuple specifying the desired height (pixels) and the width (pixels) of the grating stimulus.
direction (scalar in [0, 360) degrees, optional) – Drift direction of the bar.
speed (scalar in pixels/frame, optional) – Drift speed of the bar.
bar_width (scalar in pixels, optional) – The width of the center of the bar.
edge_width (scalar in pixels, optional) – The width of the cosine edges of the bar. An edge of width edge_width will be tacked onto both sides of the bar, so the total width will be bar_width + 2 * edge_width
px_btw_bars (scalar in pixels, optional) – The number of pixels between the bars in the stimulus.
start_pos (scalar in pixels, optional) – The starting position of the first bar. The coordinate system is a line lying along the direction of the bar motion passing through the center of the stimulus. The point 0 is the center of the stimulus.
contrast (scalar in [0, 1], optional) – Stimulus contrast between 0 and 1
time (scalar, array-like, or None; optional) –
The time points at which to evaluate the drifting bar:
- If a scalar, time is interpreted as the end time (in milliseconds) of a time series with 50 Hz frame rate.
- If array-like, time is interpreted as the exact time points (in milliseconds) at which to draw the bar (end point included).
- If None, time defaults to a 1-second time series at 50 Hz frame rate (end point included).
mask ({'gauss', 'circle', None}) –
Stimulus mask:
- ”gauss”: a 2D Gaussian designed such that the border of the image lies at 3 standard deviations
- ”circle”: a circle that fits into the shape of the stimulus
- None: no mask
electrodes (int, string or list thereof; optional, default: None) – Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

apply(func, *args, **kwargs)[source]

Apply a function to each frame of the video

Parameters:

func (function) – The function to apply to each frame in the video. Must accept a 2D or 3D image and return an image with the same dimensions
*args – Additional positional arguments passed to the function
**kwargs – Additional keyword arguments passed to the function

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the new image

center(loc=None)[source]

Center the image foreground

This function shifts the center of mass (CoM) to the image center.

Parameters:: loc ((col, row), optional) – The pixel location at which to center the CoM. By default, shifts the CoM to the image center.
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the centered image

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

crop(idx_space=None, idx_time=None, left=0, right=0, top=0, bottom=0, front=0, back=0, electrodes=None)[source]

Crop the video

This method maps a rectangle (defined by two corners) from each video frame to a rectangle of the given size. Similarly, the video can be shortened to a specified range of frames.

Alternatively, this method can be used to crop a number of columns either from the left or the right of the video frame, or a number of rows either from the top or the bottom, or a number of frames from the front (beginning) or back (end) of the video.

Added in version 0.8.

Parameters:

idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner [y0, x0] and bottom-right corner [y1, x1] (exclusive) of the rectangle to crop.
idx_time (tuple (t0, t1)) – Frame indices defining the start t0 and end t1 of the cropped video.
left (int) – Number of columns to crop from the left of each video frame
right (int) – Number of columns to crop from the right of each video frame
top (int) – Number of rows to crop from the top of each video frame
bottom (int) – Number of rows to crop from the bottom of each video frame
front (int) – Number of frames to crop from the front (beginning) of the video
back (int) – Number of frames to crop from the back (end) of the video
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the cropped image.

Returns:

stim (VideoStimulus) – A copy of the stimulus object containing the video

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

encode(amp_range=(0, 50), pulse=None)[source]

Encode image using amplitude modulation

Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in amp_range.

By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.

Parameters:

amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto min_amp and the largest onto max_amp.
pulse (Stimulus, optional) – A valid pulse or pulse train to be used for the encoding. If None given, a BiphasicPulse (0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.

Returns:

stim (Stimulus) – Encoded stimulus

filter(filt, **kwargs)[source]

Filter each frame of the video

Parameters:

filt (str) –
Image filter that will be applied to every frame of the video. Additional parameters can be passed as keyword arguments. The following filters are supported:
- ’sobel’: Edge filter the image using the Sobel filter.
- ’scharr’: Edge filter the image using the Scarr filter.
- ’canny’: Edge filter the image using the Canny algorithm. You can also specify sigma, low_threshold, high_threshold, mask, and use_quantiles.
- ’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter

Returns:

stim (VideoStimulus) – A copy of the stimulus object with the filtered image

invert()[source]

Invert the gray levels of the video

Returns:: stim (VideoStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

play(fps=None, repeat=True, annotate_time=True, ax=None)[source]

Animate the video as HTML with JavaScript

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

Parameters:

fps (float or None) – If None, uses the video’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 ms in the title of the panel.
ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object

Returns:

ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

resize(shape, electrodes=None)[source]

Resize the video

Parameters:

shape ((rows, cols)) – Shape of each frame in the resized video. If one of the dimensions is set to -1, its value will be inferred by keeping a constant aspect ratio.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the resized video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object containing the resized video

rewind()[source]: Rewind the iterator

rgb2gray(electrodes=None)[source]

Convert the video to grayscale

Parameters:

electrodes (int, string or list thereof; optional) –

Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].

rotate(angle, mode='constant')[source]

Rotate each frame of the video

Parameters:: angle (float) – Angle by which to rotate each video frame (degrees). Positive: counter-clockwise, negative: clockwise
Returns:: stim (VideoStimulus) – A copy of the stimulus object containing the rotated video

scale(scaling_factor)[source]

Scale the image foreground

This function scales the image foreground (excluding black pixels) by a factor.

Parameters:: scaling_factor (float) – Factory by which to scale the image
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the scaled image

property shape: Data container shape

shift(shift_cols, shift_rows)[source]

Shift the image foreground

This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.

Parameters:

shift_cols (float) – Number of columns by which to shift the CoM. Positive: to the right, negative: to the left
shift_rows (float) – Number of rows by which to shift the CoM. Positive: downward, negative: upward

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the shifted image

property time: Time steps A list of time steps, corresponding to the columns in the data container.

trim(tol=0, electrodes=None)[source]

Remove any black border around the video

Added in version 0.7.

Parameters:

tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in each frame of the trimmed video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object with trimmed borders.

class pulse2percept.stimuli.BiphasicPulse(amp, phase_dur, interphase_dur=0, delay_dur=0, stim_dur=None, cathodic_first=True, electrode=None)[source]

Symmetric biphasic pulse

A simple stimulus consisting of a single biphasic pulse: a cathodic and an anodic phase, optionally separated by an interphase gap. Both cathodic and anodic phases have the same duration (“symmetric”).

Added in version 0.6.

Parameters:

amp (float) – Current amplitude (uA). Negative currents: cathodic, positive: anodic. The sign will be converted automatically depending on cathodic_first.
phase_dur (float) – Duration (ms) of the cathodic/anodic phase.
interphase_dur (float, optional, default: 0) – Duration (ms) of the gap between cathodic and anodic phases.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the first pulse phase after delay_dur ms.
stim_dur (float, optional, default:) – 2*phase_dur+interphase_dur+delay_dur Total stimulus duration (ms). Zeros will be inserted at the end of the stimulus to make the stimulus last stim_dur ms overall.
cathodic_first (bool, optional, default: True) – If True, will deliver the cathodic pulse phase before the anodic one.
electrode ({ int | string }, optional, default: 0) – Optionally, you can provide your own electrode name.

Notes

The order of the two phases is given by the cathodic_first flag.
A biphasic pulse created with this class will always be considered “charge-balanced”.

Examples

A cathodic-first pulse (1ms phase duration at 20uA, no interphase gap) delivered after 2ms and embedded in a stimulus that lasts 10ms overall:

>>> from pulse2percept.stimuli import BiphasicPulse
>>> pulse = BiphasicPulse(-20, 1, delay_dur=2, stim_dur=10)

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

property shape: Data container shape

property time: Time steps A list of time steps, corresponding to the columns in the data container.

class pulse2percept.stimuli.BiphasicPulseTrain(freq, amp, phase_dur, interphase_dur=0, delay_dur=0, n_pulses=None, stim_dur=1000.0, cathodic_first=True, electrode=None, metadata=None)[source]

Symmetric biphasic pulse train

A train of symmetric biphasic pulses.

Added in version 0.6.

Parameters:

freq (float) – Pulse train frequency (Hz).
amp (float) – Current amplitude (uA). Negative currents: cathodic, positive: anodic. The sign will be converted automatically depending on cathodic_first.
phase_dur (float) – Duration (ms) of the cathodic/anodic phase.
interphase_dur (float, optional, default: 0) – Duration (ms) of the gap between cathodic and anodic phases.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the first pulse phase after delay_dur ms.
n_pulses (int) – Number of pulses requested in the pulse train. If None, the entire stimulation window (stim_dur) is filled.
stim_dur (float, optional, default: 1000 ms) – Total stimulus duration (ms). The pulse train will be trimmed to make the stimulus last stim_dur ms overall.
cathodic_first (bool, optional, default: True) – If True, will deliver the cathodic pulse phase before the anodic one.
electrode ({ int | string }, optional, default: 0) – Optionally, you can provide your own electrode name.
metadata (dict) – A dictionary of meta-data

Notes

Each cycle (“window”) of the pulse train consists of a symmetric biphasic pulse, created with BiphasicPulse.
The order and sign of the two phases (cathodic/anodic) of each pulse in the train is automatically adjusted depending on the cathodic_first flag.
A pulse train will be considered “charge-balanced” if its net current is smaller than 10 picoamps.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

property shape: Data container shape

property time: Time steps A list of time steps, corresponding to the columns in the data container.

class pulse2percept.stimuli.BiphasicTripletTrain(freq, amp, phase_dur, interphase_dur=0, interpulse_dur=0, delay_dur=0, n_pulses=None, stim_dur=1000.0, cathodic_first=True, electrode=None, metadata=None)[source]

Biphasic pulse triplets

A train of symmetric biphasic pulse triplets.

Added in version 0.6.

Parameters:

freq (float) – Pulse train frequency (Hz).
amp (float) – Current amplitude (uA). Negative currents: cathodic, positive: anodic. The sign will be converted automatically depending on cathodic_first.
phase_dur (float) – Duration (ms) of the cathodic/anodic phase.
interphase_dur (float, optional, default: 0) – Duration (ms) of the gap between cathodic and anodic phases.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the first pulse phase after delay_dur ms.
interpulse_dur (float, optional, default: 0) – Delay duration (ms) between each biphasic pulse within the train. Note, this delay is also applied after the third biphasic pulse
n_pulses (int) – Number of pulses requested in the pulse train. If None, the entire stimulation window (stim_dur) is filled.
stim_dur (float, optional, default: 1000 ms) – Total stimulus duration (ms). The pulse train will be trimmed to make the stimulus last stim_dur ms overall.
cathodic_first (bool, optional, default: True) – If True, will deliver the cathodic pulse phase before the anodic one.
electrode ({ int | string }, optional, default: 0) – Optionally, you can provide your own electrode name.
metadata (dict) – A dictionary of meta-data

Notes

Each cycle (“window”) of the pulse train consists of three biphasic pulses, created with BiphasicPulse.
The order and sign of the two phases (cathodic/anodic) of each pulse in the train is automatically adjusted depending on the cathodic_first flag.
A pulse train will be considered “charge-balanced” if its net current is smaller than 10 picoamps.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

property shape: Data container shape

property time: Time steps A list of time steps, corresponding to the columns in the data container.

class pulse2percept.stimuli.BostonTrain(resize=None, electrodes=None, as_gray=False, metadata=None)[source]

Boston Train sequence

Load the Boston subway sequence, consisting of 94 frames of 240x426x3 pixels each.

Added in version 0.7.

Parameters:

resize ((height, width) or None) – A tuple specifying the desired height and the width of the video stimulus.
electrodes (int, string or list thereof; optional, default: None) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the (resized) video frame.
as_gray (bool, optional) – Flag whether to convert the image to grayscale. A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

apply(func, *args, **kwargs)[source]

Apply a function to each frame of the video

Parameters:

func (function) – The function to apply to each frame in the video. Must accept a 2D or 3D image and return an image with the same dimensions
*args – Additional positional arguments passed to the function
**kwargs – Additional keyword arguments passed to the function

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the new image

center(loc=None)[source]

Center the image foreground

This function shifts the center of mass (CoM) to the image center.

Parameters:: loc ((col, row), optional) – The pixel location at which to center the CoM. By default, shifts the CoM to the image center.
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the centered image

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

crop(idx_space=None, idx_time=None, left=0, right=0, top=0, bottom=0, front=0, back=0, electrodes=None)[source]

Crop the video

This method maps a rectangle (defined by two corners) from each video frame to a rectangle of the given size. Similarly, the video can be shortened to a specified range of frames.

Alternatively, this method can be used to crop a number of columns either from the left or the right of the video frame, or a number of rows either from the top or the bottom, or a number of frames from the front (beginning) or back (end) of the video.

Added in version 0.8.

Parameters:

idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner [y0, x0] and bottom-right corner [y1, x1] (exclusive) of the rectangle to crop.
idx_time (tuple (t0, t1)) – Frame indices defining the start t0 and end t1 of the cropped video.
left (int) – Number of columns to crop from the left of each video frame
right (int) – Number of columns to crop from the right of each video frame
top (int) – Number of rows to crop from the top of each video frame
bottom (int) – Number of rows to crop from the bottom of each video frame
front (int) – Number of frames to crop from the front (beginning) of the video
back (int) – Number of frames to crop from the back (end) of the video
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the cropped image.

Returns:

stim (VideoStimulus) – A copy of the stimulus object containing the video

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

encode(amp_range=(0, 50), pulse=None)[source]

Encode image using amplitude modulation

Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in amp_range.

By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.

Parameters:

amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto min_amp and the largest onto max_amp.
pulse (Stimulus, optional) – A valid pulse or pulse train to be used for the encoding. If None given, a BiphasicPulse (0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.

Returns:

stim (Stimulus) – Encoded stimulus

filter(filt, **kwargs)[source]

Filter each frame of the video

Parameters:

filt (str) –
Image filter that will be applied to every frame of the video. Additional parameters can be passed as keyword arguments. The following filters are supported:
- ’sobel’: Edge filter the image using the Sobel filter.
- ’scharr’: Edge filter the image using the Scarr filter.
- ’canny’: Edge filter the image using the Canny algorithm. You can also specify sigma, low_threshold, high_threshold, mask, and use_quantiles.
- ’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter

Returns:

stim (VideoStimulus) – A copy of the stimulus object with the filtered image

invert()[source]

Invert the gray levels of the video

Returns:: stim (VideoStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

play(fps=None, repeat=True, annotate_time=True, ax=None)[source]

Animate the video as HTML with JavaScript

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

Parameters:

fps (float or None) – If None, uses the video’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 ms in the title of the panel.
ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object

Returns:

ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

resize(shape, electrodes=None)[source]

Resize the video

Parameters:

shape ((rows, cols)) – Shape of each frame in the resized video. If one of the dimensions is set to -1, its value will be inferred by keeping a constant aspect ratio.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the resized video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object containing the resized video

rewind()[source]: Rewind the iterator

rgb2gray(electrodes=None)[source]

Convert the video to grayscale

Parameters:

electrodes (int, string or list thereof; optional) –

Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].

rotate(angle, mode='constant')[source]

Rotate each frame of the video

Parameters:: angle (float) – Angle by which to rotate each video frame (degrees). Positive: counter-clockwise, negative: clockwise
Returns:: stim (VideoStimulus) – A copy of the stimulus object containing the rotated video

scale(scaling_factor)[source]

Scale the image foreground

This function scales the image foreground (excluding black pixels) by a factor.

Parameters:: scaling_factor (float) – Factory by which to scale the image
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the scaled image

property shape: Data container shape

shift(shift_cols, shift_rows)[source]

Shift the image foreground

This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.

Parameters:

shift_cols (float) – Number of columns by which to shift the CoM. Positive: to the right, negative: to the left
shift_rows (float) – Number of rows by which to shift the CoM. Positive: downward, negative: upward

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the shifted image

property time: Time steps A list of time steps, corresponding to the columns in the data container.

trim(tol=0, electrodes=None)[source]

Remove any black border around the video

Added in version 0.7.

Parameters:

tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in each frame of the trimmed video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object with trimmed borders.

class pulse2percept.stimuli.GirlPool(resize=None, electrodes=None, as_gray=False, metadata=None)[source]

A girl jumping into a swimming pool

Load the “girl jumping in a pool” sequence, consisting of 91 frames of 240x426x3 pixels each.

Added in version 0.9.

Parameters:

resize ((height, width) or None) – A tuple specifying the desired height and the width of the video stimulus.
electrodes (int, string or list thereof; optional, default: None) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the (resized) video frame.
as_gray (bool, optional) – Flag whether to convert the image to grayscale. A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

apply(func, *args, **kwargs)[source]

Apply a function to each frame of the video

Parameters:

func (function) – The function to apply to each frame in the video. Must accept a 2D or 3D image and return an image with the same dimensions
*args – Additional positional arguments passed to the function
**kwargs – Additional keyword arguments passed to the function

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the new image

center(loc=None)[source]

Center the image foreground

This function shifts the center of mass (CoM) to the image center.

Parameters:: loc ((col, row), optional) – The pixel location at which to center the CoM. By default, shifts the CoM to the image center.
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the centered image

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

crop(idx_space=None, idx_time=None, left=0, right=0, top=0, bottom=0, front=0, back=0, electrodes=None)[source]

Crop the video

This method maps a rectangle (defined by two corners) from each video frame to a rectangle of the given size. Similarly, the video can be shortened to a specified range of frames.

Alternatively, this method can be used to crop a number of columns either from the left or the right of the video frame, or a number of rows either from the top or the bottom, or a number of frames from the front (beginning) or back (end) of the video.

Added in version 0.8.

Parameters:

idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner [y0, x0] and bottom-right corner [y1, x1] (exclusive) of the rectangle to crop.
idx_time (tuple (t0, t1)) – Frame indices defining the start t0 and end t1 of the cropped video.
left (int) – Number of columns to crop from the left of each video frame
right (int) – Number of columns to crop from the right of each video frame
top (int) – Number of rows to crop from the top of each video frame
bottom (int) – Number of rows to crop from the bottom of each video frame
front (int) – Number of frames to crop from the front (beginning) of the video
back (int) – Number of frames to crop from the back (end) of the video
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the cropped image.

Returns:

stim (VideoStimulus) – A copy of the stimulus object containing the video

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

encode(amp_range=(0, 50), pulse=None)[source]

Encode image using amplitude modulation

Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in amp_range.

By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.

Parameters:

amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto min_amp and the largest onto max_amp.
pulse (Stimulus, optional) – A valid pulse or pulse train to be used for the encoding. If None given, a BiphasicPulse (0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.

Returns:

stim (Stimulus) – Encoded stimulus

filter(filt, **kwargs)[source]

Filter each frame of the video

Parameters:

filt (str) –
Image filter that will be applied to every frame of the video. Additional parameters can be passed as keyword arguments. The following filters are supported:
- ’sobel’: Edge filter the image using the Sobel filter.
- ’scharr’: Edge filter the image using the Scarr filter.
- ’canny’: Edge filter the image using the Canny algorithm. You can also specify sigma, low_threshold, high_threshold, mask, and use_quantiles.
- ’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter

Returns:

stim (VideoStimulus) – A copy of the stimulus object with the filtered image

invert()[source]

Invert the gray levels of the video

Returns:: stim (VideoStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

play(fps=None, repeat=True, annotate_time=True, ax=None)[source]

Animate the video as HTML with JavaScript

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

Parameters:

fps (float or None) – If None, uses the video’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 ms in the title of the panel.
ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object

Returns:

ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

resize(shape, electrodes=None)[source]

Resize the video

Parameters:

shape ((rows, cols)) – Shape of each frame in the resized video. If one of the dimensions is set to -1, its value will be inferred by keeping a constant aspect ratio.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the resized video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object containing the resized video

rewind()[source]: Rewind the iterator

rgb2gray(electrodes=None)[source]

Convert the video to grayscale

Parameters:

electrodes (int, string or list thereof; optional) –

Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].

rotate(angle, mode='constant')[source]

Rotate each frame of the video

Parameters:: angle (float) – Angle by which to rotate each video frame (degrees). Positive: counter-clockwise, negative: clockwise
Returns:: stim (VideoStimulus) – A copy of the stimulus object containing the rotated video

scale(scaling_factor)[source]

Scale the image foreground

This function scales the image foreground (excluding black pixels) by a factor.

Parameters:: scaling_factor (float) – Factory by which to scale the image
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the scaled image

property shape: Data container shape

shift(shift_cols, shift_rows)[source]

Shift the image foreground

This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.

Parameters:

shift_cols (float) – Number of columns by which to shift the CoM. Positive: to the right, negative: to the left
shift_rows (float) – Number of rows by which to shift the CoM. Positive: downward, negative: upward

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the shifted image

property time: Time steps A list of time steps, corresponding to the columns in the data container.

trim(tol=0, electrodes=None)[source]

Remove any black border around the video

Added in version 0.7.

Parameters:

tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in each frame of the trimmed video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object with trimmed borders.

class pulse2percept.stimuli.GratingStimulus(shape, direction=0, spatial_freq=0.1, temporal_freq=0.001, phase=0, contrast=1, time=None, mask=None, electrodes=None, metadata=None)[source]

Drifting sinusoidal grating

A drifting sinusoidal grating of a given spatial and temporal frequency.

Added in version 0.7.

Parameters:

shape ((height, width)) – A tuple specifying the desired height (pixels) and the width (pixels) of the grating stimulus.
direction (scalar in [0, 360) degrees, optional) – Drift direction of the grating.
spatial_freq (scalar (cycles/pixel), optional) – Spatial frequency of the grating in cycles per pixel
temporal_freq (scalar (cycles/frame), optional) – Temporal frequency of the grating in cycles per frame
phase (scalar (degrees), optional) – The initial phase of the grating in degrees
contrast (scalar in [0, 1], optional) – Stimulus contrast between 0 and 1
time (scalar, array-like, or None; optional) –
The time points at which to evaluate the drifting grating:
- If a scalar, time is interpreted as the end time (in milliseconds) of a time series with 50 Hz frame rate.
- If array-like, time is interpreted as the exact time points (in milliseconds) at which to draw the grating (end point included).
- If None, time defaults to a 1-second time series at 50 Hz frame rate (end point included).
mask ({'gauss', 'circle', None}) –
Stimulus mask:
- ”gauss”: a 2D Gaussian designed such that the border of the image lies at 3 standard deviations
- ”circle”: a circle that fits into the shape of the stimulus
- None: no mask
electrodes (int, string or list thereof; optional, default: None) – Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

apply(func, *args, **kwargs)[source]

Apply a function to each frame of the video

Parameters:

func (function) – The function to apply to each frame in the video. Must accept a 2D or 3D image and return an image with the same dimensions
*args – Additional positional arguments passed to the function
**kwargs – Additional keyword arguments passed to the function

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the new image

center(loc=None)[source]

Center the image foreground

This function shifts the center of mass (CoM) to the image center.

Parameters:: loc ((col, row), optional) – The pixel location at which to center the CoM. By default, shifts the CoM to the image center.
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the centered image

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

crop(idx_space=None, idx_time=None, left=0, right=0, top=0, bottom=0, front=0, back=0, electrodes=None)[source]

Crop the video

This method maps a rectangle (defined by two corners) from each video frame to a rectangle of the given size. Similarly, the video can be shortened to a specified range of frames.

Alternatively, this method can be used to crop a number of columns either from the left or the right of the video frame, or a number of rows either from the top or the bottom, or a number of frames from the front (beginning) or back (end) of the video.

Added in version 0.8.

Parameters:

idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner [y0, x0] and bottom-right corner [y1, x1] (exclusive) of the rectangle to crop.
idx_time (tuple (t0, t1)) – Frame indices defining the start t0 and end t1 of the cropped video.
left (int) – Number of columns to crop from the left of each video frame
right (int) – Number of columns to crop from the right of each video frame
top (int) – Number of rows to crop from the top of each video frame
bottom (int) – Number of rows to crop from the bottom of each video frame
front (int) – Number of frames to crop from the front (beginning) of the video
back (int) – Number of frames to crop from the back (end) of the video
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the cropped image.

Returns:

stim (VideoStimulus) – A copy of the stimulus object containing the video

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

encode(amp_range=(0, 50), pulse=None)[source]

Encode image using amplitude modulation

Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in amp_range.

By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.

Parameters:

amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto min_amp and the largest onto max_amp.
pulse (Stimulus, optional) – A valid pulse or pulse train to be used for the encoding. If None given, a BiphasicPulse (0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.

Returns:

stim (Stimulus) – Encoded stimulus

filter(filt, **kwargs)[source]

Filter each frame of the video

Parameters:

filt (str) –
Image filter that will be applied to every frame of the video. Additional parameters can be passed as keyword arguments. The following filters are supported:
- ’sobel’: Edge filter the image using the Sobel filter.
- ’scharr’: Edge filter the image using the Scarr filter.
- ’canny’: Edge filter the image using the Canny algorithm. You can also specify sigma, low_threshold, high_threshold, mask, and use_quantiles.
- ’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter

Returns:

stim (VideoStimulus) – A copy of the stimulus object with the filtered image

invert()[source]

Invert the gray levels of the video

Returns:: stim (VideoStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

play(fps=None, repeat=True, annotate_time=True, ax=None)[source]

Animate the video as HTML with JavaScript

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

Parameters:

fps (float or None) – If None, uses the video’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 ms in the title of the panel.
ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object

Returns:

ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

resize(shape, electrodes=None)[source]

Resize the video

Parameters:

shape ((rows, cols)) – Shape of each frame in the resized video. If one of the dimensions is set to -1, its value will be inferred by keeping a constant aspect ratio.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the resized video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object containing the resized video

rewind()[source]: Rewind the iterator

rgb2gray(electrodes=None)[source]

Convert the video to grayscale

Parameters:

electrodes (int, string or list thereof; optional) –

Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].

rotate(angle, mode='constant')[source]

Rotate each frame of the video

Parameters:: angle (float) – Angle by which to rotate each video frame (degrees). Positive: counter-clockwise, negative: clockwise
Returns:: stim (VideoStimulus) – A copy of the stimulus object containing the rotated video

scale(scaling_factor)[source]

Scale the image foreground

This function scales the image foreground (excluding black pixels) by a factor.

Parameters:: scaling_factor (float) – Factory by which to scale the image
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the scaled image

property shape: Data container shape

shift(shift_cols, shift_rows)[source]

Shift the image foreground

This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.

Parameters:

shift_cols (float) – Number of columns by which to shift the CoM. Positive: to the right, negative: to the left
shift_rows (float) – Number of rows by which to shift the CoM. Positive: downward, negative: upward

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the shifted image

property time: Time steps A list of time steps, corresponding to the columns in the data container.

trim(tol=0, electrodes=None)[source]

Remove any black border around the video

Added in version 0.7.

Parameters:

tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in each frame of the trimmed video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object with trimmed borders.

class pulse2percept.stimuli.ImageStimulus(source, resize=None, as_gray=False, electrodes=None, metadata=None, compress=False)[source]

A stimulus made from an image, where each pixel gets assigned to an electrode, and grayscale values in the range [0, 255] get converted to activation values in the range [0, 1].

See also

Basic Concepts > Electrical Stimuli <topics-stimuli>
VideoStimulus

Added in version 0.7.

Parameters:

source (str) – Path to image file. Supported image types include JPG, PNG, and TIF; and are inferred from the file ending. Use VideoStimulus for GIFs.
resize ((height, width) or None, optional) – Shape of the resized image. If one of the dimensions is set to -1, its value will be inferred by keeping a constant aspect ratio.
as_gray (bool, optional) – Flag whether to convert the image to grayscale. A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the (resized) image.
metadata (dict, optional) – Additional stimulus metadata can be stored in a dictionary.
compress (bool, optional) – If True, will remove pixels with 0 grayscale value.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

apply(func, *args, **kwargs)[source]

Apply a function to the image

Parameters:

func (function) – The function to apply to the image. Must accept a 2D or 3D image and return an image with the same dimensions
args (*) – Additional positional arguments passed to the function
**kwargs – Additional keyword arguments passed to the function

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the new image

center(loc=None)[source]

Center the image foreground

This function shifts the center of mass (CoM) to the image center.

Parameters:: loc ((col, row), optional) – The pixel location at which to center the CoM. By default, shifts the CoM to the image center.
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the centered image

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

crop(idx_rect=None, left=0, right=0, top=0, bottom=0, electrodes=None)[source]

Crop the image

This method maps a rectangle (defined by two corners) from the image to a rectangle of the given size. Alternatively, this method can be used to crop a number of columns either from the left or the right of the image, or a number of rows either from the top or the bottom.

Added in version 0.8.

Parameters:

idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner [y0, x0] and bottom-right corner [y1, x1] (exclusive) of the rectangle to crop.
left (int) – Number of columns to crop from the left
right (int) – Number of columns to crop from the right
top (int) – Number of rows to crop from the top
bottom (int) – Number of rows to crop from the bottom
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the cropped image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the cropped image

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

encode(amp_range=(0, 50), pulse=None)[source]

Encode image using amplitude modulation

Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in amp_range.

By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.

Parameters:

amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto min_amp and the largest onto max_amp.
pulse (Stimulus, optional) – A valid pulse or pulse train to be used for the encoding. If None given, a BiphasicPulse (0.46 ms phase duration, 500 ms total duration) will be used.

Returns:

stim (Stimulus) – Encoded stimulus

filter(filt, **kwargs)[source]

Filter the image

Parameters:

filt (str) –
Image filter. Additional parameters can be passed as keyword arguments. The following filters are supported:
- ’sobel’: Edge filter the image using the Sobel filter.
- ’scharr’: Edge filter the image using the `Scharr filter`_.
- ’canny’: Edge filter the image using the Canny algorithm. You can also specify sigma, low_threshold, high_threshold, mask, and use_quantiles.
- ’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter
filter (.. _Scharr)
filter
algorithm (.. _Canny)

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the filtered image

invert()[source]

Invert the gray levels of the image

Returns:: stim (ImageStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(ax=None, **kwargs)[source]

Plot the stimulus

Parameters:: ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
Returns:: ax (matplotlib.axes.Axes) – Returns the axes with the plot on it

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

resize(shape, electrodes=None)[source]

Resize the image

Parameters:

shape ((rows, cols)) – Shape of the resized image
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the resized image

rgb2gray(electrodes=None)[source]

Convert the image to grayscale

Parameters:

electrodes (int, string or list thereof; optional) –

Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].

Notes

A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.

rotate(angle, mode='constant')[source]

Rotate the image

Parameters:: angle (float) – Angle by which to rotate the image (degrees). Positive: counter-clockwise, negative: clockwise
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the rotated image

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

Save the stimulus as an image

Parameters:: fname (str) – The name of the image file to be created. Image type will be inferred from the file extension.

scale(scaling_factor)[source]

Scale the image foreground

This function scales the image foreground (excluding black pixels) by a factor.

Parameters:: scaling_factor (float) – Factory by which to scale the image
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the scaled image

property shape: Data container shape

shift(shift_cols, shift_rows)[source]

Shift the image foreground

This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.

Parameters:

shift_cols (float) – Number of columns by which to shift the CoM. Positive: to the right, negative: to the left
shift_rows (float) – Number of rows by which to shift the CoM. Positive: downward, negative: upward

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the shifted image

threshold(thresh, **kwargs)[source]

Threshold the image

Parameters:

thresh (str or float) –
If a float in [0,1] is provided, pixels whose grayscale value is above said threshold will be white, others black.

A number of additional methods are supported:
- ’mean’: Threshold image based on the mean of grayscale values.
- ’minimum’: Threshold image based on the minimum method, where
  the histogram of the input image is computed and smoothed until there are only two maxima.
- ’local’: Threshold image based on `local pixel neighborhood`_.
  Requires block_size: odd number of pixels in the neighborhood.
- ’otsu’: `Otsu's method`_
- ’isodata’: `ISODATA method`_, also known as the Ridler-Calvard
  method or intermeans.
neighborhood (.. _local pixel)
method (.. _ISODATA)
method

Returns:

stim (ImageStimulus) – A copy of the stimulus object with two gray levels 0.0 and 1.0

property time: Time steps A list of time steps, corresponding to the columns in the data container.

trim(tol=0, electrodes=None)[source]

Remove any black border around the image

Added in version 0.7.

Parameters:

tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the trimmed image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object with trimmed borders.

class pulse2percept.stimuli.LogoBVL(resize=None, electrodes=None, metadata=None, as_gray=False)[source]

Bionic Vision Lab (BVL) logo

Load the 576x720x4 Bionic Vision Lab (BVL) logo.

Added in version 0.7.

Parameters:

resize ((height, width) or None, optional) – A tuple specifying the desired height and the width of the image stimulus.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the (resized) image.
metadata (dict, optional) – Additional stimulus metadata can be stored in a dictionary.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

apply(func, *args, **kwargs)[source]

Apply a function to the image

Parameters:

func (function) – The function to apply to the image. Must accept a 2D or 3D image and return an image with the same dimensions
args (*) – Additional positional arguments passed to the function
**kwargs – Additional keyword arguments passed to the function

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the new image

center(loc=None)[source]

Center the image foreground

This function shifts the center of mass (CoM) to the image center.

Parameters:: loc ((col, row), optional) – The pixel location at which to center the CoM. By default, shifts the CoM to the image center.
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the centered image

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

crop(idx_rect=None, left=0, right=0, top=0, bottom=0, electrodes=None)[source]

Crop the image

This method maps a rectangle (defined by two corners) from the image to a rectangle of the given size. Alternatively, this method can be used to crop a number of columns either from the left or the right of the image, or a number of rows either from the top or the bottom.

Added in version 0.8.

Parameters:

idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner [y0, x0] and bottom-right corner [y1, x1] (exclusive) of the rectangle to crop.
left (int) – Number of columns to crop from the left
right (int) – Number of columns to crop from the right
top (int) – Number of rows to crop from the top
bottom (int) – Number of rows to crop from the bottom
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the cropped image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the cropped image

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

encode(amp_range=(0, 50), pulse=None)[source]

Encode image using amplitude modulation

Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in amp_range.

By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.

Parameters:

amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto min_amp and the largest onto max_amp.
pulse (Stimulus, optional) – A valid pulse or pulse train to be used for the encoding. If None given, a BiphasicPulse (0.46 ms phase duration, 500 ms total duration) will be used.

Returns:

stim (Stimulus) – Encoded stimulus

filter(filt, **kwargs)[source]

Filter the image

Parameters:

filt (str) –
Image filter. Additional parameters can be passed as keyword arguments. The following filters are supported:
- ’sobel’: Edge filter the image using the Sobel filter.
- ’scharr’: Edge filter the image using the `Scharr filter`_.
- ’canny’: Edge filter the image using the Canny algorithm. You can also specify sigma, low_threshold, high_threshold, mask, and use_quantiles.
- ’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter
filter (.. _Scharr)
filter
algorithm (.. _Canny)

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the filtered image

invert()[source]

Invert the gray levels of the image

Returns:: stim (ImageStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(ax=None, **kwargs)[source]

Plot the stimulus

Parameters:: ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
Returns:: ax (matplotlib.axes.Axes) – Returns the axes with the plot on it

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

resize(shape, electrodes=None)[source]

Resize the image

Parameters:

shape ((rows, cols)) – Shape of the resized image
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the resized image

rgb2gray(electrodes=None)[source]

Convert the image to grayscale

Parameters:

electrodes (int, string or list thereof; optional) –

Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].

Notes

A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.

rotate(angle, mode='constant')[source]

Rotate the image

Parameters:: angle (float) – Angle by which to rotate the image (degrees). Positive: counter-clockwise, negative: clockwise
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the rotated image

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

Save the stimulus as an image

Parameters:: fname (str) – The name of the image file to be created. Image type will be inferred from the file extension.

scale(scaling_factor)[source]

Scale the image foreground

This function scales the image foreground (excluding black pixels) by a factor.

Parameters:: scaling_factor (float) – Factory by which to scale the image
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the scaled image

property shape: Data container shape

shift(shift_cols, shift_rows)[source]

Shift the image foreground

This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.

Parameters:

shift_cols (float) – Number of columns by which to shift the CoM. Positive: to the right, negative: to the left
shift_rows (float) – Number of rows by which to shift the CoM. Positive: downward, negative: upward

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the shifted image

threshold(thresh, **kwargs)[source]

Threshold the image

Parameters:

thresh (str or float) –
If a float in [0,1] is provided, pixels whose grayscale value is above said threshold will be white, others black.

A number of additional methods are supported:
- ’mean’: Threshold image based on the mean of grayscale values.
- ’minimum’: Threshold image based on the minimum method, where
  the histogram of the input image is computed and smoothed until there are only two maxima.
- ’local’: Threshold image based on `local pixel neighborhood`_.
  Requires block_size: odd number of pixels in the neighborhood.
- ’otsu’: `Otsu's method`_
- ’isodata’: `ISODATA method`_, also known as the Ridler-Calvard
  method or intermeans.
neighborhood (.. _local pixel)
method (.. _ISODATA)
method

Returns:

stim (ImageStimulus) – A copy of the stimulus object with two gray levels 0.0 and 1.0

property time: Time steps A list of time steps, corresponding to the columns in the data container.

trim(tol=0, electrodes=None)[source]

Remove any black border around the image

Added in version 0.7.

Parameters:

tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the trimmed image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object with trimmed borders.

class pulse2percept.stimuli.LogoUCSB(resize=None, electrodes=None, metadata=None)[source]

UCSB logo

Load a 324x727 white-on-black logo of the University of California, Santa Barbara.

Added in version 0.7.

Parameters:

resize ((height, width) or None, optional) – A tuple specifying the desired height and the width of the image stimulus.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the (resized) image.
metadata (dict, optional) – Additional stimulus metadata can be stored in a dictionary.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

apply(func, *args, **kwargs)[source]

Apply a function to the image

Parameters:

func (function) – The function to apply to the image. Must accept a 2D or 3D image and return an image with the same dimensions
args (*) – Additional positional arguments passed to the function
**kwargs – Additional keyword arguments passed to the function

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the new image

center(loc=None)[source]

Center the image foreground

This function shifts the center of mass (CoM) to the image center.

Parameters:: loc ((col, row), optional) – The pixel location at which to center the CoM. By default, shifts the CoM to the image center.
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the centered image

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

crop(idx_rect=None, left=0, right=0, top=0, bottom=0, electrodes=None)[source]

Crop the image

This method maps a rectangle (defined by two corners) from the image to a rectangle of the given size. Alternatively, this method can be used to crop a number of columns either from the left or the right of the image, or a number of rows either from the top or the bottom.

Added in version 0.8.

Parameters:

idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner [y0, x0] and bottom-right corner [y1, x1] (exclusive) of the rectangle to crop.
left (int) – Number of columns to crop from the left
right (int) – Number of columns to crop from the right
top (int) – Number of rows to crop from the top
bottom (int) – Number of rows to crop from the bottom
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the cropped image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the cropped image

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

encode(amp_range=(0, 50), pulse=None)[source]

Encode image using amplitude modulation

Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in amp_range.

By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.

Parameters:

amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto min_amp and the largest onto max_amp.
pulse (Stimulus, optional) – A valid pulse or pulse train to be used for the encoding. If None given, a BiphasicPulse (0.46 ms phase duration, 500 ms total duration) will be used.

Returns:

stim (Stimulus) – Encoded stimulus

filter(filt, **kwargs)[source]

Filter the image

Parameters:

filt (str) –
Image filter. Additional parameters can be passed as keyword arguments. The following filters are supported:
- ’sobel’: Edge filter the image using the Sobel filter.
- ’scharr’: Edge filter the image using the `Scharr filter`_.
- ’canny’: Edge filter the image using the Canny algorithm. You can also specify sigma, low_threshold, high_threshold, mask, and use_quantiles.
- ’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter
filter (.. _Scharr)
filter
algorithm (.. _Canny)

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the filtered image

invert()[source]

Invert the gray levels of the image

Returns:: stim (ImageStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(ax=None, **kwargs)[source]

Plot the stimulus

Parameters:: ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
Returns:: ax (matplotlib.axes.Axes) – Returns the axes with the plot on it

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

resize(shape, electrodes=None)[source]

Resize the image

Parameters:

shape ((rows, cols)) – Shape of the resized image
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the resized image

rgb2gray(electrodes=None)[source]

Convert the image to grayscale

Parameters:

electrodes (int, string or list thereof; optional) –

Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].

Notes

A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.

rotate(angle, mode='constant')[source]

Rotate the image

Parameters:: angle (float) – Angle by which to rotate the image (degrees). Positive: counter-clockwise, negative: clockwise
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the rotated image

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

Save the stimulus as an image

Parameters:: fname (str) – The name of the image file to be created. Image type will be inferred from the file extension.

scale(scaling_factor)[source]

Scale the image foreground

This function scales the image foreground (excluding black pixels) by a factor.

Parameters:: scaling_factor (float) – Factory by which to scale the image
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the scaled image

property shape: Data container shape

shift(shift_cols, shift_rows)[source]

Shift the image foreground

This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.

Parameters:

shift_cols (float) – Number of columns by which to shift the CoM. Positive: to the right, negative: to the left
shift_rows (float) – Number of rows by which to shift the CoM. Positive: downward, negative: upward

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the shifted image

threshold(thresh, **kwargs)[source]

Threshold the image

Parameters:

thresh (str or float) –
If a float in [0,1] is provided, pixels whose grayscale value is above said threshold will be white, others black.

A number of additional methods are supported:
- ’mean’: Threshold image based on the mean of grayscale values.
- ’minimum’: Threshold image based on the minimum method, where
  the histogram of the input image is computed and smoothed until there are only two maxima.
- ’local’: Threshold image based on `local pixel neighborhood`_.
  Requires block_size: odd number of pixels in the neighborhood.
- ’otsu’: `Otsu's method`_
- ’isodata’: `ISODATA method`_, also known as the Ridler-Calvard
  method or intermeans.
neighborhood (.. _local pixel)
method (.. _ISODATA)
method

Returns:

stim (ImageStimulus) – A copy of the stimulus object with two gray levels 0.0 and 1.0

property time: Time steps A list of time steps, corresponding to the columns in the data container.

trim(tol=0, electrodes=None)[source]

Remove any black border around the image

Added in version 0.7.

Parameters:

tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the trimmed image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object with trimmed borders.

class pulse2percept.stimuli.MonophasicPulse(amp, phase_dur, delay_dur=0, stim_dur=None, electrode=None)[source]

Monophasic pulse

A simple stimulus consisting of a single monophasic pulse (either cathodic/negative or anodic/positive).

Added in version 0.6.

Parameters:

amp (float) – Current amplitude (uA). Negative currents: cathodic, positive: anodic.
phase_dur (float) – Duration (ms) of the cathodic or anodic phase.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the pulse after delay_dur ms.
stim_dur (float, optional) – Total stimulus duration (ms). Zeros will be inserted at the end of the stimulus to make the stimulus last stim_dur ms overall.
electrode ({ int | string }, optional) – Optionally, you can provide your own electrode name.

Notes

The sign of amp will determine whether the pulse is cathodic (negative current) or anodic (positive current).
A regular monophasic pulse is not considered “charge-balanced”. However, if amp is small enough, the pulse can be considered “charge-balanced” if its net current is smaller than 10 picoamps.

Examples

A single cathodic pulse (1ms phase duration at 20uA) delivered after 2ms and embedded in a stimulus that lasts 10ms overall:

>>> from pulse2percept.stimuli import MonophasicPulse
>>> pulse = MonophasicPulse(-20, 1, delay_dur=2, stim_dur=10)

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

property shape: Data container shape

property time: Time steps A list of time steps, corresponding to the columns in the data container.

class pulse2percept.stimuli.PulseTrain(freq, pulse, n_pulses=None, stim_dur=1000.0, electrode=None, metadata=None)[source]

Generic pulse train

Can be used to concatenate single pulses into a pulse train.

See also

BiphasicPulseTrain
AsymmetricBiphasicPulseTrain

Added in version 0.6.

Parameters:

freq (float) – Pulse train frequency (Hz).
pulse (Stimulus) – A Stimulus object containing a single pulse that will be concatenated.
n_pulses (int) – Number of pulses requested in the pulse train. If None, the entire stimulation window (stim_dur) is filled.
stim_dur (float, optional) – Total stimulus duration (ms). The pulse train will be trimmed to make the stimulus last stim_dur ms overall.
electrode ({ int | string }, optional) – Optionally, you can provide your own electrode name.
metadata (dict) – A dictionary of meta-data

Notes

If the pulse train frequency does not exactly divide stim_dur, the number of pulses will be rounded down. For example, when trying to fit a 11 Hz pulse train into a 100 ms window, there will be 9 pulses.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

property shape: Data container shape

property time: Time steps A list of time steps, corresponding to the columns in the data container.

class pulse2percept.stimuli.SnellenChart(resize=None, show_annotations=True, row=None, electrodes=None, metadata=None)[source]

Snellen chart

Load the 1348x840 Snellen chart commonly used to measure visual acuity.

Added in version 0.7.

Parameters:

resize ((height, width) or None, optional) – A tuple specifying the desired height and the width of the image stimulus.
show_annotations ({True, False}, optional) – If True, show the full Snellen chart including annotations of the rows and corresponding acuity measures.
row (None, optional) – Select a single row (between 1 and 11) from the Snellen chart. For example, row 1 corresponds to 20/200, row 2 to 20/100.
electrodes (int, string or list thereof; optional, default: None) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the (resized) image.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

apply(func, *args, **kwargs)[source]

Apply a function to the image

Parameters:

func (function) – The function to apply to the image. Must accept a 2D or 3D image and return an image with the same dimensions
args (*) – Additional positional arguments passed to the function
**kwargs – Additional keyword arguments passed to the function

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the new image

center(loc=None)[source]

Center the image foreground

This function shifts the center of mass (CoM) to the image center.

Parameters:: loc ((col, row), optional) – The pixel location at which to center the CoM. By default, shifts the CoM to the image center.
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the centered image

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

crop(idx_rect=None, left=0, right=0, top=0, bottom=0, electrodes=None)[source]

Crop the image

This method maps a rectangle (defined by two corners) from the image to a rectangle of the given size. Alternatively, this method can be used to crop a number of columns either from the left or the right of the image, or a number of rows either from the top or the bottom.

Added in version 0.8.

Parameters:

idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner [y0, x0] and bottom-right corner [y1, x1] (exclusive) of the rectangle to crop.
left (int) – Number of columns to crop from the left
right (int) – Number of columns to crop from the right
top (int) – Number of rows to crop from the top
bottom (int) – Number of rows to crop from the bottom
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the cropped image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the cropped image

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

encode(amp_range=(0, 50), pulse=None)[source]

Encode image using amplitude modulation

Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in amp_range.

By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.

Parameters:

amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto min_amp and the largest onto max_amp.
pulse (Stimulus, optional) – A valid pulse or pulse train to be used for the encoding. If None given, a BiphasicPulse (0.46 ms phase duration, 500 ms total duration) will be used.

Returns:

stim (Stimulus) – Encoded stimulus

filter(filt, **kwargs)[source]

Filter the image

Parameters:

filt (str) –
Image filter. Additional parameters can be passed as keyword arguments. The following filters are supported:
- ’sobel’: Edge filter the image using the Sobel filter.
- ’scharr’: Edge filter the image using the `Scharr filter`_.
- ’canny’: Edge filter the image using the Canny algorithm. You can also specify sigma, low_threshold, high_threshold, mask, and use_quantiles.
- ’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter
filter (.. _Scharr)
filter
algorithm (.. _Canny)

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the filtered image

invert()[source]

Invert the gray levels of the image

Returns:: stim (ImageStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(ax=None, **kwargs)[source]

Plot the stimulus

Parameters:: ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
Returns:: ax (matplotlib.axes.Axes) – Returns the axes with the plot on it

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

resize(shape, electrodes=None)[source]

Resize the image

Parameters:

shape ((rows, cols)) – Shape of the resized image
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the resized image

rgb2gray(electrodes=None)[source]

Convert the image to grayscale

Parameters:

electrodes (int, string or list thereof; optional) –

Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].

Notes

A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.

rotate(angle, mode='constant')[source]

Rotate the image

Parameters:: angle (float) – Angle by which to rotate the image (degrees). Positive: counter-clockwise, negative: clockwise
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the rotated image

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

Save the stimulus as an image

Parameters:: fname (str) – The name of the image file to be created. Image type will be inferred from the file extension.

scale(scaling_factor)[source]

Scale the image foreground

This function scales the image foreground (excluding black pixels) by a factor.

Parameters:: scaling_factor (float) – Factory by which to scale the image
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the scaled image

property shape: Data container shape

shift(shift_cols, shift_rows)[source]

Shift the image foreground

This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.

Parameters:

shift_cols (float) – Number of columns by which to shift the CoM. Positive: to the right, negative: to the left
shift_rows (float) – Number of rows by which to shift the CoM. Positive: downward, negative: upward

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the shifted image

threshold(thresh, **kwargs)[source]

Threshold the image

Parameters:

thresh (str or float) –
If a float in [0,1] is provided, pixels whose grayscale value is above said threshold will be white, others black.

A number of additional methods are supported:
- ’mean’: Threshold image based on the mean of grayscale values.
- ’minimum’: Threshold image based on the minimum method, where
  the histogram of the input image is computed and smoothed until there are only two maxima.
- ’local’: Threshold image based on `local pixel neighborhood`_.
  Requires block_size: odd number of pixels in the neighborhood.
- ’otsu’: `Otsu's method`_
- ’isodata’: `ISODATA method`_, also known as the Ridler-Calvard
  method or intermeans.
neighborhood (.. _local pixel)
method (.. _ISODATA)
method

Returns:

stim (ImageStimulus) – A copy of the stimulus object with two gray levels 0.0 and 1.0

property time: Time steps A list of time steps, corresponding to the columns in the data container.

trim(tol=0, electrodes=None)[source]

Remove any black border around the image

Added in version 0.7.

Parameters:

tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the trimmed image.

Returns:

stim (ImageStimulus) – A copy of the stimulus object with trimmed borders.

class pulse2percept.stimuli.Stimulus(source, electrodes=None, time=None, metadata=None, compress=False)[source]

A stimulus is comprised of a labeled 2D NumPy array that contains the data, where the rows denote electrodes and the columns denote points in time. A stimulus can be created from a variety of source types (e.g., scalars, lists, NumPy arrays, and dictionaries).

See also

Basic Concepts > Electrical Stimuli <topics-stimuli>

Added in version 0.6.

Parameters:

source (source type) –
A valid source type is one of the following:
- Scalar value: interpreted as the current amplitude delivered to a single electrode (no time component).
- NumPy array:
  - Nx1 array: interpreted as N current amplitudes delivered to N electrodes (no time component).
  - NxM array: interpreted as N electrodes each receiving M current amplitudes in time.
In addition, you can also pass a collection of source types. Each element must be a valid source type for a single electrode (e.g., scalar, 1-D array, Stimulus).
- List or tuple: List elements will be assigned to electrodes in order.
- Dictionary: Dictionary keys are used to address electrodes by name.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be extracted from the source type (e.g., the keys from a dictionary). If a scalar or NumPy array is passed, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of electrodes extracted from the source type (i.e., N).
time (int, float or list thereof; optional) –
Optionally, you can provide the time points of the source data. If none are given, time steps will be numbered 0..M.

Note

The number of time points provided must match the number of time points extracted from the source type (i.e., M). Stimuli created from scalars or 1-D NumPy arrays will have no time componenet, in which case you cannot provide your own time points.
metadata (dict, optional) – Additional stimulus metadata can be stored in a dictionary.
compress (bool, optional) –
If True, will compress the source data in two ways:
- Remove electrodes with all-zero activation.
- Retain only the time points at which the stimulus changes.
For example, in a pulse train, only the signal edges are saved. This drastically reduces the memory footprint of the stimulus.

Notes

Depending on the source type, a stimulus might have a time component or not (e.g., scalars: time=None).
You can access the stimulus applied to electrode e at time t by directly indexing into Stimulus[e, t]. In this case, t is not a column index but a time point.
If the time point is not explicitly stored in the data container, its value will be automatically interpolated from neighboring values.
If a requested time point lies outside the range of stored data, the value of its closest end point will be returned.

Examples

Stimulate a single electrode with -13uA:

>>> from pulse2percept.stimuli import Stimulus
>>> stim = Stimulus(-13)

Stimulate ten electrodes with 0uA:

>>> from pulse2percept.stimuli import Stimulus
>>> stim = Stimulus(np.zeros(10))

Provide new electrode names for an existing Stimulus object:

>>> from pulse2percept.stimuli import Stimulus
>>> old_stim = Stimulus([3, 5])
>>> new_stim = Stimulus(old_stim, electrodes=['new0', 'new1'])

Interpolate the stimulus value at some point in time. Here, the stimulus is a single-electrode ramp stimulus (stimulus value == point in time):

>>> from pulse2percept.stimuli import Stimulus
>>> stim = Stimulus(np.arange(10).reshape((1, -1)))
>>> stim[:, 3.45]
3.45...

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

property shape: Data container shape

property time: Time steps A list of time steps, corresponding to the columns in the data container.

class pulse2percept.stimuli.VideoStimulus(source, format=None, resize=None, as_gray=False, electrodes=None, time=None, metadata=None, compress=False)[source]

A stimulus made from a movie file, where each pixel gets assigned to an electrode, and grayscale values in the range [0, 255] get assigned to activation values in the range [0, 1].

The frame rate of the movie is used to infer the time points at which to stimulate.

See also

Basic Concepts > Electrical Stimuli <topics-stimuli>
ImageStimulus

Added in version 0.7.

Parameters:

source (str) –
Path to video file. Supported file types include MP4, AVI, MOV, and GIF; and are inferred from the file ending. If the file does not have a proper file ending, specify the file type via format.

Alternatively, pass a <rows x columns x channels x frames> NumPy array or another VideoStimulus object.
format (str) – A video format string supported by imageio, such as ‘MP4’, ‘AVI’, or ‘MOV’. Use if the file type cannot be inferred from source. For a full list of supported formats, see https://imageio.readthedocs.io/en/stable/formats.html.
resize ((height, width) or None, optional, default: None) – A tuple specifying the desired height and the width of each video frame
as_gray (bool, optional) – Flag whether to convert the image to grayscale. A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
electrodes (int, string or list thereof; optional, default: None) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the (resized) image.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.
compress (bool, optional, default: False) – If True, will compress the source data in two ways: * Remove electrodes with all-zero activation. * Retain only the time points at which the stimulus changes.

append(other)[source]

Append another stimulus

This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.

Added in version 0.7.

Parameters:: other (Stimulus) – Another stimulus with matching electrodes.
Returns:: comb (Stimulus) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.

apply(func, *args, **kwargs)[source]

Apply a function to each frame of the video

Parameters:

func (function) – The function to apply to each frame in the video. Must accept a 2D or 3D image and return an image with the same dimensions
*args – Additional positional arguments passed to the function
**kwargs – Additional keyword arguments passed to the function

Returns:

stim (ImageStimulus) – A copy of the stimulus object with the new image

center(loc=None)[source]

Center the image foreground

This function shifts the center of mass (CoM) to the image center.

Parameters:: loc ((col, row), optional) – The pixel location at which to center the CoM. By default, shifts the CoM to the image center.
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the centered image

compress()[source]

Compress the source data

Returns:: compressed (Stimulus)

crop(idx_space=None, idx_time=None, left=0, right=0, top=0, bottom=0, front=0, back=0, electrodes=None)[source]

Crop the video

This method maps a rectangle (defined by two corners) from each video frame to a rectangle of the given size. Similarly, the video can be shortened to a specified range of frames.

Alternatively, this method can be used to crop a number of columns either from the left or the right of the video frame, or a number of rows either from the top or the bottom, or a number of frames from the front (beginning) or back (end) of the video.

Added in version 0.8.

Parameters:

idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner [y0, x0] and bottom-right corner [y1, x1] (exclusive) of the rectangle to crop.
idx_time (tuple (t0, t1)) – Frame indices defining the start t0 and end t1 of the cropped video.
left (int) – Number of columns to crop from the left of each video frame
right (int) – Number of columns to crop from the right of each video frame
top (int) – Number of rows to crop from the top of each video frame
bottom (int) – Number of rows to crop from the bottom of each video frame
front (int) – Number of frames to crop from the front (beginning) of the video
back (int) – Number of frames to crop from the back (end) of the video
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the cropped image.

Returns:

stim (VideoStimulus) – A copy of the stimulus object containing the video

property data: Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.

property dt

Sampling time step (ms)

Defines the duration of the signal edge transitions.

Added in version 0.7.

property duration: Stimulus duration (ms)

property electrodes: Electrode names A list of electrode names, corresponding to the rows in the data container.

encode(amp_range=(0, 50), pulse=None)[source]

Encode image using amplitude modulation

Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in amp_range.

By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.

Parameters:

amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto min_amp and the largest onto max_amp.
pulse (Stimulus, optional) – A valid pulse or pulse train to be used for the encoding. If None given, a BiphasicPulse (0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.

Returns:

stim (Stimulus) – Encoded stimulus

filter(filt, **kwargs)[source]

Filter each frame of the video

Parameters:

filt (str) –
Image filter that will be applied to every frame of the video. Additional parameters can be passed as keyword arguments. The following filters are supported:
- ’sobel’: Edge filter the image using the Sobel filter.
- ’scharr’: Edge filter the image using the Scarr filter.
- ’canny’: Edge filter the image using the Canny algorithm. You can also specify sigma, low_threshold, high_threshold, mask, and use_quantiles.
- ’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter

Returns:

stim (VideoStimulus) – A copy of the stimulus object with the filtered image

invert()[source]

Invert the gray levels of the video

Returns:: stim (VideoStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].

property is_charge_balanced

Flag indicating whether the stimulus is charge-balanced

A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.

property is_compressed: Flag indicating whether the stimulus has been compressed

play(fps=None, repeat=True, annotate_time=True, ax=None)[source]

Animate the video as HTML with JavaScript

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

Parameters:

fps (float or None) – If None, uses the video’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 ms in the title of the panel.
ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object

Returns:

ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.

plot(electrodes=None, time=None, fmt='k-', ax=None)[source]

Plot the stimulus

Added in version 0.7.

Parameters:

electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.

Returns:

axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode

remove(electrodes)[source]

Remove electrode(s)

Removes the stimulus of a certain electrode or list of electrodes.

Added in version 0.8.

Parameters:: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.

resize(shape, electrodes=None)[source]

Resize the video

Parameters:

shape ((rows, cols)) – Shape of each frame in the resized video. If one of the dimensions is set to -1, its value will be inferred by keeping a constant aspect ratio.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the resized video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object containing the resized video

rewind()[source]: Rewind the iterator

rgb2gray(electrodes=None)[source]

Convert the video to grayscale

Parameters:

electrodes (int, string or list thereof; optional) –

Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in the grayscale video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].

rotate(angle, mode='constant')[source]

Rotate each frame of the video

Parameters:: angle (float) – Angle by which to rotate each video frame (degrees). Positive: counter-clockwise, negative: clockwise
Returns:: stim (VideoStimulus) – A copy of the stimulus object containing the rotated video

scale(scaling_factor)[source]

Scale the image foreground

This function scales the image foreground (excluding black pixels) by a factor.

Parameters:: scaling_factor (float) – Factory by which to scale the image
Returns:: stim (ImageStimulus) – A copy of the stimulus object containing the scaled image

property shape: Data container shape

shift(shift_cols, shift_rows)[source]

Shift the image foreground

This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.

Parameters:

shift_cols (float) – Number of columns by which to shift the CoM. Positive: to the right, negative: to the left
shift_rows (float) – Number of rows by which to shift the CoM. Positive: downward, negative: upward

Returns:

stim (ImageStimulus) – A copy of the stimulus object containing the shifted image

property time: Time steps A list of time steps, corresponding to the columns in the data container.

trim(tol=0, electrodes=None)[source]

Remove any black border around the video

Added in version 0.7.

Parameters:

tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.

Note

The number of electrode names provided must match the number of pixels in each frame of the trimmed video.

Returns:

stim (VideoStimulus) – A copy of the stimulus object with trimmed borders.