Add similarity plotting utilities (#67)

* Initial functions for plotting added

* update

* Adding matplotlib dependency

* Added utils module and updated functions to include matplotlib axes

* remove matplotlib dependency from functional

* Added examples and updates

* fix

* minor updates

* Update plotting functions

Co-authored-by: mikeheddes <mikeheddes@gmail.com>

Author: dheyay

docs/index.rst

@@ -19,5 +19,6 @@ Torchhd is a Python library dedicated to *Hyperdimensional Computing* (also knwo
    embeddings
    structures
    datasets
+   utils
 
 

docs/utils.rst

@@ -0,0 +1,16 @@
+.. _utils:
+
+torchhd.utils
+==================
+
+.. currentmodule:: torchhd.utils
+
+This module provides plotting functions for hypervector similarities.
+
+.. autosummary::
+    :toctree: generated/
+    :template: function.rst
+
+    plot_similarity
+    plot_pair_similarity
+

torchhd/__init__.py

@@ -2,6 +2,7 @@
 import torchhd.embeddings as embeddings
 import torchhd.structures as structures
 import torchhd.datasets as datasets
+import torchhd.utils as utils
 
 from torchhd.functional import (
     identity_hv,
@@ -20,6 +21,7 @@
     "embeddings",
     "structures",
     "datasets",
+    "utils",
     "identity_hv",
     "random_hv",
     "level_hv",

torchhd/utils.py

@@ -0,0 +1,91 @@
+import torch
+from torch import Tensor
+
+import torchhd.functional as functional
+
+
+def plot_pair_similarity(memory: Tensor, ax=None, **kwargs):
+    """Plots the pair-wise similarity of a hypervector set.
+
+    Args:
+        memory (Tensor): The set of :math:`n` hypervectors whose pair-wise similarity is to be displayed.
+        ax (matplotlib.axes, optional): Axes in which to draw the plot.
+
+    Other Parameters:
+        **kwargs: `matplotlib.axes.Axes.pcolormesh <https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.pcolormesh.html>`_ arguments.
+
+    Returns:
+        matplotlib.collections.QuadMesh: `matplotlib.collections.QuadMesh <https://matplotlib.org/stable/api/collections_api.html#matplotlib.collections.QuadMesh>`_.
+
+    Shapes:
+        - Memory: :math:`(n, d)`
+
+    Examples::
+
+        >>>  import matplotlib.pyplot as plt
+        >>>  hv = torchhd.level_hv(10, 10000)
+        >>>  utils.plot_pair_similarity(hv)
+        >>>  plt.show()
+    """
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError:
+        raise ImportError(
+            "Install matplotlib to use plotting functionality. \
+        See https://matplotlib.org/stable/users/installing/index.html for more information."
+        )
+
+    similarity = []
+    for vector in memory:
+        similarity.append(functional.cosine_similarity(vector, memory).tolist())
+
+    if ax is None:
+        ax = plt.gca()
+
+    xy = torch.arange(memory.size(-2))
+    x, y = torch.meshgrid(xy, xy)
+
+    ax.set_aspect("equal", adjustable="box")
+    return ax.pcolormesh(x, y, similarity, **kwargs)
+
+
+def plot_similarity(input: Tensor, memory: Tensor, ax=None, **kwargs):
+    """Plots the similarity of an one hypervector with a set of hypervectors.
+
+    Args:
+        input (torch.Tensor): Hypervector to compare against the memory.
+        memory (torch.Tensor): Set of :math:`n` hypervectors.
+        ax (matplotlib.axes, optional): Axes in which to draw the plot.
+
+    Other Parameters:
+        **kwargs: `matplotlib.axes.Axes.stem <https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.stem.html?highlight=stem#matplotlib.axes.Axes.stem>`_ arguments.
+
+    Returns:
+        StemContainer: `matplotlib.container.StemContainer <https://matplotlib.org/stable/api/container_api.html#matplotlib.container.StemContainer>`_.
+
+    Shapes:
+        - Input: :math:`(d)`
+        - Memory: :math:`(n, d)`
+
+    Examples::
+
+        >>>  import matplotlib.pyplot as plt
+        >>>  hv = torchhd.level_hv(10, 10000)
+        >>>  utils.plot_similarity(hv[4], hv)
+        >>>  plt.show()
+
+    """
+    try:
+        import matplotlib.pyplot as plt
+    except ImportError:
+        raise ImportError(
+            "Install matplotlib to use plotting functionality. \
+        See https://matplotlib.org/stable/users/installing/index.html for more information."
+        )
+
+    similarity = functional.cosine_similarity(input, memory).tolist()
+
+    if ax is None:
+        ax = plt.gca()
+
+    return ax.stem(similarity, **kwargs)