{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Tractography Clustering - Available Metrics\n\nThis page lists available metrics that can be used by the tractography\nclustering framework. For every metric a brief description is provided\nexplaining: what it does, when it's useful and how to use it. If you are not\nfamiliar with the tractography clustering framework, check this tutorial\n`clustering-framework`.\n    :depth: 1\n\n**Note**:\nAll examples assume a function `get_streamlines` exists. We defined here a\nsimple function to do so. It imports the necessary modules and loads a small\nstreamline bundle.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "def get_streamlines():\n    from dipy.data import get_fnames\n    from dipy.io.streamline import load_tractogram\n\n    fname = get_fnames('fornix')\n    fornix = load_tractogram(fname, 'same', bbox_valid_check=False)\n\n    return fornix.streamlines"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n## Average of Pointwise Euclidean Metric\n**What:** Instances of `AveragePointwiseEuclideanMetric` first compute the\npointwise Euclidean distance between two sequences *of same length* then\nreturn the average of those distances. This metric takes as inputs two features\nthat are sequences containing the same number of elements.\n\n**When:** By default the `QuickBundles` clustering will resample your\nstreamlines on-the-fly so they have 12 points. If for some reason you want\nto avoid this and you made sure all your streamlines already have the same\nnumber of points, you can manually provide an instance of\n`AveragePointwiseEuclideanMetric` to `QuickBundles`. Since the default\n`Feature` is the `IdentityFeature` the streamlines won't be resampled thus\nsaving some computational time.\n\n**Note:** Inputs must be sequences of the same length.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from dipy.segment.clustering import QuickBundles\nfrom dipy.segment.metric import AveragePointwiseEuclideanMetric\n\n# Get some streamlines.\nstreamlines = get_streamlines()  # Previously defined.\n\n# Make sure our streamlines have the same number of points.\nfrom dipy.tracking.streamline import set_number_of_points\nstreamlines = set_number_of_points(streamlines, nb_points=12)\n\n# Create the instance of `AveragePointwiseEuclideanMetric` to use.\nmetric = AveragePointwiseEuclideanMetric()\nqb = QuickBundles(threshold=10., metric=metric)\nclusters = qb.cluster(streamlines)\n\nprint(\"Nb. clusters:\", len(clusters))\nprint(\"Cluster sizes:\", map(len, clusters))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "::\n\n    Nb. clusters: 4\n\n    Cluster sizes: [64, 191, 44, 1]\n\n\n## Sum of Pointwise Euclidean Metric\n**What:** Instances of `SumPointwiseEuclideanMetric` first compute the\npointwise Euclidean distance between two sequences *of same length* then\nreturn the sum of those distances.\n\n**When:** This metric mainly exists because it is used internally by\n`AveragePointwiseEuclideanMetric`.\n\n**Note:** Inputs must be sequences of the same length.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from dipy.segment.clustering import QuickBundles\nfrom dipy.segment.metric import SumPointwiseEuclideanMetric\n\n# Get some streamlines.\nstreamlines = get_streamlines()  # Previously defined.\n\n# Make sure our streamlines have the same number of points.\nfrom dipy.tracking.streamline import set_number_of_points\nnb_points = 12\nstreamlines = set_number_of_points(streamlines, nb_points=nb_points)\n\n# Create the instance of `SumPointwiseEuclideanMetric` to use.\nmetric = SumPointwiseEuclideanMetric()\nqb = QuickBundles(threshold=10.*nb_points, metric=metric)\nclusters = qb.cluster(streamlines)\n\nprint(\"Nb. clusters:\", len(clusters))\nprint(\"Cluster sizes:\", map(len, clusters))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "::\n\n    Nb. clusters: 4\n\n    Cluster sizes: [64, 191, 44, 1]\n\n\n## Cosine Metric\n**What:** Instances of `CosineMetric` compute the cosine distance between two\nvectors (for more information see the\n[wiki page](https://en.wikipedia.org/wiki/Cosine_similarity)).\n\n**When:** This metric can be useful when you *only* need information about the\norientation of a streamline.\n\n**Note:** Inputs must be vectors (i.e. 1D array).\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import numpy as np\nfrom dipy.viz import window, actor, colormap\nfrom dipy.segment.clustering import QuickBundles\nfrom dipy.segment.featurespeed import VectorOfEndpointsFeature\nfrom dipy.segment.metric import CosineMetric\n\n# Enables/disables interactive visualization\ninteractive = False\n\n# Get some streamlines.\nstreamlines = get_streamlines()  # Previously defined.\n\nfeature = VectorOfEndpointsFeature()\nmetric = CosineMetric(feature)\nqb = QuickBundles(threshold=0.1, metric=metric)\nclusters = qb.cluster(streamlines)\n\n# Color each streamline according to the cluster they belong to.\ncolormap = colormap.create_colormap(np.arange(len(clusters)))\ncolormap_full = np.ones((len(streamlines), 3))\nfor cluster, color in zip(clusters, colormap):\n    colormap_full[cluster.indices] = color\n\n# Visualization\nscene = window.Scene()\nscene.clear()\nscene.SetBackground(0, 0, 0)\nscene.add(actor.streamtube(streamlines, colormap_full))\nwindow.record(scene, out_path='cosine_metric.png', size=(600, 600))\nif interactive:\n    window.show(scene)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. figure:: cosine_metric.png\n   :align: center\n\n   Showing the streamlines colored according to their orientation.\n\n.. include:: ../links_names.inc\n\n### References\n\n.. [Garyfallidis12] Garyfallidis E. et al., QuickBundles a method for\n   tractography simplification, Frontiers in Neuroscience, vol 6, no 175, 2012.\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
}