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

name : str

Name of condition

block_spec : np.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.

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 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

X : np.ndarray

The design matrix with X.shape[0] == t.shape[0]. The number of columns will be len(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 ANOVA-type model. If there is no field other than ‘start’ and ‘end’, add a single-level 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 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_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 ANOVA-type model. If there is no field other than time, add a single-level 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 F-contrast matrix called ‘name’ based on a sequence of keys. The contrast is added to contrasts, in-place.

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.