{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0b9dd39d",
   "metadata": {},
   "source": [
    "# How to use TRX in pyAFQ\n",
    "\n",
    "PyAFQ supports the use of the [TRX](https://tee-ar-ex.github.io/) file format.\n",
    "This has several benefits for pyAFQ users:\n",
    "\n",
    "1. TRX explicitly stores its spatial reference frame, removing ambiguity and\n",
    "   preventing errors that can occur when the spatial reference is implicit or\n",
    "   assumed.\n",
    "2. TRX supports custom data type precision for representation of streamline\n",
    "   coordinates. Based on benchmarking that we conducted [@Kruper2024HCP],\n",
    "   we use float16 precision, which helps save space\n",
    "   (approximately halving file sizes relative to the float32 precision stored\n",
    "   in the trk and tck file formats).\n",
    "3. TRX uses memory mapping. This allows pyAFQ to perform batched operations,\n",
    "   allowing parallelization of tractography and also allows pyAFQ to operate\n",
    "   over massive tractograms with >100M streamlines without commensurate\n",
    "   RAM use.\n",
    "4. TRX stores groups. This allows for intuitive and robust\n",
    "   representation of metadata about the tracts in the same file that stores\n",
    "   the streamline coordinates.\n",
    "5. Not currently utilized by pyAFQ, but may become part of it in the future is\n",
    "   the possibility to also store data-per-streamline and data-per-vertex. This\n",
    "   means that we could store attributes of the underlying volumes of tissue\n",
    "   properties (e.g., FA or MD) together with the streamline coordinates.\n",
    "\n",
    "This tutorial will demonstrate how to use the output of pyAFQ processing with\n",
    "the TRX group representation.\n",
    "\n",
    "To enable use of TRX, the pyAFQ software requires the\n",
    "[trx-python](https://tee-ar-ex.github.io/trx-python/) library,\n",
    "which implements TRX I/O. If you have pyAFQ, this library is already\n",
    "installed.\n",
    "\n",
    "We will start by importing its components:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "847b92ec",
   "metadata": {},
   "outputs": [],
   "source": [
    "from trx.trx_file_memmap import load"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bccbb86e",
   "metadata": {},
   "source": [
    "Then, we will load data from a TRX file. If you have previously run other examples\n",
    "that use the HBN dataset you should have a file with this name that you can\n",
    "load:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1ac306a7",
   "metadata": {},
   "outputs": [],
   "source": [
    "trx_file = load(\"./sub-NDARAA948VFH_ses-HBNsiteRU_acq-64dir_desc-bundles_tractography.trx\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45e145a5",
   "metadata": {},
   "source": [
    "We can access the list of tract names in this file using the `groups` dict\n",
    "that is stored as an attribute of the `trx_file`, and specifically the `keys`\n",
    "method of this dict:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4e4acca4",
   "metadata": {},
   "outputs": [],
   "source": [
    "trx_file.groups.keys()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9428391b",
   "metadata": {},
   "source": [
    "The contents of each group can be accessed using, for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a94a7d97",
   "metadata": {},
   "outputs": [],
   "source": [
    "group_trx = trx_file.get_group(\"Left Anterior Vertical Occipital\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b046aed",
   "metadata": {},
   "source": [
    "The outcome is another instance of a `TrxFile` object. Within this object,\n",
    "we can access the streamlines and their coordinates. For example, to find\n",
    "what proportion of streamlines were classified into each group:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e34e72d2",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(len(group_trx.streamlines) / len(trx_file.streamlines))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57e9e782",
   "metadata": {},
   "source": [
    ":::{only} html\n",
    "{download}`Download as Jupyter Notebook <plot_trx.ipynb>`\n",
    ":::"
   ]
  }
 ],
 "metadata": {
  "file_format": "mystnb",
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  },
  "mystnb": {
   "execution_mode": "off"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}