Segment a dataset into a set of events.
This function can be used to extract event-related samples from any time-series based dataset (actually, it don’t have to be time series, but could also be any other type of ordered samples). Boxcar-shaped event samples, potentially spanning multiple input samples can be automatically extracted using Event definition lists. For each event all samples covering that particular event are used to form the corresponding sample.
An event definition is a dictionary that contains onset (as sample index in the input dataset), duration (as number of consecutive samples after the onset), as well as an arbitrary number of additional attributes.
Alternatively, onset and duration may also be given as real time stamps (or durations). In this case a to be specified samples attribute in the input dataset will be used to convert these into sample indices.
Parameters : | ds : Dataset
events : list
time_attr : str or None
match : {‘prev’, ‘next’, ‘closest’}
eprefix : str or None
|
---|---|
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]])