pulse2percept.stimuli¶
Common electrical stimuli, such as charge-balanced square-wave pulse trains.
See also
-
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”).
New in version 0.6.
Parameters: - amp2 (amp1,) – 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_dur2 (phase_dur1,) – 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 laststim_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 thecathodic_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.
New 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.
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
electrodes
¶ Electrode names A list of electrode names, corresponding to the rows in the data container.
-
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.
-
is_compressed
¶ Flag indicating whether the stimulus has been compressed
-
plot
(electrodes=None, time=None, fmt='k-', ax=None)[source]¶ Plot the stimulus
New 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.
New 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.
-
shape
¶ Data container shape
-
time
¶ Time steps A list of time steps, corresponding to the columns in the data container.
- amp2 (amp1,) – Current amplitude (uA) of the first and second pulse phases.
Negative currents: cathodic, positive: anodic.
The signs will be converted automatically depending on
-
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.New in version 0.6.
Parameters: - freq (float) – Pulse train frequency (Hz).
- amp2 (amp1,) – 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_dur2 (phase_dur1,) – 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.
New 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.
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
electrodes
¶ Electrode names A list of electrode names, corresponding to the rows in the data container.
-
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.
-
is_compressed
¶ Flag indicating whether the stimulus has been compressed
-
plot
(electrodes=None, time=None, fmt='k-', ax=None)[source]¶ Plot the stimulus
New 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.
New 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.
-
shape
¶ Data container shape
-
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.
New 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 bebar_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).
- If a scalar,
- 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.
New 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
-
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.
New 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 endt1
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- idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
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 ontomax_amp
. - pulse (
Stimulus
, optional) – A valid pulse or pulse train to be used for the encoding. If None given, aBiphasicPulse
(0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.
Returns: stim (
Stimulus
) – Encoded stimulus- 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
-
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
, anduse_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- filt (str) –
-
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].
-
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.
-
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
New 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.
New 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
-
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
-
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: Returns: stim (
ImageStimulus
) – A copy of the stimulus object containing the shifted image
-
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
New 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”).
New 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 laststim_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.
New 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.
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
electrodes
¶ Electrode names A list of electrode names, corresponding to the rows in the data container.
-
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.
-
is_compressed
¶ Flag indicating whether the stimulus has been compressed
-
plot
(electrodes=None, time=None, fmt='k-', ax=None)[source]¶ Plot the stimulus
New 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.
New 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.
-
shape
¶ Data container shape
-
time
¶ Time steps A list of time steps, corresponding to the columns in the data container.
- amp (float) – Current amplitude (uA). Negative currents: cathodic, positive: anodic.
The sign will be converted automatically depending on
-
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.
New 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.
New 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.
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
electrodes
¶ Electrode names A list of electrode names, corresponding to the rows in the data container.
-
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.
-
is_compressed
¶ Flag indicating whether the stimulus has been compressed
-
plot
(electrodes=None, time=None, fmt='k-', ax=None)[source]¶ Plot the stimulus
New 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.
New 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.
-
shape
¶ Data container shape
-
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.
New 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.
New 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.
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
electrodes
¶ Electrode names A list of electrode names, corresponding to the rows in the data container.
-
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.
-
is_compressed
¶ Flag indicating whether the stimulus has been compressed
-
plot
(electrodes=None, time=None, fmt='k-', ax=None)[source]¶ Plot the stimulus
New 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.
New 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.
-
shape
¶ Data container shape
-
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.
New 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.
New 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
-
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.
New 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 endt1
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- idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
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 ontomax_amp
. - pulse (
Stimulus
, optional) – A valid pulse or pulse train to be used for the encoding. If None given, aBiphasicPulse
(0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.
Returns: stim (
Stimulus
) – Encoded stimulus- 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
-
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
, anduse_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- filt (str) –
-
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].
-
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.
-
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
New 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.
New 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
-
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
-
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: Returns: stim (
ImageStimulus
) – A copy of the stimulus object containing the shifted image
-
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
New 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.
New 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.
New 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
-
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.
New 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 endt1
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- idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
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 ontomax_amp
. - pulse (
Stimulus
, optional) – A valid pulse or pulse train to be used for the encoding. If None given, aBiphasicPulse
(0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.
Returns: stim (
Stimulus
) – Encoded stimulus- 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
-
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
, anduse_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- filt (str) –
-
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].
-
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.
-
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
New 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.
New 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
-
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
-
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: Returns: stim (
ImageStimulus
) – A copy of the stimulus object containing the shifted image
-
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
New 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.
New 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).
- If a scalar,
- 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.
New 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
-
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.
New 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 endt1
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- idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
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 ontomax_amp
. - pulse (
Stimulus
, optional) – A valid pulse or pulse train to be used for the encoding. If None given, aBiphasicPulse
(0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.
Returns: stim (
Stimulus
) – Encoded stimulus- 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
-
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
, anduse_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- filt (str) –
-
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].
-
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.
-
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
New 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.
New 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
-
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
-
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: Returns: stim (
ImageStimulus
) – A copy of the stimulus object containing the shifted image
-
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
New 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, format=None, 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].
New 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. If the file does not have a
proper file ending, specify the file type via
format
. UseVideoStimulus
for GIFs. - format (str, optional) – An image format string supported by imageio, such as ‘JPG’, ‘PNG’, or
‘TIFF’. 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) – 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.
New 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
-
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.
New 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- idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
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 ontomax_amp
. - pulse (
Stimulus
, optional) – A valid pulse or pulse train to be used for the encoding. If None given, aBiphasicPulse
(0.46 ms phase duration, 500 ms total duration) will be used.
Returns: stim (
Stimulus
) – Encoded stimulus- 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
-
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 Scarr filter.
- ’canny’: Edge filter the image using the Canny algorithm.
You can also specify
sigma
,low_threshold
,high_threshold
,mask
, anduse_quantiles
. - ’median’: Return local median of the image.
- **kwargs – Additional parameters passed to the filter
Returns: stim (
ImageStimulus
) – A copy of the stimulus object with the filtered image- filt (str) –
-
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].
-
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.
-
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.
New 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)[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
-
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: 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
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_local>_.
Requires
block_size
: odd number of pixels in the neighborhood.
- ’otsu’: `Otsu’s method
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_otsu>_
- ’isodata’: `ISODATA method
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_isodata>`_, also known as the Ridler-Calvard method or intermeans.
Returns: stim ( ImageStimulus
) – A copy of the stimulus object with two gray levels 0.0 and 1.0
-
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
New 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.
- source (str) – Path to image file. Supported image types include JPG, PNG, and TIF;
and are inferred from the file ending. If the file does not have a
proper file ending, specify the file type via
-
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.
New 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.
New 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
-
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.
New 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- idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
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 ontomax_amp
. - pulse (
Stimulus
, optional) – A valid pulse or pulse train to be used for the encoding. If None given, aBiphasicPulse
(0.46 ms phase duration, 500 ms total duration) will be used.
Returns: stim (
Stimulus
) – Encoded stimulus- 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
-
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 Scarr filter.
- ’canny’: Edge filter the image using the Canny algorithm.
You can also specify
sigma
,low_threshold
,high_threshold
,mask
, anduse_quantiles
. - ’median’: Return local median of the image.
- **kwargs – Additional parameters passed to the filter
Returns: stim (
ImageStimulus
) – A copy of the stimulus object with the filtered image- filt (str) –
-
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].
-
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.
-
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.
New 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)[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
-
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: 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
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_local>_.
Requires
block_size
: odd number of pixels in the neighborhood.
- ’otsu’: `Otsu’s method
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_otsu>_
- ’isodata’: `ISODATA method
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_isodata>`_, also known as the Ridler-Calvard method or intermeans.
Returns: stim ( ImageStimulus
) – A copy of the stimulus object with two gray levels 0.0 and 1.0
-
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
New 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.
New 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.
New 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
-
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.
New 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- idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
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 ontomax_amp
. - pulse (
Stimulus
, optional) – A valid pulse or pulse train to be used for the encoding. If None given, aBiphasicPulse
(0.46 ms phase duration, 500 ms total duration) will be used.
Returns: stim (
Stimulus
) – Encoded stimulus- 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
-
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 Scarr filter.
- ’canny’: Edge filter the image using the Canny algorithm.
You can also specify
sigma
,low_threshold
,high_threshold
,mask
, anduse_quantiles
. - ’median’: Return local median of the image.
- **kwargs – Additional parameters passed to the filter
Returns: stim (
ImageStimulus
) – A copy of the stimulus object with the filtered image- filt (str) –
-
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].
-
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.
-
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.
New 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)[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
-
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: 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
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_local>_.
Requires
block_size
: odd number of pixels in the neighborhood.
- ’otsu’: `Otsu’s method
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_otsu>_
- ’isodata’: `ISODATA method
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_isodata>`_, also known as the Ridler-Calvard method or intermeans.
Returns: stim ( ImageStimulus
) – A copy of the stimulus object with two gray levels 0.0 and 1.0
-
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
New 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).
New 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.
New 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.
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
electrodes
¶ Electrode names A list of electrode names, corresponding to the rows in the data container.
-
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.
-
is_compressed
¶ Flag indicating whether the stimulus has been compressed
-
plot
(electrodes=None, time=None, fmt='k-', ax=None)[source]¶ Plot the stimulus
New 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.
New 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.
-
shape
¶ Data container shape
-
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.
New 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.
New 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.
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
electrodes
¶ Electrode names A list of electrode names, corresponding to the rows in the data container.
-
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.
-
is_compressed
¶ Flag indicating whether the stimulus has been compressed
-
plot
(electrodes=None, time=None, fmt='k-', ax=None)[source]¶ Plot the stimulus
New 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.
New 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.
-
shape
¶ Data container shape
-
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.
New 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.
New 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
-
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.
New 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- idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
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 ontomax_amp
. - pulse (
Stimulus
, optional) – A valid pulse or pulse train to be used for the encoding. If None given, aBiphasicPulse
(0.46 ms phase duration, 500 ms total duration) will be used.
Returns: stim (
Stimulus
) – Encoded stimulus- 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
-
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 Scarr filter.
- ’canny’: Edge filter the image using the Canny algorithm.
You can also specify
sigma
,low_threshold
,high_threshold
,mask
, anduse_quantiles
. - ’median’: Return local median of the image.
- **kwargs – Additional parameters passed to the filter
Returns: stim (
ImageStimulus
) – A copy of the stimulus object with the filtered image- filt (str) –
-
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].
-
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.
-
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.
New 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)[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
-
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: 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
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_local>_.
Requires
block_size
: odd number of pixels in the neighborhood.
- ’otsu’: `Otsu’s method
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_otsu>_
- ’isodata’: `ISODATA method
- <https://scikit-image.org/docs/stable/api/skimage.filters.html#skimage.filters.threshold_isodata>`_, also known as the Ridler-Calvard method or intermeans.
Returns: stim ( ImageStimulus
) – A copy of the stimulus object with two gray levels 0.0 and 1.0
-
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
New 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
New 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 timet
by directly indexing intoStimulus[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] # doctest: +ELLIPSIS 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.
New 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.
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
electrodes
¶ Electrode names A list of electrode names, corresponding to the rows in the data container.
-
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.
-
is_compressed
¶ Flag indicating whether the stimulus has been compressed
-
plot
(electrodes=None, time=None, fmt='k-', ax=None)[source]¶ Plot the stimulus
New 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.
New 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.
-
shape
¶ Data container shape
-
time
¶ Time steps A list of time steps, corresponding to the columns in the data container.
- source (source type) –
-
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.
New 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.
New 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
-
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.
New 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 endt1
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- idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
-
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.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
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 ontomax_amp
. - pulse (
Stimulus
, optional) – A valid pulse or pulse train to be used for the encoding. If None given, aBiphasicPulse
(0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.
Returns: stim (
Stimulus
) – Encoded stimulus- 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
-
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
, anduse_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- filt (str) –
-
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].
-
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.
-
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
New 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.
New 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
-
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
-
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: Returns: stim (
ImageStimulus
) – A copy of the stimulus object containing the shifted image
-
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
New 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.
- source (str) –