pulse2percept.stimuli.psychophysics¶
Classes
BarStimulus (shape[, direction, speed, …]) |
Drifting bar |
GratingStimulus (shape[, direction, …]) |
Drifting sinusoidal grating |
-
class
pulse2percept.stimuli.psychophysics.
BarStimulus
(shape, direction=0, speed=0.1, bar_width=1, edge_width=3, px_btw_bars=None, start_pos=0, contrast=1, time=None, mask=None, electrodes=None, metadata=None)[source]¶ Drifting bar
A drifting bar stimulus.
New in version 0.7.
Parameters: - shape ((height, width)) – A tuple specifying the desired height (pixels) and the width (pixels) of the grating stimulus.
- direction (scalar in [0, 360) degrees, optional) – Drift direction of the bar.
- speed (scalar in pixels/frame, optional) – Drift speed of the bar.
- bar_width (scalar in pixels, optional) – The width of the center of the bar.
- edge_width (scalar in pixels, optional) – The width of the cosine edges of the bar. An edge of width
edge_width
will be tacked onto both sides of the bar, so the total width will bebar_width
+ 2 *edge_width
- px_btw_bars (scalar in pixels, optional) – The number of pixels between the bars in the stimulus.
- start_pos (scalar in pixels, optional) – The starting position of the first bar. The coordinate system is a line lying along the direction of the bar motion passing through the center of the stimulus. The point 0 is the center of the stimulus.
- contrast (scalar in [0, 1], optional) – Stimulus contrast between 0 and 1
- time (scalar, array-like, or None; optional) –
The time points at which to evaluate the drifting bar:
- If a scalar,
time
is interpreted as the end time (in milliseconds) of a time series with 50 Hz frame rate. - If array-like,
time
is interpreted as the exact time points (in milliseconds) at which to draw the bar (end point included). - If None,
time
defaults to a 1-second time series at 50 Hz frame rate (end point included).
- If a scalar,
- mask ({'gauss', 'circle', None}) –
Stimulus mask:
- ”gauss”: a 2D Gaussian designed such that the border of the image lies at 3 standard deviations
- ”circle”: a circle that fits into the
shape
of the stimulus - None: no mask
- electrodes (int, string or list thereof; optional, default: None) – Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
- metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.
-
append
(other)[source]¶ Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
New in version 0.7.
Parameters: other ( Stimulus
) – Another stimulus with matching electrodes.Returns: comb ( Stimulus
) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.
-
apply
(func, *args, **kwargs)[source]¶ Apply a function to each frame of the video
Parameters: - func (function) – The function to apply to each frame in the video. Must accept a 2D or 3D image and return an image with the same dimensions
- *args – Additional positional arguments passed to the function
- **kwargs – Additional keyword arguments passed to the function
Returns: stim (
ImageStimulus
) – A copy of the stimulus object with the new image
-
center
(loc=None)[source]¶ Center the image foreground
This function shifts the center of mass (CoM) to the image center.
Parameters: loc ((col, row), optional) – The pixel location at which to center the CoM. By default, shifts the CoM to the image center. Returns: stim ( ImageStimulus
) – A copy of the stimulus object containing the centered image
-
crop
(idx_space=None, idx_time=None, left=0, right=0, top=0, bottom=0, front=0, back=0, electrodes=None)[source]¶ Crop the video
This method maps a rectangle (defined by two corners) from each video frame to a rectangle of the given size. Similarly, the video can be shortened to a specified range of frames.
Alternatively, this method can be used to crop a number of columns either from the left or the right of the video frame, or a number of rows either from the top or the bottom, or a number of frames from the front (beginning) or back (end) of the video.
New in version 0.8.
Parameters: - idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
[y0, x0]
and bottom-right corner[y1, x1]
(exclusive) of the rectangle to crop. - idx_time (tuple (t0, t1)) – Frame indices defining the start
t0
and endt1
of the cropped video. - left (int) – Number of columns to crop from the left of each video frame
- right (int) – Number of columns to crop from the right of each video frame
- top (int) – Number of rows to crop from the top of each video frame
- bottom (int) – Number of rows to crop from the bottom of each video frame
- front (int) – Number of frames to crop from the front (beginning) of the video
- back (int) – Number of frames to crop from the back (end) of the video
- electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the cropped image.
Returns: stim (
VideoStimulus
) – A copy of the stimulus object containing the video- idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
-
data
¶ Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
electrodes
¶ Electrode names A list of electrode names, corresponding to the rows in the data container.
-
encode
(amp_range=(0, 50), pulse=None)[source]¶ Encode image using amplitude modulation
Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in
amp_range
.By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.
Parameters: - amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s
gray levels will be scaled such that the smallest value is mapped
onto
min_amp
and the largest ontomax_amp
. - pulse (
Stimulus
, optional) – A valid pulse or pulse train to be used for the encoding. If None given, aBiphasicPulse
(0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.
Returns: stim (
Stimulus
) – Encoded stimulus- amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s
gray levels will be scaled such that the smallest value is mapped
onto
-
filter
(filt, **kwargs)[source]¶ Filter each frame of the video
Parameters: - filt (str) –
Image filter that will be applied to every frame of the video. Additional parameters can be passed as keyword arguments. The following filters are supported:
- ’sobel’: Edge filter the image using the Sobel filter.
- ’scharr’: Edge filter the image using the Scarr filter.
- ’canny’: Edge filter the image using the Canny algorithm.
You can also specify
sigma
,low_threshold
,high_threshold
,mask
, anduse_quantiles
. - ’median’: Return local median of the image.
- **kwargs – Additional parameters passed to the filter
Returns: stim (
VideoStimulus
) – A copy of the stimulus object with the filtered image- filt (str) –
-
invert
()[source]¶ Invert the gray levels of the video
Returns: stim ( VideoStimulus
) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].
-
is_charge_balanced
¶ Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
-
is_compressed
¶ Flag indicating whether the stimulus has been compressed
-
play
(fps=None, repeat=True, annotate_time=True, ax=None)[source]¶ Animate the video as HTML with JavaScript
The video will be played in an interactive player in IPython or Jupyter Notebook.
Parameters: - fps (float or None) – If None, uses the video’s time axis. Not supported for non-homogeneous time axis.
- repeat (bool, optional) – Whether the animation should repeat when the sequence of frames is completed.
- annotate_time (bool, optional) – If True, the time of the frame will be shown as t = X ms in the title of the panel.
- ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object
Returns: ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.
-
plot
(electrodes=None, time=None, fmt='k-', ax=None)[source]¶ Plot the stimulus
New in version 0.7.
Parameters: - electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
- time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
- fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
- ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
Returns: axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
-
remove
(electrodes)[source]¶ Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
New in version 0.8.
Parameters: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.
-
resize
(shape, electrodes=None)[source]¶ Resize the video
Parameters: - shape ((rows, cols)) – Shape of each frame in the resized video. If one of the dimensions is set to -1, its value will be inferred by keeping a constant aspect ratio.
- electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the resized video.
Returns: stim (
VideoStimulus
) – A copy of the stimulus object containing the resized video
-
rgb2gray
(electrodes=None)[source]¶ Convert the video to grayscale
Parameters: electrodes (int, string or list thereof; optional) – Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the grayscale video.
Returns: stim ( VideoStimulus
) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].
-
rotate
(angle, mode='constant')[source]¶ Rotate each frame of the video
Parameters: angle (float) – Angle by which to rotate each video frame (degrees). Positive: counter-clockwise, negative: clockwise Returns: stim ( VideoStimulus
) – A copy of the stimulus object containing the rotated video
-
scale
(scaling_factor)[source]¶ Scale the image foreground
This function scales the image foreground (excluding black pixels) by a factor.
Parameters: scaling_factor (float) – Factory by which to scale the image Returns: stim ( ImageStimulus
) – A copy of the stimulus object containing the scaled image
-
shape
¶ Data container shape
-
shift
(shift_cols, shift_rows)[source]¶ Shift the image foreground
This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.
Parameters: Returns: stim (
ImageStimulus
) – A copy of the stimulus object containing the shifted image
-
time
¶ Time steps A list of time steps, corresponding to the columns in the data container.
-
trim
(tol=0, electrodes=None)[source]¶ Remove any black border around the video
New in version 0.7.
Parameters: - tol (float) – Any pixels with gray levels > tol will be trimmed.
- electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in each frame of the trimmed video.
Returns: stim (
VideoStimulus
) – A copy of the stimulus object with trimmed borders.
-
class
pulse2percept.stimuli.psychophysics.
GratingStimulus
(shape, direction=0, spatial_freq=0.1, temporal_freq=0.001, phase=0, contrast=1, time=None, mask=None, electrodes=None, metadata=None)[source]¶ Drifting sinusoidal grating
A drifting sinusoidal grating of a given spatial and temporal frequency.
New in version 0.7.
Parameters: - shape ((height, width)) – A tuple specifying the desired height (pixels) and the width (pixels) of the grating stimulus.
- direction (scalar in [0, 360) degrees, optional) – Drift direction of the grating.
- spatial_freq (scalar (cycles/pixel), optional) – Spatial frequency of the grating in cycles per pixel
- temporal_freq (scalar (cycles/frame), optional) – Temporal frequency of the grating in cycles per frame
- phase (scalar (degrees), optional) – The initial phase of the grating in degrees
- contrast (scalar in [0, 1], optional) – Stimulus contrast between 0 and 1
- time (scalar, array-like, or None; optional) –
The time points at which to evaluate the drifting grating:
- If a scalar,
time
is interpreted as the end time (in milliseconds) of a time series with 50 Hz frame rate. - If array-like,
time
is interpreted as the exact time points (in milliseconds) at which to draw the grating (end point included). - If None,
time
defaults to a 1-second time series at 50 Hz frame rate (end point included).
- If a scalar,
- mask ({'gauss', 'circle', None}) –
Stimulus mask:
- ”gauss”: a 2D Gaussian designed such that the border of the image lies at 3 standard deviations
- ”circle”: a circle that fits into the
shape
of the stimulus - None: no mask
- electrodes (int, string or list thereof; optional, default: None) – Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
- metadata (dict, optional, default: None) – Additional stimulus metadata can be stored in a dictionary.
-
append
(other)[source]¶ Append another stimulus
This method appends another stimulus (with matching electrodes) in time. The combined stimulus duration will be the sum of the two individual stimuli.
New in version 0.7.
Parameters: other ( Stimulus
) – Another stimulus with matching electrodes.Returns: comb ( Stimulus
) – A combined stimulus with the same number of electrodes and new stimulus duration equal to the sum of the two individual stimuli.
-
apply
(func, *args, **kwargs)[source]¶ Apply a function to each frame of the video
Parameters: - func (function) – The function to apply to each frame in the video. Must accept a 2D or 3D image and return an image with the same dimensions
- *args – Additional positional arguments passed to the function
- **kwargs – Additional keyword arguments passed to the function
Returns: stim (
ImageStimulus
) – A copy of the stimulus object with the new image
-
center
(loc=None)[source]¶ Center the image foreground
This function shifts the center of mass (CoM) to the image center.
Parameters: loc ((col, row), optional) – The pixel location at which to center the CoM. By default, shifts the CoM to the image center. Returns: stim ( ImageStimulus
) – A copy of the stimulus object containing the centered image
-
crop
(idx_space=None, idx_time=None, left=0, right=0, top=0, bottom=0, front=0, back=0, electrodes=None)[source]¶ Crop the video
This method maps a rectangle (defined by two corners) from each video frame to a rectangle of the given size. Similarly, the video can be shortened to a specified range of frames.
Alternatively, this method can be used to crop a number of columns either from the left or the right of the video frame, or a number of rows either from the top or the bottom, or a number of frames from the front (beginning) or back (end) of the video.
New in version 0.8.
Parameters: - idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
[y0, x0]
and bottom-right corner[y1, x1]
(exclusive) of the rectangle to crop. - idx_time (tuple (t0, t1)) – Frame indices defining the start
t0
and endt1
of the cropped video. - left (int) – Number of columns to crop from the left of each video frame
- right (int) – Number of columns to crop from the right of each video frame
- top (int) – Number of rows to crop from the top of each video frame
- bottom (int) – Number of rows to crop from the bottom of each video frame
- front (int) – Number of frames to crop from the front (beginning) of the video
- back (int) – Number of frames to crop from the back (end) of the video
- electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the cropped image.
Returns: stim (
VideoStimulus
) – A copy of the stimulus object containing the video- idx_space (4-tuple (y0, x0, y1, x1)) – Image indices of the top-left corner
-
data
¶ Stimulus data container A 2-D NumPy array that contains the stimulus data, where the rows denote electrodes and the columns denote points in time.
-
dt
¶ Sampling time step (ms)
Defines the duration of the signal edge transitions.
New in version 0.7.
-
duration
¶ Stimulus duration (ms)
-
electrodes
¶ Electrode names A list of electrode names, corresponding to the rows in the data container.
-
encode
(amp_range=(0, 50), pulse=None)[source]¶ Encode image using amplitude modulation
Encodes the image as a series of pulses, where the gray levels of the image are interpreted as the amplitude of a pulse with values in
amp_range
.By default, a single biphasic pulse is used for each pixel, with 0.46ms phase duration, and 500ms total stimulus duration.
Parameters: - amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s
gray levels will be scaled such that the smallest value is mapped
onto
min_amp
and the largest ontomax_amp
. - pulse (
Stimulus
, optional) – A valid pulse or pulse train to be used for the encoding. If None given, aBiphasicPulse
(0.46 ms phase duration, stimulus duration inferred from the movie frame rate) will be used.
Returns: stim (
Stimulus
) – Encoded stimulus- amp_range ((min_amp, max_amp)) – Range of amplitude values to use for the encoding. The image’s
gray levels will be scaled such that the smallest value is mapped
onto
-
filter
(filt, **kwargs)[source]¶ Filter each frame of the video
Parameters: - filt (str) –
Image filter that will be applied to every frame of the video. Additional parameters can be passed as keyword arguments. The following filters are supported:
- ’sobel’: Edge filter the image using the Sobel filter.
- ’scharr’: Edge filter the image using the Scarr filter.
- ’canny’: Edge filter the image using the Canny algorithm.
You can also specify
sigma
,low_threshold
,high_threshold
,mask
, anduse_quantiles
. - ’median’: Return local median of the image.
- **kwargs – Additional parameters passed to the filter
Returns: stim (
VideoStimulus
) – A copy of the stimulus object with the filtered image- filt (str) –
-
invert
()[source]¶ Invert the gray levels of the video
Returns: stim ( VideoStimulus
) – A copy of the stimulus object with all grayscale values inverted in the range [0, 1].
-
is_charge_balanced
¶ Flag indicating whether the stimulus is charge-balanced
A stimulus with a time component is considered charge-balanced if its net current is smaller than 10 pico Amps. For the whole stimulus to be charge-balanced, every electrode must be charge-balanced as well.
-
is_compressed
¶ Flag indicating whether the stimulus has been compressed
-
play
(fps=None, repeat=True, annotate_time=True, ax=None)[source]¶ Animate the video as HTML with JavaScript
The video will be played in an interactive player in IPython or Jupyter Notebook.
Parameters: - fps (float or None) – If None, uses the video’s time axis. Not supported for non-homogeneous time axis.
- repeat (bool, optional) – Whether the animation should repeat when the sequence of frames is completed.
- annotate_time (bool, optional) – If True, the time of the frame will be shown as t = X ms in the title of the panel.
- ax (matplotlib.axes.AxesSubplot, optional) – A Matplotlib axes object. If None, will create a new Axes object
Returns: ani (matplotlib.animation.FuncAnimation) – A Matplotlib animation object that will play the video frame-by-frame.
-
plot
(electrodes=None, time=None, fmt='k-', ax=None)[source]¶ Plot the stimulus
New in version 0.7.
Parameters: - electrodes (int, string, or list thereof; optional, default: None) – The electrodes for which to plot the stimulus. If None, all electrodes are plotted.
- time ((t_min, t_max) tuple, slice, or list of exact time points) – The time points at which to plot the stimulus. Specify a range of time points with a tuple or a slice, or specify the exact time points to interpolate. If None, all time points are plotted.
- fmt (str, optional, default: 'k-') – A Matplotlib format string; e.g., ‘ro’ for red circles.
- ax (matplotlib.axes.Axes or list thereof; optional, default: None) – A Matplotlib Axes object or a list thereof (one per electrode to plot). If None, a new Axes object will be created.
Returns: axes (matplotlib.axes.Axes or np.ndarray of them) – Returns one matplotlib.axes.Axes per electrode
-
remove
(electrodes)[source]¶ Remove electrode(s)
Removes the stimulus of a certain electrode or list of electrodes.
New in version 0.8.
Parameters: electrodes (int, string, or list of int/str) – The item(s) to remove from the stimulus. Can either be an electrode index, electrode name, or a list thereof.
-
resize
(shape, electrodes=None)[source]¶ Resize the video
Parameters: - shape ((rows, cols)) – Shape of each frame in the resized video. If one of the dimensions is set to -1, its value will be inferred by keeping a constant aspect ratio.
- electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the resized video.
Returns: stim (
VideoStimulus
) – A copy of the stimulus object containing the resized video
-
rgb2gray
(electrodes=None)[source]¶ Convert the video to grayscale
Parameters: electrodes (int, string or list thereof; optional) – Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in the grayscale video.
Returns: stim ( VideoStimulus
) – A copy of the stimulus object with all RGB values converted to grayscale in the range [0, 1].
-
rotate
(angle, mode='constant')[source]¶ Rotate each frame of the video
Parameters: angle (float) – Angle by which to rotate each video frame (degrees). Positive: counter-clockwise, negative: clockwise Returns: stim ( VideoStimulus
) – A copy of the stimulus object containing the rotated video
-
scale
(scaling_factor)[source]¶ Scale the image foreground
This function scales the image foreground (excluding black pixels) by a factor.
Parameters: scaling_factor (float) – Factory by which to scale the image Returns: stim ( ImageStimulus
) – A copy of the stimulus object containing the scaled image
-
shape
¶ Data container shape
-
shift
(shift_cols, shift_rows)[source]¶ Shift the image foreground
This function shifts the center of mass (CoM) of the image by the specified number of rows and columns.
Parameters: Returns: stim (
ImageStimulus
) – A copy of the stimulus object containing the shifted image
-
time
¶ Time steps A list of time steps, corresponding to the columns in the data container.
-
trim
(tol=0, electrodes=None)[source]¶ Remove any black border around the video
New in version 0.7.
Parameters: - tol (float) – Any pixels with gray levels > tol will be trimmed.
- electrodes (int, string or list thereof; optional) –
Optionally, you can provide your own electrode names. If none are given, electrode names will be numbered 0..N.
Note
The number of electrode names provided must match the number of pixels in each frame of the trimmed video.
Returns: stim (
VideoStimulus
) – A copy of the stimulus object with trimmed borders.