# 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.float64 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.float64 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.float64 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.float64 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.