mvpa2.datasets.eventrelated.eventrelated_dataset

mvpa2.datasets.eventrelated.eventrelated_dataset(ds, events=None, time_attr=None, match='prev', eprefix='event')

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

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 or None

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.

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

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

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.

Returns:

Dataset :

The returned dataset has one sample per each event definition that has been passed to the function.

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]])

NeuroDebian

NITRC-listed