{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# How to use Free water DTI\n\nThe free-water DTI model [1, 2]_ fits a two compartment model to dMRI data\nwith more than one non-zero shell. One compartment is a spherical compartment\nwith the diffusivity of water, which accounts for free water in the tissue.\nThe other compartment is the standard diffusion tensor.\n\nIn this example, we will compare the results of the fwDTI model and the\nstandard DTI model.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import os.path as op\n\nimport matplotlib.pyplot as plt\nimport nibabel as nib\n\nfrom AFQ.api.group import GroupAFQ\nimport AFQ.data.fetch as afd\n\nfrom AFQ.definitions.image import ImageFile, RoiImage\nimport AFQ.api.bundle_dict as abd\n\nimport pandas as pd"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Get some data\nIn this example, we will look at one subject from the Healthy Brain Network\nProcessed Open Diffusion Derivatives dataset (HBN-POD2) [3, 4]_. The data in\nthis study were collected with a multi-shell sequence, meaning that most\nsubjects in this study have data with more than one non-zero b-value. This\nmeans that we can fit the fwDTI model to their data.\n\nWe'll use a fetcher to get preprocessd dMRI data for one of the >2,000\nsubjects in that study. The data gets organized into a BIDS-compatible\nformat in the `~/AFQ_data/HBN` folder.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "study_dir = afd.fetch_hbn_preproc([\"NDARAA948VFH\"])[1]"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Define an AFQ object\nIn addition to preprocessd dMRI data, HBN-POD2 contains brain mask and mapping\ninformation for each subject. We can use this information in our pipeline, by\ninserting this information as `mapping_definition` inputs to the `GroupAFQ` class\ninitializer. When initializing this object, we will also ask for the fwDTI scalars\nto be computed. For expedience, we will limit our investigation to the bilateral\narcuate fasciculus and track only around that bundle. If you would like to do this\nfor all bundles, you would remove the `bundle_dict` and `tracking_params` inputs\nto the initializer that\nare provided below.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "bundle_names = [\"Left Arcuate\", \"Right Arcuate\"]\nbundle_dict = abd.default_bd()[bundle_names]\n\nmyafq = GroupAFQ(\n    bids_path=study_dir,\n    dwi_preproc_pipeline='qsiprep',\n    output_dir=op.join(study_dir, \"derivatives\", \"afq_fwdti\"),\n    bundle_info=bundle_dict,\n    tracking_params={\n        \"n_seeds\": 50000,\n        \"random_seeds\": True,\n        \"seed_mask\": RoiImage(use_waypoints=True, use_endpoints=True),\n    },\n    scalars=[\"fwdti_fa\", \"fwdti_md\", \"fwdti_fwf\", \"dti_fa\", \"dti_md\"])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Compare fwDTI and DTI maps\nFirst, we take a look at the maps for the FA and MD calculated using the two\nmodels\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fwFA = nib.load(myafq.export(\"fwdti_fa\")[\"NDARAA948VFH\"]).get_fdata()\nFA = nib.load(myafq.export(\"dti_fa\")[\"NDARAA948VFH\"]).get_fdata()\n\nfig, ax = plt.subplots(1, 2)\nax[0].matshow(FA[:, :, FA.shape[-1] // 2], cmap='gray')\nax[0].axis(\"off\")\n\nax[1].matshow(fwFA[:, :, fwFA.shape[-1] // 2], cmap='gray')\nax[1].axis(\"off\")\n\n\nfwMD = nib.load(myafq.export(\"fwdti_md\")[\"NDARAA948VFH\"]).get_fdata()\nMD = nib.load(myafq.export(\"dti_md\")[\"NDARAA948VFH\"]).get_fdata()\n\nfig, ax = plt.subplots(1, 2)\nax[0].matshow(MD[:, :, MD.shape[-1] // 2], cmap='gray', vmax=0.005)\nax[0].axis(\"off\")\n\nax[1].matshow(fwMD[:, :, fwMD.shape[-1] // 2], cmap='gray', vmax=0.005)\nax[1].axis(\"off\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Free-water fraction map\nIn addition to the standard tensor scalars, provided by the fwDTI model, this\nmodel also computes a free-water fraction, which is a number between 0 and 1\nthat assesses the fraction of the voxel signal that is explained by the free\nwater compartment.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "fwf = nib.load(myafq.export(\"fwdti_fwf\")[\"NDARAA948VFH\"]).get_fdata()\nfig, ax = plt.subplots()\nax.matshow(fwf[:, :, fwf.shape[-1] // 2], cmap='gray')\nax.axis(\"off\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Comparing bundle profiles\nExporting the profiles will create a CSV file that contains information about\nnode-by-node values of the scalars computed with both models. Here, we read in\nthis information with Pandas and plot a comparison. As you can see, when free\nwater is accounted for with the fwDTI model, FA along the bundle is higher and\nMD is lower than that estimated with the standard DTI model.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "profiles_csv = myafq.export(\"profiles\")['NDARAA948VFH']\nprofiles = pd.read_csv(profiles_csv)\n\nfig, ax = plt.subplots(3, 2)\nfor ii, bundle in enumerate([\"Left Arcuate\", \"Right Arcuate\"]):\n    ax[0, ii].plot(profiles[profiles[\"tractID\"] == bundle][\"fwdti_fa\"],\n                   label=\"fwDTI\")\n    ax[0, ii].plot(profiles[profiles[\"tractID\"] == bundle][\"dti_fa\"],\n                   label=\"DTI\")\n    ax[0, ii].set_ylabel(\"FA\")\n    ax[0, ii].legend()\n    ax[1, ii].plot(profiles[profiles[\"tractID\"] == bundle][\"fwdti_md\"],\n                   label=\"fwDTI\")\n    ax[1, ii].plot(profiles[profiles[\"tractID\"] == bundle][\"dti_md\"],\n                   label=\"DTI\")\n    ax[1, ii].set_ylabel(\"MD\")\n    ax[1, ii].legend()\n    ax[2, ii].plot(profiles[profiles[\"tractID\"] == bundle][\"fwdti_fwf\"])\n    ax[2, ii].set_ylabel(\"Free water fraction\")\n    ax[2, ii].set_xlabel(\"Distance along the bundle (A => P)\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## References\n\n.. [1] Hoy AR, Koay CG, Kecskemeti SR, Alexander AL. Optimization of a free\n    water elimination two-compartment model for diffusion tensor imaging.\n    Neuroimage. 2014;103:323-333.\n\n.. [2] Henriques RN, Rokem A, Garyfallidis E, St-Jean S, Peterson ET, Correia\n    MM. [Re] Optimization of a free water elimination two-compartment model\n    for diffusion tensor imaging. bioRxiv. February 2017:108795.\n    doi:10.1101/108795\n\n.. [3] Alexander LM, Escalera J, Ai L, et al. An open resource for\n    transdiagnostic research in pediatric mental health and learning\n    disorders. Sci Data. 2017;4:170181.\n\n.. [4] Richie-Halford A, Cieslak M, Ai L, et al. An analysis-ready and\n    quality controlled resource for pediatric brain white-matter research.\n    Scientific Data. 2022;9(1):1-27.\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.13.13"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}