@graphty/algorithms 2.1.2 → 2.2.0

package/dist/src/indexed/link-prediction.js

@@ -0,0 +1,317 @@
+/**
+ * Link prediction over a snapshot: common-neighbour and Adamic-Adar scores for one pair, a list of
+ * pairs, every pair, or one node's candidates, and the ranking metrics of a held-out evaluation.
+ *
+ * Every score is a merge of two sorted rows with simple-graph semantics: a neighbour reached by
+ * parallel arcs counts once, and a self-loop makes a node its own neighbour. With
+ * `{ directed: true }` a pair (u, v) intersects out(u) with in(v) -- the nodes on a path u -> z -> v
+ * -- and otherwise the two out rows (the two rows of an undirected snapshot).
+ *
+ * A node index at or beyond `nodeCount`, `INVALID_INDEX` included, is an absent node: its pairs
+ * score 0 and it has no candidates.
+ * @module
+ */
+import { sortedRowMerge } from "./common-neighbors.js";
+/**
+ * Adamic-Adar weights are multiples of 2^-36, so any sum of them below 2^16 is exact and the same in
+ * whatever order it is added: two pairs whose common neighbours have the same degrees score
+ * bit-identically, and a ranking never splits them by rounding. The snap moves a weight by at most
+ * 2^-37, far inside the 1e-9 relative tolerance of a score.
+ */
+const WEIGHT_GRID = 2 ** 36;
+/**
+ * The Adamic-Adar weight of a common neighbour of the given degree: 1 / ln(degree) snapped to the
+ * weight grid, 1 for degree 1 (ln 1 is 0) and 0 for degree 0. The legacy `adamicAdarScore` adds
+ * the unsnapped weights in neighbour-visit order, so its scores differ from these in the last bits
+ * and it may order two exactly tied pairs either way.
+ * @param degree - The neighbour's degree
+ * @returns The weight
+ */
+function adamicAdarWeight(degree) {
+    // ponytail: exact only while a pair's score stays below 2^16 (tens of thousands of hub neighbours);
+    // a coarser grid chosen from the graph's largest row sum lifts that ceiling if it is ever reached.
+    if (degree > 1) {
+        return Math.round(WEIGHT_GRID / Math.log(degree)) / WEIGHT_GRID;
+    }
+    return degree === 1 ? 1 : 0;
+}
+/**
+ * The number of distinct entries of one row of a sorted adjacency.
+ * @param view - The adjacency
+ * @param z - The row
+ * @returns The count
+ */
+function distinctRowLength(view, z) {
+    const start = view.rowPtr[z];
+    const end = view.rowPtr[z + 1];
+    let count = 0;
+    for (let a = start; a < end; a++) {
+        if (a === start || view.colIdx[a] !== view.colIdx[a - 1]) {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * The Adamic-Adar weight of a node as a common neighbour, from its degree in distinct neighbours:
+ * out-neighbours for `{ directed: true }` or an undirected snapshot, else out- plus in-neighbours,
+ * a self-loop in both. Costs the node's degree, so one pair costs the degrees of its common
+ * neighbours, not the whole graph.
+ * @param s - The snapshot
+ * @param directed - The `directed` option
+ * @returns The weight of node z
+ */
+function adamicAdarWeightOf(s, directed) {
+    const rev = s.directed && !directed ? s.reverse() : undefined;
+    return (z) => adamicAdarWeight(distinctRowLength(s, z) + (rev === undefined ? 0 : distinctRowLength(rev, z)));
+}
+/**
+ * The pair score: a count of common neighbours, or their weight sum when `weight` is given.
+ * @param s - The snapshot
+ * @param o - Options
+ * @param weight - Optional weight of a common neighbour
+ * @returns The score of (u, v); 0 when either is absent
+ */
+function scorer(s, o, weight) {
+    const bwd = o.directed === true ? s.reverse() : s;
+    const n = s.nodeCount;
+    return (u, v) => (u < n && v < n ? sortedRowMerge(s, bwd, u, v, weight) : 0);
+}
+/**
+ * The Adamic-Adar pair score for many pairs: every node's weight computed once, up front.
+ * @param s - The snapshot
+ * @param o - Options
+ * @returns The score of (u, v)
+ */
+function adamicAdarScorer(s, o) {
+    const weightOf = adamicAdarWeightOf(s, o.directed === true);
+    const w = Float64Array.from({ length: s.nodeCount }, (_, z) => weightOf(z));
+    return scorer(s, o, (z) => w[z]);
+}
+/**
+ * Sort pairs by score, highest first and stable, and keep `order.slice(0, end)`.
+ * @param sources - Pair sources in enumeration order
+ * @param targets - Pair targets
+ * @param scores - Pair scores
+ * @param end - The slice end
+ * @returns The ranked pairs
+ */
+function ranked(sources, targets, scores, end) {
+    const order = Array.from(scores, (_, k) => k)
+        .sort((a, b) => scores[b] - scores[a])
+        .slice(0, end);
+    return {
+        sources: Uint32Array.from(order, (k) => sources[k]),
+        targets: Uint32Array.from(order, (k) => targets[k]),
+        scores: Float64Array.from(order, (k) => scores[k]),
+    };
+}
+function predict(s, o, score) {
+    const sources = [];
+    const targets = [];
+    const scores = [];
+    // Each unordered pair is scored once as (u, v), u < v; without `directed` the reverse pair is
+    // listed too with the same score. Existence is tested on the arc u -> v only.
+    const mirror = o.directed !== true;
+    for (let u = 0; u < s.nodeCount; u++) {
+        for (let v = u + 1; v < s.nodeCount; v++) {
+            if (o.includeExisting !== true && s.hasArc(u, v)) {
+                continue;
+            }
+            const x = score(u, v);
+            if (x > 0) {
+                sources.push(u);
+                targets.push(v);
+                scores.push(x);
+                if (mirror) {
+                    sources.push(v);
+                    targets.push(u);
+                    scores.push(x);
+                }
+            }
+        }
+    }
+    const { topK } = o;
+    return ranked(sources, targets, scores, topK !== undefined && topK > 0 ? topK : scores.length);
+}
+function forPairs(pairs, score) {
+    return Float64Array.from(pairs.sources, (u, k) => score(u, pairs.targets[k]));
+}
+function candidatesOf(s, u, o, score) {
+    const n = s.nodeCount;
+    const sources = [];
+    const targets = [];
+    const scores = [];
+    if (u < n) {
+        const list = o.candidates ?? Array.from({ length: n }, (_, i) => i);
+        for (let k = 0; k < list.length; k++) {
+            const v = list[k];
+            if (v === u || (o.includeExisting !== true && v < n && s.hasArc(u, v))) {
+                continue;
+            }
+            const x = score(u, v);
+            if (x > 0) {
+                sources.push(u);
+                targets.push(v);
+                scores.push(x);
+            }
+        }
+    }
+    return ranked(sources, targets, scores, o.topK ?? 10);
+}
+/**
+ * Rank held-out edges against non-edges by score (stable, edges first among equal scores), then
+ * report the threshold with the best F1 and the AUC; the AUC is 0.5 when either side is empty.
+ * @param edges - The scores of the held-out edges
+ * @param nonEdges - The scores of the non-edges
+ * @returns The metrics
+ */
+function rankingMetrics(edges, nonEdges) {
+    const all = [...edges, ...nonEdges];
+    const order = Array.from(all, (_, k) => k).sort((a, b) => all[b] - all[a]);
+    let tp = 0;
+    let fp = 0;
+    let bestF1 = 0;
+    let bestPrecision = 0;
+    let bestRecall = 0;
+    let auc = 0;
+    for (const k of order) {
+        if (k < edges.length) {
+            tp++;
+        }
+        else {
+            auc += tp;
+            fp++;
+        }
+        const precision = tp / (tp + fp);
+        const recall = tp / edges.length;
+        const f1 = precision + recall > 0 ? (2 * (precision * recall)) / (precision + recall) : 0;
+        if (f1 > bestF1) {
+            bestF1 = f1;
+            bestPrecision = precision;
+            bestRecall = recall;
+        }
+    }
+    auc = tp > 0 && fp > 0 ? auc / (tp * fp) : 0.5;
+    return { precision: bestPrecision, recall: bestRecall, f1Score: bestF1, auc };
+}
+/**
+ * Common-neighbour scores of every pair not already joined, ranked.
+ * @param s - The snapshot
+ * @param o - Options
+ * @returns The pairs with a positive score, highest first
+ * @public
+ */
+export function commonNeighborsPrediction(s, o = {}) {
+    return predict(s, o, scorer(s, o));
+}
+/**
+ * Common-neighbour scores of the given pairs, in order.
+ * @param s - The snapshot
+ * @param pairs - The pairs
+ * @param o - Options
+ * @returns One score per pair
+ * @public
+ */
+export function commonNeighborsForPairs(s, pairs, o = {}) {
+    return forPairs(pairs, scorer(s, o));
+}
+/**
+ * One node's best common-neighbour candidates, ranked.
+ * @param s - The snapshot
+ * @param u - The node index
+ * @param o - Options
+ * @returns (u, v) pairs with a positive score, highest first
+ * @public
+ */
+export function getTopCandidatesForNode(s, u, o = {}) {
+    return candidatesOf(s, u, o, scorer(s, o));
+}
+/**
+ * Ranking metrics of the common-neighbour score on held-out edges against non-edges.
+ * @param s - The training snapshot
+ * @param edges - The held-out edges
+ * @param nonEdges - The non-edges
+ * @param o - Options
+ * @returns The metrics
+ * @public
+ */
+export function evaluateCommonNeighbors(s, edges, nonEdges, o = {}) {
+    const score = scorer(s, o);
+    return rankingMetrics(forPairs(edges, score), forPairs(nonEdges, score));
+}
+/**
+ * The Adamic-Adar index of two nodes: the sum over distinct common neighbours z of 1 / ln(degree(z)).
+ * @param s - The snapshot
+ * @param u - A node index
+ * @param v - A node index
+ * @param o - Options
+ * @returns The score
+ * @public
+ */
+export function adamicAdarScore(s, u, v, o = {}) {
+    return scorer(s, o, adamicAdarWeightOf(s, o.directed === true))(u, v);
+}
+/**
+ * Adamic-Adar scores of every pair not already joined, ranked.
+ * @param s - The snapshot
+ * @param o - Options
+ * @returns The pairs with a positive score, highest first
+ * @public
+ */
+export function adamicAdarPrediction(s, o = {}) {
+    return predict(s, o, adamicAdarScorer(s, o));
+}
+/**
+ * Adamic-Adar scores of the given pairs, in order.
+ * @param s - The snapshot
+ * @param pairs - The pairs
+ * @param o - Options
+ * @returns One score per pair
+ * @public
+ */
+export function adamicAdarForPairs(s, pairs, o = {}) {
+    return forPairs(pairs, adamicAdarScorer(s, o));
+}
+/**
+ * One node's best Adamic-Adar candidates, ranked.
+ * @param s - The snapshot
+ * @param u - The node index
+ * @param o - Options
+ * @returns (u, v) pairs with a positive score, highest first
+ * @public
+ */
+export function getTopAdamicAdarCandidatesForNode(s, u, o = {}) {
+    return candidatesOf(s, u, o, adamicAdarScorer(s, o));
+}
+/**
+ * Ranking metrics of the Adamic-Adar score on held-out edges against non-edges.
+ * @param s - The training snapshot
+ * @param edges - The held-out edges
+ * @param nonEdges - The non-edges
+ * @param o - Options
+ * @returns The metrics
+ * @public
+ */
+export function evaluateAdamicAdar(s, edges, nonEdges, o = {}) {
+    const score = adamicAdarScorer(s, o);
+    return rankingMetrics(forPairs(edges, score), forPairs(nonEdges, score));
+}
+/**
+ * Both evaluations on the same held-out sets. The common-neighbour side always intersects the two
+ * OUT rows, whatever `directed` says, as the legacy function of this name does; the Adamic-Adar side
+ * honours `directed`.
+ * @param s - The training snapshot
+ * @param edges - The held-out edges
+ * @param nonEdges - The non-edges
+ * @param o - Options
+ * @returns The two sets of metrics
+ * @public
+ */
+export function compareAdamicAdarWithCommonNeighbors(s, edges, nonEdges, o = {}) {
+    return {
+        adamicAdar: evaluateAdamicAdar(s, edges, nonEdges, o),
+        commonNeighbors: evaluateCommonNeighbors(s, edges, nonEdges),
+    };
+}
+//# sourceMappingURL=link-prediction.js.map

package/dist/src/indexed/link-prediction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-prediction.js","sourceRoot":"","sources":["../../../src/indexed/link-prediction.ts"],"names":[],"mappings":"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"}

package/dist/src/indexed/markov.d.ts

@@ -0,0 +1,54 @@
+import type { AdjacencyView, NumericVector } from "@graphty/graph-format";
+import { type LabelResult } from "./components.js";
+/** Options of the index-based Markov clustering, with the legacy `markovClustering` defaults. @public */
+export interface MarkovOptions {
+    /** Matrix power of each expansion step, an integer of at least 1; default 2. */
+    readonly expansion?: number | undefined;
+    /** Element-wise power of each inflation step, above 0; default 2. */
+    readonly inflation?: number | undefined;
+    /** Cap on expansion-inflation rounds; default 100. */
+    readonly maxIterations?: number | undefined;
+    /** Stop when no matrix entry moved by more than this in a round; default 1e-6. */
+    readonly tolerance?: number | undefined;
+    /** Entries below this are dropped after each inflation; default 1e-5. */
+    readonly pruningThreshold?: number | undefined;
+    /** Give every node a self-loop of weight 1 before the first round; default true. */
+    readonly selfLoops?: boolean | undefined;
+    /** Per-arc weight override, arcCount long -- the facade passes `expandEdges(s, shadow.data)`. */
+    readonly weights?: NumericVector | undefined;
+}
+/** Result of the index-based Markov clustering. @public */
+export interface MarkovResult extends LabelResult {
+    /** Nodes whose own flow survived (a positive diagonal entry), in index order. */
+    readonly attractors: Uint32Array;
+    /** Expansion-inflation rounds run. */
+    readonly iterations: number;
+    /** True when the last round moved no entry by more than `tolerance`. */
+    readonly converged: boolean;
+}
+/**
+ * Markov clustering (MCL; van Dongen, 2000), the index-based port of the legacy `markovClustering`.
+ *
+ * The flow matrix starts as the column-normalised adjacency: entry (i, j) is the weight of the arc
+ * i -> j, so column j spreads j's flow over the nodes with an arc into it (on an undirected
+ * snapshot, its neighbours). With `selfLoops` every diagonal entry is first set to 1, replacing a
+ * self-loop's weight. Each round raises the matrix to the `expansion` power, raises every entry to
+ * the `inflation` power, renormalises the columns, drops the entries below `pruningThreshold` and
+ * renormalises again, until no entry moves by more than `tolerance` or `maxIterations` rounds ran.
+ * Node j then joins the attractor with the largest entry in its column, the lowest index on a tie;
+ * a node whose column emptied is a community of its own.
+ *
+ * The matrix is kept sparse, and every sum is taken in the order the legacy dense loops take it, so
+ * the rounds are bit-identical to the legacy function's and so are the communities, their order and
+ * the attractors. Communities are labelled in the legacy function's order: the flow clusters by
+ * their lowest member, then the nodes whose column emptied. Two differences: parallel arcs are
+ * summed (a legacy graph has none), and `iterations` counts the rounds run, where the legacy
+ * function reports one more than `maxIterations` when it stops at the cap. A negative, NaN or
+ * infinite weight throws.
+ * @param s - Any snapshot or adjacency view
+ * @param options - MCL parameters and the weight override
+ * @returns The partition, the attractors, the rounds run and whether they converged
+ * @public
+ */
+export declare function markovClustering(s: AdjacencyView, options?: MarkovOptions): MarkovResult;
+//# sourceMappingURL=markov.d.ts.map

package/dist/src/indexed/markov.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markov.d.ts","sourceRoot":"","sources":["../../../src/indexed/markov.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE1E,OAAO,EAAE,KAAK,WAAW,EAAc,MAAM,iBAAiB,CAAC;AAE/D,yGAAyG;AACzG,MAAM,WAAW,aAAa;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,qEAAqE;IACrE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,sDAAsD;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,yEAAyE;IACzE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/C,oFAAoF;IACpF,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACzC,iGAAiG;IACjG,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAChD;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC7C,iFAAiF;IACjF,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;IACjC,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC/B;AAmMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CA0E5F"}

package/dist/src/indexed/markov.js

@@ -0,0 +1,284 @@
+import { withGroups } from "./components.js";
+/**
+ * Divide every column by its sum, summed in ascending row order as the legacy dense loop sums it.
+ * @param m - The matrix, changed in place
+ */
+function normaliseColumns(m) {
+    for (let j = 0; j + 1 < m.ptr.length; j++) {
+        let sum = 0;
+        for (let p = m.ptr[j]; p < m.ptr[j + 1]; p++) {
+            sum += m.val[p];
+        }
+        if (sum > 0) {
+            for (let p = m.ptr[j]; p < m.ptr[j + 1]; p++) {
+                m.val[p] /= sum;
+            }
+        }
+    }
+}
+/**
+ * The product `a * b`. For every entry the products are added in ascending k, the order the legacy
+ * dense triple loop adds them in; the zero products it adds as well leave a sum unchanged, so the
+ * result is bit-identical to the dense one.
+ * @param a - Left factor
+ * @param b - Right factor
+ * @param acc - n-long scratch, all zero on entry and on exit
+ * @param mark - n-long scratch, all zero on entry and on exit
+ * @returns The product
+ */
+function multiply(a, b, acc, mark) {
+    const n = acc.length;
+    const ptr = new Uint32Array(n + 1);
+    const rows = [];
+    const vals = [];
+    const touched = [];
+    for (let j = 0; j < n; j++) {
+        touched.length = 0;
+        for (let q = b.ptr[j]; q < b.ptr[j + 1]; q++) {
+            const k = b.row[q];
+            const bkj = b.val[q];
+            for (let p = a.ptr[k]; p < a.ptr[k + 1]; p++) {
+                const i = a.row[p];
+                if (mark[i] === 0) {
+                    mark[i] = 1;
+                    touched.push(i);
+                }
+                acc[i] += a.val[p] * bkj;
+            }
+        }
+        touched.sort((x, y) => x - y);
+        for (const i of touched) {
+            rows.push(i);
+            vals.push(acc[i]);
+            acc[i] = 0;
+            mark[i] = 0;
+        }
+        ptr[j + 1] = rows.length;
+    }
+    return { ptr, row: Uint32Array.from(rows), val: Float64Array.from(vals) };
+}
+/**
+ * Raise every entry to `inflation`, renormalise, drop the entries below `threshold` and renormalise
+ * again: the legacy inflate and prune steps.
+ * @param m - The expanded matrix
+ * @param inflation - The element-wise power
+ * @param threshold - The pruning threshold
+ * @returns The new matrix
+ */
+function inflateAndPrune(m, inflation, threshold) {
+    const powered = { ptr: m.ptr, row: m.row, val: m.val.map((v) => Math.pow(v, inflation)) };
+    normaliseColumns(powered);
+    const n = m.ptr.length - 1;
+    const ptr = new Uint32Array(n + 1);
+    const rows = [];
+    const vals = [];
+    for (let j = 0; j < n; j++) {
+        for (let p = powered.ptr[j]; p < powered.ptr[j + 1]; p++) {
+            if (powered.val[p] >= threshold) {
+                rows.push(powered.row[p]);
+                vals.push(powered.val[p]);
+            }
+        }
+        ptr[j + 1] = rows.length;
+    }
+    const out = { ptr, row: Uint32Array.from(rows), val: Float64Array.from(vals) };
+    normaliseColumns(out);
+    return out;
+}
+/**
+ * Whether no entry differs by more than `tolerance` between two matrices, an absent entry being 0.
+ * @param a - The previous matrix
+ * @param b - The new matrix
+ * @param tolerance - The tolerance
+ * @returns True when every entry is within tolerance
+ */
+function withinTolerance(a, b, tolerance) {
+    for (let j = 0; j + 1 < a.ptr.length; j++) {
+        let p = a.ptr[j];
+        let q = b.ptr[j];
+        const pe = a.ptr[j + 1];
+        const qe = b.ptr[j + 1];
+        while (p < pe || q < qe) {
+            let diff;
+            if (q >= qe || (p < pe && a.row[p] < b.row[q])) {
+                diff = a.val[p++];
+            }
+            else if (p >= pe || b.row[q] < a.row[p]) {
+                diff = b.val[q++];
+            }
+            else {
+                diff = a.val[p++] - b.val[q++];
+            }
+            if (Math.abs(diff) > tolerance) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * The starting matrix: entry (i, j) is the weight of the arc i -> j (parallel arcs summed), the
+ * diagonal set to 1 when `selfLoops`, every column normalised.
+ * @param s - The adjacency
+ * @param weights - Per-arc weights, or null for all ones
+ * @param selfLoops - Whether to set the diagonal to 1
+ * @returns The column-stochastic matrix
+ */
+function transitionMatrix(s, weights, selfLoops) {
+    const n = s.nodeCount;
+    // Column j of the matrix is the set of arcs INTO j: a counting sort of the arcs by target, which
+    // keeps each column's rows ascending because the rows are visited in order.
+    const ptr = new Uint32Array(n + 1);
+    for (let a = 0; a < s.arcCount; a++) {
+        ptr[s.colIdx[a] + 1]++;
+    }
+    if (selfLoops) {
+        for (let j = 0; j < n; j++) {
+            ptr[j + 1]++;
+        }
+    }
+    for (let j = 0; j < n; j++) {
+        ptr[j + 1] += ptr[j];
+    }
+    const fill = ptr.slice(0, n);
+    const row = new Uint32Array(ptr[n]);
+    const val = new Float64Array(ptr[n]);
+    const put = (i, j, w, replace) => {
+        const last = fill[j] - 1;
+        if (last >= ptr[j] && row[last] === i) {
+            val[last] = replace ? w : val[last] + w;
+        }
+        else {
+            row[fill[j]] = i;
+            val[fill[j]++] = w;
+        }
+    };
+    for (let i = 0; i < n; i++) {
+        // The diagonal goes in its place in row order: the arcs i -> j with j < i were placed while
+        // visiting earlier rows, so for column i this is where row i belongs.
+        for (let a = s.rowPtr[i]; a < s.rowPtr[i + 1]; a++) {
+            const j = s.colIdx[a];
+            const w = weights === null ? 1 : weights[a];
+            if (!(w >= 0) || w === Infinity) {
+                throw new RangeError(`arc ${a} has weight ${w}; Markov clustering needs finite, non-negative weights`);
+            }
+            put(i, j, w, false);
+        }
+        if (selfLoops) {
+            put(i, i, 1, true);
+        }
+    }
+    // Compact: merged parallel arcs and a self-loop folded into the diagonal left gaps.
+    const outPtr = new Uint32Array(n + 1);
+    const rows = [];
+    const vals = [];
+    for (let j = 0; j < n; j++) {
+        for (let p = ptr[j]; p < fill[j]; p++) {
+            rows.push(row[p]);
+            vals.push(val[p]);
+        }
+        outPtr[j + 1] = rows.length;
+    }
+    const m = { ptr: outPtr, row: Uint32Array.from(rows), val: Float64Array.from(vals) };
+    normaliseColumns(m);
+    return m;
+}
+/**
+ * Markov clustering (MCL; van Dongen, 2000), the index-based port of the legacy `markovClustering`.
+ *
+ * The flow matrix starts as the column-normalised adjacency: entry (i, j) is the weight of the arc
+ * i -> j, so column j spreads j's flow over the nodes with an arc into it (on an undirected
+ * snapshot, its neighbours). With `selfLoops` every diagonal entry is first set to 1, replacing a
+ * self-loop's weight. Each round raises the matrix to the `expansion` power, raises every entry to
+ * the `inflation` power, renormalises the columns, drops the entries below `pruningThreshold` and
+ * renormalises again, until no entry moves by more than `tolerance` or `maxIterations` rounds ran.
+ * Node j then joins the attractor with the largest entry in its column, the lowest index on a tie;
+ * a node whose column emptied is a community of its own.
+ *
+ * The matrix is kept sparse, and every sum is taken in the order the legacy dense loops take it, so
+ * the rounds are bit-identical to the legacy function's and so are the communities, their order and
+ * the attractors. Communities are labelled in the legacy function's order: the flow clusters by
+ * their lowest member, then the nodes whose column emptied. Two differences: parallel arcs are
+ * summed (a legacy graph has none), and `iterations` counts the rounds run, where the legacy
+ * function reports one more than `maxIterations` when it stops at the cap. A negative, NaN or
+ * infinite weight throws.
+ * @param s - Any snapshot or adjacency view
+ * @param options - MCL parameters and the weight override
+ * @returns The partition, the attractors, the rounds run and whether they converged
+ * @public
+ */
+export function markovClustering(s, options = {}) {
+    const expansion = options.expansion ?? 2;
+    const inflation = options.inflation ?? 2;
+    const maxIterations = options.maxIterations ?? 100;
+    const tolerance = options.tolerance ?? 1e-6;
+    const pruningThreshold = options.pruningThreshold ?? 1e-5;
+    if (!Number.isInteger(expansion) || expansion < 1) {
+        throw new RangeError(`expansion must be an integer of at least 1, got ${expansion}`);
+    }
+    if (!(inflation > 0) || inflation === Infinity) {
+        throw new RangeError(`inflation must be finite and above 0, got ${inflation}`);
+    }
+    if (!Number.isInteger(maxIterations) || maxIterations < 0) {
+        throw new RangeError(`maxIterations must be a non-negative integer, got ${maxIterations}`);
+    }
+    if (!(tolerance >= 0) || !(pruningThreshold >= 0)) {
+        throw new RangeError("tolerance and pruningThreshold must be non-negative");
+    }
+    const weights = options.weights ?? s.weights;
+    if (weights !== null && weights.length !== s.arcCount) {
+        throw new RangeError(`weights has ${weights.length} entries; the snapshot has ${s.arcCount} arcs`);
+    }
+    const n = s.nodeCount;
+    let m = transitionMatrix(s, weights, options.selfLoops ?? true);
+    const acc = new Float64Array(n);
+    const mark = new Uint8Array(n);
+    let converged = n === 0;
+    let iterations = 0;
+    while (!converged && iterations < maxIterations) {
+        let expanded = m;
+        for (let t = 1; t < expansion; t++) {
+            expanded = multiply(expanded, m, acc, mark);
+        }
+        const next = inflateAndPrune(expanded, inflation, pruningThreshold);
+        iterations++;
+        converged = withinTolerance(m, next, tolerance);
+        m = next;
+    }
+    const attractors = [];
+    // Column j's attractor: the row of its largest positive entry, the first on a tie.
+    const attractorOf = new Int32Array(n).fill(-1);
+    for (let j = 0; j < n; j++) {
+        let best = 0;
+        for (let p = m.ptr[j]; p < m.ptr[j + 1]; p++) {
+            if (m.row[p] === j && m.val[p] > 0) {
+                attractors.push(j);
+            }
+            if (m.val[p] > best) {
+                best = m.val[p];
+                attractorOf[j] = m.row[p];
+            }
+        }
+    }
+    const labels = new Uint32Array(n);
+    const labelOfAttractor = new Map();
+    for (let j = 0; j < n; j++) {
+        const a = attractorOf[j];
+        if (a >= 0) {
+            let label = labelOfAttractor.get(a);
+            if (label === undefined) {
+                label = labelOfAttractor.size;
+                labelOfAttractor.set(a, label);
+            }
+            labels[j] = label;
+        }
+    }
+    let count = labelOfAttractor.size;
+    for (let j = 0; j < n; j++) {
+        if (attractorOf[j] < 0) {
+            labels[j] = count++;
+        }
+    }
+    return { ...withGroups(labels, count), attractors: Uint32Array.from(attractors), iterations, converged };
+}
+//# sourceMappingURL=markov.js.map