demos/MoAE/moae_01_bids_app.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "13de9b92",
   "metadata": {},
   "source": [
    "# MoAE demo\n",
    "\n",
    "This script shows how to use the bidspm BIDS app\n",
    "\n",
    "- **Download**\n",
    "\n",
    "  -  download the dataset from the FIL for the block design SPM tutorial\n",
    "\n",
    "\n",
    "- **Preprocessing**\n",
    "\n",
    "  - copies the necessary data from the raw to the derivative folder,\n",
    "  - runs spatial preprocessing\n",
    "\n",
    "    those are otherwise handled by the workflows:\n",
    "\n",
    "  - ``bidsCopyInputFolder.m``\n",
    "  - ``bidsSpatialPrepro.m``\n",
    "\n",
    "\n",
    "- **Stats**\n",
    "\n",
    "  This will run the subject level GLM and contrasts on it of the MoaE dataset\n",
    "\n",
    "  - GLM specification + estimation\n",
    "  - compute contrasts\n",
    "  - show results\n",
    "\n",
    "  that are otherwise handled by the workflows\n",
    "\n",
    "  - ``bidsFFX.m``\n",
    "  - ``bidsResults.m``\n",
    "\n",
    " .. note::\n",
    "\n",
    "       Results might be a bit different from those in the SPM manual as some\n",
    "       default options are slightly different in this pipeline\n",
    "       (e.g use of FAST instead of AR(1), motion regressors added)\n",
    "\n",
    "\n",
    " type `bidspm help` or `bidspm('action', 'help')`\n",
    " or see this page: https://bidspm.readthedocs.io/en/stable/bids_app_api.html\n",
    " for more information on what parameters are obligatory or optional\n",
    "\n",
    "\n",
    " (C) Copyright 2022 Remi Gau\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "76d1d26b-50a2-499d-9349-12809e6069e8",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Note: octave notebook\n",
    "\n",
    "If you are running in an octave notebook.\n",
    "\n",
    "### Graphic output\n",
    "\n",
    "When using on Binder some of the SPM graphic output will not be generated, \n",
    "as SPM takes this environment as being command line only. \n",
    "\n",
    "### Running the demo locally\n",
    "\n",
    "**If you are running this notebook locally AND if SPM is not the in Octave path**\n",
    "\n",
    "Run the following cell with the appropriate path for your computer.\n",
    "\n",
    "**Note:** \n",
    "SPM will need to be compiled to work for Octave \n",
    "for some parts of this demo to work."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e0e9b1e0",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "% addpath('/home/remi/matlab/SPM/spm12');"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fdde68b2-6c8f-4a03-9564-f00443f3351d",
   "metadata": {},
   "source": [
    "## Initialize bidspm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "08ce31bb",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "this_dir = fileparts(mfilename('fullpath'));\n",
    "\n",
    "addpath(fullfile(this_dir, '..', '..'));\n",
    "\n",
    "bidspm();"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92963b3b",
   "metadata": {},
   "source": [
    "## Download the dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a34cc928",
   "metadata": {},
   "outputs": [],
   "source": [
    "download_data = true;\n",
    "clean = false;\n",
    "download_moae_ds(download_data, clean);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1e754e3",
   "metadata": {},
   "source": [
    "If the `tree` command is installed on your computer, you view it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "116eab45-792c-499a-925a-14695895a3ac",
   "metadata": {},
   "outputs": [],
   "source": [
    "system('tree inputs/raw')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "89e10f7c",
   "metadata": {},
   "source": [
    "## Preprocessing\n",
    "\n",
    "This will run:\n",
    "\n",
    "- copy the input dataset into a derivative one\n",
    "- write a summary description of the data set\n",
    "- do slice time correction (if not ignored and if slice timing is specified)\n",
    "- realign the functional data (and apply unwarping - if not ignored)\n",
    "- coregister the functional to the anatomical one\n",
    "- segmentation the anatomical data\n",
    "- skullstripping the anatomical data and creation of brain mask in native space\n",
    "- normalization to SPM MNI space (IXI549Space)\n",
    "- smooth the data"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dbe6fe64",
   "metadata": {},
   "source": [
    "You can type `bidspm help` to get more info \n",
    "on the arguments and parameters needed by the bidspm app.\n",
    "\n",
    "But it follows the general pattern of any bidsapp:\n",
    "\n",
    "```matlab\n",
    "bidspm(bids_dir, output_dir, analysis_level, ...)\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2afd6329",
   "metadata": {},
   "outputs": [],
   "source": [
    "bidspm help"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8d9dea94",
   "metadata": {},
   "outputs": [],
   "source": [
    "% where the raw bids data is\n",
    "bids_dir = fullfile(this_dir, 'inputs', 'raw');\n",
    "\n",
    "% where we want to output it\n",
    "% the data will be saved there in bidspm-preproc subfolder\n",
    "output_dir = fullfile(this_dir, 'outputs', 'derivatives');\n",
    "\n",
    "% the subject we want to analyse\n",
    "subject_label = '01';\n",
    "\n",
    "verbosity = 3;"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "954c1e4e",
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "bidspm(bids_dir, output_dir, 'subject', ...\n",
    "       'participant_label', {subject_label}, ... \n",
    "       'action', 'preprocess', ...\n",
    "       'task', {'auditory'}, ...\n",
    "       'ignore', {'unwarp', 'slicetiming'}, ...\n",
    "       'space', {'IXI549Space'}, ...\n",
    "       'fwhm', 6, ...\n",
    "       'verbosity', verbosity);"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ea14282b",
   "metadata": {},
   "source": [
    "## Stats"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7e70cfb4",
   "metadata": {},
   "outputs": [],
   "source": [
    "% for the stats we need to specify where the preprocessed data is\n",
    "preproc_dir = fullfile(output_dir, 'bidspm-preproc');"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "58d4fec7",
   "metadata": {},
   "source": [
    "### BIDS stats model\n",
    "\n",
    "The model specification as well as the contrasts to compute\n",
    "are defined in a BIDS stats model:\n",
    "https://bids-standard.github.io/stats-models/"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "309b91a5",
   "metadata": {},
   "outputs": [],
   "source": [
    "model_file = fullfile(pwd, 'models', 'model-MoAE_smdl.json');"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "726646d7",
   "metadata": {},
   "outputs": [],
   "source": [
    "system('cat models/model-MoAE_smdl.json')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cf4d697a",
   "metadata": {},
   "source": [
    "### Specify the result to show\n",
    "\n",
    "Running bidspm for the stats will perform:\n",
    "\n",
    "- model specification and estimation\n",
    "- contrasts computation\n",
    "- displaying the results\n",
    "\n",
    "Hence we need to specify in the options which results\n",
    "we want to view and how we want to save it.\n",
    "\n",
    "The results of a given contrat can be saved as:\n",
    "- an png image\n",
    "- a SPM montage of slices\n",
    "- a thresholded statistical map\n",
    "- a binary mask\n",
    "- an NIDM results zip file\n",
    "- a table of labelled activations\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d9c0e491",
   "metadata": {},
   "outputs": [],
   "source": [
    "bidspm(bids_dir, output_dir, 'subject', ...\n",
    "       'participant_label', {subject_label}, ...\n",
    "       'action', 'stats', ...\n",
    "       'preproc_dir', preproc_dir, ...\n",
    "       'model_file', model_file, ...\n",
    "       'concatenate', false, ...\n",
    "       'fwhm', 6, ...\n",
    "       'verbosity', verbosity);"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Octave",
   "language": "python",
   "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://metakernel.readthedocs.io/en/latest/source/README.html"
    }
   ],
   "mimetype": "text/x-octave",
   "name": "python",
   "version": "3.9.13 | packaged by conda-forge | (main, May 27 2022, 16:58:50) \n[GCC 10.3.0]"
  },
  "vscode": {
   "interpreter": {
    "hash": "57bcab47fba392aaf2481e270a6c32db0c9d247c375febbd49c7b44fb61a4644"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}