{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Exporting pyAFQ Results\n\nThis example shows how to use the ``export`` methods to obtain results from\nthe ParticipantAFQ object. The ``export`` methods are used to calculate\nderived quantities from the data, such as DKI parameters, tract profiles,\nand bundle segmentations. \n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import os\nimport os.path as op\nimport plotly\n\nfrom AFQ.api.participant import ParticipantAFQ\nimport AFQ.data.fetch as afd\nimport AFQ.definitions.image as afm"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Preparing the ParticipantAFQ object\nIn this example, we will create a ParticipantAFQ object based on the\n:doc:`plot_002_participant_afq_api` example. Please refer to that\nexample for a detailed description of the parameters.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "afd.fetch_hbn_preproc([\"NDARAA948VFH\"])\n\nsub_dir = op.join(afd.afq_home, \"HBN\", \"derivatives\", \"qsiprep\",\n                   \"sub-NDARAA948VFH\")\ndwi_data_file = op.join(sub_dir, \"ses-HBNsiteRU\", \"dwi\", (\n    \"sub-NDARAA948VFH_\"\n    \"ses-HBNsiteRU_\"\n    \"acq-64dir_space-T1w_desc-preproc_dwi.nii.gz\"))\nbval_file = op.join(sub_dir, \"ses-HBNsiteRU\", \"dwi\", (\n    \"sub-NDARAA948VFH_\"\n    \"ses-HBNsiteRU_\"\n    \"acq-64dir_space-T1w_desc-preproc_dwi.bval\"))\nbvec_file = op.join(sub_dir, \"ses-HBNsiteRU\", \"dwi\", (\n    \"sub-NDARAA948VFH_\"\n    \"ses-HBNsiteRU_\"\n    \"acq-64dir_space-T1w_desc-preproc_dwi.bvec\"))\nt1_file = op.join(sub_dir, \"anat\",\n                  \"sub-NDARAA948VFH_desc-preproc_T1w.nii.gz\")\n\noutput_dir = op.join(afd.afq_home, \"HBN\",\n                     \"derivatives\", \"afq\", \"sub-NDARAA948VFH\",\n                     \"ses-HBNsiteRU\", \"dwi\")\nos.makedirs(output_dir, exist_ok=True)\n\npve = afm.PVEImages(\n    afm.ImageFile(\n        path=op.join(sub_dir, \"anat\", \n                     \"sub-NDARAA948VFH_label-CSF_probseg.nii.gz\")),\n    afm.ImageFile(\n        path=op.join(sub_dir, \"anat\", \n                     \"sub-NDARAA948VFH_label-GM_probseg.nii.gz\")),\n    afm.ImageFile(\n        path=op.join(sub_dir, \"anat\", \n                     \"sub-NDARAA948VFH_label-WM_probseg.nii.gz\")))\n\n# Initialize the ParticipantAFQ object\nmyafq = ParticipantAFQ(\n    dwi_data_file=dwi_data_file,\n    bval_file=bval_file,\n    bvec_file=bvec_file,\n    t1_file=t1_file,\n    output_dir=output_dir,\n    pve=pve,\n    tracking_params={\n        \"n_seeds\": 10000,\n        \"random_seeds\": True,\n        \"rng_seed\": 2022,\n        \"trx\": True\n    },\n)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## The Export Method\nThe ParticipantAFQ object has a method called ``export``, which allows the user\nto calculate various derived quantities from the data.\n\nThe ``export`` method can be called with a string argument that specifies the\ntype of quantity to be calculated. For example, ``myafq.export(\"OPTIONS\")``.\n\nTo list the available options, you can call the ``export`` method with the\nargument \"help\". This will return a list of all the available options for\nthe ``export`` method.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "myafq.export(\"help\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "<div class=\"alert alert-info\"><h4>Note</h4><p>No all options are possible even if they are valid. This will depend on\n   you dataset and pyAFQ API parameters. For example, you cannot calculate\n   DKI model from single shell data. Please refer to\n   :doc:`/howto/tractography_params` for more documentation.</p></div>\n\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Calculating DKI FA (Diffusion Tensor Imaging Fractional Anisotropy)\nFA can be computed using the DKI model, by explicitly calling\n``myafq.export(\"dki_fa\")``. This triggers the computation of DKI parameters,\nand stores the results in the AFQ derivatives directory. In addition, it\ncalculates the FA from these parameters and stores it in a different file in\nthe same directory.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>The AFQ API computes quantities lazily. This means that DKI parameters\n   are not computed until they are required. This means that the first\n   line below is the one that requires time.</p></div>\n\nThe result of the call to ``export`` is the filename of the corresponding FA\nfiles.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "FA_fname = myafq.export(\"dki_fa\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Recognizing the bundles and calculating tract profiles:\nTypically, users of pyAFQ are interested in calculating not only an overall\nmap of the FA, but also the major white matter pathways (or bundles) and\ntract profiles of tissue properties along their length. To trigger the\npyAFQ pipeline that calculates the profiles, users can call the\n``export(\"profiles\")`` method:\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>Running the code below triggers the full pipeline of operations\n   leading to the computation of the tract profiles. Therefore, it\n   takes a little while to run (about 40 minutes, typically).</p></div>\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "myafq.export(\"profiles\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Visualizing the bundles and calculating tract profiles:\nThe pyAFQ API provides several ways to visualize bundles and profiles.\n\nFirst, we will run a function that exports an html file that contains\nan interactive visualization of the bundles that are segmented.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>By default we resample a 100 points within a bundle, however to reduce\n   processing time we will only resample 50 points.</p></div>\n\nOnce it is done running, it should pop a browser window open and let you\ninteract with the bundles.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>You can hide or show a bundle by clicking the legend, or select a\n   single bundle by double clicking the legend. The interactive\n   visualization will also all you to pan, zoom, and rotate.</p></div>\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "bundle_html = myafq.export(\"all_bundles_figure\")\nplotly.io.show(bundle_html[0])"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## The Export All Method\nThere is a ``export_all`` method that will export all the results from the\nAFQ pipeline. Undeerneath the hood, ``export_all`` calls a series of ``export``\nmethods. This method was added for convenience, and is the recommended method\nto use when you want to export everything the results from the AFQ pipeline.\n\nThis method will export the following results, if possible:\n- Transformation maps and files\n- Start and PVE mask images, associated diffusion scalar files\n- Tractography, segmented tractography in to bundles\n- Tract profiles, streamline counts, median tract length\n- Visuzalizations of the bundles and tract profiles\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "myafq.export_all()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## The Export Up To Method\nThe ``export_up_to`` method allows you to export results up to a certain\npoint (but not including) in the AFQ pipeline.\n\nFor example, if you want to export all the results up to the bundle\nsegmentation step, you can call the ``export_up_to`` method with the\nargument \"bundles\". This will export all the required derivatives\nprior to the bundle segmentation step, where you can then take the\nderivatives and debug your own custom segmentation pipeline.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "myafq.export_up_to(\"bundles\")"
      ]
    }
  ],
  "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
}