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:
Task-related regressors, that result from the convolution of the experimental paradigm regressors with hemodynamic models
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.
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:
- contrastnp.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