WIP: Adds a notebook with a rather complete baby_afq tutorial.

.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: local
+    hooks:
+      - id: jupyter-nb-clear-output
+        name: jupyter-nb-clear-output
+        files: \.ipynb$
+        stages: [commit]
+        language: system
+        entry: jupyter nbconvert --ClearOutputPreprocessor.enabled=True --inplace

examples/tutorial_examples/baby_afq.ipynb

@@ -0,0 +1,185 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "4a1973ed",
+   "metadata": {},
+   "source": [
+    "# Tutorial: run pyAFQ on data from infants\n",
+    "\n",
+    "Infant brains are profoundly different from grownup brains."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a7204feb",
+   "metadata": {},
+   "source": [
+    "## Get some baby diffusion data: \n",
+    "\n",
+    "The data for this example, provided by [Kalanit Grill Spector's Stanford Vision and Perception Neuroscience Lab](https://vpnl.stanford.edu/) is available to download [on Figshare](https://figshare.com/articles/dataset/Example_babyAFQ_BIDS_subject/21440739). You can download it from there and unzip it into `~/AFQ_Data/baby_example/` (Note that this is 2.69GB of data, so it can take a while to download). This data has been previously published in Grotheer et al. (2022).\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cbe77e4a",
+   "metadata": {},
+   "source": [
+    "In this case, a tractography has already been run with the excellent [MRtrix](https://www.mrtrix.org/) software. When you first run the following code, it will download the infant templates into your `~/AFQ_data/pediatric_templates` folder, organizing them there in the way that pyAFQ expects to find them."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cdb5a2d1",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "efe6998b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from AFQ.api.group import GroupAFQ\n",
+    "import AFQ.api.bundle_dict as abd\n",
+    "import AFQ.data.fetch as afd\n",
+    "import os.path as op\n",
+    "myafq = GroupAFQ(\n",
+    "    # ==== BIDS parameters ====\n",
+    "    bids_path=op.join(op.expanduser('~'), \"AFQ_data/example_bids_subject/\"),\n",
+    "    preproc_pipeline=\"vistasoft\",\n",
+    "    # ===== Registration parameters ====\n",
+    "    reg_template_spec=afd.read_pediatric_templates()[\"UNCNeo-withCerebellum-for-babyAFQ\"],\n",
+    "    reg_subject_spec=\"b0\",\n",
+    "    # ==== Bundle parameters ====\n",
+    "    bundle_info=abd.PediatricBundleDict(),\n",
+    "    # ==== Tracking parameters ====\n",
+    "    import_tract={\n",
+    "        \"suffix\": \"tractography\", \"scope\": \"mrtrix\"},\n",
+    "    # ==== Segmentation parameters ====\n",
+    "    segmentation_params={\n",
+    "        \"filter_by_endpoints\": False},\n",
+    "    clean_params={\n",
+    "        'distance_threshold': 4},\n",
+    ")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "43d28f0b",
+   "metadata": {},
+   "source": [
+    "### Step 3: Run pyAFQ\n",
+    "After defining your pyAFQ API object, you can ask for the output of any step of the pipeline. It is common for users to just call export_all (for example, myafq.export_all())."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4f9ad529",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "myafq.export(\"template_xform\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9eeeaa8c",
+   "metadata": {},
+   "source": [
+    "On the left, the babyAFQ template from MNI space has been transformed into the subject's native space. On the right, the subject's b0 is shown for reference.\n",
+    "![warped_template](warped_template.png)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ca8d87f1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import plotly\n",
+    "bundle_html = myafq.export(\"all_bundles_figure\")\n",
+    "plotly.io.show(bundle_html[\"01\"][0])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3a833619",
+   "metadata": {},
+   "source": [
+    "### Another way to run this: Using the pyAFQ configuration file\n",
+    "\n",
+    "pyAFQ provides a [command-line interface (CLI)](https://yeatmanlab.github.io/pyAFQ/usage/index.html). After installing the software, and organizing the data, run:\n",
+    "\n",
+    "    pyAFQ /path/to/config.toml\n",
+    "\n",
+    "At minimum, the file should contain the BIDS path:\n",
+    "\n",
+    "    [BIDS_PARAMS]\n",
+    "    bids_path = \"path/to/study\"\n",
+    "\n",
+    "But additional configuration options can be provided. Here is an example configuration file to run babyAFQ:\n",
+    "\n",
+    "    [BIDS_PARAMS]\n",
+    "    bids_path = \"/path/to/AFQ_data/example_bids_subject\"\n",
+    "    preproc_pipeline = \"vistasoft\"\n",
+    "\n",
+    "    [DATA]\n",
+    "    reg_template_spec = \"pediatric\"\n",
+    "    reg_subject_spec = \"b0\"\n",
+    "    bundle_info=\"PediatricBundleDict()\"\n",
+    "\n",
+    "    [TRACTOGRAPHY_PARAMS]\n",
+    "    import_tract = \"{'suffix': 'tractography', 'scope': 'mrtrix'}\"\n",
+    "\n",
+    "    [SEGMENTATION_PARAMS]\n",
+    "    filter_by_endpoints = false\n",
+    "    \n",
+    "    [CLEANING_PARAMS]\n",
+    "    distance_threshold = 4"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6d1cbb6d",
+   "metadata": {},
+   "source": [
+    "# References \n",
+    "\n",
+    "1. Grotheer M, Rosenke M, Wu H, Kular H, Querdasi FR, Natu VS, Yeatman JD, Grill-Spector K. White matter myelination during early infancy is linked to spatial gradients and myelin content at birth. Nat Commun. 2022 Feb 22;13(1):997. doi: 10.1038/s41467-022-28326-4. PMID: 35194018; PMCID: PMC8863985."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d8ca78c8",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "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.10.8"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}