Nipype provides also an interfaces to create a first level Model for an fMRI analysis. Such a model is needed to specify the study-specific information, such as condition, their onsets, and durations. For more information, make sure to check out nipype.algorithms.modelgen.
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 attributes.
conditions : list of namesonsets : lists of onsets corresponding to each conditiondurations : lists of durations corresponding to each condition. Should be left to a single 0 if all events are being modeled 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 runamplitudes: 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 modulatorparam: values of the modulatorpoly: degree of modulationTogether 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
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)
subject_info
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.runWords.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
...Now let's look at a TSV file from our tutorial dataset.
!cat /data/ds000114/task-fingerfootlips_events.tsv
We can also use pandas to create a data frame from our dataset.
import pandas as pd
trialinfo = pd.read_table('/data/ds000114/task-fingerfootlips_events.tsv')
trialinfo.head()
Before we can use the onsets, we first need to split them into the three conditions:
for group in trialinfo.groupby('trial_type'):
print(group)
The last thing we now need to to is to put this into a Bunch object and we're done:
from nipype.interfaces.base import Bunch
conditions = []
onsets = []
durations = []
for group in trialinfo.groupby('trial_type'):
conditions.append(group[0])
onsets.append(group[1].onset.tolist())
durations.append(group[1].duration.tolist())
subject_info = Bunch(conditions=conditions,
onsets=onsets,
durations=durations)
subject_info.items()
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