`visual_stimulus`¶

First pass at a stimulus model for abstracting the qualities and functionality of a stimulus into an abstract class. For now, we’ll assume the stimulus model only pertains to visual stimuli on a visual display over time (i.e., 3D). Hopefully this can be extended to other stimuli with an arbitrary number of dimensions (e.g., auditory stimuli).

`VisualStimulus`(stim_arr, viewing_distance, ...)
`gaussian_2D`(X, Y, x0, y0, sigma_x, sigma_y, ...)	A utility function for creating a two-dimensional Gaussian.
`generate_coordinate_matrices`(pixels_across, ...)	Creates coordinate matrices for representing the visual field in terms of degrees of visual angle.
`resample_stimulus`(stim_arr[, scale_factor, ...])	Resamples the visual stimulus
`simulate_bar_stimulus`(pixels_across, ...[, clip])	A utility function for creating a sweeping bar stimulus in memory.
`simulate_sinflicker_bar`(pixels_across, ...)

`StimulusModel`¶

class popeye.visual_stimulus.StimulusModel(stim_arr, dtype=<class 'ctypes.c_short'>, tr_length=1.0)¶

Bases: object

__init__(stim_arr, dtype=<class 'ctypes.c_short'>, tr_length=1.0)¶

A base class for all encoding stimuli.

This class houses the basic and common features of the encoding stimulus, which along with a PopulationModel constitutes what is commonly referred to as the pRF model.

stim_arr : ndarray: An array containing the stimulus. The dimensionality of the data is arbitrary but must be consistent with the pRF model, as specified in PopulationModel and PopluationFit class instances.
dtype : string: Sets the data type the stimulus array is cast into.
dtype : string: Sets the data type the stimulus array is cast into.
tr_length : float: The repetition time (TR) in seconds.

`VisualStimulus`¶

class popeye.visual_stimulus.VisualStimulus(stim_arr, viewing_distance, screen_width, scale_factor, tr_length, dtype, interp='nearest')¶

Bases: popeye.base.StimulusModel

__init__(stim_arr, viewing_distance, screen_width, scale_factor, tr_length, dtype, interp='nearest')¶

A child of the StimulusModel class for visual stimuli.

stim_arr : ndarray: An array containing the visual stimulus at the native resolution. The visual stimulus is assumed to be three-dimensional (x,y,time).
viewing_distance : float: The distance between the participant and the display (cm).
screen_width : float: The width of the display (cm). This is used to compute the visual angle for determining the pixels per degree of visual angle.
scale_factor : float: The downsampling rate for ball=parking a solution. The stim_arr is downsampled so as to speed up the fitting procedure. The final model estimates will be derived using the non-downsampled stimulus.

gaussian_2D¶

popeye.visual_stimulus.gaussian_2D(X, Y, x0, y0, sigma_x, sigma_y, degrees, amplitude=1)¶

A utility function for creating a two-dimensional Gaussian.

This function served as the model for the Cython implementation of a generator of two-dimensional Gaussians.

X : ndarray: The coordinate array for the horizontal dimension of the display.
Y : ndarray: The coordinate array for the the vertical dimension of the display.
x0 : float: The location of the center of the Gaussian on the horizontal axis.
y0 : float: The location of the center of the Gaussian on the verticala axis.
sigma_x : float: The dispersion of the Gaussian over the horizontal axis.
sigma_y : float: The dispersion of the Gaussian over the vertical axis.
degrees : float: The orientation of the two-dimesional Gaussian (degrees).
amplitude : float: The amplitude of the two-dimensional Gaussian.

gauss : ndarray: The two-dimensional Gaussian.

generate_coordinate_matrices¶

popeye.visual_stimulus.generate_coordinate_matrices(pixels_across, pixels_down, ppd, scale_factor=1)¶

Creates coordinate matrices for representing the visual field in terms: of degrees of visual angle.

This function takes the screen dimensions, the pixels per degree, and a scaling factor in order to generate a pair of ndarrays representing the horizontal and vertical extents of the visual display in degrees of visual angle.

pixels_across : int: The number of pixels along the horizontal extent of the visual display.
pixels_down : int: The number of pixels along the vertical extent of the visual display.
ppd: float: The number of pixels that spans 1 degree of visual angle. This number is computed using the display width and the viewing distance. See the config.init_config for details.
scale_factor : float: The scale factor by which the stimulus is resampled. The scale factor must be a float, and must be greater than 0.

deg_x : ndarray: An array representing the horizontal extent of the visual display in terms of degrees of visual angle.
deg_y : ndarray: An array representing the vertical extent of the visual display in terms of degrees of visual angle.

loadmat¶

popeye.visual_stimulus.loadmat(file_name, mdict=None, appendmat=True, **kwargs)¶

Load MATLAB file

file_name : str: Name of the mat file (do not need .mat extension if appendmat==True) Can also pass open file-like object.
m_dict : dict, optional: Dictionary in which to insert matfile variables.
appendmat : bool, optional: True to append the .mat extension to the end of the given filename, if not already present.
byte_order : str or None, optional: None by default, implying byte order guessed from mat file. Otherwise can be one of (‘native’, ‘=’, ‘little’, ‘<’, ‘BIG’, ‘>’).
mat_dtype : bool, optional: If True, return arrays in same dtype as would be loaded into MATLAB (instead of the dtype with which they are saved).
squeeze_me : bool, optional: Whether to squeeze unit matrix dimensions or not.
chars_as_strings : bool, optional: Whether to convert char arrays to string arrays.
matlab_compatible : bool, optional: Returns matrices as would be loaded by MATLAB (implies squeeze_me=False, chars_as_strings=False, mat_dtype=True, struct_as_record=True).
struct_as_record : bool, optional: Whether to load MATLAB structs as numpy record arrays, or as old-style numpy arrays with dtype=object. Setting this flag to False replicates the behavior of scipy version 0.7.x (returning numpy object arrays). The default setting is True, because it allows easier round-trip load and save of MATLAB files.
variable_names : None or sequence: If None (the default) - read all variables in file. Otherwise variable_names should be a sequence of strings, giving names of the matlab variables to read from the file. The reader will skip any variable with a name not in this sequence, possibly saving some read processing.

mat_dict : dict: dictionary with variable names as keys, and loaded matrices as values

v4 (Level 1.0), v6 and v7 to 7.2 matfiles are supported.

You will need an HDF5 python library to read matlab 7.3 format mat files. Because scipy does not supply one, we do not implement the HDF5 / 7.3 interface here.

resample_stimulus¶

popeye.visual_stimulus.resample_stimulus(stim_arr, scale_factor=0.05, mode='nearest', dtype='uint8')¶

Resamples the visual stimulus

The function takes an ndarray stim_arr and resamples it by the user specified scale_factor. The stimulus array is assumed to be a three dimensional ndarray representing the stimulus, in screen pixel coordinates, over time. The first two dimensions of stim_arr together represent the exent of the visual display (pixels) and the last dimensions represents time (TRs).

stim_arr : ndarray: Array_like means all those objects – lists, nested lists, etc. – that can be converted to an array.
scale_factor : float: The scale factor by which the stimulus is resampled. The scale factor must be a float, and must be greater than 0.
mode : str, optional: Points outside the boundaries of the input are filled according to the given mode (‘constant’, ‘nearest’, ‘reflect’ or ‘wrap’). Default is ‘nearest’.

resampled_arr : ndarray: An array that is resampled according to the user-specified scale factor.

simulate_bar_stimulus¶

popeye.visual_stimulus.simulate_bar_stimulus(pixels_across, pixels_down, viewing_distance, screen_width, thetas, num_bar_steps, num_blank_steps, ecc, clip=0.33)¶

A utility function for creating a sweeping bar stimulus in memory.

This function creates a standard retinotopic mapping stimulus, the sweeping bar. The user specifies some of the display and stimulus parameters. This is particularly useful for writing tests and simulating responses of visually driven voxels.

pixels_across : int: The number of pixels along the horizontal dimension of the display.
pixels_down : int: The number of pixels along the vertical dimension of the display.
viewing_distance : float: The distance between the participant and the display (cm).
screen_width : float: The width of the display (cm). This is used to compute the visual angle for determining the pixels per degree of visual angle.
thetas : array-like: An array containing the orientations of the bars that will sweep across the display. For example thetas = np.arange(0,360,360/8).
num_steps : int: The number of steps the bar makes on each sweep through the visual field.
ecc : float: The distance from fixation each bar sweep begins and ends (degees).
blanks : bool: A flag determining whether there are blank periods inserted at the beginning and the end of the stimulus run.
clip : float: The bar stimulus is created by cliping a very oblong two-dimensional Gaussian oriented orthogonally to the direction of the sweep.

bar : ndarray: An array containing the bar stimulus. The array is three-dimensional, with the first two dimensions representing the size of the display and the third dimension representing time.

simulate_sinflicker_bar¶

popeye.visual_stimulus.simulate_sinflicker_bar(pixels_across, pixels_down, viewing_distance, screen_width, thetas, sweep_steps, bar_width, ecc, tr_length, flicker_hz, projector_hz)¶

square¶

popeye.visual_stimulus.square(t, duty=0.5)¶

Return a periodic square-wave waveform.

The square wave has a period 2*pi, has value +1 from 0 to 2*pi*duty and -1 from 2*pi*duty to 2*pi. duty must be in the interval [0,1].

Note that this is not band-limited. It produces an infinite number of harmonics, which are aliased back and forth across the frequency spectrum.

t : array_like: The input time array.
duty : array_like, optional: Duty cycle. Default is 0.5 (50% duty cycle). If an array, must be the same length as t, causes wave shape to change over time.

y : ndarray: Output array containing the square waveform.

A 5 Hz waveform sampled at 500 Hz for 1 second:

>>> from scipy import signal
>>> import matplotlib.pyplot as plt
>>> t = np.linspace(0, 1, 500, endpoint=False)
>>> plt.plot(t, signal.square(2 * np.pi * 5 * t))
>>> plt.ylim(-2, 2)

A pulse-width modulated sine wave:

>>> sig = np.sin(2 * np.pi * t)
>>> pwm = signal.square(2 * np.pi * 30 * t, duty=(sig + 1)/2)
>>> plt.subplot(2, 1, 1)
>>> plt.plot(t, sig)
>>> plt.subplot(2, 1, 2)
>>> plt.plot(t, pwm)
>>> plt.ylim(-1.5, 1.5)

zoom¶

popeye.visual_stimulus.zoom(input, zoom, output=None, order=3, mode='constant', cval=0.0, prefilter=True)¶

Zoom an array.

The array is zoomed using spline interpolation of the requested order.

input : ndarray: The input array.
zoom : float or sequence, optional: The zoom factor along the axes. If a float, zoom is the same for each axis. If a sequence, zoom should contain one value for each axis.
output : ndarray or dtype, optional: The array in which to place the output, or the dtype of the returned array.
order : int, optional: The order of the spline interpolation, default is 3. The order has to be in the range 0-5.
mode : str, optional: Points outside the boundaries of the input are filled according to the given mode (‘constant’, ‘nearest’, ‘reflect’ or ‘wrap’). Default is ‘constant’.
cval : scalar, optional: Value used for points outside the boundaries of the input if mode='constant'. Default is 0.0
prefilter : bool, optional: The parameter prefilter determines if the input is pre-filtered with spline_filter before interpolation (necessary for spline interpolation of order > 1). If False, it is assumed that the input is already filtered. Default is True.

zoom : ndarray or None: The zoomed input. If output is given as a parameter, None is returned.

visual_stimulus¶

StimulusModel¶

VisualStimulus¶