Fit classes

class prfpy.fit.CFFitter(data, model, n_jobs=1, **kwargs)

Class that implements the different fitting methods on a gaussian CF model, leveraging a Model object.

get_quick_grid_preds(dset='train')

Returns the best fitting grid predictions from the quick_grid_fit method.

Parameters

dset : Which dataset to return for (train or test).

Returns

train_predictions. OR test_predictions.

grid_fit(sigma_grid, verbose=False, n_batches=1000)

performs grid fit using provided grids and predictor definitions

Parameters

sigma_grid1D ndarray

to be filled in by user

verboseboolean, optional

print output. The default is False.

n_batchesint, optional

The grid fit is performed in parallel over n_batches of units. Batch parallelization is faster than single-unit parallelization and of sequential computing.

Returns

gridsearch_params: An array containing the gridsearch parameters. vertex_centres: An array containing the vertex centres. vertex_centres_dict: A dictionary containing the vertex centres.

quick_grid_fit(sigma_grid)

Performs fast estimation of vertex centres and sizes using a simple dot product of zscored data. Does not complete the regression equation (estimating beta and baseline).

Parameters

sigma_grid1D ndarray

to be filled in by user

Returns

quick_gridsearch_params: An array containing the gridsearch parameters. quick_vertex_centres: An array containing the vertex centres. quick_vertex_centres_dict: A dictionary containing the vertex centres.

quick_xval(test_data, test_stimulus)

Takes the fitted parameters and tests their performance on the out of sample data.

Parameters

Test data: Data to test predictions on. Test stimulus: CFstimulus class associated with test data.

Returns

CV_R2 - the out of sample performance.

class prfpy.fit.CSS_Iso2DGaussianFitter(model, data, n_jobs=1, previous_gaussian_fitter=None, use_previous_gaussian_fitter_hrf=False)

Compressive Spatial Summation model

grid_fit(exponent_grid, gaussian_params=None, verbose=False, n_batches=1, rsq_threshold=0.05, fixed_grid_baseline=None, grid_bounds=None, hrf_1_grid=None, hrf_2_grid=None)

This function performs a grid_fit for the normalization model new parameters. The fit is parallel over batches of voxels, and separate predictions are made for each voxels based on its previously obtained Gaussian parameters (position and size). These can be provided explicitly in gaussian_params, or otherwise they are obtained from previous_gaussian_fitter.iterative_search_params

Parameters

exponent_grid1D ndarray

Array of exponent values.

gaussian_paramsndarray [n_units, 4], optional

The Gaussian parms [x position, y position, prf size, rsq] can be provided explicitly. If not, a previous_gaussian_fitter must be provided. The default is None.

verboseboolean, optional

print output. The default is False.

n_batchesint, optional

The data is split in n_batches of units and grid fit is performed in parallel.

rsq_thresholdfloat, optional

rsq threshold for grid fitting. The default is 0.05.

fixed_grid_baselinefloat, optional

The default is None. If not None, bold baseline will be fixed to this value (recommended).

grid_boundslist containing one tuple, optional

The default is None. If not None, only values of pRF amplitude between grid_bounds[0][0] and grid_bounds[0][1] will be allowed. This is generally used to only allow positive pRFs, for example by specifying grid_bounds = [(0,1000)], only pRFs with amplitude between 0 and 1000 will be allowed in the grid fit

hrf_1_grid1D ndarray, optional

The default is None. If not None, and if self.use_previous_gaussian_fitter_hrf is False, will perform grid over these values of the hrf_1 parameter.

hrf_1_grid1D ndarray, optional

The default is None. If not None, and if self.use_previous_gaussian_fitter_hrf is False, will perform grid over these values of the hrf_1 parameter.

Raises

ValueError

Raised if there is no previous_gaussian_fitter or gaussian params.

insert_new_model_params(old_params)

Parameters

old_paramsndarray [n_units, 8]

Previous Gaussian fitter parameters and rsq.

Returns

new_paramsndarray [n_units, 9]

Starting parameters and rsq for CSS iterative fit.

class prfpy.fit.DoG_Iso2DGaussianFitter(model, data, n_jobs=1, previous_gaussian_fitter=None, use_previous_gaussian_fitter_hrf=False)

Difference of Gaussians model

grid_fit(surround_amplitude_grid, surround_size_grid, gaussian_params=None, verbose=False, n_batches=1, rsq_threshold=0.05, fixed_grid_baseline=None, grid_bounds=None, hrf_1_grid=None, hrf_2_grid=None)

This function performs a grid_fit for the normalization model new parameters. The fit is parallel over batches of voxels, and separate predictions are made for each voxels based on its previously obtained Gaussian parameters (position and size). These can be provided explicitly in gaussian_params, or otherwise they are obtained from previous_gaussian_fitter.iterative_search_params

Parameters

surround_amplitude_grid1D ndarray

Array of surround amplitude values.

surround_size_grid1D ndarray

Array of surround size values (sigma_2).

gaussian_paramsndarray [n_units, 4], optional

The Gaussian parms [x position, y position, prf size, rsq] can be provided explicitly. If not, a previous_gaussian_fitter must be provided. The default is None.

verboseboolean, optional

print output. The default is False.

n_batchesint, optional

Number of voxel batches. The default is 1.

rsq_thresholdfloat, optional

rsq threshold for grid fitting. The default is 0.05.

fixed_grid_baselinefloat, optional

The default is None. If not None, bold baseline will be fixed to this value (recommended).

grid_boundslist containing one or two tuples, optional

The default is None. If not None, only values of pRF amplitude between grid_bounds[0][0] and grid_bounds[0][1] will be allowed. This is generally used to only allow positive pRFs, for example by specifying grid_bounds = [(0,1000)], only pRFs with amplitude between 0 and 1000 will be allowed in the grid fit. If list contains two tuples, second tuple will give bounds on Surround Amplitude.

hrf_1_grid1D ndarray, optional

The default is None. If not None, and if self.use_previous_gaussian_fitter_hrf is False, will perform grid over these values of the hrf_1 parameter.

hrf_1_grid1D ndarray, optional

The default is None. If not None, and if self.use_previous_gaussian_fitter_hrf is False, will perform grid over these values of the hrf_1 parameter.

Raises

ValueError

Raised if there is no previous_gaussian_fitter or gaussian params.

insert_new_model_params(old_params)

Parameters

old_paramsndarray [n_units, 8]

Previous Gaussian fitter parameters and rsq.

Returns

new_paramsndarray [n_units, 10]

Starting parameters and rsq for DoG iterative fit.

class prfpy.fit.Extend_Iso2DGaussianFitter(model, data, n_jobs=1, previous_gaussian_fitter=None, use_previous_gaussian_fitter_hrf=False)

Generic superclass to extend the Gaussian Fitter. If an existing Iso2DGaussianFitter object with iterative_search_params is provided, the prf position, size, and rsq parameters will be used for further minimizations.

insert_new_model_params(old_params)

Function to insert new model parameters starting values for iterfitting. To be redefined appropriately for each model (see below for examples). If grid_fit is defined and performed, self.gridsearch_params take precedence, and this function becomes unnecessary.

Generally should not be used. grid_fit is preferable.

Parameters

old_paramsndarray [n_units, 8]

Previous Gaussian fitter parameters and rsq.

Returns

new_paramsndarray [n_units, number of new model parameters]

Starting parameters for iterative fit. To be redefined appropriately for each model.

iterative_fit(rsq_threshold, verbose=False, starting_params=None, bounds=None, args={}, constraints=None, xtol=0.0001, ftol=0.0001)

Iterative_fit for models building on top of the Gaussian. Does not need to be redefined for new models. It is sufficient to define either insert_new_model_params or grid_fit, in a new model Fitter class, or provide explicit starting_params.

Parameters

rsq_thresholdfloat

Rsq threshold for iterative fitting. Must be between 0 and 1.

verboseboolean, optional

Whether to print output. The default is False.

starting_paramsndarray of size [units, model_params +1], optional

Explicit start for minimization. The default is None.

boundslist of tuples, optional

Bounds for parameter minimization. Must have the same length as start_params. The default is None.

argsdictionary, optional

Further arguments passed to iterative_search. The default is {}.

constraints: list of scipy.optimize.LinearConstraints and/or

scipy.optimize.NonLinearConstraints if constraints are not None, will use trust-constr optimizer

xtolfloat, optional

if allowed by optimizer, parameter tolerance for termination of fitting

ftolfloat, optional

if allowed by optimizer, objective function tolerance for termination of fitting

Returns

None.

class prfpy.fit.Fitter(data, model, n_jobs=1, **kwargs)

Superclass for classes that implement the different fitting methods, for a given model. It contains 2D-data and leverages a Model object.

data should be two-dimensional so that all bookkeeping with regard to voxels, electrodes, etc is done by the user. Generally, a Fitter class should implement both a grid_fit and an iterative_fit method to be run in sequence.

crossvalidate_fit(test_data, test_stimulus=None, single_hrf=True)

Simple function to crossvalidate results of previous iterative fitting.

Parameters

test_datandarray

Test data for crossvalidation.

test_stimulusPRFStimulus, optional

PRF stimulus for test. If same as train data, not needed.

single_hrfBool

If True, uses the average-across-units HRF params in crossvalidation

Returns

None.

iterative_fit(rsq_threshold, verbose=False, starting_params=None, bounds=None, args={}, constraints=None, xtol=0.0001, ftol=0.0001)

Generic function for iterative fitting. Does not need to be redefined for new models. It is sufficient to define insert_new_model_params or grid_fit in the new model Fitter class, or provide explicit starting_params (see Extend_Iso2DGaussianFitter for examples).

Parameters

rsq_thresholdfloat

Rsq threshold for iterative fitting. Must be between 0 and 1.

verboseboolean, optional

Whether to print output. The default is False.

starting_paramsndarray, optional

Explicit start for iterative fit. The default is None.

boundslist of tuples, optional

Bounds for parameter minimization. The default is None. if bounds are None, will use Powell optimizer if bounds are not None, will use LBFGSB or trust-constr

argsdictionary, optional

Further arguments passed to iterative_search. The default is {}.

constraints: list of scipy.optimize.LinearConstraints and/or

scipy.optimize.NonLinearConstraints if constraints are not None, will use trust-constr optimizer

xtolfloat, optional

if allowed by optimizer, parameter tolerance for termination of fitting

ftolfloat, optional

if allowed by optimizer, objective function tolerance for termination of fitting

Returns

None.

class prfpy.fit.Iso2DGaussianFitter(data, model, n_jobs=1, **kwargs)

Class that implements the different fitting methods on a two-dimensional isotropic Gaussian pRF model, leveraging a Model object.

grid_fit(ecc_grid, polar_grid, size_grid, verbose=False, n_batches=1, fixed_grid_baseline=None, grid_bounds=None, hrf_1_grid=None, hrf_2_grid=None)

performs grid fit using provided grids and predictor definitions

Parameters

ecc_grid1D ndarray

array of eccentricity values in grid

polar_grid1D ndarray

array of polar angle values in grid

size_grid1D ndarray

array of size values in grid

verboseboolean, optional

print output. The default is False.

n_batchesint, optional

The data is split in n_batches of units and grid fit is performed in parallel.

fixed_grid_baselinefloat, optional

The default is None. If not None, bold baseline will be fixed to this value (recommended).

grid_boundslist containing one tuple, optional

The default is None. If not None, only values of pRF amplitude between grid_bounds[0][0] and grid_bounds[0][1] will be allowed. This is generally used to only allow positive pRFs, for example by specifying grid_bounds = [(0,1000)], only pRFs with amplitude between 0 and 1000 will be allowed in the grid fit

hrf_1_grid1D ndarray, optional

The default is None. If not None, and if self.use_previous_gaussian_fitter_hrf is False, will perform grid over these values of the hrf_1 parameter.

hrf_1_grid1D ndarray, optional

The default is None. If not None, and if self.use_previous_gaussian_fitter_hrf is False, will perform grid over these values of the hrf_1 parameter.

Returns

None.

class prfpy.fit.Norm_Iso2DGaussianFitter(model, data, n_jobs=1, previous_gaussian_fitter=None, use_previous_gaussian_fitter_hrf=False)

Divisive Normalization model

grid_fit(surround_amplitude_grid, surround_size_grid, neural_baseline_grid, surround_baseline_grid, gaussian_params=None, verbose=False, n_batches=1, rsq_threshold=0.05, fixed_grid_baseline=None, grid_bounds=None, hrf_1_grid=None, hrf_2_grid=None, ecc_grid=None, polar_grid=None, size_grid=None, surround_size_as_proportion=False, ecc_in_stim_range=False)

This function performs a grid_fit for the normalization model new parameters. The fit is parallel over batches of voxels, and separate predictions are made for each voxels based on its previously obtained Gaussian parameters (position and size). These can be provided explicitly in gaussian_params, or otherwise they are obtained from previous_gaussian_fitter.iterative_search_params

Parameters

surround_amplitude_grid1D ndarray

Array of surround amplitude values (Norm param C).

surround_size_grid1D ndarray

Array of surround size values (sigma_2).

neural_baseline_grid1D ndarray

Array of neural baseline values (Norm param B).

surround_baseline_grid1D ndarray

Array of surround baseline values (Norm param D).

gaussian_paramsndarray [n_units, 4], optional

The Gaussian parms [x position, y position, prf size, rsq] can be provided explicitly. If not, a previous_gaussian_fitter must be provided. The default is None.

verboseboolean, optional

print output. The default is False.

n_batchesint, optional

The data is split in n_batches of units and grid fit is performed in parallel.

rsq_thresholdfloat, optional

rsq threshold for grid fitting. The default is 0.05.

fixed_grid_baselinefloat, optional

The default is None. If not None, bold baseline will be fixed to this value (recommended).

grid_boundslist containing one tuple, optional

The default is None. If not None, only values of pRF amplitude between grid_bounds[0][0] and grid_bounds[0][1] will be allowed. This is generally used to only allow positive pRFs, for example by specifying grid_bounds = [(0,1000)], only pRFs with amplitude between 0 and 1000 will be allowed in the grid fit. If list contains two tuples, second tuple will give bounds on Neural Baseline (Norm param B).

hrf_1_grid1D ndarray, optional

The default is None. If not None, and if self.use_previous_gaussian_fitter_hrf is False, will perform grid over these values of the hrf_1 parameter.

hrf_2_grid1D ndarray, optional

The default is None. If not None, and if self.use_previous_gaussian_fitter_hrf is False, will perform grid over these values of the hrf_2 parameter.

ecc_grid1D ndarray, optional

The default is None. If all ecc_grid, polar_grid, and size_grid are not None, will perform full grid for DN model.

polar_grid1D ndarray, optional

The default is None. If all ecc_grid, polar_grid, and size_grid are not None, will perform full grid for DN model.

size_grid1D ndarray, optional

The default is None. If all ecc_grid, polar_grid, and size_grid are not None, will perform full grid for DN model.

surround_size_as_proportionboolean, optional

If True, interpret surround_size_grid as a factor multiplying the activation pRF size. The default is False.

ecc_in_stim_rangeboolean, optional

If True, rescale eccentricity and size of pRFs outside of the screen in gaussian params to be in screen. The default is False.

Raises

ValueError

Raised if there is no previous_gaussian_fitter or gaussian params.

insert_new_model_params(old_params)

Note: this function is generally unused since there is an efficient grid_fit for the normalization model (below)

Parameters

old_paramsndarray [n_units, 8]

Previous Gaussian fitter parameters and rsq.

Returns

new_paramsndarray [n_units, 12]

Starting parameters and rsq for norm iterative fit.

prfpy.fit.error_function(parameters, args, data, objective_function)

Parameters

parameterslist or ndarray

A tuple of values representing a model setting.

argsdictionary

Extra arguments to objective_function beyond those in parameters.

datandarray

The actual, measured time-series against which the model is fit.

objective_functioncallable

The objective function that takes parameters and args and produces a model time-series.

Returns

errorfloat

The residual sum of squared errors between the prediction and data.

prfpy.fit.iterative_search(model, data, start_params, args, xtol, ftol, verbose=True, bounds=None, constraints=None)

Generic minimization function called by iterative_fit. Do not call this directly. Use iterative_fit instead.

[description]

Parameters

modelModel

Object that provides the predictions using its return_prediction method

data1D numpy.ndarray

the data to fit, same dimensions as are returned by Model’s return_prediction method

start_paramslist or 1D numpy.ndarray

initial values for the fit

argsdictionary, arguments to model.return_prediction that

are not optimized

xtolfloat, passed to fitting routine

numerical tolerance on x

ftolfloat, passed to fitting routine

numerical tolerance on function

verbosebool, optional

whether to have minimizer output.

boundslist of tuples, optional

Bounds for parameter minimization. Must have the same length as start_params. The default is None.

constraints: list of scipy.optimize.LinearConstraints and/or

scipy.optimize.NonLinearConstraints

Raises

AssertionError

Raised if parameters and bounds do not have the same length.

Returns

2-tuple

first element: parameter values second element: rsq value