Multivariate Pattern Analysis in Python

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