anywidget-vector 0.1.0__tar.gz → 0.2.0__tar.gz

{anywidget_vector-0.1.0 → anywidget_vector-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anywidget-vector
-Version: 0.1.0
+Version: 0.2.0
 Summary: Interactive vector visualization for Python notebooks using anywidget
 Project-URL: Homepage, https://grafeo.dev/
 Project-URL: Repository, https://github.com/GrafeoDB/anywidget-vector
@@ -264,6 +264,73 @@ widget = VectorSpace(
 )
 ```
 
+## Distance Metrics
+
+Compute distances and visualize similarity relationships between points.
+
+### Supported Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `euclidean` | Straight-line distance (L2 norm) |
+| `cosine` | Angle-based distance (1 - cosine similarity) |
+| `manhattan` | Sum of absolute differences (L1 norm) |
+| `dot_product` | Negative dot product (higher = closer) |
+
+### Color by Distance
+
+```python
+# Color points by distance from a reference
+widget.color_by_distance("point_a")
+widget.color_by_distance("point_a", metric="cosine")
+```
+
+### Find Neighbors
+
+```python
+# Find k nearest neighbors
+neighbors = widget.find_neighbors("point_a", k=5)
+# Returns: [("point_b", 0.1), ("point_c", 0.2), ...]
+
+# Find neighbors within distance threshold
+neighbors = widget.find_neighbors("point_a", threshold=0.5)
+```
+
+### Show Connections
+
+```python
+# Draw lines to k-nearest neighbors
+widget.show_neighbors("point_a", k=5)
+
+# Draw lines to all points within threshold
+widget.show_neighbors("point_a", threshold=0.3)
+
+# Manual connection settings
+widget = VectorSpace(
+    points=data,
+    show_connections=True,
+    k_neighbors=3,
+    distance_metric="cosine",
+    connection_color="#00ff00",
+    connection_opacity=0.5,
+)
+```
+
+### Compute Distances
+
+```python
+# Get distances from reference to all points
+distances = widget.compute_distances("point_a")
+# Returns: {"point_b": 0.1, "point_c": 0.5, ...}
+
+# Use high-dimensional vectors (not just x,y,z)
+distances = widget.compute_distances(
+    "point_a",
+    metric="cosine",
+    vector_field="embedding"  # Use full embedding vector
+)
+```
+
 ## Export
 
 ```python

{anywidget_vector-0.1.0 → anywidget_vector-0.2.0}/README.md

@@ -216,6 +216,73 @@ widget = VectorSpace(
 )
 ```
 
+## Distance Metrics
+
+Compute distances and visualize similarity relationships between points.
+
+### Supported Metrics
+
+| Metric | Description |
+|--------|-------------|
+| `euclidean` | Straight-line distance (L2 norm) |
+| `cosine` | Angle-based distance (1 - cosine similarity) |
+| `manhattan` | Sum of absolute differences (L1 norm) |
+| `dot_product` | Negative dot product (higher = closer) |
+
+### Color by Distance
+
+```python
+# Color points by distance from a reference
+widget.color_by_distance("point_a")
+widget.color_by_distance("point_a", metric="cosine")
+```
+
+### Find Neighbors
+
+```python
+# Find k nearest neighbors
+neighbors = widget.find_neighbors("point_a", k=5)
+# Returns: [("point_b", 0.1), ("point_c", 0.2), ...]
+
+# Find neighbors within distance threshold
+neighbors = widget.find_neighbors("point_a", threshold=0.5)
+```
+
+### Show Connections
+
+```python
+# Draw lines to k-nearest neighbors
+widget.show_neighbors("point_a", k=5)
+
+# Draw lines to all points within threshold
+widget.show_neighbors("point_a", threshold=0.3)
+
+# Manual connection settings
+widget = VectorSpace(
+    points=data,
+    show_connections=True,
+    k_neighbors=3,
+    distance_metric="cosine",
+    connection_color="#00ff00",
+    connection_opacity=0.5,
+)
+```
+
+### Compute Distances
+
+```python
+# Get distances from reference to all points
+distances = widget.compute_distances("point_a")
+# Returns: {"point_b": 0.1, "point_c": 0.5, ...}
+
+# Use high-dimensional vectors (not just x,y,z)
+distances = widget.compute_distances(
+    "point_a",
+    metric="cosine",
+    vector_field="embedding"  # Use full embedding vector
+)
+```
+
 ## Export
 
 ```python

{anywidget_vector-0.1.0 → anywidget_vector-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "anywidget-vector"
-version = "0.1.0"
+version = "0.2.0"
 description = "Interactive vector visualization for Python notebooks using anywidget"
 readme = "README.md"
 license = { text = "Apache-2.0" }

{anywidget_vector-0.1.0 → anywidget_vector-0.2.0}/src/anywidget_vector/__init__.py

@@ -3,4 +3,4 @@
 from anywidget_vector.widget import VectorSpace
 
 __all__ = ["VectorSpace"]
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{anywidget_vector-0.1.0 → anywidget_vector-0.2.0}/src/anywidget_vector/widget.py

@@ -39,6 +39,33 @@ const SHAPES = {
   cylinder: () => new THREE.CylinderGeometry(0.5, 0.5, 1, 16),
 };
 
+// Distance metrics
+const DISTANCE_METRICS = {
+  euclidean: (a, b) => {
+    const dx = a.x - b.x, dy = a.y - b.y, dz = a.z - b.z;
+    return Math.sqrt(dx*dx + dy*dy + dz*dz);
+  },
+  cosine: (a, b) => {
+    const dot = a.x*b.x + a.y*b.y + a.z*b.z;
+    const magA = Math.sqrt(a.x*a.x + a.y*a.y + a.z*a.z);
+    const magB = Math.sqrt(b.x*b.x + b.y*b.y + b.z*b.z);
+    if (magA === 0 || magB === 0) return 1;
+    return 1 - (dot / (magA * magB));  // Convert similarity to distance
+  },
+  manhattan: (a, b) => {
+    return Math.abs(a.x - b.x) + Math.abs(a.y - b.y) + Math.abs(a.z - b.z);
+  },
+  dot_product: (a, b) => {
+    // Negative dot product as distance (higher dot = closer)
+    return -(a.x*b.x + a.y*b.y + a.z*b.z);
+  },
+};
+
+function computeDistance(p1, p2, metric) {
+  const fn = DISTANCE_METRICS[metric] || DISTANCE_METRICS.euclidean;
+  return fn(p1, p2);
+}
+
 function getColorFromScale(value, scaleName, domain) {
   const scale = COLOR_SCALES[scaleName] || COLOR_SCALES.viridis;
   const [min, max] = domain || [0, 1];
@@ -74,7 +101,7 @@ function getCategoricalColor(value) {
 
 function render({ model, el }) {
   let scene, camera, renderer, controls;
-  let pointsGroup;
+  let pointsGroup, connectionsGroup;
   let raycaster, mouse;
   let hoveredObject = null;
   let tooltip;
@@ -127,6 +154,8 @@ function render({ model, el }) {
     // Groups
     pointsGroup = new THREE.Group();
     scene.add(pointsGroup);
+    connectionsGroup = new THREE.Group();
+    scene.add(connectionsGroup);
     axesGroup = new THREE.Group();
     scene.add(axesGroup);
 
@@ -135,6 +164,7 @@ function render({ model, el }) {
     setupRaycaster(container);
     setupTooltip(container);
     createPoints();
+    createConnections();
     bindModelEvents();
   }
 
@@ -349,6 +379,98 @@ function render({ model, el }) {
     }
   }
 
+  function createConnections() {
+    // Clear existing connections
+    while (connectionsGroup.children.length > 0) {
+      const obj = connectionsGroup.children[0];
+      if (obj.geometry) obj.geometry.dispose();
+      if (obj.material) obj.material.dispose();
+      connectionsGroup.remove(obj);
+    }
+
+    const points = model.get("points") || [];
+    const showConnections = model.get("show_connections");
+    const kNeighbors = model.get("k_neighbors") || 0;
+    const distanceThreshold = model.get("distance_threshold");
+    const referencePoint = model.get("reference_point");
+    const distanceMetric = model.get("distance_metric") || "euclidean";
+    const connectionColor = model.get("connection_color") || "#ffffff";
+    const connectionOpacity = model.get("connection_opacity") || 0.3;
+
+    if (!showConnections || points.length < 2) return;
+
+    const material = new THREE.LineBasicMaterial({
+      color: new THREE.Color(connectionColor),
+      transparent: true,
+      opacity: connectionOpacity,
+    });
+
+    // If reference point is set, connect to k-nearest or within threshold
+    if (referencePoint) {
+      const refIdx = points.findIndex(p => p.id === referencePoint);
+      if (refIdx === -1) return;
+      const ref = points[refIdx];
+
+      // Compute distances from reference
+      const distances = points.map((p, i) => ({
+        idx: i,
+        point: p,
+        dist: i === refIdx ? Infinity : computeDistance(ref, p, distanceMetric)
+      })).filter(d => d.dist !== Infinity);
+
+      // Sort by distance
+      distances.sort((a, b) => a.dist - b.dist);
+
+      // Select neighbors
+      let neighbors;
+      if (distanceThreshold !== null && distanceThreshold !== undefined) {
+        neighbors = distances.filter(d => d.dist <= distanceThreshold);
+      } else if (kNeighbors > 0) {
+        neighbors = distances.slice(0, kNeighbors);
+      } else {
+        return;
+      }
+
+      // Draw lines
+      neighbors.forEach(n => {
+        const geometry = new THREE.BufferGeometry();
+        const positions = new Float32Array([
+          ref.x ?? 0, ref.y ?? 0, ref.z ?? 0,
+          n.point.x ?? 0, n.point.y ?? 0, n.point.z ?? 0
+        ]);
+        geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+        const line = new THREE.Line(geometry, material);
+        connectionsGroup.add(line);
+      });
+    } else if (kNeighbors > 0) {
+      // Connect each point to its k-nearest neighbors
+      points.forEach((p, i) => {
+        const distances = points.map((other, j) => ({
+          idx: j,
+          point: other,
+          dist: i === j ? Infinity : computeDistance(p, other, distanceMetric)
+        })).filter(d => d.dist !== Infinity);
+
+        distances.sort((a, b) => a.dist - b.dist);
+        const neighbors = distances.slice(0, kNeighbors);
+
+        neighbors.forEach(n => {
+          // Only draw if i < n.idx to avoid duplicate lines
+          if (i < n.idx) {
+            const geometry = new THREE.BufferGeometry();
+            const positions = new Float32Array([
+              p.x ?? 0, p.y ?? 0, p.z ?? 0,
+              n.point.x ?? 0, n.point.y ?? 0, n.point.z ?? 0
+            ]);
+            geometry.setAttribute("position", new THREE.BufferAttribute(positions, 3));
+            const line = new THREE.Line(geometry, material);
+            connectionsGroup.add(line);
+          }
+        });
+      });
+    }
+  }
+
   function setupRaycaster(container) {
     raycaster = new THREE.Raycaster();
     mouse = new THREE.Vector2();
@@ -500,7 +622,7 @@ function render({ model, el }) {
   }
 
   function bindModelEvents() {
-    model.on("change:points", createPoints);
+    model.on("change:points", () => { createPoints(); createConnections(); });
     model.on("change:background", () => {
       scene.background = new THREE.Color(model.get("background"));
     });
@@ -514,6 +636,15 @@ function render({ model, el }) {
     model.on("change:shape_field", createPoints);
     model.on("change:shape_map", createPoints);
 
+    // Distance/connection related
+    model.on("change:show_connections", createConnections);
+    model.on("change:k_neighbors", createConnections);
+    model.on("change:distance_threshold", createConnections);
+    model.on("change:reference_point", createConnections);
+    model.on("change:distance_metric", createConnections);
+    model.on("change:connection_color", createConnections);
+    model.on("change:connection_opacity", createConnections);
+
     model.on("change:camera_position", () => {
       const pos = model.get("camera_position");
       if (pos) camera.position.set(pos[0], pos[1], pos[2]);
@@ -614,6 +745,19 @@ class VectorSpace(anywidget.AnyWidget):
     use_instancing = traitlets.Bool(default_value=True).tag(sync=True)
     point_budget = traitlets.Int(default_value=100000).tag(sync=True)
 
+    # Distance metrics and connections
+    distance_metric = traitlets.Unicode(default_value="euclidean").tag(
+        sync=True
+    )  # euclidean, cosine, manhattan, dot_product
+    show_connections = traitlets.Bool(default_value=False).tag(sync=True)
+    k_neighbors = traitlets.Int(default_value=0).tag(sync=True)  # k-nearest neighbors to connect
+    distance_threshold = traitlets.Float(default_value=None, allow_none=True).tag(
+        sync=True
+    )  # max distance for connections
+    reference_point = traitlets.Unicode(default_value=None, allow_none=True).tag(sync=True)  # point ID to measure from
+    connection_color = traitlets.Unicode(default_value="#ffffff").tag(sync=True)
+    connection_opacity = traitlets.Float(default_value=0.3).tag(sync=True)
+
     def __init__(
         self,
         points: list[dict[str, Any]] | None = None,
@@ -933,6 +1077,145 @@ class VectorSpace(anywidget.AnyWidget):
         """Clear all selections."""
         self.selected_points = []
 
+    # === Distance Methods ===
+
+    def compute_distances(
+        self,
+        reference_id: str,
+        metric: str | None = None,
+        vector_field: str = "vector",
+    ) -> dict[str, float]:
+        """Compute distances from a reference point to all other points.
+
+        Args:
+            reference_id: ID of the reference point
+            metric: Distance metric (euclidean, cosine, manhattan, dot_product).
+                   If None, uses self.distance_metric
+            vector_field: Field containing the full vector (for high-dim distance).
+                         Falls back to x,y,z if not present.
+
+        Returns:
+            Dict mapping point ID to distance from reference
+        """
+        metric = metric or self.distance_metric
+        ref_point = next((p for p in self.points if p.get("id") == reference_id), None)
+        if not ref_point:
+            return {}
+
+        ref_vec = self._get_vector(ref_point, vector_field)
+        distances = {}
+
+        for point in self.points:
+            if point.get("id") == reference_id:
+                continue
+            vec = self._get_vector(point, vector_field)
+            distances[point.get("id")] = self._compute_distance(ref_vec, vec, metric)
+
+        return distances
+
+    def find_neighbors(
+        self,
+        reference_id: str,
+        k: int | None = None,
+        threshold: float | None = None,
+        metric: str | None = None,
+        vector_field: str = "vector",
+    ) -> list[tuple[str, float]]:
+        """Find nearest neighbors of a reference point.
+
+        Args:
+            reference_id: ID of the reference point
+            k: Number of neighbors to return (if None, uses threshold)
+            threshold: Maximum distance (if None, uses k)
+            metric: Distance metric to use
+            vector_field: Field containing the full vector
+
+        Returns:
+            List of (point_id, distance) tuples, sorted by distance
+        """
+        distances = self.compute_distances(reference_id, metric, vector_field)
+        sorted_distances = sorted(distances.items(), key=lambda x: x[1])
+
+        if threshold is not None:
+            return [(pid, d) for pid, d in sorted_distances if d <= threshold]
+        elif k is not None:
+            return sorted_distances[:k]
+        else:
+            return sorted_distances
+
+    def color_by_distance(
+        self,
+        reference_id: str,
+        metric: str | None = None,
+        vector_field: str = "vector",
+    ) -> None:
+        """Color points by distance from a reference point.
+
+        Updates points with a '_distance' field and sets color_field to use it.
+        """
+        distances = self.compute_distances(reference_id, metric, vector_field)
+
+        # Update points with distance field
+        updated_points = []
+        for point in self.points:
+            point_copy = dict(point)
+            pid = point.get("id")
+            if pid == reference_id:
+                point_copy["_distance"] = 0.0
+            elif pid in distances:
+                point_copy["_distance"] = distances[pid]
+            updated_points.append(point_copy)
+
+        self.points = updated_points
+        self.color_field = "_distance"
+        self.reference_point = reference_id
+
+    def show_neighbors(
+        self,
+        reference_id: str,
+        k: int | None = None,
+        threshold: float | None = None,
+    ) -> None:
+        """Show connections to nearest neighbors of a reference point."""
+        self.reference_point = reference_id
+        self.show_connections = True
+        if k is not None:
+            self.k_neighbors = k
+        if threshold is not None:
+            self.distance_threshold = threshold
+
+    def _get_vector(self, point: dict[str, Any], vector_field: str) -> list[float]:
+        """Extract vector from point, falling back to x,y,z."""
+        if vector_field in point and point[vector_field]:
+            vec = point[vector_field]
+            return list(vec) if hasattr(vec, "__iter__") else [vec]
+        return [point.get("x", 0), point.get("y", 0), point.get("z", 0)]
+
+    def _compute_distance(self, v1: list[float], v2: list[float], metric: str) -> float:
+        """Compute distance between two vectors."""
+        import math
+
+        # Ensure same length
+        n = min(len(v1), len(v2))
+        v1, v2 = v1[:n], v2[:n]
+
+        if metric == "euclidean":
+            return math.sqrt(sum((a - b) ** 2 for a, b in zip(v1, v2)))
+        elif metric == "cosine":
+            dot = sum(a * b for a, b in zip(v1, v2))
+            mag1 = math.sqrt(sum(a * a for a in v1))
+            mag2 = math.sqrt(sum(b * b for b in v2))
+            if mag1 == 0 or mag2 == 0:
+                return 1.0
+            return 1 - (dot / (mag1 * mag2))
+        elif metric == "manhattan":
+            return sum(abs(a - b) for a, b in zip(v1, v2))
+        elif metric == "dot_product":
+            return -sum(a * b for a, b in zip(v1, v2))
+        else:
+            # Default to euclidean
+            return math.sqrt(sum((a - b) ** 2 for a, b in zip(v1, v2)))
+
     # === Export ===
 
     def to_json(self) -> str:

{anywidget_vector-0.1.0 → anywidget_vector-0.2.0}/tests/test_widget.py

@@ -175,3 +175,128 @@ class TestTraitlets:
         shape_map = {"type_a": "cube", "type_b": "cone"}
         widget = VectorSpace(shape_map=shape_map)
         assert widget.shape_map == shape_map
+
+
+class TestDistanceMetrics:
+    """Test distance computation methods."""
+
+    def test_default_distance_metric(self):
+        """Test default distance metric is euclidean."""
+        widget = VectorSpace()
+        assert widget.distance_metric == "euclidean"
+
+    def test_compute_distances_euclidean(self):
+        """Test euclidean distance computation."""
+        widget = VectorSpace(
+            points=[
+                {"id": "a", "x": 0, "y": 0, "z": 0},
+                {"id": "b", "x": 1, "y": 0, "z": 0},
+                {"id": "c", "x": 0, "y": 1, "z": 0},
+            ]
+        )
+        distances = widget.compute_distances("a", metric="euclidean")
+        assert abs(distances["b"] - 1.0) < 0.001
+        assert abs(distances["c"] - 1.0) < 0.001
+
+    def test_compute_distances_manhattan(self):
+        """Test manhattan distance computation."""
+        widget = VectorSpace(
+            points=[
+                {"id": "a", "x": 0, "y": 0, "z": 0},
+                {"id": "b", "x": 1, "y": 1, "z": 1},
+            ]
+        )
+        distances = widget.compute_distances("a", metric="manhattan")
+        assert abs(distances["b"] - 3.0) < 0.001
+
+    def test_compute_distances_cosine(self):
+        """Test cosine distance computation."""
+        widget = VectorSpace(
+            points=[
+                {"id": "a", "x": 1, "y": 0, "z": 0},
+                {"id": "b", "x": 1, "y": 0, "z": 0},  # Same direction
+                {"id": "c", "x": -1, "y": 0, "z": 0},  # Opposite direction
+            ]
+        )
+        distances = widget.compute_distances("a", metric="cosine")
+        assert abs(distances["b"] - 0.0) < 0.001  # Identical = 0 distance
+        assert abs(distances["c"] - 2.0) < 0.001  # Opposite = 2 distance
+
+    def test_find_neighbors_k(self):
+        """Test finding k nearest neighbors."""
+        widget = VectorSpace(
+            points=[
+                {"id": "a", "x": 0, "y": 0, "z": 0},
+                {"id": "b", "x": 1, "y": 0, "z": 0},
+                {"id": "c", "x": 2, "y": 0, "z": 0},
+                {"id": "d", "x": 3, "y": 0, "z": 0},
+            ]
+        )
+        neighbors = widget.find_neighbors("a", k=2)
+        assert len(neighbors) == 2
+        assert neighbors[0][0] == "b"  # Closest
+        assert neighbors[1][0] == "c"  # Second closest
+
+    def test_find_neighbors_threshold(self):
+        """Test finding neighbors within threshold."""
+        widget = VectorSpace(
+            points=[
+                {"id": "a", "x": 0, "y": 0, "z": 0},
+                {"id": "b", "x": 1, "y": 0, "z": 0},
+                {"id": "c", "x": 5, "y": 0, "z": 0},
+            ]
+        )
+        neighbors = widget.find_neighbors("a", threshold=2.0)
+        assert len(neighbors) == 1
+        assert neighbors[0][0] == "b"
+
+    def test_color_by_distance(self):
+        """Test coloring points by distance."""
+        widget = VectorSpace(
+            points=[
+                {"id": "a", "x": 0, "y": 0, "z": 0},
+                {"id": "b", "x": 1, "y": 0, "z": 0},
+            ]
+        )
+        widget.color_by_distance("a")
+        assert widget.color_field == "_distance"
+        assert widget.reference_point == "a"
+        assert widget.points[0]["_distance"] == 0.0
+        assert widget.points[1]["_distance"] == 1.0
+
+    def test_show_neighbors(self):
+        """Test showing neighbor connections."""
+        widget = VectorSpace(
+            points=[
+                {"id": "a", "x": 0, "y": 0, "z": 0},
+                {"id": "b", "x": 1, "y": 0, "z": 0},
+            ]
+        )
+        widget.show_neighbors("a", k=1)
+        assert widget.show_connections is True
+        assert widget.reference_point == "a"
+        assert widget.k_neighbors == 1
+
+
+class TestConnectionTraits:
+    """Test connection-related traits."""
+
+    def test_default_connections_off(self):
+        """Test connections are off by default."""
+        widget = VectorSpace()
+        assert widget.show_connections is False
+        assert widget.k_neighbors == 0
+        assert widget.distance_threshold is None
+
+    def test_connection_settings(self):
+        """Test connection trait settings."""
+        widget = VectorSpace(
+            show_connections=True,
+            k_neighbors=5,
+            connection_color="#ff0000",
+            connection_opacity=0.5,
+        )
+        assert widget.show_connections is True
+        assert widget.k_neighbors == 5
+        assert widget.connection_color == "#ff0000"
+        assert widget.connection_opacity == 0.5

{anywidget_vector-0.1.0 → anywidget_vector-0.2.0}/uv.lock

@@ -50,7 +50,7 @@ wheels = [
 
 [[package]]
 name = "anywidget-vector"
-version = "0.1.0"
+version = "0.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "anywidget" },