Multivariate Pattern Analysis in Python

# 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']