Model Specification for 1st-Level fMRI Analysis

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.

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 attributes.

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 modeled 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

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

Example

An example Bunch definition:



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

Input via textfile

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

Example based on dataset

Now let's look at a TSV file from our tutorial dataset.



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()

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