lightgraph 1.1.0__tar.gz → 1.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lightgraph
-Version: 1.1.0
+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.0 → lightgraph-1.2.0}/lightgraph/__init__.py

@@ -1,5 +1,6 @@
 from .network import net_vis, NetworkVisualization
 from . import analytics
+from . import datasets
 from .analytics import (
     degree,
     betweenness,
@@ -17,6 +18,7 @@ __all__ = [
     'net_vis',
     'NetworkVisualization',
     'analytics',
+    'datasets',
     'degree',
     'betweenness',
     'closeness',

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

@@ -34,9 +34,9 @@
         edges: {
             defaultColor: '#333333',
             selectedColor: '#999999',
-            defaultOpacity: 0.1,
+            defaultOpacity: 0.3,
             selectedOpacity: 0.6,
-            defaultWidth: 0.3,
+            defaultWidth: 0.45,
             selectedWidth: 2,
             // Scale edge opacity (and, when weight-mapped widths make
             // strokes thick, edge width) by on-screen ink density so dense
@@ -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',
@@ -112,7 +120,14 @@
             theme: 'light',
             showLegend: true,
             showStatistics: false,
-            showTooltips: true
+            showTooltips: true,
+            // Metadata describing a numeric metric encoded as node size
+            // and/or color, rendered as an extra legend section. The
+            // Python/R wrappers set this automatically for node_metric;
+            // standalone users can supply it directly:
+            // { label, min, max, map: 'size'|'color'|'both',
+            //   sizeRange: [minPx, maxPx], colors: [lowHex, highHex] }
+            metricLegend: null
         },
         layout: 'force' // 'force' or 'circular'
     };
@@ -172,6 +187,25 @@
         return value;
     }
 
+    // Linear interpolation between two '#rrggbb' colors; used for the
+    // metric legend's size dots when the metric also drives color.
+    function lerpHex(hex0, hex1, t) {
+        const c0 = [1, 3, 5].map(i => parseInt(hex0.slice(i, i + 2), 16));
+        const c1 = [1, 3, 5].map(i => parseInt(hex1.slice(i, i + 2), 16));
+        return '#' + c0.map((v, i) => Math.round(v + (c1[i] - v) * t)
+            .toString(16).padStart(2, '0')).join('');
+    }
+
+    // Compact human-readable form of a metric value for legend labels.
+    function formatMetricValue(value) {
+        if (!Number.isFinite(value)) return '';
+        const abs = Math.abs(value);
+        if (abs !== 0 && (abs < 0.001 || abs >= 100000)) {
+            return value.toExponential(2);
+        }
+        return String(parseFloat(value.toPrecision(3)));
+    }
+
     // Eigen decomposition of a symmetric 2x2 covariance matrix; used for the
     // orientation and radii of group ellipses.
     function computeEigen(covMatrix) {
@@ -268,6 +302,10 @@
             throw new Error('LightGraph: d3 v7 must be loaded (or passed via options.d3)');
         }
         const self = this;
+        // Expose the instance on the container element so embedding hosts
+        // (the R htmlwidget, generated Python/R pages, onRender hooks) can
+        // reach the API without holding the constructor's return value.
+        container.lightgraph = this;
         const userConfig = options.config || {};
         const theme = (userConfig.ui && userConfig.ui.theme) || DEFAULT_CONFIG.ui.theme;
         let config = mergeConfig(
@@ -793,20 +831,18 @@
             bottom: '16px',
             left: '16px',
             padding: '10px 12px',
-            maxHeight: '220px',
+            // Cap the legend to roughly half the viewport; long group
+            // lists (plus the metric section) scroll beyond that.
+            maxHeight: 'min(50%, 340px)',
             overflowY: 'auto',
             fontSize: '12px',
             display: 'none',
             minWidth: '130px'
         });
-        const legendTitle = createElement('div', { textContent: 'Groups' }, {
-            marginBottom: '6px',
-            paddingBottom: '5px',
-            fontWeight: '600',
-            borderBottom: '1px solid var(--lg-border)'
-        });
+        // Section titles ('Groups', metric label) are rebuilt inside
+        // updateLegend along with the items.
         const legendContent = createElement('div', { id: 'legendContent' });
-        legendPanel.append(legendTitle, legendContent);
+        legendPanel.append(legendContent);
         lightGraph.appendChild(legendPanel);
 
         // 1.3.4 Statistics Panel
@@ -890,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.
@@ -1020,6 +1085,76 @@
         function hideFloatingInput(x, y) {
             floatingInput.style.display = 'none';
         }
+        function legendSectionTitle(text, isFirst) {
+            return createElement('div', { textContent: text }, {
+                marginTop: isFirst ? '0' : '10px',
+                marginBottom: '6px',
+                paddingBottom: '5px',
+                fontWeight: '600',
+                borderBottom: '1px solid var(--lg-border)'
+            });
+        }
+
+        // Legend section for a metric encoded as node size and/or color:
+        // a row of proportionally sized dots for size, a gradient bar for
+        // color, and min/max value labels underneath.
+        function buildMetricLegend(metric) {
+            const section = createElement('div', { id: 'metricLegend' });
+            const mapsSize = metric.map === 'size' || metric.map === 'both';
+            const mapsColor = metric.map === 'color' || metric.map === 'both';
+            const colors = (mapsColor && Array.isArray(metric.colors)
+                && metric.colors.length >= 2) ? metric.colors : null;
+
+            if (mapsSize) {
+                const range = (Array.isArray(metric.sizeRange)
+                    && metric.sizeRange.length >= 2) ? metric.sizeRange : [4, 20];
+                // Dots keep their relative proportions but are capped so
+                // large node sizes do not blow up the panel.
+                const scale = Math.min(1, 16 / Math.max(range[0], range[1], 1));
+                const row = createElement('div', {}, {
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: '8px',
+                    margin: '2px 0 4px'
+                });
+                [0, 0.5, 1].forEach(t => {
+                    const d = Math.max(3,
+                        (range[0] + t * (range[1] - range[0])) * scale);
+                    row.appendChild(createElement('div', {}, {
+                        width: `${d}px`,
+                        height: `${d}px`,
+                        borderRadius: '50%',
+                        backgroundColor: colors
+                            ? lerpHex(colors[0], colors[1], t)
+                            : config.nodes.defaultColor,
+                        flexShrink: '0'
+                    }));
+                });
+                section.appendChild(row);
+            }
+            if (colors) {
+                section.appendChild(createElement('div', { className: 'lg-metric-gradient' }, {
+                    height: '10px',
+                    borderRadius: '3px',
+                    background: `linear-gradient(to right, ${colors[0]}, ${colors[1]})`,
+                    margin: '2px 0 4px'
+                }));
+            }
+            const labels = createElement('div', {}, {
+                display: 'flex',
+                justifyContent: 'space-between',
+                gap: '12px',
+                color: 'var(--lg-muted)',
+                fontSize: '11px'
+            });
+            labels.append(
+                createElement('span', { textContent: formatMetricValue(metric.min) }),
+                createElement('span', { textContent: formatMetricValue(metric.max) })
+            );
+            section.appendChild(labels);
+            return section;
+        }
+
         function updateLegend() {
             if (!config.ui.showLegend) {
                 legendPanel.style.display = 'none';
@@ -1027,7 +1162,11 @@
             }
 
             const groups = [...new Set(nodes.map(node => node.group).filter(Boolean))].sort();
-            if (groups.length === 0) {
+            const metric = config.ui.metricLegend;
+            const hasMetric = !!(metric
+                && ['size', 'color', 'both'].includes(metric.map)
+                && Number.isFinite(metric.min) && Number.isFinite(metric.max));
+            if (groups.length === 0 && !hasMetric) {
                 legendPanel.style.display = 'none';
                 return;
             }
@@ -1035,6 +1174,9 @@
             legendPanel.style.display = 'block';
             legendContent.innerHTML = '';
 
+            if (groups.length > 0) {
+                legendContent.appendChild(legendSectionTitle('Groups', true));
+            }
             groups.forEach(group => {
                 const count = nodes.filter(n => n.group === group).length;
                 const item = createElement('div', { className: 'lg-legend-item' });
@@ -1043,7 +1185,7 @@
                     width: '11px',
                     height: '11px',
                     borderRadius: '3px',
-                    backgroundColor: groupColorScale(group),
+                    backgroundColor: getGroupColor(group),
                     flexShrink: '0'
                 });
 
@@ -1059,6 +1201,12 @@
 
                 legendContent.appendChild(item);
             });
+
+            if (hasMetric) {
+                legendContent.appendChild(legendSectionTitle(
+                    metric.label || 'Metric', groups.length === 0));
+                legendContent.appendChild(buildMetricLegend(metric));
+            }
         }
 
         function updateStatistics() {
@@ -1207,11 +1355,16 @@
             const meanScreenWidth = screenEdgeWidth(totalWidth / counted);
             const coverage = edges.length * meanScreenLen *
                 meanScreenWidth * visibleShare / viewArea;
-            // Aim for ~40% accumulated alpha coverage. Only ever dim: sparse
-            // graphs keep their configured style (factors cap at 1), and
-            // the effective alpha never drops below 0.02.
+            // Sub-linear ink budget, tuned on a matrix of graph sizes and
+            // degrees (benchmark: 50-5000 nodes, mean degree 2-16): target
+            // alpha ~= 0.12/sqrt(coverage). Linear-in-coverage budgets fail
+            // at both ends — edges concentrate near the center, so a budget
+            // loose enough for hairballs lets mid-density graphs go gray,
+            // and one tight enough for mid-density erases hairball fringes.
+            // Only ever dims: sparse graphs keep their configured style
+            // (factors cap at 1), and effective alpha never drops below 0.02.
             const base = Math.max(baseEdgeAlpha(), 0.001);
-            const ideal = 0.4 / Math.max(coverage, 1e-6);
+            const ideal = 0.12 / Math.sqrt(Math.max(coverage, 1e-6));
             const needed = Math.min(1, ideal / base);
             // Width absorbs up to half the correction (in log space), but
             // the mean stroke never shrinks below the 0.5px hairline — so
@@ -1287,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;
@@ -1492,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();
@@ -1532,6 +1685,7 @@
             nodes = newNodes;
             edges = newEdges;
 
+            updateGroupColorDomain();
             recalculateForce();
             updateEdgeAlpha();
             updateLegend();
@@ -1813,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) {
@@ -2042,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);
@@ -2130,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;
@@ -2235,6 +2392,9 @@
              legendPanel, statsPanel, tooltip].forEach(el => el.remove());
             lightGraph.classList.remove('lg-root');
             lightGraph.removeAttribute('data-lg-theme');
+            if (container.lightgraph === self) {
+                delete container.lightgraph;
+            }
         };
 
         // Initial data load
@@ -2309,6 +2469,8 @@
         mergeConfig,
         escapeHtml,
         hexToRgba,
+        lerpHex,
+        formatMetricValue,
         computeEigen,
         isNodeInSelection
     };