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 on-off 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:
- namestr
Name of condition
- block_specnp.recarray or array-like
A recarray having fields
start, end, amplitude
, or a 2D ndarray / array-like with three columns corresponding to start, end, amplitude.- tnp.ndarray
An array of np.float64 values at which to evaluate the design. Common examples would be the acquisition times of an fMRI image.
- hrfssequence, optional
A sequence of (symbolic) HRFs that will be convolved with each block. Default is
(glover,)
.- convolution_paddingfloat, 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_dtfloat, optional
Time step for high-resolution 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:
- Xnp.ndarray
The design matrix with
X.shape[0] == t.shape[0]
. The number of columns will belen(hrfs)
.- contrastsdict
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_specnp.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 ANOVA-type model. If there is no field other than ‘start’ and ‘end’, add a single-level placeholder block type
_block_
.- tnp.ndarray
An array of np.float64 values at which to evaluate the design. Common examples would be the acquisition times of an fMRI image.
- orderint, optional
The highest order interaction to be considered in constructing the contrast matrices.
- hrfssequence, optional
A sequence of (symbolic) HRFs that will be convolved with each block. Default is
(glover,)
.- convolution_paddingfloat, 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_dtfloat, optional
Time step for high-resolution 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_contrastsbool, optional
If true, generate contrasts for each individual level of each factor.
- Returns:
- Xnp.ndarray
The design matrix with
X.shape[0] == t.shape[0]
. The number of columns will depend on the other fields of block_spec.- contrastsdict
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_specnp.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 ANOVA-type model. If there is no field other than time, add a single-level placeholder event type
_event_
.- tnp.ndarray
An array of np.float64 values at which to evaluate the design. Common examples would be the acquisition times of an fMRI image.
- orderint, optional
The highest order interaction to be considered in constructing the contrast matrices.
- hrfssequence, optional
A sequence of (symbolic) HRFs that will be convolved with each event. Default is
(glover,)
.- level_contrastsbool, optional
If True, generate contrasts for each individual level of each factor.
- Returns:
- Xnp.ndarray
The design matrix with
X.shape[0] == t.shape[0]
. The number of columns will depend on the other fields of event_spec.- contrastsdict
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:
- tnp.ndarray
An array of np.float64 values at which to evaluate the design. Common examples would be the acquisition times of an fMRI image.
- freqsequence of float
Frequencies for the terms in the Fourier basis.
- Returns:
- Xnp.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:
- tvalsnp.array
Time values
- knotsNone or sequence, optional
Sequence of float. Default None (same as empty list)
- orderint, optional
Order of the spline. Defaults to a cubic (==3)
- interceptbool, optional
If True, include a constant function in the natural spline. Default is False
- Returns:
- Xnp.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_ampstr or array
Path to OpenFMRI stimulus file or 2D array containing three columns corresponding to onset, duration, amplitude.
- Returns:
- block_specarray
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_Xnp.ndarray
A design matrix
- new_Xnp.ndarray
A second design matrix to be stacked with old_X
- old_contrastdict
Dictionary of contrasts in the old_X column space
- new_contrastsdict
Dictionary of contrasts in the new_X column space
- Returns:
- Xnp.ndarray
A new design matrix: np.hstack([old_X, new_X])
- contrastsdict
The new contrast matrices reflecting changes to the columns.
- nipy.modalities.fmri.design.stack_contrasts(contrasts, name, keys)¶
Create a new F-contrast matrix called ‘name’ based on a sequence of keys. The contrast is added to contrasts, in-place.
- Parameters:
- contrastsdict
Dictionary of contrast matrices
- namestr
Name of new contrast. Should not already be a key of contrasts.
- keyssequence 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:
- *pairssequence
Elements of either (np.ndarray, dict) or (np.ndarray,) or np.ndarray
- Returns:
- Xnp.ndarray
new design matrix: np.hstack([old_X, new_X])
- contrastsdict
The new contrast matrices reflecting changes to the columns.