lightgraph 1.1.1__tar.gz → 1.2.0__tar.gz

{lightgraph-1.1.1 → lightgraph-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lightgraph
-Version: 1.1.1
+Version: 1.2.0
 Summary: A lightweight Python binding for lightGraph network visualization
 Author-email: Hao Zhu <haozhu233@gmail.com>, Aiden McComiskey <aiden.mccomiskey@tufts.edu>, Donna Slonim <donna.slonim@tufts.edu>
 Requires-Python: >=3.6

{lightgraph-1.1.1 → lightgraph-1.2.0}/lightgraph/assets/lightgraph.js

@@ -91,7 +91,15 @@
         groups: {
             fillOpacity: 0.125,
             strokeWidth: 2,
-            showEllipses: true
+            showEllipses: true,
+            // Pinned assignments: {groupName: hexColor}. Wins over the
+            // palette for the named groups; unmatched names are ignored so
+            // one map can be reused across filtered subsets.
+            colors: null,
+            // Explicit palette domain: [groupName, ...]. Listed groups keep
+            // their palette slot even when absent from the data, so a shared
+            // order keeps colors stable across a series of figures.
+            colorOrder: null
         },
         canvas: {
             backgroundColor: '#ffffff',
@@ -918,6 +926,35 @@
             ...d3.schemeSet3
         ];
         const groupColorScale = d3.scaleOrdinal(extendedColors);
+        // Seed the palette domain deterministically on every data load:
+        // config.groups.colorOrder first (listed groups keep their slot even
+        // when absent from the data), then the remaining groups in sorted
+        // order. Without an explicit domain d3 assigns colors by first paint
+        // order, so the same group changes color whenever the node array does.
+        function updateGroupColorDomain() {
+            const present = [...new Set(nodes.map(n => n.group).filter(Boolean))].sort();
+            const order = config.groups.colorOrder;
+            const ordered = Array.isArray(order) ? order.map(String)
+                : (order != null ? [String(order)] : []);
+            const orderSet = new Set(ordered);
+            const domain = [...new Set([...ordered, ...present.filter(g => !orderSet.has(g))])];
+            if (domain.length > extendedColors.length) {
+                console.warn(`lightGraph: ${domain.length} groups exceed the `
+                    + `${extendedColors.length}-color palette; colors will repeat. `
+                    + `Pin colors via config.groups.colors to disambiguate.`);
+            }
+            groupColorScale.domain(domain);
+        }
+        // Single resolution point for every group-colored surface (legend
+        // swatch, node fill, ellipse, tooltip dot, SVG export): pinned
+        // config.groups.colors first, palette otherwise.
+        function getGroupColor(group) {
+            const pinned = config.groups.colors;
+            if (pinned && Object.prototype.hasOwnProperty.call(pinned, group)) {
+                return pinned[group];
+            }
+            return groupColorScale(group);
+        }
         // Modeless interaction: d3-zoom owns wheel events and drags that
         // start on empty space; node drags and shift box-selects fall
         // through to the canvas listeners below.
@@ -1148,7 +1185,7 @@
                     width: '11px',
                     height: '11px',
                     borderRadius: '3px',
-                    backgroundColor: groupColorScale(group),
+                    backgroundColor: getGroupColor(group),
                     flexShrink: '0'
                 });
 
@@ -1403,7 +1440,7 @@
             maxNodeSize = config.nodes.defaultSize;
             for (const d of nodes) {
                 if (egoSet && !egoSet.has(d)) continue;
-                const color = d.group ? groupColorScale(d.group) : (d.color || config.nodes.defaultColor);
+                const color = d.group ? getGroupColor(d.group) : (d.color || config.nodes.defaultColor);
                 const isSelected = selectedNodes.has(d);
                 const isFaded = highlightSet !== null && !highlightSet.has(d);
                 let opacity = d.opacity !== undefined ? d.opacity : config.nodes.defaultOpacity;
@@ -1608,9 +1645,9 @@
                 context.rotate(angle);
                 context.beginPath();
                 context.ellipse(0, 0, radiusX + 5, radiusY + 5, 0, 0, 2 * Math.PI);
-                context.fillStyle = hexToRgba(groupColorScale(group), config.groups.fillOpacity);
+                context.fillStyle = hexToRgba(getGroupColor(group), config.groups.fillOpacity);
                 context.fill();
-                context.strokeStyle = groupColorScale(group);
+                context.strokeStyle = getGroupColor(group);
                 context.lineWidth = config.groups.strokeWidth;
                 context.stroke();
                 context.restore();
@@ -1648,6 +1685,7 @@
             nodes = newNodes;
             edges = newEdges;
 
+            updateGroupColorDomain();
             recalculateForce();
             updateEdgeAlpha();
             updateLegend();
@@ -1929,7 +1967,7 @@
             if (config.ui.showTooltips && hoveredNode) {
                 let tooltipContent = `<strong>${escapeHtml(hoveredNode.id)}</strong>`;
                 if (hoveredNode.group) {
-                    tooltipContent += `<br><span style="color: ${groupColorScale(hoveredNode.group)};">● ${escapeHtml(hoveredNode.group)}</span>`;
+                    tooltipContent += `<br><span style="color: ${getGroupColor(hoveredNode.group)};">● ${escapeHtml(hoveredNode.group)}</span>`;
                 }
                 // Add any custom metadata
                 if (hoveredNode.metadata) {
@@ -2158,7 +2196,7 @@
                 circle.setAttribute('cy', node.y);
                 circle.setAttribute('r',
                     (node.size || config.nodes.defaultSize) * config.nodes.sizeScale / 2);
-                circle.setAttribute('fill', node.group ? groupColorScale(node.group) : (node.color || config.nodes.defaultColor));
+                circle.setAttribute('fill', node.group ? getGroupColor(node.group) : (node.color || config.nodes.defaultColor));
                 circle.setAttribute('stroke', config.nodes.borderColor);
                 circle.setAttribute('stroke-width', config.nodes.borderWidth);
                 g.appendChild(circle);
@@ -2246,6 +2284,9 @@
         // Merge a partial config over the current one and re-render.
         this.updateConfig = (partial = {}) => {
             config = mergeConfig(config, partial);
+            if (partial.groups && ('colors' in partial.groups || 'colorOrder' in partial.groups)) {
+                updateGroupColorDomain();
+            }
             if (partial.edges && 'showArrows' in partial.edges) {
                 showArrows = config.edges.showArrows;
                 arrowsToggle.checked = showArrows;

{lightgraph-1.1.1 → lightgraph-1.2.0}/lightgraph/network.py

@@ -8,7 +8,7 @@ import base64
 import uuid
 import numpy as np
 import os
-from typing import Optional, Dict, Union, Literal
+from typing import Optional, Dict, List, Union, Literal
 
 from .analytics import _normalize_edges, communities as _communities
 
@@ -151,6 +151,8 @@ def net_vis(
     adj_matrix=None,
     node_names=None,
     node_groups: Optional[Union[Dict[str, str], str]] = None,
+    group_colors: Optional[Dict[str, str]] = None,
+    group_order: Optional[List[str]] = None,
     node_colors: Optional[Dict[str, str]] = None,
     node_sizes: Optional[Dict[str, float]] = None,
     remove_unconnected: bool = True,
@@ -252,6 +254,18 @@ def net_vis(
         Dictionary mapping node names to group identifiers for coloring.
         Pass 'auto' to detect communities automatically (networkx Louvain
         when installed, else a built-in label-propagation fallback).
+    group_colors : dict, optional
+        Mapping of group name to hex color (e.g. {'alpha': '#ff7f0e'}),
+        pinning those groups' colors. Unpinned groups stay on the default
+        palette. Names matching no group are ignored, so one mapping can be
+        reused across filtered subsets of the same data.
+    group_order : list, optional
+        Explicit group ordering for palette assignment. Groups keep their
+        palette slot even when absent from the data, so passing the same
+        list (e.g. computed once from the full dataset) to every figure in
+        a series keeps each group's color stable across subsets. Groups not
+        listed are appended in sorted order. Without group_order, groups
+        are assigned palette colors in sorted-name order.
     node_colors : dict, optional
         Dictionary mapping node names to hex color strings (e.g., '#FF5733').
     node_sizes : dict, optional
@@ -381,6 +395,10 @@ def net_vis(
         raise ValueError("node_groups must be a dictionary or 'auto'.")
     if node_colors is not None and not isinstance(node_colors, dict):
         raise ValueError("node_colors must be a dictionary.")
+    if group_colors is not None and not isinstance(group_colors, dict):
+        raise ValueError("group_colors must be a dictionary of {group: hex_color}.")
+    if group_order is not None and isinstance(group_order, (str, dict)):
+        raise ValueError("group_order must be a list of group names.")
     if node_sizes is not None and not isinstance(node_sizes, dict):
         raise ValueError("node_sizes must be a dictionary.")
     if node_metric is not None and not isinstance(node_metric, dict):
@@ -573,6 +591,11 @@ def net_vis(
         graph_config['ui']['metricLegend'] = metric_legend
 
     # Only set optional values if explicitly provided
+    if group_colors is not None:
+        graph_config['groups']['colors'] = {
+            str(k): str(v) for k, v in group_colors.items()}
+    if group_order is not None:
+        graph_config['groups']['colorOrder'] = [str(g) for g in group_order]
     if node_color is not None:
         graph_config['nodes']['defaultColor'] = node_color
     if edge_width is not None:

{lightgraph-1.1.1 → lightgraph-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "lightgraph"
-version = "1.1.1"
+version = "1.2.0"
 description = "A lightweight Python binding for lightGraph network visualization"
 authors = [
     {name = "Hao Zhu", email = "haozhu233@gmail.com"},

{lightgraph-1.1.1 → lightgraph-1.2.0}/tests/test_network.py

@@ -367,6 +367,28 @@ class TestDataInputs:
         with pytest.raises(ValueError, match="dictionary or 'auto'"):
             net_vis(edges=[('A', 'B')], node_groups='louvain')
 
+    def test_group_colors_and_order_config(self):
+        result = net_vis(edges=[('A', 'B'), ('B', 'C')],
+                         node_groups={'A': 'g1', 'B': 'g2', 'C': 'g1'},
+                         group_colors={'g1': '#ff7f0e'},
+                         group_order=['g2', 'g1'])
+        groups = self._extract_config(result)['groups']
+        assert groups['colors'] == {'g1': '#ff7f0e'}
+        assert groups['colorOrder'] == ['g2', 'g1']
+
+    def test_group_colors_omitted_by_default(self):
+        result = net_vis(edges=[('A', 'B')],
+                         node_groups={'A': 'g1', 'B': 'g2'})
+        groups = self._extract_config(result)['groups']
+        assert 'colors' not in groups
+        assert 'colorOrder' not in groups
+
+    def test_group_colors_validation(self):
+        with pytest.raises(ValueError, match="group_colors"):
+            net_vis(edges=[('A', 'B')], group_colors=['#ff0000'])
+        with pytest.raises(ValueError, match="group_order"):
+            net_vis(edges=[('A', 'B')], group_order='g1')
+
     def test_sparse_matrix(self):
         scipy_sparse = pytest.importorskip('scipy.sparse')
         adj = scipy_sparse.csr_matrix(np.array([[0, 1, 0], [1, 0, 1], [0, 1, 0]]))

{lightgraph-1.1.1 → lightgraph-1.2.0}/uv.lock

@@ -1564,7 +1564,7 @@ wheels = [
 
 [[package]]
 name = "lightgraph"
-version = "1.1.1"
+version = "1.2.0"
 source = { editable = "." }
 dependencies = [
     { name = "ipython", version = "7.16.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.7'" },