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”).
Added in version 0.6.
- Parameters:
amp1 (float) – Current amplitude (uA) of the first and second pulse phases. Negative currents: cathodic, positive: anodic. The signs will be converted automatically depending on
cathodic_first
.amp2 (float) – Current amplitude (uA) of the first and second pulse phases. Negative currents: cathodic, positive: anodic. The signs will be converted automatically depending on
cathodic_first
.phase_dur1 (float) – Duration (ms) of the first and second pulse phases.
phase_dur2 (float) – Duration (ms) of the first and second pulse phases.
interphase_dur (float, optional, default: 0) – Duration (ms) of the gap between cathodic and anodic phases.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the first pulse phase after
delay_dur
ms.stim_dur (float, optional, default:) –
2*phase_dur+interphase_dur+delay_dur
Total stimulus duration (ms). Zeros will be inserted at the end of the stimulus to make the stimulus 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.
Added in version 0.7.
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- property shape
Data container shape
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- class pulse2percept.stimuli.AsymmetricBiphasicPulseTrain(freq, amp1, amp2, phase_dur1, phase_dur2, interphase_dur=0, delay_dur=0, n_pulses=None, stim_dur=1000.0, cathodic_first=True, electrode=None, metadata=None)[source]
Asymmetric biphasic pulse
A simple stimulus consisting of a single biphasic pulse: a cathodic and an anodic phase, optionally separated by an interphase gap. The two pulse phases can have different amplitudes and duration (“asymmetric”). The order of the two phases is given by the
cathodic_first
flag.Added in version 0.6.
- Parameters:
freq (float) – Pulse train frequency (Hz).
amp1 (float) – Current amplitude (uA) of the first and second pulse phases. Negative currents: cathodic, positive: anodic. The signs will be converted automatically depending on
cathodic_first
.amp2 (float) – Current amplitude (uA) of the first and second pulse phases. Negative currents: cathodic, positive: anodic. The signs will be converted automatically depending on
cathodic_first
.phase_dur1 (float) – Duration (ms) of the first and second pulse phases.
phase_dur2 (float) – Duration (ms) of the first and second pulse phases.
interphase_dur (float, optional, default: 0) – Duration (ms) of the gap between cathodic and anodic phases.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the first pulse phase after
delay_dur
ms.n_pulses (int) – Number of pulses requested in the pulse train. If None, the entire stimulation window (
stim_dur
) is filled.stim_dur (float, optional, default: 1000 ms) – Total stimulus duration (ms). Zeros will be inserted at the end of the stimulus to make the the stimulus last
stim_dur
ms overall.cathodic_first (bool, optional, default: True) – If True, will deliver the cathodic pulse phase before the anodic one.
electrode ({ int | string }, optional, default: 0) – Optionally, you can provide your own electrode name.
metadata (dict) – A dictionary of meta-data
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- property shape
Data container shape
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- class pulse2percept.stimuli.BarStimulus(shape, direction=0, speed=0.1, bar_width=1, edge_width=3, px_btw_bars=None, start_pos=0, contrast=1, time=None, mask=None, electrodes=None, metadata=None)[source]
Drifting bar
A drifting bar stimulus.
Added in version 0.7.
- Parameters:
shape ((height, width)) – A tuple specifying the desired height (pixels) and the width (pixels) of the grating stimulus.
direction (scalar in [0, 360) degrees, optional) – Drift direction of the bar.
speed (scalar in pixels/frame, optional) – Drift speed of the bar.
bar_width (scalar in pixels, optional) – The width of the center of the bar.
edge_width (scalar in pixels, optional) – The width of the cosine edges of the bar. An edge of width edge_width will be tacked onto both sides of the bar, so the total width will be bar_width + 2 * edge_width
px_btw_bars (scalar in pixels, optional) – The number of pixels between the bars in the stimulus.
start_pos (scalar in pixels, optional) – The starting position of the first bar. The coordinate system is a line lying along the direction of the bar motion passing through the center of the stimulus. The point 0 is the center of the stimulus.
contrast (scalar in [0, 1], optional) – Stimulus contrast between 0 and 1
time (scalar, array-like, or None; optional) –
The time points at which to evaluate the drifting bar:
If a scalar,
time
is interpreted as the end time (in milliseconds) of a time series with 50 Hz frame rate.If array-like,
time
is interpreted as the exact time points (in milliseconds) at which to draw the bar (end point included).If None,
time
defaults to a 1-second time series at 50 Hz frame rate (end point included).
mask ({'gauss', 'circle', None}) –
Stimulus mask:
”gauss”: a 2D Gaussian designed such that the border of the image lies at 3 standard deviations
”circle”: a circle that fits into the
shape
of the stimulusNone: no mask
electrodes (int, string or list thereof; optional, default: None) – Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- 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.
Added in version 0.8.
- Parameters:
idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
[y0, x0]
and bottom-right corner[y1, x1]
(exclusive) of the rectangle to crop.idx_time (tuple (t0, t1)) – Frame indices defining the start
t0
and 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
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- encode(amp_range=(0, 50), pulse=None)[source]
Encode image using amplitude modulation
Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in
amp_range
.By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.
- Parameters:
amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto
min_amp
and the largest 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
- 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
- invert()[source]
Invert the gray levels of the video
- Returns:
stim (VideoStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- play(fps=None, repeat=True, annotate_time=True, ax=None)[source]
Animate the video as HTML with JavaScript
The video will be played in an interactive player in IPython or Jupyter Notebook.
- Parameters:
fps (float or None) – If None, uses the video’s time axis. Not supported for non-homogeneous time axis.
repeat (bool, optional) – Whether the animation should repeat when the sequence of frames is completed.
annotate_time (bool, optional) – If True, the time of the frame will be shown as t = X ms in the title of the panel.
ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object
- Returns:
ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- 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
- property shape
Data container shape
- shift(shift_cols, shift_rows)[source]
Shift the image foreground
This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.
- Parameters:
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the shifted image
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- trim(tol=0, electrodes=None)[source]
Remove any black border around the video
Added in version 0.7.
- Parameters:
tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in each frame of the trimmed video.
- Returns:
stim (VideoStimulus) – A copy of the stimulus object with trimmed borders.
- class pulse2percept.stimuli.BiphasicPulse(amp, phase_dur, interphase_dur=0, delay_dur=0, stim_dur=None, cathodic_first=True, electrode=None)[source]
Symmetric biphasic pulse
A simple stimulus consisting of a single biphasic pulse: a cathodic and an anodic phase, optionally separated by an interphase gap. Both cathodic and anodic phases have the same duration (“symmetric”).
Added in version 0.6.
- Parameters:
amp (float) – Current amplitude (uA). Negative currents: cathodic, positive: anodic. The sign will be converted automatically depending on
cathodic_first
.phase_dur (float) – Duration (ms) of the cathodic/anodic phase.
interphase_dur (float, optional, default: 0) – Duration (ms) of the gap between cathodic and anodic phases.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the first pulse phase after
delay_dur
ms.stim_dur (float, optional, default:) –
2*phase_dur+interphase_dur+delay_dur
Total stimulus duration (ms). Zeros will be inserted at the end of the stimulus to make the stimulus 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.
Added in version 0.7.
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- property shape
Data container shape
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- class pulse2percept.stimuli.BiphasicPulseTrain(freq, amp, phase_dur, interphase_dur=0, delay_dur=0, n_pulses=None, stim_dur=1000.0, cathodic_first=True, electrode=None, metadata=None)[source]
Symmetric biphasic pulse train
A train of symmetric biphasic pulses.
Added in version 0.6.
- Parameters:
freq (float) – Pulse train frequency (Hz).
amp (float) – Current amplitude (uA). Negative currents: cathodic, positive: anodic. The sign will be converted automatically depending on
cathodic_first
.phase_dur (float) – Duration (ms) of the cathodic/anodic phase.
interphase_dur (float, optional, default: 0) – Duration (ms) of the gap between cathodic and anodic phases.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the first pulse phase after
delay_dur
ms.n_pulses (int) – Number of pulses requested in the pulse train. If None, the entire stimulation window (
stim_dur
) is filled.stim_dur (float, optional, default: 1000 ms) – Total stimulus duration (ms). The pulse train will be trimmed to make the stimulus last
stim_dur
ms overall.cathodic_first (bool, optional, default: True) – If True, will deliver the cathodic pulse phase before the anodic one.
electrode ({ int | string }, optional, default: 0) – Optionally, you can provide your own electrode name.
metadata (dict) – A dictionary of meta-data
Notes
Each cycle (“window”) of the pulse train consists of a symmetric biphasic pulse, created with
BiphasicPulse
.The order and sign of the two phases (cathodic/anodic) of each pulse in the train is automatically adjusted depending on the
cathodic_first
flag.A pulse train will be considered “charge-balanced” if its net current is smaller than 10 picoamps.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- property shape
Data container shape
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- class pulse2percept.stimuli.BiphasicTripletTrain(freq, amp, phase_dur, interphase_dur=0, interpulse_dur=0, delay_dur=0, n_pulses=None, stim_dur=1000.0, cathodic_first=True, electrode=None, metadata=None)[source]
Biphasic pulse triplets
A train of symmetric biphasic pulse triplets.
Added in version 0.6.
- Parameters:
freq (float) – Pulse train frequency (Hz).
amp (float) – Current amplitude (uA). Negative currents: cathodic, positive: anodic. The sign will be converted automatically depending on
cathodic_first
.phase_dur (float) – Duration (ms) of the cathodic/anodic phase.
interphase_dur (float, optional, default: 0) – Duration (ms) of the gap between cathodic and anodic phases.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the first pulse phase after
delay_dur
ms.interpulse_dur (float, optional, default: 0) – Delay duration (ms) between each biphasic pulse within the train. Note, this delay is also applied after the third biphasic pulse
n_pulses (int) – Number of pulses requested in the pulse train. If None, the entire stimulation window (
stim_dur
) is filled.stim_dur (float, optional, default: 1000 ms) – Total stimulus duration (ms). The pulse train will be trimmed to make the stimulus last
stim_dur
ms overall.cathodic_first (bool, optional, default: True) – If True, will deliver the cathodic pulse phase before the anodic one.
electrode ({ int | string }, optional, default: 0) – Optionally, you can provide your own electrode name.
metadata (dict) – A dictionary of meta-data
Notes
Each cycle (“window”) of the pulse train consists of three biphasic pulses, created with
BiphasicPulse
.The order and sign of the two phases (cathodic/anodic) of each pulse in the train is automatically adjusted depending on the
cathodic_first
flag.A pulse train will be considered “charge-balanced” if its net current is smaller than 10 picoamps.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- property shape
Data container shape
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- class pulse2percept.stimuli.BostonTrain(resize=None, electrodes=None, as_gray=False, metadata=None)[source]
Boston Train sequence
Load the Boston subway sequence, consisting of 94 frames of 240x426x3 pixels each.
Added in version 0.7.
- Parameters:
resize ((height, width) or None) – A tuple specifying the desired height and the width of the video stimulus.
electrodes (int, string or list thereof; optional, default: None) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the (resized) video frame.
as_gray (bool, optional) – Flag whether to convert the image to grayscale. A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- 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.
Added in version 0.8.
- Parameters:
idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
[y0, x0]
and bottom-right corner[y1, x1]
(exclusive) of the rectangle to crop.idx_time (tuple (t0, t1)) – Frame indices defining the start
t0
and 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
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- encode(amp_range=(0, 50), pulse=None)[source]
Encode image using amplitude modulation
Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in
amp_range
.By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.
- Parameters:
amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto
min_amp
and the largest 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
- 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
- invert()[source]
Invert the gray levels of the video
- Returns:
stim (VideoStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- play(fps=None, repeat=True, annotate_time=True, ax=None)[source]
Animate the video as HTML with JavaScript
The video will be played in an interactive player in IPython or Jupyter Notebook.
- Parameters:
fps (float or None) – If None, uses the video’s time axis. Not supported for non-homogeneous time axis.
repeat (bool, optional) – Whether the animation should repeat when the sequence of frames is completed.
annotate_time (bool, optional) – If True, the time of the frame will be shown as t = X ms in the title of the panel.
ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object
- Returns:
ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- 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
- property shape
Data container shape
- shift(shift_cols, shift_rows)[source]
Shift the image foreground
This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.
- Parameters:
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the shifted image
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- trim(tol=0, electrodes=None)[source]
Remove any black border around the video
Added in version 0.7.
- Parameters:
tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in each frame of the trimmed video.
- Returns:
stim (VideoStimulus) – A copy of the stimulus object with trimmed borders.
- class pulse2percept.stimuli.GirlPool(resize=None, electrodes=None, as_gray=False, metadata=None)[source]
A girl jumping into a swimming pool
Load the “girl jumping in a pool” sequence, consisting of 91 frames of 240x426x3 pixels each.
Added in version 0.9.
- Parameters:
resize ((height, width) or None) – A tuple specifying the desired height and the width of the video stimulus.
electrodes (int, string or list thereof; optional, default: None) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the (resized) video frame.
as_gray (bool, optional) – Flag whether to convert the image to grayscale. A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- 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.
Added in version 0.8.
- Parameters:
idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
[y0, x0]
and bottom-right corner[y1, x1]
(exclusive) of the rectangle to crop.idx_time (tuple (t0, t1)) – Frame indices defining the start
t0
and 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
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- encode(amp_range=(0, 50), pulse=None)[source]
Encode image using amplitude modulation
Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in
amp_range
.By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.
- Parameters:
amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto
min_amp
and the largest 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
- 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
- invert()[source]
Invert the gray levels of the video
- Returns:
stim (VideoStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- play(fps=None, repeat=True, annotate_time=True, ax=None)[source]
Animate the video as HTML with JavaScript
The video will be played in an interactive player in IPython or Jupyter Notebook.
- Parameters:
fps (float or None) – If None, uses the video’s time axis. Not supported for non-homogeneous time axis.
repeat (bool, optional) – Whether the animation should repeat when the sequence of frames is completed.
annotate_time (bool, optional) – If True, the time of the frame will be shown as t = X ms in the title of the panel.
ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object
- Returns:
ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- 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
- property shape
Data container shape
- shift(shift_cols, shift_rows)[source]
Shift the image foreground
This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.
- Parameters:
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the shifted image
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- trim(tol=0, electrodes=None)[source]
Remove any black border around the video
Added in version 0.7.
- Parameters:
tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in each frame of the trimmed video.
- Returns:
stim (VideoStimulus) – A copy of the stimulus object with trimmed borders.
- class pulse2percept.stimuli.GratingStimulus(shape, direction=0, spatial_freq=0.1, temporal_freq=0.001, phase=0, contrast=1, time=None, mask=None, electrodes=None, metadata=None)[source]
Drifting sinusoidal grating
A drifting sinusoidal grating of a given spatial and temporal frequency.
Added in version 0.7.
- Parameters:
shape ((height, width)) – A tuple specifying the desired height (pixels) and the width (pixels) of the grating stimulus.
direction (scalar in [0, 360) degrees, optional) – Drift direction of the grating.
spatial_freq (scalar (cycles/pixel), optional) – Spatial frequency of the grating in cycles per pixel
temporal_freq (scalar (cycles/frame), optional) – Temporal frequency of the grating in cycles per frame
phase (scalar (degrees), optional) – The initial phase of the grating in degrees
contrast (scalar in [0, 1], optional) – Stimulus contrast between 0 and 1
time (scalar, array-like, or None; optional) –
The time points at which to evaluate the drifting grating:
If a scalar,
time
is interpreted as the end time (in milliseconds) of a time series with 50 Hz frame rate.If array-like,
time
is interpreted as the exact time points (in milliseconds) at which to draw the grating (end point included).If None,
time
defaults to a 1-second time series at 50 Hz frame rate (end point included).
mask ({'gauss', 'circle', None}) –
Stimulus mask:
”gauss”: a 2D Gaussian designed such that the border of the image lies at 3 standard deviations
”circle”: a circle that fits into the
shape
of the stimulusNone: no mask
electrodes (int, string or list thereof; optional, default: None) – Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- 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.
Added in version 0.8.
- Parameters:
idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
[y0, x0]
and bottom-right corner[y1, x1]
(exclusive) of the rectangle to crop.idx_time (tuple (t0, t1)) – Frame indices defining the start
t0
and 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
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- encode(amp_range=(0, 50), pulse=None)[source]
Encode image using amplitude modulation
Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in
amp_range
.By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.
- Parameters:
amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto
min_amp
and the largest 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
- 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
- invert()[source]
Invert the gray levels of the video
- Returns:
stim (VideoStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- play(fps=None, repeat=True, annotate_time=True, ax=None)[source]
Animate the video as HTML with JavaScript
The video will be played in an interactive player in IPython or Jupyter Notebook.
- Parameters:
fps (float or None) – If None, uses the video’s time axis. Not supported for non-homogeneous time axis.
repeat (bool, optional) – Whether the animation should repeat when the sequence of frames is completed.
annotate_time (bool, optional) – If True, the time of the frame will be shown as t = X ms in the title of the panel.
ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object
- Returns:
ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- 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
- property shape
Data container shape
- shift(shift_cols, shift_rows)[source]
Shift the image foreground
This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.
- Parameters:
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the shifted image
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- trim(tol=0, electrodes=None)[source]
Remove any black border around the video
Added in version 0.7.
- Parameters:
tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in each frame of the trimmed video.
- Returns:
stim (VideoStimulus) – A copy of the stimulus object with trimmed borders.
- class pulse2percept.stimuli.ImageStimulus(source, resize=None, as_gray=False, electrodes=None, metadata=None, compress=False)[source]
A stimulus made from an image, where each pixel gets assigned to an electrode, and grayscale values in the range [0, 255] get converted to activation values in the range [0, 1].
See also
Basic Concepts > Electrical Stimuli <topics-stimuli>
Added in version 0.7.
- Parameters:
source (str) – Path to image file. Supported image types include JPG, PNG, and TIF; and are inferred from the file ending. Use
VideoStimulus
for GIFs.resize ((height, width) or None, optional) – Shape of the resized image. If one of the dimensions is set to -1, its value will be inferred by keeping a constant aspect ratio.
as_gray (bool, optional) – Flag whether to convert the image to grayscale. A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the (resized) image.
metadata (dict, optional) – Additional stimulus metadata can be stored in a dictionary.
compress (bool, optional) – If True, will remove pixels with 0 grayscale value.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- 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.
Added in version 0.8.
- Parameters:
idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
[y0, x0]
and bottom-right corner[y1, x1]
(exclusive) of the rectangle to crop.left (int) – Number of columns to crop from the left
right (int) – Number of columns to crop from the right
top (int) – Number of rows to crop from the top
bottom (int) – Number of rows to crop from the bottom
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the cropped image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the cropped image
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- encode(amp_range=(0, 50), pulse=None)[source]
Encode image using amplitude modulation
Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in
amp_range
.By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.
- Parameters:
amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto
min_amp
and the largest 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
- filter(filt, **kwargs)[source]
Filter the image
- Parameters:
filt (str) –
Image filter. Additional parameters can be passed as keyword arguments. The following filters are supported:
’sobel’: Edge filter the image using the Sobel filter.
’scharr’: Edge filter the image using the `Scharr filter`_.
’canny’: Edge filter the image using the Canny algorithm. You can also specify
sigma
,low_threshold
,high_threshold
,mask
, anduse_quantiles
.’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter
filter (.. _Scharr)
filter
algorithm (.. _Canny)
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with the filtered image
- invert()[source]
Invert the gray levels of the image
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(ax=None, **kwargs)[source]
Plot the stimulus
- Parameters:
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
ax (matplotlib.axes.Axes) – Returns the axes with the plot on it
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- resize(shape, electrodes=None)[source]
Resize the image
- Parameters:
shape ((rows, cols)) – Shape of the resized image
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the grayscale image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the resized image
- rgb2gray(electrodes=None)[source]
Convert the image to grayscale
- Parameters:
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the grayscale image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].
Notes
A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
- rotate(angle, mode='constant')[source]
Rotate the image
- Parameters:
angle (float) – Angle by which to rotate the image (degrees). Positive: counter-clockwise, negative: clockwise
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the rotated image
- save(fname, vmin=0, vmax=None)[source]
Save the stimulus as an image
- Parameters:
fname (str) – The name of the image file to be created. Image type will be inferred from the file extension.
- scale(scaling_factor)[source]
Scale the image foreground
This function scales the image foreground (excluding black pixels) by a factor.
- Parameters:
scaling_factor (float) – Factory by which to scale the image
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the scaled image
- property shape
Data container shape
- shift(shift_cols, shift_rows)[source]
Shift the image foreground
This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.
- Parameters:
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the shifted image
- threshold(thresh, **kwargs)[source]
Threshold the image
- Parameters:
If a float in [0,1] is provided, pixels whose grayscale value is above said threshold will be white, others black.
A number of additional methods are supported:
’mean’: Threshold image based on the mean of grayscale values.
- ’minimum’: Threshold image based on the minimum method, where
the histogram of the input image is computed and smoothed until there are only two maxima.
- ’local’: Threshold image based on `local pixel neighborhood`_.
Requires
block_size
: odd number of pixels in the neighborhood.
’otsu’: `Otsu's method`_
- ’isodata’: `ISODATA method`_, also known as the Ridler-Calvard
method or intermeans.
neighborhood (.. _local pixel)
method (.. _ISODATA)
method
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with two gray levels 0.0 and 1.0
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- trim(tol=0, electrodes=None)[source]
Remove any black border around the image
Added in version 0.7.
- Parameters:
tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the trimmed image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with trimmed borders.
- class pulse2percept.stimuli.LogoBVL(resize=None, electrodes=None, metadata=None, as_gray=False)[source]
Bionic Vision Lab (BVL) logo
Load the 576x720x4 Bionic Vision Lab (BVL) logo.
Added in version 0.7.
- Parameters:
resize ((height, width) or None, optional) – A tuple specifying the desired height and the width of the image stimulus.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the (resized) image.
metadata (dict, optional) – Additional stimulus metadata can be stored in a dictionary.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- 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.
Added in version 0.8.
- Parameters:
idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
[y0, x0]
and bottom-right corner[y1, x1]
(exclusive) of the rectangle to crop.left (int) – Number of columns to crop from the left
right (int) – Number of columns to crop from the right
top (int) – Number of rows to crop from the top
bottom (int) – Number of rows to crop from the bottom
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the cropped image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the cropped image
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- encode(amp_range=(0, 50), pulse=None)[source]
Encode image using amplitude modulation
Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in
amp_range
.By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.
- Parameters:
amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto
min_amp
and the largest 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
- filter(filt, **kwargs)[source]
Filter the image
- Parameters:
filt (str) –
Image filter. Additional parameters can be passed as keyword arguments. The following filters are supported:
’sobel’: Edge filter the image using the Sobel filter.
’scharr’: Edge filter the image using the `Scharr filter`_.
’canny’: Edge filter the image using the Canny algorithm. You can also specify
sigma
,low_threshold
,high_threshold
,mask
, anduse_quantiles
.’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter
filter (.. _Scharr)
filter
algorithm (.. _Canny)
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with the filtered image
- invert()[source]
Invert the gray levels of the image
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(ax=None, **kwargs)[source]
Plot the stimulus
- Parameters:
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
ax (matplotlib.axes.Axes) – Returns the axes with the plot on it
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- resize(shape, electrodes=None)[source]
Resize the image
- Parameters:
shape ((rows, cols)) – Shape of the resized image
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the grayscale image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the resized image
- rgb2gray(electrodes=None)[source]
Convert the image to grayscale
- Parameters:
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the grayscale image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].
Notes
A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
- rotate(angle, mode='constant')[source]
Rotate the image
- Parameters:
angle (float) – Angle by which to rotate the image (degrees). Positive: counter-clockwise, negative: clockwise
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the rotated image
- save(fname, vmin=0, vmax=None)[source]
Save the stimulus as an image
- Parameters:
fname (str) – The name of the image file to be created. Image type will be inferred from the file extension.
- scale(scaling_factor)[source]
Scale the image foreground
This function scales the image foreground (excluding black pixels) by a factor.
- Parameters:
scaling_factor (float) – Factory by which to scale the image
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the scaled image
- property shape
Data container shape
- shift(shift_cols, shift_rows)[source]
Shift the image foreground
This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.
- Parameters:
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the shifted image
- threshold(thresh, **kwargs)[source]
Threshold the image
- Parameters:
If a float in [0,1] is provided, pixels whose grayscale value is above said threshold will be white, others black.
A number of additional methods are supported:
’mean’: Threshold image based on the mean of grayscale values.
- ’minimum’: Threshold image based on the minimum method, where
the histogram of the input image is computed and smoothed until there are only two maxima.
- ’local’: Threshold image based on `local pixel neighborhood`_.
Requires
block_size
: odd number of pixels in the neighborhood.
’otsu’: `Otsu's method`_
- ’isodata’: `ISODATA method`_, also known as the Ridler-Calvard
method or intermeans.
neighborhood (.. _local pixel)
method (.. _ISODATA)
method
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with two gray levels 0.0 and 1.0
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- trim(tol=0, electrodes=None)[source]
Remove any black border around the image
Added in version 0.7.
- Parameters:
tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the trimmed image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with trimmed borders.
- class pulse2percept.stimuli.LogoUCSB(resize=None, electrodes=None, metadata=None)[source]
UCSB logo
Load a 324x727 white-on-black logo of the University of California, Santa Barbara.
Added in version 0.7.
- Parameters:
resize ((height, width) or None, optional) – A tuple specifying the desired height and the width of the image stimulus.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the (resized) image.
metadata (dict, optional) – Additional stimulus metadata can be stored in a dictionary.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- 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.
Added in version 0.8.
- Parameters:
idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
[y0, x0]
and bottom-right corner[y1, x1]
(exclusive) of the rectangle to crop.left (int) – Number of columns to crop from the left
right (int) – Number of columns to crop from the right
top (int) – Number of rows to crop from the top
bottom (int) – Number of rows to crop from the bottom
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the cropped image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the cropped image
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- encode(amp_range=(0, 50), pulse=None)[source]
Encode image using amplitude modulation
Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in
amp_range
.By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.
- Parameters:
amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto
min_amp
and the largest 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
- filter(filt, **kwargs)[source]
Filter the image
- Parameters:
filt (str) –
Image filter. Additional parameters can be passed as keyword arguments. The following filters are supported:
’sobel’: Edge filter the image using the Sobel filter.
’scharr’: Edge filter the image using the `Scharr filter`_.
’canny’: Edge filter the image using the Canny algorithm. You can also specify
sigma
,low_threshold
,high_threshold
,mask
, anduse_quantiles
.’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter
filter (.. _Scharr)
filter
algorithm (.. _Canny)
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with the filtered image
- invert()[source]
Invert the gray levels of the image
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(ax=None, **kwargs)[source]
Plot the stimulus
- Parameters:
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
ax (matplotlib.axes.Axes) – Returns the axes with the plot on it
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- resize(shape, electrodes=None)[source]
Resize the image
- Parameters:
shape ((rows, cols)) – Shape of the resized image
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the grayscale image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the resized image
- rgb2gray(electrodes=None)[source]
Convert the image to grayscale
- Parameters:
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the grayscale image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].
Notes
A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
- rotate(angle, mode='constant')[source]
Rotate the image
- Parameters:
angle (float) – Angle by which to rotate the image (degrees). Positive: counter-clockwise, negative: clockwise
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the rotated image
- save(fname, vmin=0, vmax=None)[source]
Save the stimulus as an image
- Parameters:
fname (str) – The name of the image file to be created. Image type will be inferred from the file extension.
- scale(scaling_factor)[source]
Scale the image foreground
This function scales the image foreground (excluding black pixels) by a factor.
- Parameters:
scaling_factor (float) – Factory by which to scale the image
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the scaled image
- property shape
Data container shape
- shift(shift_cols, shift_rows)[source]
Shift the image foreground
This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.
- Parameters:
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the shifted image
- threshold(thresh, **kwargs)[source]
Threshold the image
- Parameters:
If a float in [0,1] is provided, pixels whose grayscale value is above said threshold will be white, others black.
A number of additional methods are supported:
’mean’: Threshold image based on the mean of grayscale values.
- ’minimum’: Threshold image based on the minimum method, where
the histogram of the input image is computed and smoothed until there are only two maxima.
- ’local’: Threshold image based on `local pixel neighborhood`_.
Requires
block_size
: odd number of pixels in the neighborhood.
’otsu’: `Otsu's method`_
- ’isodata’: `ISODATA method`_, also known as the Ridler-Calvard
method or intermeans.
neighborhood (.. _local pixel)
method (.. _ISODATA)
method
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with two gray levels 0.0 and 1.0
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- trim(tol=0, electrodes=None)[source]
Remove any black border around the image
Added in version 0.7.
- Parameters:
tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the trimmed image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with trimmed borders.
- class pulse2percept.stimuli.MonophasicPulse(amp, phase_dur, delay_dur=0, stim_dur=None, electrode=None)[source]
Monophasic pulse
A simple stimulus consisting of a single monophasic pulse (either cathodic/negative or anodic/positive).
Added in version 0.6.
- Parameters:
amp (float) – Current amplitude (uA). Negative currents: cathodic, positive: anodic.
phase_dur (float) – Duration (ms) of the cathodic or anodic phase.
delay_dur (float) – Delay duration (ms). Zeros will be inserted at the beginning of the stimulus to deliver the pulse after
delay_dur
ms.stim_dur (float, optional) – Total stimulus duration (ms). Zeros will be inserted at the end of the stimulus to make the stimulus last
stim_dur
ms overall.electrode ({ int | string }, optional) – Optionally, you can provide your own electrode name.
Notes
The sign of
amp
will determine whether the pulse is cathodic (negative current) or anodic (positive current).A regular monophasic pulse is not considered “charge-balanced”. However, if
amp
is small enough, the pulse can be considered “charge-balanced” if its net current is smaller than 10 picoamps.
Examples
A single cathodic pulse (1ms phase duration at 20uA) delivered after 2ms and embedded in a stimulus that lasts 10ms overall:
>>> from pulse2percept.stimuli import MonophasicPulse >>> pulse = MonophasicPulse(-20, 1, delay_dur=2, stim_dur=10)
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- property shape
Data container shape
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- class pulse2percept.stimuli.PulseTrain(freq, pulse, n_pulses=None, stim_dur=1000.0, electrode=None, metadata=None)[source]
Generic pulse train
Can be used to concatenate single pulses into a pulse train.
Added in version 0.6.
- Parameters:
freq (float) – Pulse train frequency (Hz).
pulse (
Stimulus
) – A Stimulus object containing a single pulse that will be concatenated.n_pulses (int) – Number of pulses requested in the pulse train. If None, the entire stimulation window (
stim_dur
) is filled.stim_dur (float, optional) – Total stimulus duration (ms). The pulse train will be trimmed to make the stimulus last
stim_dur
ms overall.electrode ({ int | string }, optional) – Optionally, you can provide your own electrode name.
metadata (dict) – A dictionary of meta-data
Notes
If the pulse train frequency does not exactly divide
stim_dur
, the number of pulses will be rounded down. For example, when trying to fit a 11 Hz pulse train into a 100 ms window, there will be 9 pulses.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- property shape
Data container shape
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- class pulse2percept.stimuli.SnellenChart(resize=None, show_annotations=True, row=None, electrodes=None, metadata=None)[source]
Snellen chart
Load the 1348x840 Snellen chart commonly used to measure visual acuity.
Added in version 0.7.
- Parameters:
resize ((height, width) or None, optional) – A tuple specifying the desired height and the width of the image stimulus.
show_annotations ({True, False}, optional) – If True, show the full Snellen chart including annotations of the rows and corresponding acuity measures.
row (None, optional) – Select a single row (between 1 and 11) from the Snellen chart. For example, row 1 corresponds to 20/200, row 2 to 20/100.
electrodes (int, string or list thereof; optional, default: None) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the (resized) image.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- 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.
Added in version 0.8.
- Parameters:
idx_rect (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
[y0, x0]
and bottom-right corner[y1, x1]
(exclusive) of the rectangle to crop.left (int) – Number of columns to crop from the left
right (int) – Number of columns to crop from the right
top (int) – Number of rows to crop from the top
bottom (int) – Number of rows to crop from the bottom
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the cropped image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the cropped image
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- encode(amp_range=(0, 50), pulse=None)[source]
Encode image using amplitude modulation
Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in
amp_range
.By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.
- Parameters:
amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto
min_amp
and the largest 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
- filter(filt, **kwargs)[source]
Filter the image
- Parameters:
filt (str) –
Image filter. Additional parameters can be passed as keyword arguments. The following filters are supported:
’sobel’: Edge filter the image using the Sobel filter.
’scharr’: Edge filter the image using the `Scharr filter`_.
’canny’: Edge filter the image using the Canny algorithm. You can also specify
sigma
,low_threshold
,high_threshold
,mask
, anduse_quantiles
.’median’: Return local median of the image.
**kwargs – Additional parameters passed to the filter
filter (.. _Scharr)
filter
algorithm (.. _Canny)
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with the filtered image
- invert()[source]
Invert the gray levels of the image
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(ax=None, **kwargs)[source]
Plot the stimulus
- Parameters:
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
ax (matplotlib.axes.Axes) – Returns the axes with the plot on it
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- resize(shape, electrodes=None)[source]
Resize the image
- Parameters:
shape ((rows, cols)) – Shape of the resized image
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the grayscale image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the resized image
- rgb2gray(electrodes=None)[source]
Convert the image to grayscale
- Parameters:
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the grayscale image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].
Notes
A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
- rotate(angle, mode='constant')[source]
Rotate the image
- Parameters:
angle (float) – Angle by which to rotate the image (degrees). Positive: counter-clockwise, negative: clockwise
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the rotated image
- save(fname, vmin=0, vmax=None)[source]
Save the stimulus as an image
- Parameters:
fname (str) – The name of the image file to be created. Image type will be inferred from the file extension.
- scale(scaling_factor)[source]
Scale the image foreground
This function scales the image foreground (excluding black pixels) by a factor.
- Parameters:
scaling_factor (float) – Factory by which to scale the image
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the scaled image
- property shape
Data container shape
- shift(shift_cols, shift_rows)[source]
Shift the image foreground
This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.
- Parameters:
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the shifted image
- threshold(thresh, **kwargs)[source]
Threshold the image
- Parameters:
If a float in [0,1] is provided, pixels whose grayscale value is above said threshold will be white, others black.
A number of additional methods are supported:
’mean’: Threshold image based on the mean of grayscale values.
- ’minimum’: Threshold image based on the minimum method, where
the histogram of the input image is computed and smoothed until there are only two maxima.
- ’local’: Threshold image based on `local pixel neighborhood`_.
Requires
block_size
: odd number of pixels in the neighborhood.
’otsu’: `Otsu's method`_
- ’isodata’: `ISODATA method`_, also known as the Ridler-Calvard
method or intermeans.
neighborhood (.. _local pixel)
method (.. _ISODATA)
method
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with two gray levels 0.0 and 1.0
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- trim(tol=0, electrodes=None)[source]
Remove any black border around the image
Added in version 0.7.
- Parameters:
tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the trimmed image.
- Returns:
stim (ImageStimulus) – A copy of the stimulus object with trimmed borders.
- class pulse2percept.stimuli.Stimulus(source, electrodes=None, time=None, metadata=None, compress=False)[source]
A stimulus is comprised of a labeled 2D NumPy array that contains the data, where the rows denote electrodes and the columns denote points in time. A stimulus can be created from a variety of source types (e.g., scalars, lists, NumPy arrays, and dictionaries).
See also
Basic Concepts > Electrical Stimuli <topics-stimuli>
Added in version 0.6.
- Parameters:
source (source type) –
A valid source type is one of the following:
Scalar value: interpreted as the current amplitude delivered to a single electrode (no time component).
- NumPy array:
Nx1 array: interpreted as N current amplitudes delivered to N electrodes (no time component).
NxM array: interpreted as N electrodes each receiving M current amplitudes in time.
In addition, you can also pass a collection of source types. Each element must be a valid source type for a single electrode (e.g., scalar, 1-D array,
Stimulus
).List or tuple: List elements will be assigned to electrodes in order.
Dictionary: Dictionary keys are used to address electrodes by name.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be extracted from the source type (e.g., the keys from a dictionary). If a scalar or NumPy array is passed, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of electrodes extracted from the source type (i.e., N).
time (int, float or list thereof; optional) –
Optionally, you can provide the time points of the source data. If none are given, time steps will be numbered 0..M.
Note
The number of time points provided must match the number of time points extracted from the source type (i.e., M). Stimuli created from scalars or 1-D NumPy arrays will have no time componenet, in which case you cannot provide your own time points.
metadata (dict, optional) – Additional stimulus metadata can be stored in a dictionary.
compress (bool, optional) –
If True, will compress the source data in two ways:
Remove electrodes with all-zero activation.
Retain only the time points at which the stimulus changes.
For example, in a pulse train, only the signal edges are saved. This drastically reduces the memory footprint of the stimulus.
Notes
Depending on the source type, a stimulus might have a time component or not (e.g., scalars: time=None).
You can access the stimulus applied to electrode
e
at 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] 3.45...
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- property shape
Data container shape
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- class pulse2percept.stimuli.VideoStimulus(source, format=None, resize=None, as_gray=False, electrodes=None, time=None, metadata=None, compress=False)[source]
A stimulus made from a movie file, where each pixel gets assigned to an electrode, and grayscale values in the range [0, 255] get assigned to activation values in the range [0, 1].
The frame rate of the movie is used to infer the time points at which to stimulate.
See also
Basic Concepts > Electrical Stimuli <topics-stimuli>
Added in version 0.7.
- Parameters:
source (str) –
Path to video file. Supported file types include MP4, AVI, MOV, and GIF; and are inferred from the file ending. If the file does not have a proper file ending, specify the file type via
format
.Alternatively, pass a <rows x columns x channels x frames> NumPy array or another
VideoStimulus
object.format (str) – A video format string supported by imageio, such as ‘MP4’, ‘AVI’, or ‘MOV’. Use if the file type cannot be inferred from
source
. For a full list of supported formats, see https://imageio.readthedocs.io/en/stable/formats.html.resize ((height, width) or None, optional, default: None) – A tuple specifying the desired height and the width of each video frame
as_gray (bool, optional) – Flag whether to convert the image to grayscale. A four-channel image is interpreted as RGBA (e.g., a PNG), and the alpha channel will be blended with the color black.
electrodes (int, string or list thereof; optional, default: None) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the (resized) image.
metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.
compress (bool, optional, default: False) – If True, will compress the source data in two ways: * Remove electrodes with all-zero activation. * Retain only the time points at which the stimulus changes.
- append(other)[source]
Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
Added in version 0.7.
- 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.
Added in version 0.8.
- Parameters:
idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
[y0, x0]
and bottom-right corner[y1, x1]
(exclusive) of the rectangle to crop.idx_time (tuple (t0, t1)) – Frame indices defining the start
t0
and 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
- property data
Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
- property dt
Sampling time step (ms)
Defines the duration of the signal edge transitions.
Added in version 0.7.
- property duration
Stimulus duration (ms)
- property electrodes
Electrode names A list of electrode names, corresponding to the rows in the data container.
- encode(amp_range=(0, 50), pulse=None)[source]
Encode image using amplitude modulation
Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in
amp_range
.By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.
- Parameters:
amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s gray levels will be scaled such that the smallest value is mapped onto
min_amp
and the largest 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
- 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
- invert()[source]
Invert the gray levels of the video
- Returns:
stim (VideoStimulus) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].
- property is_charge_balanced
Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
- property is_compressed
Flag indicating whether the stimulus has been compressed
- play(fps=None, repeat=True, annotate_time=True, ax=None)[source]
Animate the video as HTML with JavaScript
The video will be played in an interactive player in IPython or Jupyter Notebook.
- Parameters:
fps (float or None) – If None, uses the video’s time axis. Not supported for non-homogeneous time axis.
repeat (bool, optional) – Whether the animation should repeat when the sequence of frames is completed.
annotate_time (bool, optional) – If True, the time of the frame will be shown as t = X ms in the title of the panel.
ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object
- Returns:
ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.
- plot(electrodes=None, time=None, fmt='k-', ax=None)[source]
Plot the stimulus
Added in version 0.7.
- Parameters:
electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
- Returns:
axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
- remove(electrodes)[source]
Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
Added in version 0.8.
- 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
- property shape
Data container shape
- shift(shift_cols, shift_rows)[source]
Shift the image foreground
This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.
- Parameters:
- Returns:
stim (ImageStimulus) – A copy of the stimulus object containing the shifted image
- property time
Time steps A list of time steps, corresponding to the columns in the data container.
- trim(tol=0, electrodes=None)[source]
Remove any black border around the video
Added in version 0.7.
- Parameters:
tol (float) – Any pixels with gray levels > tol will be trimmed.
electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in each frame of the trimmed video.
- Returns:
stim (VideoStimulus) – A copy of the stimulus object with trimmed borders.