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):
event, and are either returned in a flattened shape, or subject to further processing.
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
events : list
model : {‘boxcar’, ‘hrf’}
time_attr : str or None
match : {‘prev’, ‘next’, ‘closest’}
eprefix : str or None
event_mapper : Mapper
condition_attr : str
design_kwargs : dict
glmfit_kwargs : dict
regr_attrs : list
|
---|---|
Returns: | Dataset :
|
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']
mvpa2.datasets.eventrelated.find_events
Enter search terms or a module, class or function name.