Nipype provides a general purpose model specification mechanism with specialized subclasses for package specific extensions.
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.
conditions : list of names
onsets : lists of onsets corresponding to each condition
left to a single 0 if all events are being modelled as impulses.
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
SPM’s Level1Design.
The following two (tmod, pmod) will be ignored by any Level1Design class other than SPM:
default to None if not being used.
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:
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.
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’.
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.