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
andduration
. 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 inthesameunit and are used to determine corresponding samples from realvalue 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 asregressors
sample attribute. If enabled, an instance with the fitted NiPy GLM results is included as a dataset attributemodel
, and can be used for computing contrasts subsequently.Examples
The documentation also contains an example script showing a spatiotemporal 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']