Multivariate Pattern Analysis in Python

### Navigation

- index
- modules |
- modules |
- PyMVPA Home |
- Sitemap »

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

### Navigation

- index
- modules |
- modules |
- PyMVPA Home |
- Sitemap »