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.
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
In [ ]:
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)
In [ ]:
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
...
In [ ]:
!cat /data/ds000114/task-fingerfootlips_events.tsv
We can also use pandas to create a data frame from our dataset.
In [ ]:
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:
In [ ]:
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:
In [ ]:
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