{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n# Tractography Clustering - Available Features\n\nThis page lists available features that can be used by the tractography\nclustering framework. For every feature 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, read the\n`clustering-framework` first.\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    from dipy.tracking.streamline import Streamlines\n\n    fname = get_fnames('fornix')\n    fornix = load_tractogram(fname, 'same',\n                             bbox_valid_check=False).streamlines\n\n    streamlines = Streamlines(fornix)\n    return streamlines"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n## Identity Feature\n**What:** Instances of `IdentityFeature` simply return the streamlines\nunaltered.  In other words the features are the original data.\n\n**When:** The QuickBundles algorithm requires streamlines to have the same\nnumber of points. If this is the case for your streamlines, you can tell\nQuickBundles to not perform resampling (see following example). The clustering\nshould be faster than using the default behaviour of QuickBundles since it will\nrequire less computation (i.e. no resampling). However, it highly depends\non the number of points streamlines have. By default, QuickBundles resamples\nstreamlines so that they have 12 points each [Garyfallidis12]_.\n\n*Unless stated otherwise, it is the default feature used by `Metric` objects\nin the clustering framework.*\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\nfrom dipy.segment.featurespeed import IdentityFeature\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 an instance of `IdentityFeature` and tell metric to use it.\nfeature = IdentityFeature()\nmetric = AveragePointwiseEuclideanMetric(feature=feature)\nqb = QuickBundles(threshold=10., metric=metric)\nclusters = qb.cluster(streamlines)\n\nprint(\"Nb. clusters:\", len(clusters))\nprint(\"Cluster sizes:\", list(map(len, clusters)))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "::\n\n    Nb. clusters: 4\n\n    Cluster sizes: [64, 191, 47, 1]\n\n\n\n## Resample Feature\n**What:** Instances of `ResampleFeature` resample streamlines to a\npredetermined number of points. The resampling is done on the fly such that\nthere are no permanent modifications made to your streamlines.\n\n**When:** The QuickBundles algorithm requires streamlines to have the same\nnumber of points. By default, QuickBundles uses `ResampleFeature` to resample\nstreamlines so that they have 12 points each [Garyfallidis12]_. If you want to\nuse a different number of points for the resampling, you should provide your\nown instance of `ResampleFeature` (see following example).\n\n**Note:** Resampling streamlines has an impact on clustering results both in\nterm of speed and quality. Setting the number of points too low will result in\na loss of information about the shape of the streamlines. On the contrary,\nsetting the number of points too high will slow down the clustering process.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "from dipy.segment.clustering import QuickBundles\nfrom dipy.segment.featurespeed import ResampleFeature\nfrom dipy.segment.metric import AveragePointwiseEuclideanMetric\n\n# Get some streamlines.\nstreamlines = get_streamlines()  # Previously defined.\n\n# Streamlines will be resampled to 24 points on the fly.\nfeature = ResampleFeature(nb_points=24)\nmetric = AveragePointwiseEuclideanMetric(feature=feature)  # a.k.a. MDF\nqb = QuickBundles(threshold=10., metric=metric)\nclusters = qb.cluster(streamlines)\n\nprint(\"Nb. clusters:\", len(clusters))\nprint(\"Cluster sizes:\", list(map(len, clusters)))"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "::\n\n    Nb. clusters: 4\n\n    Cluster sizes: [64, 191, 44, 1]\n\n\n## Center of Mass Feature\n**What:** Instances of `CenterOfMassFeature` compute the center of mass (also\nknown as center of gravity) of a set of points. This is achieved by taking the\nmean of every coordinate independently (for more information see the\n[wiki page](https://en.wikipedia.org/wiki/Center_of_mass)).\n\n**When:** This feature can be useful when you *only* need information about the\nspatial position of a streamline.\n\n**Note:** The computed center is not guaranteed to be an existing point in the\nstreamline.\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 CenterOfMassFeature\nfrom dipy.segment.metric import EuclideanMetric\n\n# Enables/disables interactive visualization\ninteractive = False\n\n# Get some streamlines.\nstreamlines = get_streamlines()  # Previously defined.\n\n\nfeature = CenterOfMassFeature()\nmetric = EuclideanMetric(feature)\n\nqb = QuickBundles(threshold=5., metric=metric)\nclusters = qb.cluster(streamlines)\n\n# Extract feature of every streamline.\ncenters = np.asarray(list(map(feature.extract, streamlines)))\n\n# Color each center of mass 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, window.colors.white, opacity=0.05))\nscene.add(actor.point(centers[:, 0, :], colormap_full, point_radius=0.2))\nwindow.record(scene, n_frames=1, out_path='center_of_mass_feature.png',\n              size=(600, 600))\nif interactive:\n    window.show(scene)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. figure:: center_of_mass_feature.png\n   :align: center\n\n   Showing the center of mass of each streamline colored according to\n   the QuickBundles results.\n\n\n## Midpoint Feature\n**What:** Instances of `MidpointFeature` extract the middle point of a\nstreamline. If there is an even number of points, the feature will then\ncorrespond to the point halfway between the two middle points.\n\n**When:** This feature can be useful when you *only* need information about the\nspatial position of a streamline. This can also be an alternative to the\n`CenterOfMassFeature` if the point extracted must be on the streamline.\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 MidpointFeature\nfrom dipy.segment.metric import EuclideanMetric\n\n# Get some streamlines.\nstreamlines = get_streamlines()  # Previously defined.\n\nfeature = MidpointFeature()\nmetric = EuclideanMetric(feature)\n\nqb = QuickBundles(threshold=5., metric=metric)\nclusters = qb.cluster(streamlines)\n\n# Extract feature of every streamline.\nmidpoints = np.asarray(list(map(feature.extract, streamlines)))\n\n# Color each midpoint 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.point(midpoints[:, 0, :], colormap_full, point_radius=0.2))\nscene.add(actor.streamtube(streamlines, window.colors.white, opacity=0.05))\nwindow.record(scene, n_frames=1, out_path='midpoint_feature.png',\n              size=(600, 600))\nif interactive:\n    window.show(scene)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. figure:: midpoint_feature.png\n   :align: center\n\n   Showing the middle point of each streamline colored according to the\n   QuickBundles results.\n\n\n## ArcLength Feature\n**What:** Instances of `ArcLengthFeature` compute the length of a streamline.\nMore specifically, this feature corresponds to the sum of the lengths of every\nstreamline's segments.\n\n**When:** This feature can be useful when you *only* need information about the\nlength of a streamline.\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 ArcLengthFeature\nfrom dipy.segment.metric import EuclideanMetric\n\n# Get some streamlines.\nstreamlines = get_streamlines()  # Previously defined.\n\nfeature = ArcLengthFeature()\nmetric = EuclideanMetric(feature)\nqb = QuickBundles(threshold=2., metric=metric)\nclusters = qb.cluster(streamlines)\n\n# Color each streamline according to the cluster they belong to.\ncolormap = colormap.create_colormap(np.ravel(clusters.centroids))\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='arclength_feature.png', size=(600, 600))\nif interactive:\n    window.show(scene)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. figure:: arclength_feature.png\n   :align: center\n\n   Showing the streamlines colored according to their length.\n\n\n## Vector Between Endpoints Feature\n**What:** Instances of `VectorOfEndpointsFeature` extract the vector going\nfrom one extremity of the streamline to the other. In other words, this feature\nrepresents the vector beginning at the first point and ending at the last point\nof the streamlines.\n\n**When:** This feature can be useful when you *only* need information about the\norientation of a streamline.\n\n**Note:** Since streamlines endpoints are ambiguous (e.g. the first point could\nbe either the beginning or the end of the streamline), one must be careful when\nusing this feature.\n\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import numpy as np\nfrom dipy.viz import window, colormap\nfrom dipy.segment.clustering import QuickBundles\nfrom dipy.segment.featurespeed import VectorOfEndpointsFeature\nfrom dipy.segment.metric import CosineMetric\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='vector_of_endpoints_feature.png',\n              size=(600, 600))\nif interactive:\n    window.show(scene)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        ".. figure:: vector_of_endpoints_feature.png\n   :align: center\n\n   Showing the streamlines colored according to their orientation.\n\n.. include:: ../links_names.inc\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
}