mvpa2.datasets.eventrelated.eventrelated_dataset

mvpa2.datasets.eventrelated.eventrelated_dataset(ds, events, time_attr=None, match='prev', eprefix='event', event_mapper=None, condition_attr='targets', design_kwargs=None, glmfit_kwargs=None, regr_attrs=None, model='boxcar')

Segment a dataset by modeling events.

This function can be used to extract event-related samples from any (time-series) based dataset. The principal event modeling approaches are available (see model argument):

  1. Boxcar model: (multiple) consecutive samples are extracted for each

    event, and are either returned in a flattened shape, or subject to further processing.

  2. HRF model: a univariate GLM is fitted for each feature and model

    parameters are returned as samples. Model parameters returned for each regressor in the design matrix. Using NiPy design matrices can be generated with a variety of customizations (HRF model, confound regressors, ...).

Events are specified as a list of dictionaries (see:class:Event) for a helper class. Each dictionary contains all relevant attributes to describe an event. This is at least the onset time of an event, but can also comprise of duration, amplitude, and arbitrary other attributes – depending on the selected event model.

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.

model : {‘boxcar’, ‘hrf’}

Event model selection – see documentation for details.

time_attr : str or None

Attribute with dataset sample time-stamps. For boxcar modeling, if not None, the onset and duration specs from the event list will be converted using information from this sample attribute. 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.

match : {‘prev’, ‘next’, ‘closest’}

For boxcar modeling: strategy used to match real-value onsets to sample indices. ‘prev’ chooses the closes preceding samples, ‘next’ the closest following sample and ‘closest’ to absolute closest sample.

eprefix : str or None

For boxcar modeling: if not None, this prefix is used to name additional attributes generated by the underlying BoxcarMapper. If it is set to None, no additional attributes will be created.

event_mapper : Mapper

This mapper is used to forward-map the dataset containing the boxcar event samples. If None (default) a FlattenMapper is employed to convert multi-dimensional sample matrices into simple one-dimensional sample vectors. This option can be used to implement temporal compression, by e.g. averaging samples within an event boxcar using an FxMapper. Any mapper needs to keep the sample axis unchanged, i.e. number and order of samples remain the same.

condition_attr : str

For HRF modeling: 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.

Returns:

Dataset :

In case of a boxcar model, the returned dataset has one sample per each event definition that has been passed to the function. Additional event attributes are included as sample attributes.

In case of an HRF model, 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. An instance with the fitted NiPy GLM results is included as a dataset attribute glmfit, 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))
>>> events = [{'onset': 2, 'duration': 4},
...           {'onset': 4, 'duration': 4}]
>>> eds = eventrelated_dataset(ds, events)
>>> len(eds)
2
>>> eds.nfeatures == ds.nfeatures * 4
True
>>> 'mapper' in ds.a
False
>>> print eds.a.mapper
<Chain: <Boxcar: bl=4>-<Flatten>>

And now the same conversion, but with events specified as real time. This is on possible if the input dataset contains a sample attribute with the necessary information about the input samples.

>>> ds.sa['record_time'] = np.linspace(0, 5, len(ds))
>>> rt_events = [{'onset': 1.05, 'duration': 2.2},
...              {'onset': 2.3, 'duration': 2.12}]
>>> rt_eds = eventrelated_dataset(ds, rt_events, time_attr='record_time',
...                               match='closest')
>>> np.all(eds.samples == rt_eds.samples)
True
>>> # returned dataset e.g. has info from original samples
>>> rt_eds.sa.record_time
array([[ 1.11111111,  1.66666667,  2.22222222,  2.77777778],
       [ 2.22222222,  2.77777778,  3.33333333,  3.88888889]])

And finally some simplistic HRF modeling:

>>> 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 = eventrelated_dataset(
...                   ds, events,
...                   time_attr='time_coords',
...                   condition_attr='condition',
...                   design_kwargs=dict(drift_model='blank'),
...                   glmfit_kwargs=dict(model='ols'),
...                   model='hrf')
>>> 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']

Next topic

mvpa2.datasets.eventrelated.find_events

NeuroDebian

NITRC-listed