# modalities.fmri.design_matrix

## Module: `modalities.fmri.design_matrix`

Inheritance diagram for `nipy.modalities.fmri.design_matrix`:

This module implements fMRI Design Matrix creation.

The DesignMatrix object is just a container that represents the design matrix. Computations of the different parts of the design matrix are confined to the make_dmtx() function, that instantiates the DesignMatrix object. All the remainder are just ancillary functions.

Design matrices contain three different types of regressors:

1. Task-related regressors, that result from the convolution of the experimental paradigm regressors with hemodynamic models

2. User-specified regressors, that represent information available on the data, e.g. motion parameters, physiological data resampled at the acquisition rate, or sinusoidal regressors that model the signal at a frequency of interest.

3. Drift regressors, that represent low_frequency phenomena of no interest in the data; they need to be included to reduce variance estimates.

Author: Bertrand Thirion, 2009-2011

## Class

## `DesignMatrix`

class nipy.modalities.fmri.design_matrix.DesignMatrix(matrix, names, frametimes=None)

  Bases: `object`

  This is a container for a light-weight class for design matrices

  This class is only used to make IO and visualization.

  Attributes:
    matrix: array of shape (n_scans, n_regressors)

      the numerical specification of the matrix.

    names: list of len (n_regressors)

      the names associated with the columns.

    frametimes: array of shape (n_scans), optional

      the occurrence time of the matrix rows.

  __init__(matrix, names, frametimes=None)
  show(rescale=True, ax=None, cmap=None)

    Visualization of a design matrix

    Parameters:
      rescale: bool, optional

        rescale columns magnitude for visualization or not.

      ax: axis handle, optional

        Handle to axis onto which we will draw design matrix.

      cmap: colormap, optional

        Matplotlib colormap to use, passed to imshow.

    Returns:
      ax: axis handle
  show_contrast(contrast, ax=None, cmap=None)

    Plot a contrast for a design matrix.

    Parameters:
      contrast np.float64

        Array forming contrast with respect to the design matrix.

      ax: axis handle, optional

        Handle to axis onto which we will draw design matrix.

      cmap: colormap, optional

        Matplotlib colormap to use, passed to imshow.

    Returns:
      ax: axis handle
  write_csv(path)

    write self.matrix as a csv file with appropriate column names

    Parameters:
      path: string, path of the resulting csv file

    Notes

    The frametimes are not written

## Functions

nipy.modalities.fmri.design_matrix.dmtx_from_csv(path, frametimes=None)

  Return a DesignMatrix instance from a csv file

  Parameters:
    path: string, path of the .csv file
  Returns:
    A DesignMatrix instance

nipy.modalities.fmri.design_matrix.dmtx_light(frametimes, paradigm=None, hrf_model='canonical', drift_model='cosine', hfcut=128, drift_order=1, fir_delays=[0], add_regs=None, add_reg_names=None, min_onset=-24, path=None)

  Make a design matrix while avoiding framework

  Parameters:
    see make_dmtx, plus
    path: string, optional: a path to write the output
  Returns:
    dmtx array of shape(nreg, nbframes):

      the sampled design matrix

    names list of strings of len (nreg)

      the names of the columns of the design matrix

nipy.modalities.fmri.design_matrix.make_dmtx(frametimes, paradigm=None, hrf_model='canonical', drift_model='cosine', hfcut=128, drift_order=1, fir_delays=[0], add_regs=None, add_reg_names=None, min_onset=-24)

  Generate a design matrix from the input parameters

  Parameters:
    frametimes: array of shape(nbframes), the timing of the scans
    paradigm: Paradigm instance, optional

      description of the experimental paradigm

    hrf_model: string, optional,

      that specifies the hemodynamic response function. Can be one of {‘canonical’, ‘canonical with derivative’, ‘fir’, ‘spm’, ‘spm_time’, ‘spm_time_dispersion’}.

    drift_model: string, optional

      specifies the desired drift model, to be chosen among ‘polynomial’, ‘cosine’, ‘blank’

    hfcut: float, optional

      cut period of the low-pass filter

    drift_order: int, optional

      order of the drift model (in case it is polynomial)

    fir_delays: array of shape(nb_onsets) or list, optional,

      in case of FIR design, yields the array of delays used in the FIR model

    add_regs: array of shape(nbframes, naddreg), optional

      additional user-supplied regressors

    add_reg_names: list of (naddreg) regressor names, optional

      if None, while naddreg>0, these will be termed ‘reg_%i’,i=0..naddreg-1

    min_onset: float, optional

      minimal onset relative to frametimes[0] (in seconds) events that start before frametimes[0] + min_onset are not considered

  Returns:
    DesignMatrix instance