auditory

Classes and functions for fitting population encoding models

AuditoryFit(model, data, grids, bounds, Ns)
AuditoryModel(stimulus, hrf_model)

AuditoryFit

class popeye.auditory.AuditoryFit(model, data, grids, bounds, Ns, voxel_index=(1, 2, 3), auto_fit=True, verbose=0)

Bases: popeye.base.PopulationFit

__init__(model, data, grids, bounds, Ns, voxel_index=(1, 2, 3), auto_fit=True, verbose=0)

A class containing tools for fitting the 1D Gaussian pRF model.

The AuditoryFit class houses all the fitting tool that are associated with estimatinga pRF model. The PopulationFit takes a AuditoryModel instance model and a time-series data. In addition, extent and sampling-rate of a brute-force grid-search is set with grids and Ns. Use bounds to set limits on the search space for each parameter.

model : AuditoryModel class instance
An object representing the 1D Gaussian model.
data : ndarray
An array containing the measured BOLD signal of a single voxel.
grids : tuple

A tuple indicating the search space for the brute-force grid-search. The tuple contains pairs of upper and lower bounds for exploring a given dimension. For example grids=((-10,10),(0,5),) will search the first dimension from -10 to 10 and the second from 0 to 5. These values cannot be None.

For more information, see scipy.optimize.brute.

bounds : tuple
A tuple containing the upper and lower bounds for each parameter in parameters. If a parameter is not bounded, simply use None. For example, fit_bounds=((0,None),(-10,10),) would bound the first parameter to be any positive number while the second parameter would be bounded between -10 and 10.
Ns : int

Number of samples per stimulus dimension to sample during the ballpark search.

For more information, see scipy.optimize.brute.

voxel_index : tuple
A tuple containing the index of the voxel being modeled. The fitting procedure does not require a voxel index, but collating the results across many voxels will does require voxel indices. With voxel indices, the brain volume can be reconstructed using the newly computed model estimates.
auto_fit : bool
A flag for automatically running the fitting procedures once the GaussianFit object is instantiated.
verbose : int
0 = silent 1 = print the final solution of an error-minimization 2 = print each error-minimization step
baseline()
baseline0()
beta()
beta0()
center_freq()
center_freq0()
hrf0()
hrf_delay()
sigma()
sigma0()

AuditoryModel

class popeye.auditory.AuditoryModel(stimulus, hrf_model)

Bases: popeye.base.PopulationModel

__init__(stimulus, hrf_model)

A 1D Gaussian population receptive field model [1].

stimulus : AuditoryStimulus class object
A class instantiation of the AuditoryStimulus class containing a representation of the auditory stimulus.
hrf_model : callable
A function that generates an HRF model given an HRF delay. For more information, see popeye.utilties.double_gamma_hrf_hrf
[1]Thomas JM, Huber E, Stecker GC, Boynton GM, Saenz M, Fine I. (2015)

Population receptive field estimates in human auditory cortex. NeuroImage 105, 428-439.

generate_ballpark_prediction(center_freq, sigma, beta, baseline, hrf_delay)

Generate a prediction for the 1D Gaussian model.

This function generates a prediction of the 1D Gaussian model, given a stimulus and the stimulus-referred model parameters. This function operates on the native stimulus. Usually, the function generate_ballpark_prediction would operate on the downsampled stimulus.

center_freq : float
The center frequency of the 1D Gaussian, units are in Hz.
sigma : float
The dispersion of the 1D Gaussian, units are in Hz.
beta : float
The scaling factor to account for arbitrary units of the BOLD signal.
hrf_delay : float
The delay of the HRF, units are in seconds.
generate_prediction(center_freq, sigma, beta, baseline, hrf_delay)

Generate a prediction for the 1D Gaussian model.

This function generates a prediction of the 1D Gaussian model, given a stimulus and the stimulus-referred model parameters. This function operates on the native stimulus.

center_freq : float
The center frequency of the 1D Gaussian, units are in Hz.
sigma : float
The dispersion of the 1D Gaussian, units are in Hz.
beta : float
The scaling factor to account for arbitrary units of the BOLD signal.
hrf_delay : float
The delay of the HRF, units are in seconds.

PopulationFit

class popeye.auditory.PopulationFit(model, data, grids, bounds, Ns, voxel_index, auto_fit, verbose)

Bases: object

Base class for all pRF model fits.

__init__(model, data, grids, bounds, Ns, voxel_index, auto_fit, verbose)

A class containing tools for fitting pRF models.

The PopulationFit class houses all the fitting tool that are associated with estimatinga pRF model. The PopulationFit takes a PoulationModel instance model and a time-series data. In addition, extent and sampling-rate of a brute-force grid-search is set with grids and Ns. Use bounds to set limits on the search space for each parameter.

model : AuditoryModel class instance
An object representing the 1D Gaussian model.
data : ndarray
An array containing the measured BOLD signal of a single voxel.
grids : tuple

A tuple indicating the search space for the brute-force grid-search. The tuple contains pairs of upper and lower bounds for exploring a given dimension. For example grids=((-10,10),(0,5),) will search the first dimension from -10 to 10 and the second from 0 to 5. These values cannot be None.

For more information, see scipy.optimize.brute.

bounds : tuple
A tuple containing the upper and lower bounds for each parameter in parameters. If a parameter is not bounded, simply use None. For example, fit_bounds=((0,None),(-10,10),) would bound the first parameter to be any positive number while the second parameter would be bounded between -10 and 10.
Ns : int

Number of samples per stimulus dimension to sample during the ballpark search.

For more information, see scipy.optimize.brute.

voxel_index : tuple
A tuple containing the index of the voxel being modeled. The fitting procedure does not require a voxel index, but collating the results across many voxels will does require voxel indices. With voxel indices, the brain volume can be reconstructed using the newly computed model estimates.
auto_fit : bool
A flag for automatically running the fitting procedures once the GaussianFit object is instantiated.
verbose : int
0 = silent 1 = print the final solution of an error-minimization 2 = print each error-minimization step
Jout()
allvecs()
ballpark()
brute_force()
direc()
estimate()
fopt()
funcalls()
fval()
gradient_descent()
grid()
iter()
msg()
overloaded_estimate()
prediction()
rsquared()
rss()

PopulationModel

class popeye.auditory.PopulationModel(stimulus, hrf_model, nuissance=None)

Bases: object

Base class for all pRF models.

__init__(stimulus, hrf_model, nuissance=None)

Base class for all pRF models.

stimulus : StimulusModel class instance
An instance of the StimulusModel class containing the stim_arr and various stimulus parameters, and can represent various stimulus modalities, including visual, auditory, etc.
hrf_model : callable
A function that generates an HRF model given an HRF delay. For more information, see popeye.utilties.double_gamma_hrf_hrf and `popeye.utilities.spm_hrf
nuissance : ndarray
A nuissance regressor for removing effects of non-interest. You can regress out any nuissance effects from you data prior to fitting the model of interest. The nuissance model is a statsmodels.OLS compatible design matrix, and the user is expected to have already added any constants.
generate_ballpark_prediction()
generate_prediction()

interp1d

class popeye.auditory.interp1d(x, y, kind='linear', axis=-1, copy=True, bounds_error=True, fill_value=nan)

Bases: scipy.interpolate.polyint._Interpolator1D

interp1d(x, y, kind=’linear’, axis=-1, copy=True, bounds_error=True,
fill_value=np.nan)

Interpolate a 1-D function.

x and y are arrays of values used to approximate some function f: y = f(x). This class returns a function whose call method uses interpolation to find the value of new points.

x : (N,) array_like
A 1-D array of monotonically increasing real values.
y : (...,N,...) array_like
A N-D array of real values. The length of y along the interpolation axis must be equal to the length of x.
kind : str or int, optional
Specifies the kind of interpolation as a string (‘linear’,’nearest’, ‘zero’, ‘slinear’, ‘quadratic, ‘cubic’) or as an integer specifying the order of the spline interpolator to use. Default is ‘linear’.
axis : int, optional
Specifies the axis of y along which to interpolate. Interpolation defaults to the last axis of y.
copy : bool, optional
If True, the class makes internal copies of x and y. If False, references to x and y are used. The default is to copy.
bounds_error : bool, optional
If True, a ValueError is raised any time interpolation is attempted on a value outside of the range of x (where extrapolation is necessary). If False, out of bounds values are assigned fill_value. By default, an error is raised.
fill_value : float, optional
If provided, then this value will be used to fill in for requested points outside of the data range. If not provided, then the default is NaN.

UnivariateSpline : A more recent wrapper of the FITPACK routines. splrep, splev

Spline interpolation based on FITPACK.

interp2d

>>> from scipy import interpolate
>>> x = np.arange(0, 10)
>>> y = np.exp(-x/3.0)
>>> f = interpolate.interp1d(x, y)
>>> xnew = np.arange(0,9, 0.1)
>>> ynew = f(xnew)   # use interpolation function returned by `interp1d`
>>> plt.plot(x, y, 'o', xnew, ynew, '-')
>>> plt.show()
__init__(x, y, kind='linear', axis=-1, copy=True, bounds_error=True, fill_value=nan)

Initialize a 1D linear interpolation class.

auto_attr

popeye.auditory.auto_attr(func)

Decorator to create OneTimeProperty attributes.

func : method
The method that will be called the first time to compute a value. Afterwards, the method’s name will be a standard attribute holding the value of this computation.
>>> class MagicProp(object):
...     @auto_attr
...     def a(self):
...         return 99
...
>>> x = MagicProp()
>>> 'a' in x.__dict__
False
>>> x.a
99
>>> 'a' in x.__dict__
True

fftconvolve

popeye.auditory.fftconvolve(in1, in2, mode='full')

Convolve two N-dimensional arrays using FFT.

Convolve in1 and in2 using the fast Fourier transform method, with the output size determined by the mode argument.

This is generally much faster than convolve for large arrays (n > ~500), but can be slower when only a few output values are needed, and can only output float arrays (int or object array inputs will be cast to float).

in1 : array_like
First input.
in2 : array_like
Second input. Should have the same number of dimensions as in1; if sizes of in1 and in2 are not equal then in1 has to be the larger array.
mode : str {‘full’, ‘valid’, ‘same’}, optional

A string indicating the size of the output:

full
The output is the full discrete linear convolution of the inputs. (Default)
valid
The output consists only of those elements that do not rely on the zero-padding.
same
The output is the same size as in1, centered with respect to the ‘full’ output.
out : array
An N-dimensional array containing a subset of the discrete linear convolution of in1 with in2.

generate_rf_timeseries_1D

popeye.auditory.generate_rf_timeseries_1D()