{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Getting started with DIPY\n\nIn diffusion MRI (dMRI) usually we use three types of files, a Nifti file with\nthe diffusion weighted data, and two text files one with b-values and\none with the b-vectors.\n\nIn DIPY_ we provide tools to load and process these files and we also provide\naccess to publicly available datasets for those who haven't acquired yet\ntheir own datasets.\n\nWith the following commands we can download a dMRI dataset\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from dipy.data import fetch_sherbrooke_3shell\nfetch_sherbrooke_3shell()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "By default these datasets will go in the ``.dipy`` folder inside your home\ndirectory. Here is how you can access them.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from os.path import expanduser, join\nhome = expanduser('~')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "``dname`` holds the directory name where the 3 files are in.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "dname = join(home, '.dipy', 'sherbrooke_3shell')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Here, we show the complete filenames of the 3 files\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fdwi = join(dname, 'HARDI193.nii.gz')\n\nprint(fdwi)\n\nfbval = join(dname, 'HARDI193.bval')\n\nprint(fbval)\n\nfbvec = join(dname, 'HARDI193.bvec')\n\nprint(fbvec)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "``/home/username/.dipy/sherbrooke_3shell/HARDI193.nii.gz``\n\n``/home/username/.dipy/sherbrooke_3shell/HARDI193.bval``\n\n``/home/username/.dipy/sherbrooke_3shell/HARDI193.bvec``\n\nNow, that we have their filenames we can start checking what these look like.\n\nLet's start first by loading the dMRI datasets. For this purpose, we\nuse a python library called nibabel_ which enables us to read and write\nneuroimaging-specific file formats.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from dipy.io.image import load_nifti\ndata, affine, img = load_nifti(fdwi, return_img=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "``data`` is a 4D array where the first 3 dimensions are the i, j, k voxel\ncoordinates and the last dimension is the number of non-weighted (S0s) and\ndiffusion-weighted volumes.\n\nWe can very easily check the size of ``data`` in the following way:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(data.shape)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "``(128, 128, 60, 193)``\n\nWe can also check the dimensions of each voxel in the following way:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(img.header.get_zooms()[:3])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "``(2.0, 2.0, 2.0)``\n\nWe can quickly visualize the results using matplotlib_. For example,\nlet's show here the middle axial slices of volume 0 and volume 10.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import matplotlib.pyplot as plt\n\naxial_middle = data.shape[2] // 2\nplt.figure('Showing the datasets')\nplt.subplot(1, 2, 1).set_axis_off()\nplt.imshow(data[:, :, axial_middle, 0].T, cmap='gray', origin='lower')\nplt.subplot(1, 2, 2).set_axis_off()\nplt.imshow(data[:, :, axial_middle, 10].T, cmap='gray', origin='lower')\nplt.show()\nplt.savefig('data.png', bbox_inches='tight')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. figure:: data.png\n   :align: center\n\n   Showing the middle axial slice without (left) and with (right) diffusion\n   weighting.\n\nThe next step is to load the b-values and b-vectors from the disk using\nthe function ``read_bvals_bvecs``.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from dipy.io import read_bvals_bvecs\nbvals, bvecs = read_bvals_bvecs(fbval, fbvec)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "In DIPY, we use an object called ``GradientTable`` which holds all the\nacquisition specific parameters, e.g. b-values, b-vectors, timings and others.\nTo create this object you can use the function ``gradient_table``.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from dipy.core.gradients import gradient_table\ngtab = gradient_table(bvals, bvecs)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Finally, you can use ``gtab`` (the GradientTable object) to show some\ninformation about the acquisition parameters\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(gtab.info)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "B-values shape (193,)\n         min 0.000000\n         max 3500.000000\nB-vectors shape (193, 3)\n         min -0.964050\n         max 0.999992\n\nYou can also see the b-values using:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(gtab.bvals)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "::\n\n    [    0.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.\n      1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.\n      1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.\n      1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.\n      1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.\n      1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.  1000.\n      1000.  1000.  1000.  1000.  1000.  2000.  2000.  2000.  2000.  2000.\n      2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.\n      2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.\n      2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.\n      2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.\n      2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.\n      2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  2000.  3500.\n      3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.\n      3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.\n      3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.\n      3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.\n      3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.\n      3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.  3500.\n      3500.  3500.  3500.]\n\nOr, for example the 10 first b-vectors using:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(gtab.bvecs[:10, :])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "::\n\n    array([[ 0.        ,  0.        ,  0.        ],\n           [ 0.999979  , -0.00504001, -0.00402795],\n           [ 0.        ,  0.999992  , -0.00398794],\n           [-0.0257055 ,  0.653861  , -0.756178  ],\n           [ 0.589518  , -0.769236  , -0.246462  ],\n           [-0.235785  , -0.529095  , -0.815147  ],\n           [-0.893578  , -0.263559  , -0.363394  ],\n           [ 0.79784   ,  0.133726  , -0.587851  ],\n           [ 0.232937  ,  0.931884  , -0.278087  ],\n           [ 0.93672   ,  0.144139  , -0.31903   ]])\n\n``gtab``  can be used to tell what part of the data is the S0 volumes\n(volumes which correspond to b-values of 0).\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "S0s = data[:, :, :, gtab.b0s_mask]"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Here, we had only 1 S0 as we can verify by looking at the dimensions of S0s\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "print(S0s.shape)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "``(128, 128, 60, 1)``\n\nJust, for fun let's save this in a new Nifti file.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from dipy.io.image import save_nifti\nsave_nifti('HARDI193_S0.nii.gz', S0s, affine)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Now, that we learned how to load dMRI datasets we can start the analysis.\nSee example `example_reconst_dti` to learn how to create FA maps.\n\n.. include:: ../links_names.inc\n\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "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.13"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}