{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Brain maps dashboard \n",
    "This tutorial shows how to use a NIAK pipeline to generate a dashboard with different brain maps presented as interactive volumetric viewers. \n",
    "  * **More documentation**: in the help of the pipeline, see [code on GitHub](https://github.com/SIMEXP/niak/blob/master/reports/brain_map/niak_brick_report_brain_map.m). \n",
    "  * **.m script**: The notebook and associated Matlab script are available [here](https://nbviewer.jupyter.org/github/SIMEXP/niak_tutorials/blob/master/niak_tutorial_dashboard_brain_map.ipynb).\n",
    "  Pre-requisites**: before running this tutorial, you need to complete the [fMRI preprocessing tutorial]\n",
    "  * **Time for completion**: this tutorial will take 5-10 minutes to complete. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Adding library niak to the search path.\n",
      "\n",
      "Adding library psom to the search path.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "clear\n",
    "path_data = pwd;\n",
    "cd\n",
    "build_path niak psom\n",
    "cd(path_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Preparing files\n",
    "\n",
    "### Background\n",
    "The background is a 3D volume, typically a structural scan. Here we are just going to use the brain template that ships with NIAK (MNI ICBM152 2009)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "clear\n",
    "path_data = [pwd filesep];\n",
    "niak_gb_vars\n",
    "in.background = [GB_NIAK.path_niak filesep 'template' ...\n",
    "                 filesep 'mni-models_icbm152-nl-2009-1.0' filesep ...\n",
    "                 'mni_icbm152_t1_tal_nlin_sym_09a.mnc.gz'];"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overlays\n",
    "We will downlowd a few preprocessed fMRI volumes, to have something to use as overlay. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "[status,msg,data_fmri] = niak_wget('cobre_lightweight20_nii');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We are going to select two random subjects to generate two overlays. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "in.overlay{1} = [data_fmri.path filesep 'fmri_40003.nii.gz'];\n",
    "in.overlay{2} = [data_fmri.path filesep 'fmri_40008.nii.gz'];"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the overlay volumes are assumed to be in the same space (coregistered) with the background, but do not need to have identical sampling grid. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Options\n",
    "We will start by specifying labels for each overlay, which will appear as title for each corresponding viewer in the dashboard."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "opt.labels{1} = 'volume10_subject_40003';\n",
    "opt.labels{2} = 'volume5_subject_40008';"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next we need to tell NIAK where to generate the dashboard:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "opt.folder_out = [path_data filesep 'dashboard_brain_map'];"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's specify some range parameters and a colormap for the viewers. These cannot be adjusted interactively in the viewer. The pipeline will need to re-run with different options in order to adjust the overlay parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "opt.overlay.limits = [0 1300];\n",
    "opt.overlay.thresh = 100;\n",
    "opt.overlay.colormap = 'jet';"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " * The first parameter `limits` sets the min and max for the overlay. Any value below 0 will have the lowest color in the map. Any value above 1300 will have the max color. \n",
    " * The second parameter `thresh` sets a minimum on values to be displayed anything below that is transparent. Note that it is also possible to remove a range of values: `[-0.3 0.3]` would mask out all values between $-0.3$ and $0.3$. Finally, `colormap` is the colormap to use for the overlay. Here we selected the classis (but controversial) jet, but any Octave colormap will work.\n",
    " * Note that equivalent parameters exist for the background, specifically `opt.background.colormap` and `opt.background.limits`. But for structural scans the default values (gray colormap, and adaptative min max) should work fine. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we select the colors for the text and the viewers. Here the structural scan has a black background and we will use a white text. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "opt.color_background = '#FFFFFF'; % those are hexadecimal red/green/blue codes\n",
    "opt.color_font = '#000000';"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We select the number of viewers per row. Different numbers can be specified for different screen size. There are 12 columns available in the layout. Selecting a size of 3 means that each viewer uses 3 columns, and thus 4 viewers will fit on a single row. Here we go with two viewers side by side. See this [documentation](https://www.w3schools.com/bootstrap/bootstrap_grid_system.asp) to learn more on the bootstrap gird layout. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "opt.class_viewer = 'col-lg-6';"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Because the fMRI datasets are 4D (space+time), we need to select which volume to display as an overlay, for each brain viewer. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "opt.ind = [10 5];"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "if a single number was specified, the same volume would be used for all viewers. Here we will look at volume number 10 for the first subject, and volume number 5 for the second one. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Run the pipeline\n",
    "Now let's run the pipeline:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Logs will be stored in /sandbox/home/git/niak_tutorials/dashboard_brain_map/logs/\n",
      "Generating dependencies ...\n",
      "       Reorganizing inputs/outputs ... 0.01 sec\n",
      "       Analyzing job inputs/outputs... 0.00 sec\n",
      "Setting up the to-do list ...\n",
      "   I found 4 job(s) to do, and 1 job(s) already completed.\n",
      "Deamon started on 07-Jun-2017 16:54:34\n",
      "07-Jun-2017 16:54:34 Starting the pipeline manager...\n",
      "07-Jun-2017 16:54:34 Starting the garbage collector...\n",
      "07-Jun-2017 16:54:34 Starting worker number 1...\n",
      "07-Jun-2017 16:54:34 Starting worker number 2...\n",
      "\n",
      "Pipeline started on 07-Jun-2017 16:54:35\n",
      "user: , host: 5269e56ff0d2, system: unix\n",
      "****************************************\n",
      "07-Jun-2017 16:54:36 background                     submitted  (1 run | 0 fail | 1 done | 3 left)\n",
      "07-Jun-2017 16:54:36 overlay_volume10_subject_40003 submitted  (2 run | 0 fail | 1 done | 2 left)\n",
      "07-Jun-2017 16:54:36 overlay_volume5_subject_40008  submitted  (3 run | 0 fail | 1 done | 1 left)\n",
      "07-Jun-2017 16:54:49 overlay_volume10_subject_40003 finished   (2 run | 0 fail | 2 done | 1 left)\n",
      "07-Jun-2017 16:54:49 Stopping idle worker 2 (not enough jobs left to do).\n",
      "07-Jun-2017 16:54:52 background                     finished   (1 run | 0 fail | 3 done | 1 left)\n",
      "07-Jun-2017 16:54:59 overlay_volume5_subject_40008  finished   (0 run | 0 fail | 4 done | 1 left)\n",
      "07-Jun-2017 16:54:59 brain_map_report               submitted  (1 run | 0 fail | 4 done | 0 left)\n",
      "Deamon terminated on 07-Jun-2017 16:55:00\n",
      "\n",
      "07-Jun-2017 16:55:00 brain_map_report               finished   (0 run | 0 fail | 5 done | 0 left)\n",
      "07-Jun-2017 16:55:00 Stopping idle worker 1 (not enough jobs left to do).\n",
      "\n",
      "*******************************************\n",
      "Pipeline terminated on 07-Jun-2017 16:55:00\n",
      "All jobs have been successfully completed.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "opt.flag_test = false; \n",
    "pipeline = niak_report_brain_map(in,opt); "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Reviewing outputs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can open the dashboard by opening the file [dashboard_brain_map/index.html](dashboard_brain_map/index.html). To share that report, simply copy over the folder with all the files. An internet access is not required to use the dashboard. We recommend using Firefox or Chrome for a better experience, although on some OS users may experience some difficulties with one or the other (but hopefully not both)."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Octave",
   "language": "octave",
   "name": "octave"
  },
  "language_info": {
   "file_extension": ".m",
   "help_links": [
    {
     "text": "GNU Octave",
     "url": "https://www.gnu.org/software/octave/support.html"
    },
    {
     "text": "Octave Kernel",
     "url": "https://github.com/Calysto/octave_kernel"
    },
    {
     "text": "MetaKernel Magics",
     "url": "https://github.com/calysto/metakernel/blob/master/metakernel/magics/README.md"
    }
   ],
   "mimetype": "text/x-octave",
   "name": "octave",
   "version": "4.0.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}