# modalities.fmri.design¶

## 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. 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. 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. 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. 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 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. 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 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. 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 X : np.ndarray new design matrix: np.hstack([old_X, new_X]) contrasts : dict The new contrast matrices reflecting changes to the columns.