@graphty/graph-samples 0.0.1 → 0.1.2

package/src/datasets/political-blogs/index.ts

@@ -0,0 +1,17 @@
+/**
+ * `@graphty/graph-samples/datasets/political-blogs`: US political blogs, 2004.
+ */
+
+import { type SampleGraph } from "../../types.js";
+import { buildDataset } from "../build.js";
+import { DATA } from "./data.js";
+
+export { politicalBlogsMeta } from "./meta.js";
+
+/**
+ * US political blogs, 2004: 1,490 blogs, 19,022 directed links, and each blog's political lean (`lean`).
+ * @returns a fresh copy of the graph as typed arrays
+ */
+export function politicalBlogs(): SampleGraph {
+    return buildDataset(DATA);
+}

package/src/datasets/political-blogs/meta.ts

@@ -0,0 +1,30 @@
+import { type DatasetMeta } from "../build.js";
+
+/** What the politicalBlogs dataset is, where it came from and under which terms. */
+export const politicalBlogsMeta: DatasetMeta = {
+    name: "political-blogs",
+    title: "US political blogs, 2004",
+    description:
+        "Hyperlinks between US political weblogs, crawled from their front pages in February 2005, with each blog labelled liberal or conservative from blog directories and by hand. Directed; 266 blogs have no links. The crawl recorded 65 links twice and 3 blogs linking to themselves: each link is kept once and the self-links are dropped.",
+    citation:
+        "L. A. Adamic and N. Glance, The political blogosphere and the 2004 U.S. election: divided they blog, Proceedings of the 3rd International Workshop on Link Discovery (LinkKDD 2005), 36-43. doi:10.1145/1134271.1134277",
+    source: "https://web.archive.org/web/20240730122800id_/https://public.websites.umich.edu/~mejn/netdata/polblogs.zip",
+    license:
+        'unclear: posted on Mark Newman\'s data page with the authors\' permission, "free for scientific use"; the SuiteSparse Matrix Collection republishes the graph under CC BY 4.0.',
+    nodes: 1490,
+    edges: 19022,
+    directed: true,
+    weighted: false,
+    attributes: {
+        label: "string: the blog's address",
+        lean: "dict: liberal or conservative (ground truth)",
+        directory: "string: the blog directories the label came from",
+    },
+    groundTruth: "lean",
+    showcases: [
+        "two-way community detection against the political lean",
+        "PageRank and HITS on a directed graph",
+        "degree-corrected block models",
+        "force-directed layouts coloured by lean",
+    ],
+};

package/src/datasets/political-books/data.ts

@@ -0,0 +1,167 @@
+// THIS FILE IS AUTO GENERATED: DO NOT EDIT THIS FILE. INSTEAD EDIT graph-samples/scripts/convert-datasets.mjs
+// Source: https://web.archive.org/web/20240730210010id_/https://public.websites.umich.edu/~mejn/netdata/polbooks.zip
+// sha256: b8e37351ae9ae8ee39f8b75ed52170d2435f290855605680c9b4f4c8b46b3c37
+
+import { type DatasetData } from "../build.js";
+
+export const DATA: DatasetData = {
+    directed: false,
+    nodeCount: 105,
+    ids: null,
+    edges: [
+        1, 0, 2, 0, 3, 0, 3, 1, 4, 0, 4, 2, 5, 0, 5, 1, 5, 2, 5, 3, 5, 4, 6, 0, 6, 1, 6, 4, 6, 5, 7, 2, 7, 5, 7, 6, 8,
+        3, 9, 3, 9, 8, 10, 3, 10, 6, 10, 8, 11, 3, 11, 8, 11, 9, 11, 10, 12, 3, 12, 6, 12, 8, 12, 9, 12, 10, 12, 11, 13,
+        3, 13, 8, 13, 11, 13, 12, 14, 3, 14, 8, 14, 9, 14, 11, 14, 12, 14, 7, 15, 3, 15, 10, 15, 12, 16, 3, 16, 10, 16,
+        15, 17, 3, 17, 11, 17, 12, 17, 13, 18, 3, 18, 6, 18, 12, 19, 3, 19, 10, 20, 3, 20, 8, 20, 9, 20, 11, 21, 3, 21,
+        8, 21, 10, 21, 11, 22, 3, 22, 6, 22, 8, 22, 11, 23, 3, 23, 8, 23, 12, 23, 21, 24, 3, 24, 8, 24, 9, 24, 12, 24,
+        20, 25, 3, 25, 6, 25, 14, 25, 22, 26, 3, 26, 8, 26, 11, 26, 14, 26, 24, 27, 3, 27, 8, 27, 9, 27, 11, 27, 23, 28,
+        4, 29, 4, 29, 6, 29, 11, 29, 13, 30, 4, 30, 7, 31, 4, 31, 30, 32, 8, 32, 12, 32, 13, 32, 23, 33, 32, 33, 8, 33,
+        10, 33, 12, 33, 23, 35, 34, 35, 8, 35, 10, 36, 34, 36, 35, 36, 12, 37, 34, 37, 8, 37, 10, 37, 35, 37, 33, 38,
+        34, 38, 10, 38, 35, 38, 12, 38, 37, 38, 33, 39, 34, 39, 10, 39, 35, 39, 12, 39, 38, 39, 33, 40, 8, 40, 35, 40,
+        12, 40, 13, 40, 20, 40, 22, 40, 39, 40, 24, 40, 25, 40, 26, 40, 27, 41, 8, 41, 9, 41, 40, 41, 12, 41, 36, 41,
+        27, 42, 8, 42, 40, 42, 13, 42, 39, 43, 8, 43, 35, 43, 13, 43, 42, 44, 8, 44, 40, 44, 35, 44, 12, 44, 13, 45, 8,
+        45, 9, 45, 40, 45, 11, 45, 26, 46, 8, 46, 12, 47, 9, 47, 40, 47, 41, 47, 11, 47, 12, 47, 13, 47, 42, 47, 36, 47,
+        37, 47, 17, 47, 33, 47, 45, 47, 46, 47, 23, 47, 24, 47, 26, 47, 27, 48, 9, 48, 20, 49, 9, 49, 20, 49, 31, 49,
+        48, 50, 9, 50, 11, 51, 9, 52, 9, 52, 22, 52, 51, 53, 40, 53, 20, 53, 24, 53, 26, 54, 40, 54, 41, 54, 12, 54, 47,
+        54, 23, 54, 27, 55, 10, 55, 12, 55, 15, 55, 19, 56, 11, 56, 19, 56, 43, 57, 13, 57, 56, 57, 20, 57, 48, 57, 49,
+        58, 14, 58, 7, 58, 30, 58, 49, 58, 50, 58, 51, 58, 52, 60, 59, 61, 59, 62, 59, 62, 60, 63, 59, 63, 60, 63, 62,
+        64, 58, 64, 51, 64, 52, 65, 64, 65, 58, 65, 51, 66, 64, 66, 28, 66, 30, 67, 64, 67, 65, 67, 66, 67, 30, 68, 64,
+        68, 58, 68, 65, 69, 64, 69, 58, 69, 65, 69, 51, 70, 64, 70, 66, 70, 30, 71, 7, 71, 68, 71, 70, 72, 71, 72, 28,
+        72, 66, 72, 49, 72, 70, 73, 71, 73, 72, 73, 66, 73, 30, 73, 31, 74, 71, 74, 72, 74, 73, 74, 66, 74, 30, 74, 31,
+        75, 71, 75, 72, 75, 73, 75, 74, 75, 30, 75, 31, 75, 70, 76, 71, 76, 72, 76, 75, 76, 66, 76, 30, 76, 31, 76, 49,
+        76, 53, 77, 71, 77, 75, 77, 58, 77, 30, 77, 19, 77, 31, 77, 76, 78, 71, 78, 72, 78, 74, 78, 75, 78, 31, 79, 71,
+        79, 72, 79, 74, 79, 75, 79, 30, 80, 71, 80, 72, 80, 66, 80, 30, 81, 71, 82, 71, 82, 72, 82, 73, 82, 74, 82, 75,
+        82, 30, 82, 31, 82, 76, 83, 71, 83, 73, 83, 75, 83, 30, 83, 76, 84, 72, 84, 74, 84, 75, 84, 66, 84, 73, 84, 60,
+        84, 30, 84, 62, 84, 76, 84, 79, 84, 81, 84, 82, 84, 83, 85, 72, 85, 7, 85, 58, 85, 65, 85, 66, 86, 72, 86, 73,
+        86, 66, 86, 84, 86, 60, 86, 30, 86, 61, 86, 76, 86, 81, 87, 72, 87, 74, 87, 84, 87, 83, 88, 72, 88, 74, 88, 66,
+        88, 84, 89, 72, 89, 73, 89, 66, 89, 84, 89, 86, 89, 88, 90, 72, 90, 66, 90, 70, 91, 72, 91, 74, 91, 75, 91, 31,
+        91, 90, 91, 79, 92, 72, 92, 73, 92, 75, 93, 73, 93, 66, 93, 86, 93, 30, 94, 73, 94, 84, 94, 93, 95, 73, 95, 94,
+        95, 61, 96, 73, 96, 66, 96, 84, 96, 94, 97, 73, 97, 66, 97, 84, 97, 86, 97, 96, 97, 81, 98, 73, 98, 74, 98, 87,
+        98, 91, 99, 73, 99, 74, 99, 66, 99, 84, 99, 93, 99, 60, 99, 59, 99, 30, 99, 62, 99, 63, 99, 90, 100, 73, 100,
+        66, 100, 84, 100, 86, 100, 96, 100, 98, 100, 99, 100, 62, 100, 79, 100, 91, 100, 83, 101, 84, 101, 86, 101, 94,
+        101, 100, 101, 61, 102, 93, 102, 94, 102, 95, 102, 46, 103, 67, 104, 67, 104, 69, 104, 103,
+    ],
+    weights: null,
+    columns: {
+        label: {
+            dtype: "string",
+            role: "label",
+            values: [
+                "1000 Years for Revenge",
+                "Bush vs. the Beltway",
+                "Charlie Wilson's War",
+                "Losing Bin Laden",
+                "Sleeping With the Devil",
+                "The Man Who Warned America",
+                "Why America Slept",
+                "Ghost Wars",
+                "A National Party No More",
+                "Bush Country",
+                "Dereliction of Duty",
+                "Legacy",
+                "Off with Their Heads",
+                "Persecution",
+                "Rumsfeld's War",
+                "Breakdown",
+                "Betrayal",
+                "Shut Up and Sing",
+                "Meant To Be",
+                "The Right Man",
+                "Ten Minutes from Normal",
+                "Hillary's Scheme",
+                "The French Betrayal of America",
+                "Tales from the Left Coast",
+                "Hating America",
+                "The Third Terrorist",
+                "Endgame",
+                "Spin Sisters",
+                "All the Shah's Men",
+                "Dangerous Dimplomacy",
+                "The Price of Loyalty",
+                "House of Bush, House of Saud",
+                "The Death of Right and Wrong",
+                "Useful Idiots",
+                "The O'Reilly Factor",
+                "Let Freedom Ring",
+                "Those Who Trespass",
+                "Bias",
+                "Slander",
+                "The Savage Nation",
+                "Deliver Us from Evil",
+                "Give Me a Break",
+                "The Enemy Within",
+                "The Real America",
+                "Who's Looking Out for You?",
+                "The Official Handbook Vast Right Wing Conspiracy",
+                "Power Plays",
+                "Arrogance",
+                "The Perfect Wife",
+                "The Bushes",
+                "Things Worth Fighting For",
+                "Surprise, Security, the American Experience",
+                "Allies",
+                "Why Courage Matters",
+                "Hollywood Interrupted",
+                "Fighting Back",
+                "We Will Prevail",
+                "The Faith of George W Bush",
+                "Rise of the Vulcans",
+                "Downsize This!",
+                "Stupid White Men",
+                "Rush Limbaugh Is a Big Fat Idiot",
+                "The Best Democracy Money Can Buy",
+                "The Culture of Fear",
+                "America Unbound",
+                "The Choice",
+                "The Great Unraveling",
+                "Rogue Nation",
+                "Soft Power",
+                "Colossus",
+                "The Sorrows of Empire",
+                "Against All Enemies",
+                "American Dynasty",
+                "Big Lies",
+                "The Lies of George W. Bush",
+                "Worse Than Watergate",
+                "Plan of Attack",
+                "Bush at War",
+                "The New Pearl Harbor",
+                "Bushwomen",
+                "The Bubble of American Supremacy",
+                "Living History",
+                "The Politics of Truth",
+                "Fanatics and Fools",
+                "Bushwhacked",
+                "Disarming Iraq",
+                "Lies and the Lying Liars Who Tell Them",
+                "MoveOn's 50 Ways to Love Your Country",
+                "The Buying of the President 2004",
+                "Perfectly Legal",
+                "Hegemony or Survival",
+                "The Exception to the Rulers",
+                "Freethinkers",
+                "Had Enough?",
+                "It's Still the Economy, Stupid!",
+                "We're Right They're Wrong",
+                "What Liberal Media?",
+                "The Clinton Wars",
+                "Weapons of Mass Deception",
+                "Dude, Where's My Country?",
+                "Thieves in High Places",
+                "Shrub",
+                "Buck Up Suck Up",
+                "The Future of Freedom",
+                "Empire",
+            ],
+        },
+        lean: {
+            dtype: "dict",
+            categories: ["liberal", "conservative", "neutral"],
+            codes: [
+                2, 1, 1, 1, 2, 1, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 1, 0, 0, 1, 1, 1,
+                1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 1, 2, 1, 1, 2, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2,
+                0, 0, 0, 0, 0, 0, 2, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2, 2,
+            ],
+        },
+    },
+};

package/src/datasets/political-books/index.ts

@@ -0,0 +1,17 @@
+/**
+ * `@graphty/graph-samples/datasets/political-books`: Books about US politics.
+ */
+
+import { type SampleGraph } from "../../types.js";
+import { buildDataset } from "../build.js";
+import { DATA } from "./data.js";
+
+export { politicalBooksMeta } from "./meta.js";
+
+/**
+ * The political books co-purchase network: 105 books, 441 co-purchases, each book's `label` and political `lean`.
+ * @returns a fresh copy of the graph as typed arrays
+ */
+export function politicalBooks(): SampleGraph {
+    return buildDataset(DATA);
+}

package/src/datasets/political-books/meta.ts

@@ -0,0 +1,23 @@
+import { type DatasetMeta } from "../build.js";
+
+/** What the politicalBooks dataset is, where it came from and under which terms. */
+export const politicalBooksMeta: DatasetMeta = {
+    name: "political-books",
+    title: "Books about US politics",
+    description:
+        "Books about US politics sold by Amazon.com around the 2004 election, joined when the same buyers frequently bought both. Mark Newman labelled each book liberal, neutral or conservative from its descriptions and reviews.",
+    citation: "V. Krebs, unpublished (compiled 2004), http://www.orgnet.com/; labels by M. E. J. Newman.",
+    source: "https://web.archive.org/web/20240730210010id_/https://public.websites.umich.edu/~mejn/netdata/polbooks.zip",
+    license:
+        'unclear: Mark Newman\'s data page says only "free for scientific use to the best of my knowledge"; the SuiteSparse Matrix Collection republishes the graph under CC BY 4.0.',
+    nodes: 105,
+    edges: 441,
+    directed: false,
+    weighted: false,
+    attributes: { label: "string: the book title", lean: "dict: liberal, conservative or neutral (ground truth)" },
+    groundTruth: "lean",
+    showcases: [
+        "two- and three-way community detection against the political lean",
+        "force-directed layouts coloured by lean",
+    ],
+};

package/src/datasets/remote.ts

@@ -0,0 +1,42 @@
+/**
+ * Datasets too large to bundle (over about 5,000 nodes) are hosted on graphty.app as
+ * graph-format wire bytes and fetched at runtime.
+ */
+
+import { fromBytes, type GraphSnapshot } from "@graphty/graph-format";
+
+/**
+ * Where hosted datasets live: `<base><name>.gsnp.gz`, a gzipped graph-format wire container.
+ * The `v1` segment is the hosting layout's version, independent of the package version.
+ */
+export const DEFAULT_DATASET_BASE_URL = "https://graphty.app/data/graph-samples/v1/";
+
+/** Options of {@link fetchDataset}. */
+export interface FetchDatasetOptions {
+    /** Serve the files from elsewhere (self-hosting, a mirror, a test server). */
+    baseUrl?: string | undefined;
+    /** The fetch implementation; the global `fetch` by default. */
+    fetch?: typeof fetch | undefined;
+    /** Cancels the download. */
+    signal?: AbortSignal | undefined;
+}
+
+/**
+ * Download a hosted dataset and decode it.
+ * @param name - the dataset name: lowercase letters, digits and dashes
+ * @param options - the base URL, fetch implementation and abort signal
+ * @returns the graph as a frozen graph-format snapshot
+ */
+export async function fetchDataset(name: string, options: FetchDatasetOptions = {}): Promise<GraphSnapshot> {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+        throw new RangeError(`not a dataset name: ${JSON.stringify(name)}`);
+    }
+    const base = options.baseUrl ?? DEFAULT_DATASET_BASE_URL;
+    const url = new URL(`${name}.gsnp.gz`, base.endsWith("/") ? base : `${base}/`);
+    const response = await (options.fetch ?? fetch)(url, { signal: options.signal ?? null });
+    if (!response.ok || response.body === null) {
+        throw new Error(`fetching ${url.href} failed: HTTP ${response.status}`);
+    }
+    const unzipped = response.body.pipeThrough(new DecompressionStream("gzip"));
+    return fromBytes(new Uint8Array(await new Response(unzipped).arrayBuffer()));
+}

package/src/element.ts

@@ -0,0 +1,41 @@
+/**
+ * Records for graphty-element's `nodeData` / `edgeData` properties.
+ */
+
+import { type SampleGraph } from "./types.js";
+
+/** The node and edge records graphty-element loads. */
+export interface ElementData {
+    /** One record per node: `id` plus one field per node column. */
+    readonly nodes: Record<string, unknown>[];
+    /** One record per edge: `source`, `target` and, when weighted, `weight`. */
+    readonly edges: Record<string, unknown>[];
+}
+
+/**
+ * Turn a graph into the plain records `<graphty-element>` takes as `nodeData` and `edgeData`.
+ * A node's id is its external id when the graph has them, else its index. Builds one object per
+ * node and edge, so it is meant for graphs a browser draws, not for millions of edges.
+ * @param graph - a generator's or dataset's graph
+ * @returns the node and edge records
+ */
+export function toElementData(graph: SampleGraph): ElementData {
+    const { ids, src, dst, weights } = graph;
+    const columns = Object.entries(graph.nodeColumns ?? {}).map(
+        ([name, column]) => [name, ArrayBuffer.isView(column) ? column : column.data] as const,
+    );
+    const idOf = (i: number): string | number => (ids === undefined ? i : ids[i]);
+    const nodes = Array.from({ length: graph.nodeCount }, (_, i) => {
+        const record: Record<string, unknown> = { id: idOf(i) };
+        for (const [name, data] of columns) {
+            record[name] = data[i];
+        }
+        return record;
+    });
+    const edges = Array.from(src, (u, e) =>
+        weights === undefined
+            ? { source: idOf(u), target: idOf(dst[e]) }
+            : { source: idOf(u), target: idOf(dst[e]), weight: weights[e] },
+    );
+    return { nodes, edges };
+}

package/src/generators/bipartite.ts

@@ -0,0 +1,127 @@
+/**
+ * The random bipartite graph G(n1, n2, p), optionally with a planted perfect matching.
+ */
+
+import { type U32 } from "@graphty/graph-format";
+
+import { detLog } from "../random/log.js";
+import { RandomStream, resolveSeed } from "../random/stream.js";
+import { type SampleGraph } from "../types.js";
+import { binomialBuffer, checkInt, checkProbability, type EdgeBuffer, toGraph } from "./util.js";
+import { applyWeights, type WeightOptions } from "./weights.js";
+
+/** Options of {@link randomBipartiteGraph}. */
+export interface RandomBipartiteOptions extends WeightOptions {
+    /** The left side's size, >= 0. */
+    n1: number;
+    /** The right side's size, >= 0. */
+    n2: number;
+    /** The probability of each left-right pair, in [0, 1]. */
+    p: number;
+    /**
+     * Plant a perfect matching: left node i is always joined to right node `matching[i]` of a
+     * uniformly random permutation, so a perfect matching is guaranteed. Needs n1 === n2.
+     */
+    perfectMatching?: boolean | undefined;
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+
+/**
+ * The planted matching: a Fisher-Yates shuffle of 0 .. n - 1 from stream (seed,
+ * "bipartite-matching", 0), drawing nextBelow(i + 1) for i = n - 1 down to 1.
+ * @param n - the side size
+ * @param seed - the seed
+ * @returns match[i] = the right-side offset joined to left node i
+ */
+export function plantedMatching(n: number, seed: number): U32 {
+    const stream = new RandomStream(seed, "bipartite-matching", 0);
+    const match = new Uint32Array(n);
+    for (let i = 0; i < n; i++) {
+        match[i] = i;
+    }
+    for (let i = n - 1; i > 0; i--) {
+        const j = stream.nextBelow(i + 1);
+        const t = match[i];
+        match[i] = match[j];
+        match[j] = t;
+    }
+    return match;
+}
+
+/**
+ * Rows [start, end) of the bipartite graph: left node u draws from stream (seed, "bipartite", u)
+ * and holds (u, n1 + j) for the chosen right offsets j in ascending order, with the planted match
+ * merged in at its place (never twice).
+ * @param options - the checked options
+ * @param match - the planted matching, or null
+ * @param start - the first row
+ * @param end - one past the last row
+ * @param out - receives the edges
+ */
+export function bipartiteRows(
+    options: RandomBipartiteOptions,
+    match: U32 | null,
+    start: number,
+    end: number,
+    out: EdgeBuffer,
+): void {
+    const { n1, n2, p } = options;
+    const seed = resolveSeed(options.seed);
+    const logQ = detLog(1 - p);
+    const stream = new RandomStream(seed, "bipartite", 0);
+    for (let u = start; u < end; u++) {
+        stream.reset(u);
+        let pending = match === null ? -1 : match[u];
+        const emit = (j: number): void => {
+            if (pending >= 0 && pending < j) {
+                out.push(u, n1 + pending);
+            }
+            if (pending >= 0 && pending <= j) {
+                pending = -1;
+            }
+            out.push(u, n1 + j);
+        };
+        if (p === 1) {
+            for (let j = 0; j < n2; j++) {
+                emit(j);
+            }
+        } else if (p > 0) {
+            let j = stream.nextSkip(logQ);
+            while (j < n2) {
+                emit(j);
+                j += 1 + stream.nextSkip(logQ);
+            }
+        }
+        if (pending >= 0) {
+            out.push(u, n1 + pending);
+        }
+    }
+}
+
+/**
+ * The random bipartite graph G(n1, n2, p) in O(n + m): left nodes 0 .. n1 - 1, right nodes
+ * n1 .. n1 + n2 - 1, each left-right pair independently with probability p; edges row by row from
+ * the left side, right ends ascending. Node column `side` (u8): 0 left, 1 right.
+ * @param options - n1, n2, p, perfectMatching and seed
+ * @returns the undirected graph
+ */
+export function randomBipartiteGraph(options: RandomBipartiteOptions): SampleGraph {
+    const { n1, n2, p } = options;
+    checkInt("n1", n1, 0);
+    checkInt("n2", n2, 0);
+    checkInt("n1 + n2", n1 + n2, 0);
+    checkProbability("p", p);
+    const seed = resolveSeed(options.seed);
+    let match: U32 | null = null;
+    if (options.perfectMatching === true) {
+        if (n1 !== n2) {
+            throw new RangeError(`perfectMatching needs n1 === n2, got ${n1} and ${n2}`);
+        }
+        match = plantedMatching(n1, seed);
+    }
+    const out = binomialBuffer(n1 * n2, p);
+    bipartiteRows(options, match, 0, n1, out);
+    const side = new Uint8Array(n1 + n2).fill(1, n1);
+    return applyWeights(toGraph(n1 + n2, out, false, { side }), options);
+}

package/src/generators/block-model.ts

@@ -0,0 +1,160 @@
+/**
+ * Stochastic block models (P. W. Holland, K. B. Laskey and S. Leinhardt, "Stochastic blockmodels:
+ * first steps", Social Networks 5, 109-137, 1983) and the planted partition model (A. Condon and
+ * R. M. Karp, Random Structures and Algorithms 18, 116-140, 2001), with the planted blocks emitted
+ * as ground truth.
+ */
+
+import { type U32 } from "@graphty/graph-format";
+
+import { detLog } from "../random/log.js";
+import { RandomStream, resolveSeed } from "../random/stream.js";
+import { type SampleGraph } from "../types.js";
+import { bernoulliSegment, binomialBuffer, checkInt, checkProbability, type EdgeBuffer, toGraph } from "./util.js";
+import { applyWeights, type WeightOptions } from "./weights.js";
+
+/** Options of {@link stochasticBlockModelGraph}. */
+export interface StochasticBlockModelOptions extends WeightOptions {
+    /** The size of every block; block b holds the next `sizes[b]` node indices. */
+    sizes: readonly number[];
+    /** The symmetric B x B matrix of edge probabilities between blocks. */
+    probabilities: readonly (readonly number[])[];
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+
+/** The checked and precomputed form of the options. */
+interface BlockPlan {
+    readonly n: number;
+    readonly seed: number;
+    /** starts[b] = first node of block b; starts[B] = n. */
+    readonly starts: readonly number[];
+    readonly block: U32;
+    readonly p: readonly (readonly number[])[];
+    readonly logQ: readonly (readonly number[])[];
+}
+
+/**
+ * Check the options and precompute block boundaries and detLog(1 - p).
+ * @param options - the options
+ * @returns the plan
+ */
+export function planBlocks(options: StochasticBlockModelOptions): BlockPlan {
+    const { sizes, probabilities } = options;
+    const seed = resolveSeed(options.seed);
+    const count = sizes.length;
+    checkInt("sizes.length", count, 1);
+    if (probabilities.length !== count) {
+        throw new RangeError(`probabilities must be ${count} x ${count}`);
+    }
+    const starts = [0];
+    for (let b = 0; b < count; b++) {
+        checkInt(`sizes[${b}]`, sizes[b], 0);
+        starts.push(starts[b] + sizes[b]);
+        if (probabilities[b].length !== count) {
+            throw new RangeError(`probabilities must be ${count} x ${count}`);
+        }
+        for (let c = 0; c < count; c++) {
+            checkProbability(`probabilities[${b}][${c}]`, probabilities[b][c]);
+            if (probabilities[b][c] !== probabilities[c][b]) {
+                throw new RangeError(`probabilities must be symmetric: [${b}][${c}] differs from [${c}][${b}]`);
+            }
+        }
+    }
+    const n = starts[count];
+    checkInt("the total size", n, 0);
+    const block = new Uint32Array(n);
+    for (let b = 0; b < count; b++) {
+        block.fill(b, starts[b], starts[b + 1]);
+    }
+    return {
+        n,
+        seed,
+        starts,
+        block,
+        p: probabilities,
+        logQ: probabilities.map((row) => row.map((p) => detLog(1 - p))),
+    };
+}
+
+/**
+ * Rows [start, end) of the block model: row u (in block b) draws from stream (seed, "sbm", u) and
+ * walks blocks c = b .. B - 1 in order, holding the pairs (u, v) for v > u in block c with
+ * probability p[b][c], ascending v. Concatenating consecutive row ranges gives the whole graph.
+ * @param plan - the checked options
+ * @param start - the first row
+ * @param end - one past the last row
+ * @param out - receives the edges
+ */
+export function blockModelRows(plan: BlockPlan, start: number, end: number, out: EdgeBuffer): void {
+    const { starts, block, p, logQ } = plan;
+    const stream = new RandomStream(plan.seed, "sbm", 0);
+    const count = starts.length - 1;
+    for (let u = start; u < end; u++) {
+        stream.reset(u);
+        const b = block[u];
+        // ponytail: O(B) per row, fine to n * B ~ 1e8; iterate only non-zero blocks if B grows large
+        for (let c = b; c < count; c++) {
+            bernoulliSegment(stream, p[b][c], logQ[b][c], u, c === b ? u + 1 : starts[c], starts[c + 1], out);
+        }
+    }
+}
+
+/**
+ * The stochastic block model in O(n B + m): node pairs are joined independently with the
+ * probability of their blocks, by geometric skipping inside each row's block segments. Edges are
+ * the pairs (u, v), u < v, row-major. Node column `community` (u32): the block.
+ * @param options - sizes, probabilities and seed
+ * @returns the undirected graph
+ */
+export function stochasticBlockModelGraph(options: StochasticBlockModelOptions): SampleGraph {
+    const plan = planBlocks(options);
+    let expected = 0;
+    let pairs = 0;
+    for (let b = 0; b < plan.starts.length - 1; b++) {
+        for (let c = b; c < plan.starts.length - 1; c++) {
+            const sb = plan.starts[b + 1] - plan.starts[b];
+            const sc = plan.starts[c + 1] - plan.starts[c];
+            const blockPairs = b === c ? (sb * (sb - 1)) / 2 : sb * sc;
+            expected += blockPairs * plan.p[b][c];
+            pairs += blockPairs;
+        }
+    }
+    const out = binomialBuffer(pairs, pairs === 0 ? 0 : expected / pairs);
+    blockModelRows(plan, 0, plan.n, out);
+    return applyWeights(toGraph(plan.n, out, false, { community: plan.block }), options);
+}
+
+/** Options of {@link plantedPartitionGraph}. */
+export interface PlantedPartitionOptions extends WeightOptions {
+    /** The number of groups, >= 1. */
+    groups: number;
+    /** The size of every group, >= 1. */
+    groupSize: number;
+    /** The edge probability inside a group. */
+    pIn: number;
+    /** The edge probability between groups. */
+    pOut: number;
+    /** The seed, an integer in [0, 2^53); default 0. */
+    seed?: number | undefined;
+}
+
+/**
+ * The planted partition model: `groups` equal blocks, `pIn` inside, `pOut` between. Exactly the
+ * stochastic block model with that matrix (same seed, same graph). Node column `community` (u32).
+ * @param options - groups, groupSize, pIn, pOut and seed
+ * @returns the undirected graph
+ */
+export function plantedPartitionGraph(options: PlantedPartitionOptions): SampleGraph {
+    const { groups, groupSize, pIn, pOut, seed } = options;
+    checkInt("groups", groups, 1);
+    checkInt("groupSize", groupSize, 1);
+    return stochasticBlockModelGraph({
+        sizes: new Array<number>(groups).fill(groupSize),
+        probabilities: Array.from({ length: groups }, (_, b) =>
+            Array.from({ length: groups }, (_2, c) => (b === c ? pIn : pOut)),
+        ),
+        seed,
+        weights: options.weights,
+    });
+}