diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 000000000..1abfefe00 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/examples/tutorial_examples/baby_afq.ipynb b/examples/tutorial_examples/baby_afq.ipynb new file mode 100644 index 000000000..b2475ebdb --- /dev/null +++ b/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 +}