{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5f42c8f7",
   "metadata": {},
   "source": [
    "# How to add new bundles into pyAFQ (Acoustic Radiations Example)\n",
    "\n",
    "pyAFQ is designed to be customizable and extensible. This example shows how you\n",
    "can customize it to define a new bundle based on a definition of waypoint and\n",
    "endpoint ROIs of your design. In this case, we add the acoustic radiations.\n",
    "\n",
    "We start by importing some of the components that we need for this example and\n",
    "fixing the random seed for reproducibility.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a6470559",
   "metadata": {},
   "outputs": [],
   "source": [
    "from paths import afq_home\n",
    "\n",
    "import os.path as op\n",
    "import plotly\n",
    "import numpy as np\n",
    "\n",
    "from AFQ.api.group import GroupAFQ\n",
    "import AFQ.api.bundle_dict as abd\n",
    "import AFQ.data.fetch as afd\n",
    "from AFQ.definitions.image import ImageFile, RoiImage\n",
    "\n",
    "np.random.seed(1234)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9c20ca0",
   "metadata": {},
   "source": [
    "## Get dMRI data\n",
    "\n",
    "We will analyze one subject from the Healthy Brain Network Processed Open\n",
    "Diffusion Derivatives dataset (HBN-POD2) [](https://doi.org/10.1038/s41597-022-01695-7). We'll use a fetcher to\n",
    "get preprocessed dMRI data for one of the >2,000 subjects in that study.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bddfaccd",
   "metadata": {},
   "outputs": [],
   "source": [
    "study_dir = afd.fetch_hbn_preproc([\"NDARAA948VFH\"])[1]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "98fa0ad1",
   "metadata": {},
   "source": [
    "## Define custom `BundleDict` object\n",
    "\n",
    "The `BundleDict` object holds information about \"include\" and \"exclude\" ROIs,\n",
    "as well as endpoint ROIs, and whether the bundle crosses the midline.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5d0b4f04",
   "metadata": {},
   "outputs": [],
   "source": [
    "ar_rois = afd.read_ar_templates()\n",
    "\n",
    "bundles = abd.BundleDict({\n",
    "    \"Left Acoustic Radiation\": {\n",
    "        \"start\": ar_rois[\"AAL_Thal_L\"],\n",
    "        \"end\": ar_rois[\"AAL_TempSup_L\"],\n",
    "        \"cross_midline\": False,\n",
    "    },\n",
    "    \"Right Acoustic Radiation\": {\n",
    "        \"start\": ar_rois[\"AAL_Thal_R\"],\n",
    "        \"end\": ar_rois[\"AAL_TempSup_R\"],\n",
    "        \"cross_midline\": False\n",
    "    }\n",
    "})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "83daa8c1",
   "metadata": {},
   "source": [
    "## Define GroupAFQ object\n",
    "\n",
    "For tractography, we use CSD-based probabilistic tractography seeding\n",
    "extensively (`n_seeds=4` means 81 seeds per voxel!), but only within the ROIs.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a4ac9fe3",
   "metadata": {},
   "outputs": [],
   "source": [
    "brain_mask_definition = ImageFile(\n",
    "    suffix=\"mask\",\n",
    "    filters={'desc': 'brain',\n",
    "             'space': 'T1w',\n",
    "             'scope': 'qsiprep'})\n",
    "\n",
    "my_afq = GroupAFQ(\n",
    "    bids_path=study_dir,\n",
    "    preproc_pipeline=\"qsiprep\",\n",
    "    participant_labels=[\"NDARAA948VFH\"],\n",
    "    output_dir=op.join(study_dir, \"derivatives\", \"afq_ar\"),\n",
    "    brain_mask_definition=brain_mask_definition,\n",
    "    tracking_params={\"n_seeds\": 4,\n",
    "                     \"directions\": \"prob\",\n",
    "                     \"odf_model\": \"CSD\",\n",
    "                     \"seed_mask\": RoiImage(use_endpoints=True)},\n",
    "    bundle_info=bundles)\n",
    "\n",
    "my_afq.export(\"profiles\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9c201c5",
   "metadata": {},
   "source": [
    "## Interactive bundle visualization\n",
    "\n",
    "Another way to examine the outputs is to export the bundles as interactive HTML files."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fc799dc2",
   "metadata": {},
   "outputs": [],
   "source": [
    "bundle_html = my_afq.export(\"all_bundles_figure\")\n",
    "\n",
    "plotly.io.show(bundle_html[\"NDARAA948VFH\"][0])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7493df6f",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "- Richie-Halford A, Cieslak M, Ai L, et al. An analysis-ready and quality\n",
    "  controlled resource for pediatric brain white-matter research. Scientific\n",
    "  Data. 2022.\n",
    "  [](https://doi.org/10.1038/s41597-022-01695-7)\n",
    "\n",
    "- Cieslak M, Cook PA, He X, et al. QSIPrep: an integrative platform for\n",
    "  preprocessing and reconstructing diffusion MRI data. Nat Methods. 2021.\n",
    "  [](https://doi.org/10.1038/s41592-021-01185-5)\n",
    "\n"
   ]
  }
 ],
 "metadata": {
  "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.12.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}