{ "cells": [ { "cell_type": "markdown", "id": "d75a91ea", "metadata": {}, "source": [ "# Exporting pyAFQ Results\n", "\n", "This example shows how to use the `export` methods to obtain results from\n", "the ParticipantAFQ object. The `export` methods are used to calculate\n", "derived quantities from the data, such as DKI parameters, tract profiles,\n", "and bundle segmentations." ] }, { "cell_type": "code", "execution_count": null, "id": "a367d240", "metadata": {}, "outputs": [], "source": [ "import os\n", "import os.path as op\n", "import plotly\n", "\n", "from AFQ.api.participant import ParticipantAFQ\n", "import AFQ.data.fetch as afd\n", "import AFQ.definitions.image as afm" ] }, { "cell_type": "markdown", "id": "1a817268", "metadata": {}, "source": [ "## Preparing the ParticipantAFQ object\n", "\n", "In this example, we will create a ParticipantAFQ object based on the\n", "[Participant AFQ API example](plot_002_participant_afq_api). Please refer to that\n", "example for a detailed description of the parameters." ] }, { "cell_type": "code", "execution_count": null, "id": "e189ae1e", "metadata": {}, "outputs": [], "source": [ "afd.fetch_hbn_preproc([\"NDARAA948VFH\"])\n", "\n", "sub_dir = op.join(afd.afq_home, \"HBN\", \"derivatives\", \"qsiprep\",\n", " \"sub-NDARAA948VFH\")\n", "dwi_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\"))\n", "bval_file = op.join(sub_dir, \"ses-HBNsiteRU\", \"dwi\", (\n", " \"sub-NDARAA948VFH_\"\n", " \"ses-HBNsiteRU_\"\n", " \"acq-64dir_space-T1w_desc-preproc_dwi.bval\"))\n", "bvec_file = op.join(sub_dir, \"ses-HBNsiteRU\", \"dwi\", (\n", " \"sub-NDARAA948VFH_\"\n", " \"ses-HBNsiteRU_\"\n", " \"acq-64dir_space-T1w_desc-preproc_dwi.bvec\"))\n", "t1_file = op.join(sub_dir, \"anat\",\n", " \"sub-NDARAA948VFH_desc-preproc_T1w.nii.gz\")\n", "\n", "output_dir = op.join(afd.afq_home, \"HBN\",\n", " \"derivatives\", \"afq\", \"sub-NDARAA948VFH\",\n", " \"ses-HBNsiteRU\", \"dwi\")\n", "os.makedirs(output_dir, exist_ok=True)\n", "\n", "pve = 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\n", "myafq = 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", "id": "3f84319e", "metadata": {}, "source": [ "## The Export Method\n", "The ParticipantAFQ object has a method called `export`, which allows the user\n", "to calculate various derived quantities from the data.\n", "\n", "The `export` method can be called with a string argument that specifies the\n", "type of quantity to be calculated. For example, `myafq.export(\"OPTIONS\")`.\n", "\n", "To list the available options, you can call the `export` method with the\n", "argument \"help\". This will return a list of all the available options for\n", "the `export` method." ] }, { "cell_type": "code", "execution_count": null, "id": "415603bc", "metadata": {}, "outputs": [], "source": [ "myafq.export(\"help\")" ] }, { "cell_type": "markdown", "id": "4c1c7022", "metadata": {}, "source": [ ":::{note}\n", "Not all options are possible even if they are valid. This will depend on\n", "your dataset and pyAFQ API parameters. For example, you cannot calculate\n", "DKI model from single shell data. Please refer to the\n", "[tractography params documentation](/howto/tractography_params) for more documentation.\n", ":::\n", "\n", "## Calculating DTI FA (Diffusion Tensor Imaging Fractional Anisotropy)\n", "\n", "FA can be computed using the DTI model, by explicitly calling\n", "`myafq.export(\"dti_fa\")`. This triggers the computation of DTI parameters,\n", "and stores the results in the AFQ derivatives directory. In addition, it\n", "calculates the FA from these parameters and stores it in a different file in\n", "the same directory.\n", "\n", ":::{note}\n", "The AFQ API computes quantities lazily. This means that DTI parameters\n", "are not computed until they are required. This means that the first\n", "line below is the one that requires time.\n", ":::\n", "\n", "The result of the call to `export` is the filename of the corresponding FA\n", "files." ] }, { "cell_type": "code", "execution_count": null, "id": "bcc3f280", "metadata": {}, "outputs": [], "source": [ "FA_fname = myafq.export(\"dti_fa\")" ] }, { "cell_type": "code", "execution_count": null, "id": "277090d7", "metadata": { "tags": [ "remove-input" ] }, "outputs": [], "source": [ "from AFQ.utils.docs import embed_image, embed_html\n", "\n", "embed_image(FA_fname)" ] }, { "cell_type": "markdown", "id": "b28b998f", "metadata": {}, "source": [ "## Recognizing the bundles and calculating tract profiles:\n", "\n", "Typically, users of pyAFQ are interested in calculating not only an overall\n", "map of the FA, but also the major white matter pathways (or bundles) and\n", "tract profiles of tissue properties along their length. To trigger the\n", "pyAFQ pipeline that calculates the profiles, users can call the\n", "`export(\"profiles\")` method:\n", "\n", ":::{note}\n", "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).\n", ":::" ] }, { "cell_type": "code", "execution_count": null, "id": "709c657e", "metadata": {}, "outputs": [], "source": [ "myafq.export(\"profiles\")" ] }, { "cell_type": "markdown", "id": "022b9d1c", "metadata": {}, "source": [ "## Visualizing the bundles and calculating tract profiles:\n", "\n", "The pyAFQ API provides several ways to visualize bundles and profiles.\n", "\n", "First, we will run a function that exports an html file that contains\n", "an interactive visualization of the bundles that are segmented.\n", "\n", ":::{note}\n", "By default we resample a 100 points within a bundle, however to reduce\n", "processing time we will only resample 50 points.\n", ":::\n", "\n", "Once it is done running, it should pop a browser window open and let you\n", "interact with the bundles.\n", "\n", ":::{note}\n", "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 allow you to pan, zoom, and rotate.\n", ":::" ] }, { "cell_type": "code", "execution_count": null, "id": "1d4a083e", "metadata": { "tags": [ "remove-execution" ] }, "outputs": [], "source": [ "bundle_html = myafq.export(\"all_bundles_figure\")\n", "plotly.io.show(bundle_html[0])" ] }, { "cell_type": "code", "execution_count": null, "id": "2512b235", "metadata": { "tags": [ "remove-input" ] }, "outputs": [], "source": [ "bundle_html = myafq.export(\"all_bundles_figure\")\n", "embed_html(bundle_html[1])" ] }, { "cell_type": "markdown", "id": "7b1d18d0", "metadata": {}, "source": [ "## The Export All Method\n", "There is a `export_all` method that will export all the results from the\n", "AFQ pipeline. Undeerneath the hood, `export_all` calls a series of `export`\n", "methods. This method was added for convenience, and is the recommended method\n", "to use when you want to export everything the results from the AFQ pipeline.\n", "\n", "This 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" ] }, { "cell_type": "code", "execution_count": null, "id": "d783afd2", "metadata": {}, "outputs": [], "source": [ "myafq.export_all()" ] }, { "cell_type": "markdown", "id": "d988447c", "metadata": {}, "source": [ "## The Export Up To Method\n", "The `export_up_to` method allows you to export results up to a certain\n", "point (but not including) in the AFQ pipeline.\n", "\n", "For example, if you want to export all the results up to the bundle\n", "segmentation step, you can call the `export_up_to` method with the\n", "argument \"bundles\". This will export all the required derivatives\n", "prior to the bundle segmentation step, where you can then take the\n", "derivatives and debug your own custom segmentation pipeline." ] }, { "cell_type": "code", "execution_count": null, "id": "83e598b0", "metadata": {}, "outputs": [], "source": [ "myafq.export_up_to(\"bundles\")" ] }, { "cell_type": "markdown", "id": "6def85fa", "metadata": {}, "source": [ ":::{only} html\n", "{download}`Download as Jupyter Notebook `\n", ":::" ] } ], "metadata": { "file_format": "mystnb", "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "name": "python", "pygments_lexer": "ipython3" } }, "nbformat": 4, "nbformat_minor": 5 }