mvpa2.datasets.eventrelated.fit_event_hrf_model

mvpa2.datasets.eventrelated.fit_event_hrf_model(ds, events, time_attr, condition_attr='targets', design_kwargs=None, glmfit_kwargs=None, regr_attrs=None, return_model=False)

Fit a GLM with HRF regressor and yield a dataset with model parameters

A univariate GLM is fitted for each feature and model parameters are returned as samples. Model parameters are returned for each regressor in the design matrix. Using functionality from NiPy, design matrices can be generated from event definitions with a variety of customizations (HRF model, confound regressors, ...).

Events need to be specified as a list of dictionaries (see:class:Event) for a helper class. Each dictionary contains all relevant attributes to describe an event.

Parameters:

ds : Dataset

The samples of this input dataset have to be in whatever ascending order.

events : list

Each event definition has to specify onset and duration. All other attributes will be passed on to the sample attributes collection of the returned dataset.

time_attr : str

Attribute with dataset sample time stamps. Its values will be treated as in-the-same-unit and are used to determine corresponding samples from real-value onset and duration definitions. For HRF modeling this argument is mandatory.

condition_attr : str

Name of the event attribute with the condition labels. Can be a list of those (e.g. [‘targets’, ‘chunks’] combination of which would constitute a condition.

design_kwargs : dict

Arbitrary keyword arguments for NiPy’s make_dmtx() used for design matrix generation. Choose HRF model, confound regressors, etc.

glmfit_kwargs : dict

Arbitrary keyword arguments for NiPy’s GeneralLinearModel.fit() used for estimating model parameter. Choose fitting algorithm: OLS or AR1.

regr_attrs : list

List of dataset sample attribute names that shall be extracted from the input dataset and used as additional regressors in the design matrix.

return_model : bool

Flag whether to included the fitted GLM model in the returned dataset. For large input data this can be problematic, as the model may contain the residuals (same size is input data), hence multiplies the memory demand. Off by default.

Returns:

Dataset

One sample for each regressor/condition in the design matrix is returned. The condition names are included as a sample attribute with the name specified by the condition_attr argument. The actual design regressors are included as regressors sample attribute. If enabled, an instance with the fitted NiPy GLM results is included as a dataset attribute model, and can be used for computing contrasts subsequently.

Examples

The documentation also contains an example script showing a spatio-temporal analysis of fMRI data that involves this function.

>>> from mvpa2.datasets import Dataset
>>> ds = Dataset(np.random.randn(10, 25))
>>> ds.sa['time_coords'] = np.linspace(0, 50, len(ds))
>>> events = [{'onset': 2, 'duration': 4, 'condition': 'one'},
...           {'onset': 4, 'duration': 4, 'condition': 'two'}]
>>> hrf_estimates = fit_event_hrf_model(
...                   ds, events,
...                   time_attr='time_coords',
...                   condition_attr='condition',
...                   design_kwargs=dict(drift_model='blank'),
...                   glmfit_kwargs=dict(model='ols'),
...                   return_model=True)
>>> print hrf_estimates.sa.condition
['one' 'two']
>>> print hrf_estimates.shape
(2, 25)
>>> len(hrf_estimates.a.model.get_mse())
25

Additional regressors used in GLM modeling are also available in a dataset attribute:

>>> print hrf_estimates.a.add_regs.sa.regressor_names
['constant']