Merge branch 'master' into models

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-20.04]
-        python-version: ["3.9", "3.8", "3.7"]
+        python-version: ["3.10", "3.9", "3.8", "3.7"]
 
     steps:
       - uses: actions/checkout@v2

.gitignore

@@ -136,3 +136,9 @@ dmypy.json
 
 # Cython debug symbols
 cython_debug/
+
+# pycharm
+.idea/
+
+# guide data
+guide/data/

.pre-commit-config.yaml

@@ -5,18 +5,18 @@ ci:
 
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.1.0
+    rev: v4.3.0
     hooks:
     -   id: check-added-large-files
     -   id: check-yaml
     -   id: end-of-file-fixer
     -   id: trailing-whitespace
 -   repo: https://github.com/psf/black
-    rev: 22.1.0
+    rev: 22.6.0
     hooks:
     -   id: black
 -   repo: https://github.com/PyCQA/flake8
-    rev: 4.0.1
+    rev: 5.0.4
     hooks:
     - id: flake8
 -   repo: https://github.com/PyCQA/isort

guide/api_train_binary_segmentation.ipynb

@@ -0,0 +1,319 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "ijHnNTIjDkt0"
+   },
+   "source": [
+    "# Train a neural network for binary volumetric segmentation\n",
+    "\n",
+    "In this notebook, we will use Nobrainer to train a model for brain extraction. Brain extraction is a common step in processing neuroimaging data. It is a voxel-wise, binary classification task, where each voxel is classified as brain or not brain. Incidentally, the name for the Nobrainer framework comes from creating models for brain extraction.\n",
+    "\n",
+    "In the following cells, we will:\n",
+    "\n",
+    "1. Get sample T1-weighted MR scans as features and FreeSurfer segmentations as labels.\n",
+    "    - We will binarize the FreeSurfer to get a precise brainmask.\n",
+    "2. Convert the data to TFRecords format.\n",
+    "3. Create two Datasets of the features and labels.\n",
+    "    - One dataset will be for training and the other will be for evaluation.\n",
+    "4. Instantiate a 3D convolutional neural network.\n",
+    "5. Choose a loss function and metrics to use.\n",
+    "6. Train on part of the data.\n",
+    "7. Evaluate on the rest of the data.\n",
+    "\n",
+    "## Google Colaboratory\n",
+    "\n",
+    "If you are using Colab, please switch your runtime to GPU. To do this, select `Runtime > Change runtime type` in the top menu. Then select GPU under `Hardware accelerator`. A GPU greatly speeds up training."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "WhBnt2WdDlx9"
+   },
+   "outputs": [],
+   "source": [
+    "!pip install --no-cache-dir nilearn https://github.com/neuronets/nobrainer/archive/refs/heads/enh/api.zip"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "Ht_CGSk1Dkt3"
+   },
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "os.environ['TF_CPP_MIN_LOG_LEVEL'] = '2' \n",
+    "import nobrainer\n",
+    "import tensorflow as tf"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "hVCchp9uDkt3"
+   },
+   "source": [
+    "# Get sample features and labels\n",
+    "\n",
+    "We use 9 pairs of volumes for training and 1 pair of volumes for evaluation. Many more volumes would be required to train a model for any useful purpose."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "YpqTxNu4Dkt4"
+   },
+   "outputs": [],
+   "source": [
+    "csv_of_filepaths = nobrainer.utils.get_data()\n",
+    "filepaths = nobrainer.io.read_csv(csv_of_filepaths)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "m3P3BUQKiCjg"
+   },
+   "source": [
+    "Here is an example of one training pair, with the brainmask overlaid on the anatomical image."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "filepaths[0]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "9tAhbM4ChgIj"
+   },
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "from nilearn import plotting\n",
+    "fig = plt.figure(figsize=(12, 6))\n",
+    "plotting.plot_roi(filepaths[0][1], bg_img=filepaths[0][0], alpha=0.4, vmin=0, vmax=1.5, figure=fig)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "id": "ScgF78rmDkt4"
+   },
+   "source": [
+    "# Convert medical images to TFRecords\n",
+    "\n",
+    "Remember how many full volumes are in the TFRecords files. This will be necessary to know how many steps are in on training epoch. The default training method needs to know this number, because Datasets don't always know how many items they contain."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "n7lCL-55Ta4R"
+   },
+   "outputs": [],
+   "source": [
+    "from nobrainer.dataset import Dataset"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "Q3zPyRlbTa4R"
+   },
+   "outputs": [],
+   "source": [
+    "n_epochs = 2\n",
+    "DT = Dataset(n_classes=1,\n",
+    "             batch_size=2,\n",
+    "             block_shape=(128, 128, 128),\n",
+    "             n_epochs=n_epochs)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "ABkdYOFyTa4S"
+   },
+   "outputs": [],
+   "source": [
+    "dataset_train, dataset_eval = DT.to_nbd(paths=filepaths,\n",
+    "                                        eval_size=0.1,\n",
+    "                                        tfrecdir=\"data/binseg\",\n",
+    "                                        shard_size=3,\n",
+    "                                        augment=None,\n",
+    "                                        shuffle_buffer_size=10,\n",
+    "                                        num_parallel_calls=None)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "X8u_owicTa4T"
+   },
+   "outputs": [],
+   "source": [
+    "from nobrainer.processing.segmentation import Segmentation\n",
+    "from nobrainer.models import unet"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "RhJ7upa5Ta4T"
+   },
+   "outputs": [],
+   "source": [
+    "bem = Segmentation(unet, model_args=dict(batchnorm=True))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "oKQm8qrOTa4U"
+   },
+   "outputs": [],
+   "source": [
+    "bem.fit(dataset_train=dataset_train,\n",
+    "        dataset_validate=dataset_eval,\n",
+    "        epochs=n_epochs,\n",
+    "        # optimizer = tf.keras.optimizers.Adam,\n",
+    "        # opt_args = dict(learning_rate=1e-04),\n",
+    "        # loss=nobrainer.losses.dice,\n",
+    "        # metrics=[nobrainer.metrics.dice, nobrainer.metrics.jaccard]\n",
+    "       )"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "OWqLu2xFTa4U"
+   },
+   "outputs": [],
+   "source": [
+    "from nobrainer.volume import standardize\n",
+    "\n",
+    "image_path = filepaths[0][0]\n",
+    "out = bem.predict(image_path, normalizer=standardize)\n",
+    "out.shape"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "4xJxR7Ddbd-0"
+   },
+   "outputs": [],
+   "source": [
+    "fig = plt.figure(figsize=(12, 6))\n",
+    "plotting.plot_roi(out, bg_img=image_path, alpha=0.4, vmin=0, vmax=5, figure=fig)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "1. Save model\n",
+    "2. Load model back as a class instance\n",
+    "3. Perform prediction\n",
+    "4. Continue training"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bem.save(\"data/testsave\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from nobrainer.processing.segmentation import Segmentation\n",
+    "bem = Segmentation.load(\"data/testsave\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "image_path = filepaths[0][0]\n",
+    "out = bem.predict(image_path, normalizer=standardize)\n",
+    "out.shape"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "bem.fit(dataset_train=dataset_train,\n",
+    "        dataset_validate=dataset_eval,\n",
+    "        epochs=1,\n",
+    "        warm_start=True\n",
+    "       )"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "accelerator": "GPU",
+  "colab": {
+   "name": "train_binary_segmentation.ipynb",
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}