Add shape diagnostic function

Author: stefmolin

src/data_morph/data/dataset.py

@@ -201,6 +201,7 @@ def plot(
         ax: Axes | None = None,
         show_bounds: bool = True,
         title: str | None = 'default',
+        alpha: Number = 1,
     ) -> Axes:
         """
         Plot the dataset and its bounds.
@@ -214,6 +215,8 @@ def plot(
         title : str | ``None``, optional
             Title to use for the plot. The default will call ``str()`` on the
             Dataset. Pass ``None`` to leave the plot untitled.
+        alpha : Number, default ``1``
+            The transparency to use for the points in the plot.
 
         Returns
         -------
@@ -225,7 +228,7 @@ def plot(
             fig.get_layout_engine().set(w_pad=0.2, h_pad=0.2)
 
         ax.axis('equal')
-        ax.scatter(self.data.x, self.data.y, s=2, color='black')
+        ax.scatter(self.data.x, self.data.y, s=2, color='black', alpha=alpha)
         ax.set(xlabel='', ylabel='', title=self if title == 'default' else title)
 
         if show_bounds:

src/data_morph/plotting/diagnostics.py

@@ -0,0 +1,79 @@
+"""Diagnostic plot to visualize a shape superimposed on the dataset."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..plotting.style import plot_with_custom_style
+
+if TYPE_CHECKING:
+    from numbers import Number
+
+    from matplotlib.axes import Axes
+
+    from ..data.dataset import Dataset
+    from ..shapes.bases.shape import Shape
+
+
+@plot_with_custom_style
+def plot_shape_on_dataset(
+    dataset: Dataset,
+    shape: Shape,
+    show_bounds: bool = False,
+    alpha: Number = 0.25,
+) -> Axes:
+    """
+    Plot a shape superimposed on a dataset to evaluate heuristics.
+
+    Parameters
+    ----------
+    dataset : Dataset
+        The dataset that ``shape`` was instantiated with.
+    shape : Shape
+        The shape that was instantiated with ``dataset``.
+    show_bounds : bool, default ``False``
+        Whether to include the dataset's bounds in the plot.
+    alpha : Number, default ``0.25``
+        The transparency to use for the dataset's points.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+        The :class:`~matplotlib.axes.Axes` object containing the plot.
+
+    Examples
+    --------
+
+    .. plot::
+       :scale: 75
+       :include-source:
+       :caption:
+            Visualization of the :class:`.Star` when calculated based on the
+            music :class:`.Dataset`, with the dataset's bounds.
+
+        from data_morph.data.loader import DataLoader
+        from data_morph.plotting.diagnostics import plot_shape_on_dataset
+        from data_morph.shapes.lines import Star
+
+        dataset = DataLoader.load_dataset('music')
+        shape = Star(dataset)
+        plot_shape_on_dataset(dataset, shape, show_bounds=True, alpha=0.1)
+
+    .. plot::
+       :scale: 75
+       :include-source:
+       :caption:
+            Visualization of the :class:`.Heart` when calculated based on the
+            music :class:`.Dataset`, without the dataset's bounds.
+
+        from data_morph.data.loader import DataLoader
+        from data_morph.plotting.diagnostics import plot_shape_on_dataset
+        from data_morph.shapes.points import Heart
+
+        dataset = DataLoader.load_dataset('music')
+        shape = Heart(dataset)
+        plot_shape_on_dataset(dataset, shape, alpha=0.1)
+    """
+    ax = dataset.plot(show_bounds=show_bounds, title=None, alpha=alpha)
+    shape.plot(ax=ax)
+    return ax