{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Groupwise Bundle Registration\n\nThis example explains how to coregister a set of bundles to a common space that\nis not biased by any specific bundle. This is useful when we want to align all\nthe bundles but do not have a target reference space defined by an atlas.\n\n## How it works\n\nThe bundle groupwise registration framework in DIPY relies on streamline linear\nregistration (SLR) [Garyfallidis15]_ and an iterative process.\n\nIn each iteration, bundles are shuffled and matched in pairs. Then, each pair\nof bundles are simultaneously moved to a common space in between both.\n\nAfter all pairs have been aligned, a group distance metric is computed as the\nmean pairwise distance between all bundle pairs. With each iteration, bundles\nget closer to each other and the group distance decreases.\n\nWhen the reduction in the group distance reaches a tolerance level the process\nends.\n\nTo reduce computational time, by default both registration and distance\ncomputation are performed on streamline centroids (obtained with Quickbundles)\n[Garyfallidis12]_.\n\n## Example\n\nWe start by importing and creating the necessary functions:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from dipy.align.streamlinear import groupwise_slr\nfrom dipy.data import read_five_af_bundles\nfrom dipy.viz.streamline import show_bundles\n\nimport logging\nlogging.basicConfig(level=logging.INFO)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "To run groupwise registration we need to have our input bundles stored in a\nlist.\n\nHere we load 5 left arcuate fasciculi and store them in a list.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "bundles = read_five_af_bundles()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Let's now visualize our input bundles:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "colors = [[0.91, 0.26, 0.35], [0.99, 0.50, 0.38], [0.99, 0.88, 0.57],\n          [0.69, 0.85, 0.64], [0.51, 0.51, 0.63]]\n\nshow_bundles(bundles, interactive=False, colors=colors,\n             save_as='before_group_registration.png')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. figure:: before_group_registration.png\n   :align: center\n\n   Bundles before registration.\n\nThey are in native space and, therefore, not aligned.\n\nNow running groupwise registration is as simple as:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "bundles_reg, aff, d = groupwise_slr(bundles, verbose=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Finally, we visualize the registered bundles to confirm that they are now in a\ncommon space:\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "show_bundles(bundles_reg, interactive=False, colors=colors,\n             save_as='after_group_registration.png')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. figure:: after_group_registration.png\n   :align: center\n\n   Bundles after registration.\n\n## Extended capabilities\n\nIn addition to the registered bundles, `groupwise_slr` also returns a list with\nthe individual transformation matrices as well as the pairwise distances\ncomputed in each iteration.\n\nBy changing the input arguments the user can modify the transformation (up to\naffine), the number of maximum number of streamlines per bundle, the level of\nclustering, or the tolerance of the method.\n\n### References\n\n.. [Garyfallidis15] Garyfallidis et al., \"Robust and efficient linear\n                    registration of white-matter fascicles in the space of\n                    streamlines\", Neuroimage, 117:124-140, 2015.\n.. [Garyfallidis12] Garyfallidis E. et al., \"QuickBundles a method for\n                    tractography simplification\", Frontiers in Neuroscience,\n                    vol 6, no 175, 2012.\n.. [RomeroBascones22] Romero-Bascones D. et al., \"BundleAtlasing: unbiased\n                    population-specific atlasing of bundles in streamline\n                    space\", ISMRM, 2022.\n\n\n\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "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.9.13"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}