<commit_before>{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interfaces\n",
    "\n",
    "In Nipype, interfaces are python modules that allow you to use various external packages (e.g. FSL, SPM or FreeSurfer), even if they themselves are written in another programming language than python. Such an interface knows what sort of options an external program has and how to execute it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interfaces vs. Workflows\n",
    "\n",
    "Interfaces are the building blocks that solve well-defined tasks. We solve more complex tasks by combining interfaces with workflows:\n",
    "\n",
    "<table style=\"width: 100%; font-size: 14px;\">\n",
    "  <thead>\n",
    "    <th style=\"text-align:left\">Interfaces</th>\n",
    "    <th style=\"text-align:left\">Workflows</th>\n",
    "  </thead>\n",
    "  <tbody>\n",
    "    <tr>\n",
    "      <td style=\"text-align:left\">Wrap *unitary* tasks</td>\n",
    "      <td style=\"text-align:left\">Wrap *meta*-tasks\n",
    "        <li style=\"text-align:left\">implemented with nipype interfaces wrapped inside ``Node`` objects</li>\n",
    "        <li style=\"text-align:left\">subworkflows can also be added to a workflow without any wrapping</li>\n",
    "      </td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "      <td style=\"text-align:left\">Keep track of the inputs and outputs, and check their expected types</td>\n",
    "      <td style=\"text-align:left\">Do not have inputs/outputs, but expose them from the interfaces wrapped inside</td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "      <td style=\"text-align:left\">Do not cache results (unless you use [interface caching](advanced_interfaces_caching.ipynb))</td>\n",
    "      <td style=\"text-align:left\">Cache results</td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "      <td style=\"text-align:left\">Run by a nipype plugin</td>\n",
    "      <td style=\"text-align:left\">Run by a nipype plugin</td>\n",
    "    </tr>\n",
    "  </tbody>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To illustrate why interfaces are so useful, let's have a look at the brain extraction algorithm [BET](http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/BET) from FSL. Once in its original framework and once in the Nipype framework."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## BET in the original framework\n",
    "\n",
    "Let's take a look at one of the T1 images we have in our dataset on which we want to run BET."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nilearn.plotting import plot_anat\n",
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "plot_anat('/data/ds000114/sub-01/ses-test/anat/sub-01_ses-test_T1w.nii.gz', title='original',\n",
    "          display_mode='ortho', dim=-1, draw_cross=False, annotate=False);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In its simplest form, you can run BET by just specifying the input image and tell it what to name the output image:\n",
    "\n",
    "    bet <input> <output>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "\n",
    "FILENAME=/data/ds000114/sub-01/ses-test/anat/sub-01_ses-test_T1w\n",
    "\n",
    "bet ${FILENAME}.nii.gz /output/sub-01_ses-test_T1w_bet.nii.gz"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's take a look at the results:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_anat('/output/sub-01_ses-test_T1w_bet.nii.gz', title='original',\n",
    "          display_mode='ortho', dim=-1, draw_cross=False, annotate=False);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Perfect! Exactly what we want. Hmm... what else could we want from BET? Well, it's actually a fairly complicated program. As is the case for all FSL binaries, just call it with the help flag `-h` to see all its options."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "bet -h"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see that BET can also return a binary brain mask as a result of the skull-strip, which can be useful for masking our GLM analyses (among other things). Let's run it again including that option and see the result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},<commit_msg>WIP: update bet command to oneliner<commit_after>{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Interfaces\n",
    "\n",
    "In Nipype, interfaces are python modules that allow you to use various external packages (e.g. FSL, SPM or FreeSurfer), even if they themselves are written in another programming language than python. Such an interface knows what sort of options an external program has and how to execute it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Interfaces vs. Workflows\n",
    "\n",
    "Interfaces are the building blocks that solve well-defined tasks. We solve more complex tasks by combining interfaces with workflows:\n",
    "\n",
    "<table style=\"width: 100%; font-size: 14px;\">\n",
    "  <thead>\n",
    "    <th style=\"text-align:left\">Interfaces</th>\n",
    "    <th style=\"text-align:left\">Workflows</th>\n",
    "  </thead>\n",
    "  <tbody>\n",
    "    <tr>\n",
    "      <td style=\"text-align:left\">Wrap *unitary* tasks</td>\n",
    "      <td style=\"text-align:left\">Wrap *meta*-tasks\n",
    "        <li style=\"text-align:left\">implemented with nipype interfaces wrapped inside ``Node`` objects</li>\n",
    "        <li style=\"text-align:left\">subworkflows can also be added to a workflow without any wrapping</li>\n",
    "      </td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "      <td style=\"text-align:left\">Keep track of the inputs and outputs, and check their expected types</td>\n",
    "      <td style=\"text-align:left\">Do not have inputs/outputs, but expose them from the interfaces wrapped inside</td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "      <td style=\"text-align:left\">Do not cache results (unless you use [interface caching](advanced_interfaces_caching.ipynb))</td>\n",
    "      <td style=\"text-align:left\">Cache results</td>\n",
    "    </tr>\n",
    "    <tr>\n",
    "      <td style=\"text-align:left\">Run by a nipype plugin</td>\n",
    "      <td style=\"text-align:left\">Run by a nipype plugin</td>\n",
    "    </tr>\n",
    "  </tbody>\n",
    "</table>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To illustrate why interfaces are so useful, let's have a look at the brain extraction algorithm [BET](http://fsl.fmrib.ox.ac.uk/fsl/fslwiki/BET) from FSL. Once in its original framework and once in the Nipype framework."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## BET in the original framework\n",
    "\n",
    "Let's take a look at one of the T1 images we have in our dataset on which we want to run BET."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nilearn.plotting import plot_anat\n",
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "plot_anat('/data/ds000114/sub-01/ses-test/anat/sub-01_ses-test_T1w.nii.gz', title='original',\n",
    "          display_mode='ortho', dim=-1, draw_cross=False, annotate=False);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In its simplest form, you can run BET by just specifying the input image and tell it what to name the output image:\n",
    "\n",
    "    bet <input> <output>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "\n",
    "FILENAME=/data/ds000114/sub-01/ses-test/anat/sub-01_ses-test_T1w\n",
    "\n",
    "bet ${FILENAME}.nii.gz /output/sub-01_ses-test_T1w_bet.nii.gz"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's take a look at the results:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_anat('/output/sub-01_ses-test_T1w_bet.nii.gz', title='original',\n",
    "          display_mode='ortho', dim=-1, draw_cross=False, annotate=False);"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Perfect! Exactly what we want. Hmm... what else could we want from BET? Well, it's actually a fairly complicated program. As is the case for all FSL binaries, just call it with the help flag `-h` to see all its options."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "!bet"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We see that BET can also return a binary brain mask as a result of the skull-strip, which can be useful for masking our GLM analyses (among other things). Let's run it again including that option and see the result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
{'fraction_non_alphanumeric': 0.18083126550868486, 'fraction_numerical': 0.007444168734491315, 'mean_word_length': 2.7347490347490346, 'pattern_counts': {'":': 96, '<': 83, '<?xml version=': 0, '>': 83, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7369317', 'n_tokens_mistral': 3448, 'n_tokens_neox': 3330, 'n_words': 899}