@fusion.dev/helix-graph 0.132.0 → 0.133.1

package/README.md

@@ -133,6 +133,12 @@ light. Each catches a glint from a light fixed in the scene, so the glint moves
 as the reader turns the graph. The selected note keeps its own color and is told apart by
 a ring and a glow in that color.
 
+**Data without groups can take them from its links.** `groupByCommunity(notes,
+links)` gives each note without a `group` the community its links form, found
+by Louvain and named after its most linked note, so the drawing colors the
+clusters and a `legend` names them. On 20,000 notes in twelve clusters it finds
+the twelve in about 65 milliseconds.
+
 **A note without a `size` is as large as it is connected**, so hubs read at a
 glance. Links are tinted by the note they leave, the selected note's and the
 hovered note's in their color, and choosing a note in the list frames it with
@@ -345,7 +351,7 @@ connectGraph(frame, threeDriver(box), {
 
 | Import | What |
 |---|---|
-| `@fusion.dev/helix-graph` | `connectGraph`, `diffGraph`, `fitToStencil`, `graphColorsFrom`, `linkKey`, `seedPositions`, and the types `ConnectGraphOptions`, `DrawnLink`, `DrawnNode`, `GraphChanges`, `GraphColors`, `GraphConnection`, `GraphDriver`, `GraphGroup`, `GraphLooks`, `GraphPoint`, `GraphStencil`, `GraphTone`, `LinkLook`, `NodeLook`, `SeedLink`, `SeedNode`, `ShapeField` and `StencilFrame` |
+| `@fusion.dev/helix-graph` | `communitiesOf`, `connectGraph`, `diffGraph`, `fitToStencil`, `graphColorsFrom`, `groupByCommunity`, `linkKey`, `seedPositions`, and the types `ConnectGraphOptions`, `DrawnLink`, `DrawnNode`, `GraphChanges`, `GraphColors`, `GraphConnection`, `GraphDriver`, `GraphGroup`, `GraphLooks`, `GraphPoint`, `GraphReach`, `GraphStencil`, `GraphTone`, `GroupByCommunityOptions`, `LinkLook`, `NodeLook`, `SeedLink`, `SeedNode`, `ShapeField` and `StencilFrame` |
 | `@fusion.dev/helix-graph/sigma` | `sigmaDriver(sigma, options)`, and the types `SigmaDriverOptions`, `SigmaGraph`, `SigmaLayout` and `SigmaRenderer` |
 | `@fusion.dev/helix-graph/cosmos` | `cosmosDriver(graph, box, options)`, and the types `CosmosDriverOptions` and `CosmosGraph` |
 | `@fusion.dev/helix-graph/three` | `threeDriver(box, options)`, and the type `ThreeDriverOptions` |

package/dist/connect-graph/communities.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Groups found in the links, for a graph whose notes carry none.
+ *
+ * **Louvain**, which moves each note to the neighboring community that raises
+ * the graph's modularity most, then folds each community into one note and
+ * moves those, until nothing moves. Written here, not taken from a package,
+ * so it costs a page no dependency and runs for every renderer: it reads the
+ * notes and links a page hands the frame, and gives back notes with a `group`.
+ *
+ * **The same communities on every load.** Notes are visited in the order the
+ * page gives them and a tie keeps the community a note is in, so nothing
+ * random decides where a note lands.
+ */
+/** A link, as the frame takes it. */
+interface Link {
+    source: string;
+    target: string;
+}
+/** A note, as the frame takes it, as far as communities read it. */
+interface Note {
+    group?: string | undefined;
+    id: string;
+    label?: string | undefined;
+}
+/**
+ * Each note's community, by `id`, numbered from 0 in the order the
+ * communities first appear among the notes. A note no link touches is a
+ * community of its own.
+ */
+export declare const communitiesOf: (ids: readonly string[], links: readonly Link[]) => Map<string, number>;
+/** How `groupByCommunity` names and gathers what it finds. */
+export interface GroupByCommunityOptions {
+    /**
+     * The fewest notes a community needs to be a group of its own. Smaller ones
+     * share one group, named by `rest`, so a scatter of loose notes is one name
+     * in the legend and not hundreds. 3 by default.
+     */
+    fewest?: number | undefined;
+    /** The group the small communities share. `Other` by default. */
+    rest?: string | undefined;
+}
+/**
+ * The notes, each without a group given one from the communities its links
+ * form, **named after its community's most linked note**, so a reader sees
+ * "Pricing" over the cluster around Pricing. A note with a group keeps it.
+ * Hand the result to the frame as its `nodes`; the drawing colors the groups
+ * and a `legend` names them.
+ */
+export declare const groupByCommunity: <T extends Note>(nodes: readonly T[], links: readonly Link[], options?: GroupByCommunityOptions) => (T & {
+    group: string;
+})[];
+export {};

package/dist/connect-graph/communities.js

@@ -0,0 +1,154 @@
+const GAIN = 1e-12;
+const PASSES = 32;
+const add = (list, at, by) => {
+    list[at] = (list[at] ?? 0) + by;
+};
+const settle = (level, total, community) => {
+    const count = level.degree.length;
+    const sums = new Array(count).fill(0);
+    for (let node = 0; node < count; node++) {
+        add(sums, community[node], level.degree[node]);
+    }
+    let movedAtAll = false;
+    for (let pass = 0; pass < PASSES; pass++) {
+        let moved = false;
+        for (let node = 0; node < count; node++) {
+            const own = community[node];
+            const degree = level.degree[node];
+            const toward = new Map();
+            for (const [other, weight] of level.near[node]) {
+                const at = community[other];
+                toward.set(at, (toward.get(at) ?? 0) + weight);
+            }
+            add(sums, own, -degree);
+            let best = own;
+            let bestGain = (toward.get(own) ?? 0) - (sums[own] * degree) / total;
+            for (const [at, weight] of toward) {
+                const gain = weight - (sums[at] * degree) / total;
+                if (gain > bestGain + GAIN) {
+                    best = at;
+                    bestGain = gain;
+                }
+            }
+            add(sums, best, degree);
+            if (best !== own) {
+                community[node] = best;
+                moved = true;
+                movedAtAll = true;
+            }
+        }
+        if (!moved) {
+            break;
+        }
+    }
+    return movedAtAll;
+};
+const renumber = (community) => {
+    const numbers = new Map();
+    return community.map((at) => {
+        let number = numbers.get(at);
+        if (number === undefined) {
+            number = numbers.size;
+            numbers.set(at, number);
+        }
+        return number;
+    });
+};
+const fold = (level, community, count) => {
+    const near = Array.from({ length: count }, () => new Map());
+    const degree = new Array(count).fill(0);
+    level.near.forEach((neighbors, node) => {
+        const from = community[node];
+        add(degree, from, level.degree[node]);
+        for (const [other, weight] of neighbors) {
+            const to = community[other];
+            if (to !== from) {
+                const ofFrom = near[from];
+                ofFrom.set(to, (ofFrom.get(to) ?? 0) + weight);
+            }
+        }
+    });
+    return { degree, near };
+};
+export const communitiesOf = (ids, links) => {
+    const index = new Map(ids.map((id, at) => [id, at]));
+    const near = ids.map(() => new Map());
+    const degree = new Array(ids.length).fill(0);
+    for (const { source, target } of links) {
+        const from = index.get(source);
+        const to = index.get(target);
+        if (from === undefined || to === undefined || from === to) {
+            continue;
+        }
+        const ofFrom = near[from];
+        const ofTo = near[to];
+        ofFrom.set(to, (ofFrom.get(to) ?? 0) + 1);
+        ofTo.set(from, (ofTo.get(from) ?? 0) + 1);
+        add(degree, from, 1);
+        add(degree, to, 1);
+    }
+    const total = degree.reduce((sum, one) => sum + one, 0);
+    let placed = ids.map((_, at) => at);
+    if (total === 0) {
+        return new Map(ids.map((id, at) => [id, at]));
+    }
+    let level = { degree, near };
+    for (;;) {
+        const community = level.degree.map((_, at) => at);
+        if (!settle(level, total, community)) {
+            break;
+        }
+        const numbered = renumber(community);
+        const count = Math.max(...numbered) + 1;
+        placed = placed.map((at) => numbered[at]);
+        if (count === level.degree.length) {
+            break;
+        }
+        level = fold(level, numbered, count);
+    }
+    const final = renumber(placed);
+    return new Map(ids.map((id, at) => [id, final[at]]));
+};
+export const groupByCommunity = (nodes, links, options = {}) => {
+    const fewest = options.fewest ?? 3;
+    const rest = options.rest ?? 'Other';
+    const found = communitiesOf(nodes.map((node) => node.id), links);
+    const degree = new Map();
+    for (const { source, target } of links) {
+        if (source !== target) {
+            degree.set(source, (degree.get(source) ?? 0) + 1);
+            degree.set(target, (degree.get(target) ?? 0) + 1);
+        }
+    }
+    const members = new Map();
+    for (const node of nodes) {
+        const at = found.get(node.id);
+        const list = members.get(at);
+        if (list) {
+            list.push(node);
+        }
+        else {
+            members.set(at, [node]);
+        }
+    }
+    const names = new Map();
+    const taken = new Set(nodes.flatMap((node) => (node.group ? [node.group] : [])));
+    for (const [at, list] of members) {
+        if (list.length < fewest) {
+            names.set(at, rest);
+            continue;
+        }
+        const hub = list.reduce((best, node) => (degree.get(node.id) ?? 0) > (degree.get(best.id) ?? 0) ? node : best);
+        const base = hub.label || hub.id;
+        let name = base;
+        for (let number = 2; taken.has(name) || name === rest; number++) {
+            name = `${base} ${number}`;
+        }
+        taken.add(name);
+        names.set(at, name);
+    }
+    return nodes.map((node) => ({
+        ...node,
+        group: node.group || names.get(found.get(node.id)),
+    }));
+};

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { communitiesOf, type GroupByCommunityOptions, groupByCommunity, } from './connect-graph/communities.js';
 export { type ConnectGraphOptions, connectGraph, type DrawnLink, type DrawnNode, type GraphChanges, type GraphConnection, type GraphDriver, type GraphGroup, type GraphReach, } from './connect-graph/connect-graph.js';
 export { diffGraph, linkKey } from './connect-graph/diff.js';
 export { type GraphColors, type GraphLooks, type GraphTone, graphColorsFrom, type LinkLook, type NodeLook, } from './connect-graph/looks.js';

package/dist/index.js

@@ -1,3 +1,4 @@
+export { communitiesOf, groupByCommunity, } from './connect-graph/communities.js';
 export { connectGraph, } from './connect-graph/connect-graph.js';
 export { diffGraph, linkKey } from './connect-graph/diff.js';
 export { graphColorsFrom, } from './connect-graph/looks.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-graph",
   "description": "Connects the Helix Graph frame to a graph renderer: Sigma.js, cosmos.gl, three.js, or a driver of your own.",
-  "version": "0.132.0",
+  "version": "0.133.1",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -51,12 +51,12 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.132.0"
+    "@fusion.dev/helix-core": "0.133.1"
   },
   "devDependencies": {
     "@cosmos.gl/graph": "^3.4.2",
-    "@fusion.dev/helix-headless": "0.132.0",
-    "@fusion.dev/helix-testing": "0.132.0",
+    "@fusion.dev/helix-headless": "0.133.1",
+    "@fusion.dev/helix-testing": "0.133.1",
     "@types/bun": "^1.3.0",
     "@types/three": "^0.186.0",
     "d3-force-3d": "^3.0.6",