mvpa2.datasets.eventrelated.extract_boxcar_event_samples

mvpa2.datasets.eventrelated.extract_boxcar_event_samples(ds, events=None, time_attr=None, match='prev', event_offset=None, event_duration=None, eprefix='event', event_mapper=None)

Segment a dataset by extracting boxcar events

(Multiple) consecutive samples are extracted for each event, and are either returned in a flattened shape, or subject to further processing.

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.

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

Attribute with dataset sample time-stamps. 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’}

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.

event_offset : None or float

If not None, all event onset specifications will be offset by this value before boxcar modeling is performed.

event_duration : None or float

If not None, all event duration specifications will be set to this value before boxcar modeling is done.

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.

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.

Returns:

Dataset

One sample per each event definition that has been passed to the function. Additional event attributes are included as sample attributes.

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