basic_model_specification.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Model Specification for 1st-Level fMRI Analysis\n",
    "\n",
    "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 [Model Specificaton](http://nipype.readthedocs.io/en/latest/users/model_specification.html) and [nipype.algorithms.modelgen](http://nipype.readthedocs.io/en/latest/interfaces/generated/nipype.algorithms.modelgen.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simple Example\n",
    "\n",
    "Let's consider a simple experiment, where we have three different stimuli such as ``'faces'``, ``'houses'`` and ``'scrambled pix'``. Now each of those three conditions has different stimuli onsets, but all of them have a stimuli presentation duration of 3 seconds.\n",
    "\n",
    "So to summarize:\n",
    "\n",
    "    conditions = ['faces', 'houses', 'scrambled pix']\n",
    "    onsets = [[0, 30, 60, 90],\n",
    "              [10, 40, 70, 100],\n",
    "              [20, 50, 80, 110]]\n",
    "    durations = [[3], [3], [3]]\n",
    "    \n",
    "The way we would create this model with Nipype is almsot as simple as that. The only step that is missing is to put this all into a ``Bunch`` object. This can be done as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "from nipype.interfaces.base import Bunch\n",
    "\n",
    "conditions = ['faces', 'houses', 'scrambled pix']\n",
    "onsets = [[0, 30, 60, 90],\n",
    "          [10, 40, 70, 100],\n",
    "          [20, 50, 80, 110]]\n",
    "durations = [[3], [3], [3]]\n",
    "\n",
    "subject_info = Bunch(conditions=conditions,\n",
    "                     onsets=onsets,\n",
    "                     durations=durations)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It's also possible to specify additional regressors. For this you need to additionally specify:\n",
    "\n",
    "- **``regressors``**: list of regressors that you want to include in the model (must correspond to the number of volumes in the functional run)\n",
    "- **``regressor_names``**: name of the regressors that you want to include"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example based on dataset\n",
    "\n",
    "Now for a more realistic example, let's look at a TVA file from our tutorial dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false,
    "deletable": true,
    "editable": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "onset\tduration\ttrial_type\tresponse_time\tcorrectness\tStimVar\tRsponse\tStimulus\tcond\r\n",
      "0.0\t2.0\tincongruent_correct\t1.095\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "10.0\t2.0\tincongruent_correct\t0.988\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "20.0\t2.0\tcongruent_correct\t0.591\tcorrect\t1\t1\tcongruent\tcond001\r\n",
      "30.0\t2.0\tcongruent_correct\t0.499\tcorrect\t1\t1\tcongruent\tcond001\r\n",
      "40.0\t2.0\tincongruent_correct\t0.719\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "52.0\t2.0\tcongruent_correct\t0.544\tcorrect\t1\t1\tcongruent\tcond001\r\n",
      "64.0\t2.0\tcongruent_correct\t0.436\tcorrect\t1\t1\tcongruent\tcond001\r\n",
      "76.0\t2.0\tincongruent_correct\t0.47\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "88.0\t2.0\tcongruent_correct\t0.409\tcorrect\t1\t1\tcongruent\tcond001\r\n",
      "102.0\t2.0\tincongruent_correct\t0.563\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "116.0\t2.0\tcongruent_correct\t0.493\tcorrect\t1\t1\tcongruent\tcond001\r\n",
      "130.0\t2.0\tcongruent_correct\t0.398\tcorrect\t1\t1\tcongruent\tcond001\r\n",
      "140.0\t2.0\tcongruent_correct\t0.466\tcorrect\t1\t1\tcongruent\tcond001\r\n",
      "150.0\t2.0\tincongruent_correct\t0.518\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "164.0\t2.0\tincongruent_correct\t0.56\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "174.0\t2.0\tincongruent_correct\t0.533\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "184.0\t2.0\tcongruent_correct\t0.439\tcorrect\t1\t1\tcongruent\tcond001\r\n",
      "196.0\t2.0\tcongruent_correct\t0.458\tcorrect\t1\t1\tcongruent\tcond001\r\n",
      "208.0\t2.0\tincongruent_correct\t0.734\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "220.0\t2.0\tincongruent_correct\t0.479\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "232.0\t2.0\tincongruent_correct\t0.538\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "246.0\t2.0\tcongruent_correct\t0.54\tcorrect\t1\t1\tcongruent\tcond001\r\n",
      "260.0\t2.0\tincongruent_correct\t0.622\tcorrect\t2\t1\tincongruent\tcond003\r\n",
      "274.0\t2.0\tcongruent_correct\t0.488\tcorrect\t1\t1\tcongruent\tcond001\r\n"
     ]
    }
   ],
   "source": [
    "!cat /data/ds102/sub-01/func/sub-01_task-flanker_run-1_events.tsv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, the only things that we need to specify our model are the onset and the stimuli type, i.e. **column 0** and **column 5 or 7**. Those we can get with the command:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "filename = '/data/ds102/sub-01/func/sub-01_task-flanker_run-1_events.tsv'\n",
    "trailinfo = np.genfromtxt(filename, delimiter='\\t', dtype=None, skip_header=1)\n",
    "trailinfo = [[t[0], t[7]] for t in trailinfo]\n",
    "trailinfo"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Before we can use the onsets, we first need to split them into the two conditions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "onset1 = []\n",
    "onset2 = []\n",
    "\n",
    "for t in trailinfo:\n",
    "    if 'incongruent' in t[1]:\n",
    "        onset2.append(t[0])\n",
    "    else:\n",
    "        onset1.append(t[0])\n",
    "\n",
    "print onset1\n",
    "print onset2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The last thing we now need to to is to put this into a ``Bunch`` object and we're done:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "from nipype.interfaces.base import Bunch\n",
    "\n",
    "conditions = ['congruent', 'incongruent']\n",
    "onsets = [onset1, onset2]\n",
    "durations = [[2], [2]]\n",
    "\n",
    "subject_info = Bunch(conditions=conditions,\n",
    "                     onsets=onsets,\n",
    "                     durations=durations)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [default]",
   "language": "python",
   "name": "python2"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 2
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython2",
   "version": "2.7.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}