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 be len(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.