modalities.fmri.design¶
Module: modalities.fmri.design
¶
Convenience functions for specifying a design in the GLM
Functions¶

nipy.modalities.fmri.design.
block_amplitudes
(name, block_spec, t, hrfs=(glover, ), convolution_padding=5.0, convolution_dt=0.02, hrf_interval=(0.0, 30.0))¶ Design matrix at times t for blocks specification block_spec
Create design matrix for linear model from a block specification block_spec, evaluating design rows at a sequence of time values t.
block_spec may specify amplitude of response for each event, if different (see description of block_spec parameter below).
The onoff step function implied by block_spec will be convolved with each HRF in hrfs to form a design matrix shape
(len(t), len(hrfs))
.Parameters: name : str
Name of condition
block_spec : np.recarray or arraylike
A recarray having fields
start, end, amplitude
, or a 2D ndarray / arraylike with three columns corresponding to start, end, amplitude.t : np.ndarray
An array of np.float values at which to evaluate the design. Common examples would be the acquisition times of an fMRI image.
hrfs : sequence, optional
A sequence of (symbolic) HRFs that will be convolved with each block. Default is
(glover,)
.convolution_padding : float, optional
A padding for the convolution with the HRF. The intervals used for the convolution are the smallest ‘start’ minus this padding to the largest ‘end’ plus this padding.
convolution_dt : float, optional
Time step for highresolution time course for use in convolving the blocks with each HRF.
hrf_interval: length 2 sequence of floats, optional
Interval over which the HRF is assumed supported, used in the convolution.
Returns: X : np.ndarray
The design matrix with
X.shape[0] == t.shape[0]
. The number of columns will belen(hrfs)
.contrasts : dict
A contrast is generated for each HRF specified in hrfs.

nipy.modalities.fmri.design.
block_design
(block_spec, t, order=2, hrfs=(glover, ), convolution_padding=5.0, convolution_dt=0.02, hrf_interval=(0.0, 30.0), level_contrasts=False)¶ Create design matrix at times t for blocks specification block_spec
Create design matrix for linear model from a block specification block_spec, evaluating design rows at a sequence of time values t. Each column in the design matrix will be convolved with each HRF in hrfs.
Parameters: block_spec : np.recarray
A recarray having at least a field named ‘start’ and a field named ‘end’ signifying the block onset and offset times. All other fields will be treated as factors in an ANOVAtype model. If there is no field other than ‘start’ and ‘end’, add a singlelevel placeholder block type
_block_
.t : np.ndarray
An array of np.float values at which to evaluate the design. Common examples would be the acquisition times of an fMRI image.
order : int, optional
The highest order interaction to be considered in constructing the contrast matrices.
hrfs : sequence, optional
A sequence of (symbolic) HRFs that will be convolved with each block. Default is
(glover,)
.convolution_padding : float, optional
A padding for the convolution with the HRF. The intervals used for the convolution are the smallest ‘start’ minus this padding to the largest ‘end’ plus this padding.
convolution_dt : float, optional
Time step for highresolution time course for use in convolving the blocks with each HRF.
hrf_interval: length 2 sequence of floats, optional
Interval over which the HRF is assumed supported, used in the convolution.
level_contrasts : bool, optional
If true, generate contrasts for each individual level of each factor.
Returns: X : np.ndarray
The design matrix with
X.shape[0] == t.shape[0]
. The number of columns will depend on the other fields of block_spec.contrasts : dict
Dictionary of contrasts that are expected to be of interest from the block specification. Each interaction / effect up to a given order will be returned. Also, a contrast is generated for each interaction / effect for each HRF specified in hrfs.

nipy.modalities.fmri.design.
event_design
(event_spec, t, order=2, hrfs=(glover, ), level_contrasts=False)¶ Create design matrix at times t for event specification event_spec
Create a design matrix for linear model based on an event specification event_spec, evaluating the design rows at a sequence of time values t. Each column in the design matrix will be convolved with each HRF in hrfs.
Parameters: event_spec : np.recarray
A recarray having at least a field named ‘time’ signifying the event time, and all other fields will be treated as factors in an ANOVAtype model. If there is no field other than time, add a singlelevel placeholder event type
_event_
.t : np.ndarray
An array of np.float values at which to evaluate the design. Common examples would be the acquisition times of an fMRI image.
order : int, optional
The highest order interaction to be considered in constructing the contrast matrices.
hrfs : sequence, optional
A sequence of (symbolic) HRFs that will be convolved with each event. Default is
(glover,)
.level_contrasts : bool, optional
If True, generate contrasts for each individual level of each factor.
Returns: X : np.ndarray
The design matrix with
X.shape[0] == t.shape[0]
. The number of columns will depend on the other fields of event_spec.contrasts : dict
Dictionary of contrasts that is expected to be of interest from the event specification. Each interaction / effect up to a given order will be returned. Also, a contrast is generated for each interaction / effect for each HRF specified in hrfs.

nipy.modalities.fmri.design.
fourier_basis
(t, freq)¶ Create a design matrix with columns given by the Fourier basis with a given set of frequencies.
Parameters: t : np.ndarray
An array of np.float values at which to evaluate the design. Common examples would be the acquisition times of an fMRI image.
freq : sequence of float
Frequencies for the terms in the Fourier basis.
Returns: X : np.ndarray
Examples
>>> t = np.linspace(0,50,101) >>> drift = fourier_basis(t, np.array([4,6,8])) >>> drift.shape (101, 6)

nipy.modalities.fmri.design.
natural_spline
(tvals, knots=None, order=3, intercept=True)¶ Design matrix with columns given by a natural spline order order
Return design matrix with natural splines with knots knots, order order. If intercept == True (the default), add constant column.
Parameters: tvals : np.array
Time values
knots : None or sequence, optional
Sequence of float. Default None (same as empty list)
order : int, optional
Order of the spline. Defaults to a cubic (==3)
intercept : bool, optional
If True, include a constant function in the natural spline. Default is False
Returns: X : np.ndarray
Examples
>>> tvals = np.linspace(0,50,101) >>> drift = natural_spline(tvals, knots=[10,20,30,40]) >>> drift.shape (101, 8)

nipy.modalities.fmri.design.
openfmri2nipy
(ons_dur_amp)¶ Contents of OpenFMRI condition file ons_dur_map as nipy recarray
Parameters: ons_dur_amp : str or array
Path to OpenFMRI stimulus file or 2D array containing three columns corresponding to onset, duration, amplitude.
Returns: block_spec : array
Structured array with fields “start” (corresponding to onset time), “end” (onset time plus duration), “amplitude”.

nipy.modalities.fmri.design.
stack2designs
(old_X, new_X, old_contrasts={}, new_contrasts={})¶ Add some columns to a design matrix that has contrasts matrices already specified, adding some possibly new contrasts as well.
This basically performs an np.hstack of old_X, new_X and makes sure the contrast matrices are dealt with accordingly.
If two contrasts have the same name, an exception is raised.
Parameters: old_X : np.ndarray
A design matrix
new_X : np.ndarray
A second design matrix to be stacked with old_X
old_contrast : dict
Dictionary of contrasts in the old_X column space
new_contrasts : dict
Dictionary of contrasts in the new_X column space
Returns: X : np.ndarray
A new design matrix: np.hstack([old_X, new_X])
contrasts : dict
The new contrast matrices reflecting changes to the columns.

nipy.modalities.fmri.design.
stack_contrasts
(contrasts, name, keys)¶ Create a new Fcontrast matrix called ‘name’ based on a sequence of keys. The contrast is added to contrasts, inplace.
Parameters: contrasts : dict
Dictionary of contrast matrices
name : str
Name of new contrast. Should not already be a key of contrasts.
keys : sequence of str
Keys of contrasts that are to be stacked.
Returns: None

nipy.modalities.fmri.design.
stack_designs
(*pairs)¶ Stack a sequence of design / contrast dictionary pairs
Uses multiple calls to
stack2designs()
Parameters: *pairs : sequence
Elements of either (np.ndarray, dict) or (np.ndarray,) or np.ndarray
Returns: X : np.ndarray
new design matrix: np.hstack([old_X, new_X])
contrasts : dict
The new contrast matrices reflecting changes to the columns.