Home · Quickstart · Documentation · Citation · NiPy

# Model Specification for First Level fMRI Analysis

Nipype provides a general purpose model specification mechanism with specialized subclasses for package specific extensions.

## General purpose model specification

The `SpecifyModel` provides a generic mechanism for model specification. A mandatory input called subject_info provides paradigm specification for each run corresponding to a subject. This has to be in the form of a `Bunch` or a list of Bunch objects (one for each run). Each Bunch object contains the following attribules.

### Required for most designs

- conditions : list of names

- onsets : lists of onsets corresponding to each condition

- durations : lists of durations corresponding to each condition. Should be

    left to a single 0 if all events are being modelled as impulses.

### Optional

- regressor_names : list of names corresponding to each column. Should be None if automatically assigned.

- regressors : list of lists. values for each regressor - must correspond to the number of volumes in the functional run

- amplitudes : lists of amplitudes for each event. This will be ignored by

    SPM’s Level1Design.

The following two (tmod, pmod) will be ignored by any Level1Design class other than SPM:

- tmod : lists of conditions that should be temporally modulated. Should

    default to None if not being used.

- pmod : list of Bunch corresponding to conditions
    - name : name of parametric modulator
    - param : values of the modulator
    - poly : degree of modulation

An example Bunch definition:

    from nipype.interfaces.base import Bunch
    condnames = ['Tapping', 'Speaking', 'Yawning']
    event_onsets = [[0, 10, 50], [20, 60, 80], [30, 40, 70]]
    durations = [[0],[0],[0]]

    subject_info = Bunch(conditions=condnames,
                                       onsets = event_onsets,
                                       durations = durations)

Alternatively, you can provide condition, onset, duration and amplitude information through event files. The event files have to be in 1,2 or 3 column format with the columns corresponding to Onsets, Durations and Amplitudes and they have to have the name event_name.run<anything else> e.g.: Words.run001.txt. The event_name part will be used to create the condition names. Words.run001.txt may look like:

    # Word Onsets Durations
     0   10
     20   10
     ...

or with amplitudes:

    # Word Onsets Durations Amplitudes
    0    10     1
    20   10    1
    ...

Together with this information, one needs to specify:

- whether the durations and event onsets are specified in terms of scan volumes or secs.
- the high-pass filter cutoff,
- the repetition time per scan
- functional data files corresponding to each run.

Optionally you can specify realignment parameters, outlier indices. Outlier files should contain a list of numbers, one per row indicating which scans should not be included in the analysis. The numbers are 0-based.

## SPM specific attributes

in addition to the generic specification options, several SPM specific options can be provided. In particular, the subject_info function can provide temporal and parametric modulators in the Bunch attributes tmod and pmod. The following example adds a linear parametric modulator for speaking rate for the events specified earlier:

    pmod = [None, Bunch(name=['Rate'], param=[[.300, .500, .600]],
                                         poly=[1]), None]
    subject_info = Bunch(conditions=condnames,
                                        onsets = event_onsets,
                                        durations = durations,
                                        pmod = pmod)

`SpecifySPMModel` also allows specifying additional components. If you have a study with multiple runs, you can choose to concatenate conditions from different runs. by setting the input option concatenate_runs to True. You can also choose to set the output options for this class to be in terms of ‘scans’.

## Sparse model specification

In addition to standard models, `SpecifySparseModel` allows model generation for sparse and sparse-clustered acquisition experiments. Details of the model generation and utility are provided in Ghosh et al. (2009) OHBM 2009.