feat(example): more 2d distributions and better graph comparision

Author: Neiko2002

examples/graph_2d/dataset.py

@@ -7,7 +7,19 @@
 __all__ = ["MAX_POINTS", "MIN_POINTS", "PRESETS", "make_points"]
 
 #: Synthetic 2D distributions the graph can be built on.
-PRESETS: tuple[str, ...] = ("blobs", "moons", "circles", "spiral", "grid", "uniform")
+PRESETS: tuple[str, ...] = (
+    "blobs",
+    "moons",
+    "circles",
+    "spiral",
+    "grid",
+    "uniform",
+    "s-curve",
+    "annulus",
+    "overlap",
+    "twins",
+    "segments",
+)
 
 #: Smallest and largest cloud the example accepts. The upper bound is not a memory limit but a runtime
 #: one: the theoretical reference graphs in `theory.py` compare the DEG against the Delaunay graph, the
@@ -70,13 +82,66 @@ def _uniform(num_points: int, rng: np.random.Generator) -> tuple[np.ndarray, np.
     return rng.uniform(0.0, 10.0, size=(num_points, 2)), np.zeros(num_points, dtype=np.int64)
 
 
+def _s_curve(num_points: int, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+    """A sine-wave manifold with thickness — a narrow curved strip to navigate along."""
+    t = rng.uniform(0.0, 3.0 * np.pi, size=num_points)
+    points = np.column_stack([t, np.sin(t) * 3.0])
+    points = points + rng.standard_normal((num_points, 2)) * 0.18
+    group = (np.sin(t) > 0.0).astype(np.int64)
+    return points, group
+
+
+def _annulus(num_points: int, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+    """A filled disc whose density falls off toward the rim, grouped by radius band."""
+    bands = 3
+    theta = rng.uniform(0.0, 2.0 * np.pi, size=num_points)
+    radius = rng.uniform(0.0, 1.0, size=num_points) ** 1.6 * 4.6
+    group = np.minimum((radius / 4.6 * bands).astype(np.int64), bands - 1)
+    return np.column_stack([radius * np.cos(theta), radius * np.sin(theta)]), group
+
+
+def _overlap(num_points: int, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+    """A dense blob laid over a uniform fill — heterogeneous density that shares space."""
+    group = (rng.random(num_points) < 0.5).astype(np.int64)
+    dense = rng.standard_normal((num_points, 2)) * 0.7 + np.array([1.5, 1.0])
+    flat = rng.uniform(-5.0, 5.0, size=(num_points, 2))
+    return np.where(group[:, None] == 1, dense, flat), group
+
+
+def _twins(num_points: int, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+    """Two spiral arms wound in opposite senses — strongly non-linearly separable."""
+    arms = 2
+    group = np.arange(num_points) % arms
+    radius = np.sqrt(rng.uniform(0.0, 1.0, size=num_points)) * 4.5
+    sense = np.where(group == 0, 1.0, -1.0)
+    theta = radius * 1.5 * sense + group * np.pi
+    points = np.column_stack([radius * np.cos(theta), radius * np.sin(theta)])
+    return points + rng.standard_normal((num_points, 2)) * 0.07, group
+
+
+def _segments(num_points: int, rng: np.random.Generator) -> tuple[np.ndarray, np.ndarray]:
+    """Points strung along a handful of random line segments — sparse, filamentary structure."""
+    lines = int(np.clip(num_points // 120, 3, 8))
+    start = rng.uniform(-5.0, 5.0, size=(lines, 2))
+    end = rng.uniform(-5.0, 5.0, size=(lines, 2))
+    group = np.arange(num_points) % lines
+    t = rng.uniform(0.0, 1.0, size=num_points)
+    points = start[group] * (1.0 - t[:, None]) + end[group] * t[:, None]
+    return points + rng.standard_normal((num_points, 2)) * 0.12, group
+
+
 _GENERATORS = {
     "blobs": _blobs,
     "moons": _moons,
     "circles": _circles,
     "spiral": _spiral,
     "grid": _grid,
     "uniform": _uniform,
+    "s-curve": _s_curve,
+    "annulus": _annulus,
+    "overlap": _overlap,
+    "twins": _twins,
+    "segments": _segments,
 }
 
 

examples/graph_2d/deg_graph.py

@@ -11,7 +11,7 @@
 from deglib.distances import FloatSpace, Metric
 from deglib.optimization import mips_l2_transform_query
 from pysearch import epsilon_search
-from theory import TheoryReport, compare, dissimilarities
+from theory import TheoryReport, compare, dissimilarities, knng_edges, nsw_edges
 
 __all__ = [
     "DEFAULT_K",
@@ -240,74 +240,6 @@ def deg_hit(self) -> bool:
         return bool(self.exact in self.deg_indices)
 
 
-def _nearest_neighbours(points: np.ndarray, k: int, metric: Metric) -> np.ndarray:
-    """
-    The `[n, m]` matrix of each vertex's `m = min(k, n - 1)` nearest neighbour indices under `metric`.
-
-    The knng reads its links from this one computation. The neighbour set is read from the same
-    dissimilarity the reference graphs use (`theory.dissimilarities`, whose infinite diagonal keeps a
-    vertex out of its own neighbour set), so an inner-product cloud links by inner product and an L2
-    cloud by Euclidean distance. The indices are distinct by construction, so a vertex's out-degree is
-    exactly `m`.
-    """
-    points = np.asarray(points)
-    num_points = int(points.shape[0])
-    neighbours = min(int(k), max(num_points - 1, 0))
-    if num_points < 2 or neighbours <= 0:
-        return np.zeros((num_points, 0), dtype=np.int64)
-    distances = dissimilarities(points, metric)
-    return np.argsort(distances, axis=1)[:, :neighbours].astype(np.int64)
-
-
-def knng_edges(points: np.ndarray, k: int, metric: Metric = Metric.FP32_L2) -> np.ndarray:
-    """
-    The directed k-nearest-neighbour graph over `points`, as a directed `[e, 2]` int32 edge list.
-
-    Each vertex points at its `k` nearest neighbours under `metric`, read from the shared neighbour
-    computation, and the link is kept in the direction it was chosen — the edge list holds `(v, neighbour)`
-    for every selection and is never symmetrized. So the out-degree is exactly `k` per vertex (fewer only
-    when `k` exceeds the number of other vertices), while an in-degree can exceed `k` when a vertex is a
-    popular neighbour. A vertex can only walk the neighbours it chose itself.
-    """
-    points = np.asarray(points)
-    num_points = int(points.shape[0])
-    nearest = _nearest_neighbours(points, k, metric)
-    neighbours = int(nearest.shape[1])
-    if neighbours <= 0:
-        return np.zeros((0, 2), dtype=np.int32)
-
-    sources = np.repeat(np.arange(num_points, dtype=np.int32), neighbours)
-    targets = nearest.reshape(-1).astype(np.int32)
-    return np.column_stack((sources, targets)).astype(np.int32).reshape(-1, 2)
-
-
-def nsw_edges(points: np.ndarray, k: int, metric: Metric = Metric.FP32_L2) -> np.ndarray:
-    """
-    The navigable small world over `points`, built incrementally as an undirected `[e, 2]` int32 edge list.
-
-    Vertices are inserted in index order, and each new vertex links — undirected — to its `k` nearest among
-    the vertices already in the graph, the same dissimilarity the reference graphs read. Because a later
-    vertex can add a link to an earlier one, an earlier vertex ends up with more than `k` neighbours: the
-    degree is the count of vertices that chose it plus the `k` it chose itself, so the maximum degree is
-    unbounded. The first vertex has no earlier vertex to link and the first few hold fewer than `k` links,
-    simply because too few vertices precede them.
-    """
-    points = np.asarray(points)
-    num_points = int(points.shape[0])
-    if num_points < 2:
-        return np.zeros((0, 2), dtype=np.int32)
-
-    distances = dissimilarities(points, metric)
-    kept: list[tuple[int, int]] = []
-    for i in range(1, num_points):
-        earlier = distances[i, :i]
-        chosen = min(int(k), i)
-        nearest = np.argpartition(earlier, chosen - 1)[:chosen]
-        nearest = nearest[np.argsort(earlier[nearest], kind="stable")]
-        kept.extend((i, int(j)) for j in nearest)
-    return np.asarray(kept, dtype=np.int32).reshape(-1, 2)
-
-
 def build_model(
     points: np.ndarray,
     groups: np.ndarray,
@@ -382,7 +314,7 @@ def build_model(
         metric=metric,
         mips=mips,
         graph=graph,
-        theory=compare(points, edges, metric) if theory else None,
+        theory=compare(points, edges, metric, k) if theory else None,
     )
 
 

examples/graph_2d/test_graph_2d.py

@@ -387,8 +387,8 @@ def test_describe_covers_the_built_graph(model) -> None:
 
     assert "vertices" in text and "build" in text and "4" in text
     overlap = [line for line in lines if line.startswith("∩")]
-    assert [line.split()[1] for line in overlap] == ["delaunay", "gabriel", "rng", "mst", "mrng"], (
-        "one line per reference"
+    assert [line.split()[1] for line in overlap] == ["knng", "nsw", "delaunay", "gabriel", "rng", "mst", "mrng", "nsg"], (
+        "one line per reference, in the selector's order"
     )
     for line, item in zip(overlap, model.theory.graphs):
         assert f"{item.edges:6d}" in line and f"{item.shared:7d}" in line, "the panel quotes the report"
@@ -1052,9 +1052,11 @@ def test_the_k_field_follows_the_view_it_lands_on(viewer: GraphViewer) -> None:
 
     class _SpinStub:
         state = "normal"
+        increment = 1
 
-        def configure(self, state: str) -> None:
+        def configure(self, state: str, increment: int = 1) -> None:
             self.state = state
+            self.increment = increment
 
     viewer._k_spin = _SpinStub()
     try:
@@ -1073,6 +1075,31 @@ def configure(self, state: str) -> None:
         viewer._k_spin = None
 
 
+def test_the_k_field_steps_by_two_only_for_the_deg(viewer: GraphViewer) -> None:
+    """The DEG builds at an even degree, so its k arrows step by 2; the knng and NSW read k raw and step by 1."""
+
+    class _SpinStub:
+        state = "normal"
+        increment = 1
+
+        def configure(self, state: str, increment: int = 1) -> None:
+            self.state = state
+            self.increment = increment
+
+    viewer._k_spin = _SpinStub()
+    try:
+        viewer._on_view(DEG_VIEW)
+        assert viewer._k_spin.increment == 2, "the DEG snaps k to even, so a step of 1 would leave the down arrow inert"
+
+        viewer._on_view(KNNG_VIEW)
+        assert viewer._k_spin.increment == 1, "the knng reads the raw neighbour count, so it steps by 1"
+
+        viewer._on_view(NSW_VIEW)
+        assert viewer._k_spin.increment == 1, "the NSW reads the raw k too"
+    finally:
+        viewer._k_spin = None
+
+
 def test_viewer_picks_the_vertex_under_the_cursor(viewer: GraphViewer) -> None:
     viewer._fig.canvas.draw()
     target = 42
@@ -1112,9 +1139,11 @@ def test_the_mrng_view_is_offered_undirected_and_timed(viewer: GraphViewer) -> N
 
     class _SpinStub:
         state = "normal"
+        increment = 1
 
-        def configure(self, state: str) -> None:
+        def configure(self, state: str, increment: int = 1) -> None:
             self.state = state
+            self.increment = increment
 
     viewer._k_spin = _SpinStub()
     try:
@@ -1138,19 +1167,22 @@ def configure(self, state: str) -> None:
     assert drawn <= symmetrised, "and that graph is a subgraph of the symmetrised NSG graph"
 
 
-def test_the_nsg_view_is_offered_directed_but_never_compared(viewer: GraphViewer) -> None:
+def test_the_nsg_view_is_offered_directed_and_scored_in_the_report(viewer: GraphViewer) -> None:
     """
     The NSG is a viewer-built view like the knng and the NSW: offered under every metric, drawn directed,
-    reads no k — yet it holds no report entry, so it is never scored against the DEG.
+    reads no k. It carries a report entry, so the panel scores it against the DEG — yet it stays out of
+    the colour key, so its own view states its edge count and time, never a DEG share.
     """
     assert NSG_VIEW in viewer.views, "the NSG is offered in the selector"
-    assert NSG_VIEW not in viewer.model.theory.names, "but it is not a reference graph in the comparison"
+    assert NSG_VIEW in viewer.model.theory.names, "the NSG is scored against the DEG in the report"
 
     class _SpinStub:
         state = "normal"
+        increment = 1
 
-        def configure(self, state: str) -> None:
+        def configure(self, state: str, increment: int = 1) -> None:
             self.state = state
+            self.increment = increment
 
     viewer._k_spin = _SpinStub()
     try:
@@ -1162,7 +1194,7 @@ def configure(self, state: str) -> None:
     assert viewer._view_directed(), "the NSG is drawn directed"
     panel = viewer._panel_text.get_text()
     assert panel.startswith("nsg"), "the column heads with the NSG's name"
-    assert "of DEG" not in panel, "the NSG states no DEG share — it is not compared"
+    assert "of DEG" not in panel, "the NSG view states its own edge count and time, not a DEG share"
 
     drawn = {(int(u), int(v)) for u, v in viewer._display_edges()}
     library = {
@@ -1499,7 +1531,7 @@ def test_compare_counts_the_deg_edges_each_graph_shares() -> None:
 
     undirected = {tuple(sorted(edge)) for edge in scene.edges.reshape(-1, 2)}
     assert report.deg_edges == len(undirected)
-    assert tuple(item.name for item in report.graphs) == ("delaunay", "gabriel", "rng", "mst", "mrng")
+    assert tuple(item.name for item in report.graphs) == ("knng", "nsw", "delaunay", "gabriel", "rng", "mst", "mrng", "nsg")
     assert all(0 < item.shared <= min(report.deg_edges, item.edges) for item in report.graphs)
 
     by_name = {item.name: item for item in report.graphs}
@@ -1631,8 +1663,8 @@ def test_an_inner_product_report_carries_only_the_graphs_it_can_decide() -> None
     euclidean = build_scene("blobs", 120, DEFAULT_K, 5, Metric.FP32_L2, threads=1).theory
     inner = build_scene("blobs", 120, DEFAULT_K, 5, Metric.FP32_InnerProduct, threads=1).theory
 
-    assert euclidean.names == ("delaunay", "gabriel", "rng", "mst", "mrng")
-    assert inner.names == ("rng", "mst", "mrng")
+    assert euclidean.names == ("knng", "nsw", "delaunay", "gabriel", "rng", "mst", "mrng", "nsg")
+    assert inner.names == ("knng", "nsw", "rng", "mst", "mrng", "nsg")
 
 
 def test_the_colour_key_names_only_what_the_report_holds() -> None:
@@ -1831,7 +1863,7 @@ def test_viewer_reports_the_theory_overlap_on_every_build(viewer: GraphViewer) -
 
     assert viewer.model.theory is not None, "a fresh cloud is compared again"
     names = tuple(item.name for item in viewer.model.theory.graphs)
-    assert len(names) == 5, "every reference graph is listed"
+    assert len(names) == 8, "every graph the selector offers is listed, the knng and NSW among them"
     assert all(f"∩ {name}" in viewer._panel_text.get_text() for name in names), "the reseeded panel lists them all"
     assert all(f"∩ {name}" in text for name in names), "and so did the panel before the reseed"
     assert all(item.shared > 0 for item in viewer.model.theory.graphs)
@@ -1925,13 +1957,13 @@ def test_an_overlay_switch_survives_a_rebuild(viewer: GraphViewer) -> None:
 
     viewer._on_metric("IP")
 
-    assert viewer.overlays == {"mst", "mrng"}, "the graphs that were on stay on, the hidden one stays off"
+    assert viewer.overlays == {"mst", "mrng", "nsg", "knng", "nsw"}, "the graphs that were on stay on, the hidden one stays off"
     assert viewer._legend_names() == ("DEG only", "rng", "mrng", "mst"), "and the key names exactly those"
 
     viewer._on_metric("L2")
 
     assert "rng" not in viewer.overlays, "the graph is still hidden when the metric brings it back"
-    assert viewer.overlays == {"delaunay", "gabriel", "mst", "mrng"}
+    assert viewer.overlays == {"delaunay", "gabriel", "mst", "mrng", "nsg", "knng", "nsw"}
 
 
 def test_a_graph_new_to_the_report_defaults_on(viewer: GraphViewer) -> None:
@@ -2117,16 +2149,20 @@ def test_viewer_draws_the_graph_the_selector_picks(viewer: GraphViewer) -> None:
         DEG_VIEW,
         KNNG_VIEW,
         NSW_VIEW,
-        *(overlap.name for overlap in viewer.model.theory.graphs),
+        "delaunay",
+        "gabriel",
+        "rng",
+        "mst",
+        "mrng",
         NSG_VIEW,
         NONE_VIEW,
-    ), "the DEG, the knng, the NSW, the reference graphs, the NSG and the empty view are the selector's entries"
+    ), "the selector lists every graph in GRAPH_ORDER's order, the knng, NSW and NSG among them"
 
     viewer._fig.canvas.draw()
     assert len(viewer._edges.get_segments()) == viewer.model.edges.shape[0], "the DEG view draws the graph itself"
     assert viewer._legend.get_visible(), "and has to explain what its edge colours mean"
 
-    for name in viewer.model.theory.names:
+    for name in (n for n in OVERLAP_ORDER if n in viewer.model.theory.names):
         viewer._on_view(name)
         viewer._fig.canvas.draw()