@graphty/graph-io 0.3.42 → 0.3.44

package/src/styles/plan/discrete.ts

@@ -0,0 +1,165 @@
+/**
+ * A discrete mapping on one categorical feature: the feature's values fall inside the family's blocks, up to 20% of
+ * the styled elements excepted, and the elements missing the feature may form their own group.
+ */
+
+import { type Family, valueKey } from "./families.js";
+import type { FeatureInfo } from "./features.js";
+
+/** Below this many styled elements anything explains anything: no mapping is tried. */
+export const MIN_MAPPED = 8;
+/** The most keys a discrete table may hold. */
+const MAX_KEYS = 256;
+/** The share of styled elements a mapping may get wrong; the replay moves them into the exceptions. */
+const MAX_EXCEPTION_SHARE = 0.2;
+
+/** A key of a discrete table, as the feature holds it. */
+type KeyValue = string | number | boolean;
+
+/**
+ * A discrete mapping that explains a family.
+ */
+export interface DiscreteCandidate {
+    /** The kind of candidate. */
+    readonly type: "discrete";
+    /** The feature the table reads. */
+    readonly info: FeatureInfo;
+    /** Each key (by its value key) with its raw value and the block it maps to. */
+    readonly table: Map<string, { readonly raw: KeyValue; readonly block: number }>;
+    /** The block the elements missing the feature share, or null. */
+    readonly bucket: number | null;
+    /** The description cost. */
+    readonly cost: number;
+}
+
+/**
+ * Tests a discrete mapping on one feature.
+ * @param fam - the family
+ * @param info - the feature
+ * @param n - the element count
+ * @param spend - spends work from the budget
+ * @returns the candidate, or null when the feature does not explain the family
+ */
+export function discreteCandidate(
+    fam: Family,
+    info: FeatureInfo,
+    n: number,
+    spend: (ops: number) => void,
+): DiscreteCandidate | null {
+    const nF = fam.styled.length;
+    if (!info.categorical || info.raw || nF < MIN_MAPPED) {
+        return null;
+    }
+    if (info.distinct < 2 || info.distinct > Math.min(MAX_KEYS, nF / 2) || info.distinct >= 0.9 * n) {
+        return null;
+    }
+    spend(n);
+    const { values } = info.feature;
+    const { votes, nullBlocks } = votesOf(fam, values);
+    const { table, exceptions: wrong } = tableOf(votes);
+    let exceptions = wrong;
+    // never paint an element the file left unstyled
+    const unstyledMissing = unstyledOf(fam, values, table, n);
+    if (unstyledMissing === null) {
+        return null;
+    }
+    // the elements missing the key form one group when they share one style (Gephi's "null" partition)
+    let bucket: number | null = null;
+    if (nullBlocks.size === 1 && !unstyledMissing) {
+        bucket = nullBlocks.keys().next().value ?? null;
+    } else {
+        for (const c of nullBlocks.values()) {
+            exceptions += c;
+        }
+    }
+    if (exceptions > Math.max(2, MAX_EXCEPTION_SHARE * nF)) {
+        return null;
+    }
+    const cost =
+        50 + table.size * fam.props.length + (exceptions > 0 ? 50 + exceptions : 0) + (bucket === null ? 0 : 50);
+    return { type: "discrete", info, table, bucket, cost };
+}
+
+/** How the styled elements of each key fall into the family's blocks. */
+type Votes = Map<string, { raw: KeyValue; counts: Map<number, number> }>;
+
+/**
+ * Counts, per key of the feature, the styled elements in each block; and per block, those missing the feature.
+ * @param fam - the family
+ * @param values - the feature's values
+ * @returns the votes, and the blocks of the elements missing the feature
+ */
+function votesOf(fam: Family, values: readonly (KeyValue | null)[]): { votes: Votes; nullBlocks: Map<number, number> } {
+    const votes: Votes = new Map();
+    const nullBlocks = new Map<number, number>();
+    for (const i of fam.styled) {
+        const b = fam.blocks[i];
+        const kv = values[i];
+        if (kv === null) {
+            nullBlocks.set(b, (nullBlocks.get(b) ?? 0) + 1);
+            continue;
+        }
+        const key = valueKey(kv);
+        let vote = votes.get(key);
+        if (vote === undefined) {
+            vote = { raw: kv, counts: new Map() };
+            votes.set(key, vote);
+        }
+        vote.counts.set(b, (vote.counts.get(b) ?? 0) + 1);
+    }
+    return { votes, nullBlocks };
+}
+
+/**
+ * The table: each key maps to the block most of its elements are in; the others are exceptions.
+ * @param votes - the votes
+ * @returns the table and how many elements it gets wrong
+ */
+function tableOf(votes: Votes): { table: Map<string, { raw: KeyValue; block: number }>; exceptions: number } {
+    const table = new Map<string, { raw: KeyValue; block: number }>();
+    let exceptions = 0;
+    for (const [key, { raw, counts }] of votes) {
+        let best = -1;
+        let bestCount = -1;
+        let total = 0;
+        for (const [b, c] of counts) {
+            total += c;
+            if (c > bestCount) {
+                bestCount = c;
+                best = b;
+            }
+        }
+        table.set(key, { raw, block: best });
+        exceptions += total - bestCount;
+    }
+    return { table, exceptions };
+}
+
+/**
+ * Whether an element the file left unstyled misses the feature (or holds false, which a missing-key group's "not has"
+ * also matches).
+ * @param fam - the family
+ * @param values - the feature's values
+ * @param table - the table
+ * @param n - the element count
+ * @returns the answer, or null when the table would paint an unstyled element
+ */
+function unstyledOf(
+    fam: Family,
+    values: readonly (KeyValue | null)[],
+    table: ReadonlyMap<string, unknown>,
+    n: number,
+): boolean | null {
+    let missing = false;
+    for (let i = 0; i < n; i++) {
+        const v = values[i];
+        if (fam.blocks[i] !== 0) {
+            continue;
+        }
+        if (v !== null && table.has(valueKey(v))) {
+            return null;
+        }
+        missing ||= v === null || v === false;
+    }
+    return missing;
+}

package/src/styles/plan/families.ts

@@ -0,0 +1,115 @@
+/**
+ * Exact equivalence classes: every property's values partition the elements (null is a block of its own), and
+ * properties with identical partitions form one family, explained once.
+ */
+
+import type { StyleValue } from "../types.js";
+
+/**
+ * A group of properties that partition the elements the same way.
+ */
+export interface Family {
+    /** The properties, in the order they were given. */
+    readonly props: string[];
+    /** Each element's block: 0 for null, 1.. by first appearance. */
+    readonly blocks: Int32Array;
+    /** The number of non-null blocks. */
+    readonly k: number;
+    /** The elements with a value (block above 0), ascending. */
+    readonly styled: number[];
+}
+
+/**
+ * The text a value is compared by.
+ * @param v - the value
+ * @returns a key unique per value and type
+ */
+export function valueKey(v: string | number | boolean | null | undefined): string {
+    return v === null || v === undefined ? "\u0000null" : `${typeof v}:${String(v)}`;
+}
+
+/**
+ * The partition of the elements by a property's values.
+ * @param values - the values by element
+ * @returns each element's block (0 for null, then by first appearance) and the number of non-null blocks
+ */
+function partition(values: readonly (StyleValue | null)[]): { blocks: Int32Array; k: number } {
+    const ids = new Map<string, number>();
+    const blocks = new Int32Array(values.length);
+    for (let i = 0; i < values.length; i++) {
+        const v = values[i];
+        if (v === null) {
+            continue;
+        }
+        const key = valueKey(v);
+        let id = ids.get(key);
+        if (id === undefined) {
+            id = ids.size + 1;
+            ids.set(key, id);
+        }
+        blocks[i] = id;
+    }
+    return { blocks, k: ids.size };
+}
+
+/**
+ * A hash of a block array.
+ * @param blocks - the blocks
+ * @returns its hash
+ */
+function hashBlocks(blocks: Int32Array): number {
+    let h = 0x811c9dc5;
+    for (const b of blocks) {
+        h = Math.imul(h ^ b, 0x01000193);
+    }
+    return h >>> 0;
+}
+
+/**
+ * Whether two block arrays are equal.
+ * @param a - one
+ * @param b - the other
+ * @returns true when equal
+ */
+function sameBlocks(a: Int32Array, b: Int32Array): boolean {
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * Groups properties by identical partitions.
+ * @param props - the properties, each with its values
+ * @returns the families, in the order of their first property
+ */
+export function familiesOf(props: readonly (readonly [string, readonly (StyleValue | null)[]])[]): Family[] {
+    const byHash = new Map<number, Family[]>();
+    const out: Family[] = [];
+    for (const [p, values] of props) {
+        const { blocks, k } = partition(values);
+        const h = hashBlocks(blocks);
+        const list = byHash.get(h) ?? [];
+        const hit = list.find((f) => sameBlocks(f.blocks, blocks));
+        if (hit !== undefined) {
+            hit.props.push(p);
+            continue;
+        }
+        const styled: number[] = [];
+        for (let i = 0; i < blocks.length; i++) {
+            if (blocks[i] !== 0) {
+                styled.push(i);
+            }
+        }
+        const fam: Family = { props: [p], blocks, k, styled };
+        list.push(fam);
+        byHash.set(h, list);
+        out.push(fam);
+    }
+    return out;
+}

package/src/styles/plan/features.ts

@@ -0,0 +1,234 @@
+/**
+ * Candidate explaining columns: the snapshot's attributes and the graph's degrees, which the planner tests as
+ * explanations of a file's per-element style values, and the fingerprint that ties styles to their graph.
+ */
+
+import type { GraphSnapshot } from "@graphty/graph-format";
+
+import type { ColumnRef, Scalar, StyleFeature, StyleFingerprint, StyleTarget } from "../types.js";
+import { dataCell, degreeValues } from "./resolve.js";
+
+/** Column types whose values can be features: one scalar per element. */
+const SCALAR_DTYPES: ReadonlySet<string> = new Set(["string", "dict", "bool", "i32", "u32", "u8", "f32", "f64"]);
+/** Coordinates say where the writer put a node, not what it is. */
+const COORDINATE = /^(?:x|y|z|_pos)$/i;
+/** The column holding the group a node sits in. */
+const PARENT_COLUMN = "graphty.parent";
+/** An integer column of at least this many values that fills a whole range is an index, not a quantity. */
+const MIN_INDEX = 8;
+
+/**
+ * The candidate explaining columns of one target: every scalar attribute (the reserved `graphty.*` columns,
+ * coordinates and Cytoscape's selection state excepted), the group a node sits in as the style column `group`, and
+ * for nodes the degree (and the in- and out-degree of a directed graph) as `{ computed }` references, which follow
+ * later edits of the graph.
+ * @param snapshot - the graph
+ * @param target - nodes or edges
+ * @returns the features, in column order with the degrees last
+ * @category Styles
+ */
+export function featuresOf(snapshot: GraphSnapshot, target: StyleTarget): StyleFeature[] {
+    const table = target === "node" ? snapshot.nodes : snapshot.edges;
+    const n = target === "node" ? snapshot.nodeCount : snapshot.edgeCount;
+    const out: StyleFeature[] = [];
+    for (const name of table.names().filter((c) => isFeatureColumn(table, c))) {
+        const values = Array.from({ length: n }, (_, i): Scalar | null => {
+            const v = dataCell(table, name, i);
+            return typeof v === "string" || typeof v === "number" || typeof v === "boolean" ? v : null;
+        });
+        if (name !== PARENT_COLUMN) {
+            out.push({ ref: { data: name }, values });
+        } else if (target === "node") {
+            // the group a node sits in, by the group's id: graphty-element keeps no graphty.* column in its records
+            const group = values.map((v) =>
+                typeof v === "number" && v >= 0 && v < snapshot.nodeCount ? String(snapshot.ids.idOf(v)) : null,
+            );
+            out.push({ ref: { style: "group" }, values: group });
+        }
+    }
+    if (target === "node" && n > 0) {
+        const kinds: ("degree" | "indegree" | "outdegree")[] = snapshot.directed
+            ? ["degree", "indegree", "outdegree"]
+            : ["degree"];
+        for (const k of kinds) {
+            out.push({ ref: { computed: k }, values: degreeValues(snapshot, k) });
+        }
+    }
+    return out;
+}
+
+/**
+ * Whether a column may explain styles: one scalar component, neither a position nor a coordinate, nor graphty's own
+ * columns (the parent excepted) or Cytoscape's selection state.
+ * @param table - the node or edge table
+ * @param name - the column
+ * @returns true for a candidate
+ */
+function isFeatureColumn(table: GraphSnapshot["nodes"], name: string): boolean {
+    if ((name.startsWith("graphty.") && name !== PARENT_COLUMN) || name === "selected" || COORDINATE.test(name)) {
+        return false;
+    }
+    const col = table.get(name);
+    return (
+        col !== null && col.meta.role !== "position" && SCALAR_DTYPES.has(col.meta.dtype) && col.meta.components === 1
+    );
+}
+
+/**
+ * The fingerprint of a graph: its node and edge counts and a hash of its node ids' text, whatever their order (a
+ * format may read nodes back in another order). The id 7 and the id "7" hash alike, so a graph written to a format
+ * that reads its ids back as text (or as numbers) keeps its fingerprint.
+ * @param snapshot - the graph
+ * @returns the fingerprint
+ * @category Styles
+ */
+export function styleFingerprint(snapshot: GraphSnapshot): StyleFingerprint {
+    // two FNV-1a hashes with different seeds over each id's text, summed: the sum does not depend on the order
+    let h1 = 0;
+    let h2 = 0;
+    for (let i = 0; i < snapshot.nodeCount; i++) {
+        const text = String(snapshot.ids.idOf(i));
+        let a = 0x811c9dc5;
+        let b = 0x01000193 ^ 0x5bd1e995;
+        for (let c = 0; c < text.length; c++) {
+            const code = text.charCodeAt(c); // NOSONAR(S7758): hashes UTF-16 code units; code points would change every fingerprint
+            a = Math.imul(a ^ code, 0x01000193);
+            b = Math.imul(b ^ code, 0x01000193) ^ (b >>> 13);
+        }
+        h1 = (h1 + (a >>> 0)) >>> 0;
+        h2 = (h2 + (b >>> 0)) >>> 0;
+    }
+    const hex = (h: number): string => (h >>> 0).toString(16).padStart(8, "0");
+    return {
+        nodes: snapshot.nodeCount,
+        edges: snapshot.edgeCount,
+        heldEdges: heldEdgeRows(snapshot).length,
+        ids: hex(h1) + hex(h2),
+    };
+}
+
+/**
+ * The edge rows a file holds, in order: every row but the second half of an undirected edge in a directed graph,
+ * which every format writes once.
+ * @param snapshot - the graph
+ * @returns the rows
+ */
+export function heldEdgeRows(snapshot: GraphSnapshot): number[] {
+    const pair = snapshot.edges.byRole("pair");
+    const rows: number[] = [];
+    for (let e = 0; e < snapshot.edgeCount; e++) {
+        if (!(pair?.isSet(e) === true && (pair.value(e) as number) < e)) {
+            rows.push(e);
+        }
+    }
+    return rows;
+}
+
+/** What describeFeature() reads off a feature's values. */
+interface ValueStats {
+    /** The distinct values, as type and text. */
+    readonly seen: ReadonlySet<string>;
+    /** Whether every value is text, a boolean or a finite integer. */
+    readonly categorical: boolean;
+    /** Whether every value is a finite number. */
+    readonly numeric: boolean;
+    /** Whether every value is an integer. */
+    readonly integers: boolean;
+    /** The smallest finite number. */
+    readonly lo: number;
+    /** The largest finite number. */
+    readonly hi: number;
+    /** How many values are set. */
+    readonly count: number;
+}
+
+/**
+ * The statistics of a feature's values.
+ * @param values - the values
+ * @returns the statistics
+ */
+function valueStats(values: readonly (Scalar | null)[]): ValueStats {
+    const seen = new Set<string>();
+    let categorical = true;
+    let numeric = true;
+    let integers = true;
+    let lo = Infinity;
+    let hi = -Infinity;
+    let count = 0;
+    for (const v of values) {
+        if (v === null) {
+            continue;
+        }
+        count++;
+        seen.add(`${typeof v}:${String(v)}`);
+        if (typeof v !== "number") {
+            numeric = false;
+            integers = false;
+        } else if (Number.isFinite(v)) {
+            integers &&= Number.isInteger(v);
+            categorical &&= Number.isInteger(v);
+            lo = Math.min(lo, v);
+            hi = Math.max(hi, v);
+        } else {
+            numeric = false;
+            categorical = false;
+        }
+    }
+    return { seen, categorical, numeric, integers, lo, hi, count };
+}
+
+/**
+ * A feature's name in rule ids: the column's name, the generated key or the degree's name.
+ * @param ref - the column
+ * @returns its name
+ */
+function featureName(ref: ColumnRef): string {
+    if ("style" in ref) {
+        return ref.style;
+    }
+    if ("computed" in ref) {
+        return ref.computed;
+    }
+    return (ref as { data: string }).data;
+}
+
+/**
+ * What the planner knows about a feature.
+ */
+export interface FeatureInfo {
+    /** The feature. */
+    readonly feature: StyleFeature;
+    /** Its name in rule ids. */
+    readonly name: string;
+    /** Distinct non-null values. */
+    readonly distinct: number;
+    /** Whether a table on it may explain styles (strings, booleans, integers). */
+    readonly categorical: boolean;
+    /** Whether a ramp on it may explain styles (finite numbers that are not an index). */
+    readonly numeric: boolean;
+    /** Whether it is the file's own raw style column, which explains nothing. */
+    readonly raw: boolean;
+}
+
+/**
+ * Describes a feature for the planner.
+ * @param feature - the feature
+ * @param raw - whether it is the raw style column a reader read
+ * @returns what the planner knows about it
+ */
+export function describeFeature(feature: StyleFeature, raw: boolean): FeatureInfo {
+    const { seen, categorical, numeric, integers, lo, hi, count } = valueStats(feature.values);
+    const computed = "computed" in feature.ref;
+    // an integer column whose values are all different and fill a whole range (0..n-1, a z order) is an index:
+    // a ramp on it would only replay the order the writer stored the elements in
+    const index =
+        !computed && numeric && integers && count >= MIN_INDEX && seen.size === count && hi - lo + 1 === count;
+    return {
+        feature,
+        name: featureName(feature.ref),
+        distinct: seen.size,
+        categorical: count > 0 && categorical,
+        numeric: count > 0 && numeric && !index,
+        raw,
+    };
+}

package/src/styles/plan/index.ts

@@ -0,0 +1,7 @@
+/**
+ * The planner, the candidate features and the reference resolver of a file's styles.
+ */
+
+export { featuresOf, styleFingerprint } from "./features.js";
+export { MAX_STYLE_RULES, type PlanOptions, planStyles, type StyleValues } from "./plan.js";
+export { resolveStyles } from "./resolve.js";