@mark1russell7/highways 0.2.0 → 0.4.0

package/src/bench/measures/routes.ts

@@ -0,0 +1,226 @@
+import { dist, polylineLength, turns, type Point } from "../../geom.ts";
+import { rng } from "../../fixtures.ts";
+import { Grid } from "../../grid.ts";
+import { nodeIndex, type Graph, type Route } from "../../model.ts";
+import { nearestSide } from "../../plugs.ts";
+import { TOLERANCE } from "../properties.ts";
+import { quantile } from "./stats.ts";
+
+/** A drawn segment: a pair of points. */
+export type DrawnSegment = readonly [Point, Point];
+
+const key = (p: Point): string => `${Math.round(p.x * 8)},${Math.round(p.y * 8)}`;
+
+/**
+ * This function gives the drawn segments of the routes: one segment for each distinct pair of ends.
+ * A segment that several routes share is one drawn segment, as in `measureQuality`.
+ */
+export function drawnSegments(routes: readonly Route[]): DrawnSegment[] {
+  const segs: DrawnSegment[] = [];
+  const seen = new Set<string>();
+  for (const r of routes) {
+    const p = r.points;
+    for (let i = 1; i < p.length; i++) {
+      const ka = key(p[i - 1]!);
+      const kb = key(p[i]!);
+      if (ka === kb) continue;
+      const k = ka < kb ? `${ka}|${kb}` : `${kb}|${ka}`;
+      if (seen.has(k)) continue;
+      seen.add(k);
+      segs.push([p[i - 1]!, p[i]!]);
+    }
+  }
+  return segs;
+}
+
+/** This function gives the key of the drawn segment between two points. Two routes share a segment when they give the same key. */
+export function segmentKey(a: Point, b: Point): string | undefined {
+  const ka = key(a);
+  const kb = key(b);
+  if (ka === kb) return undefined;
+  return ka < kb ? `${ka}|${kb}` : `${kb}|${ka}`;
+}
+
+/**
+ * This function gives the unit of length of a board: the median of the short sides of the boxes of the nodes.
+ * A length divided by the unit has no unit, so boards of different sizes compare. The unit of a board without nodes is 1.
+ */
+export function boardUnit(graph: Graph): number {
+  if (graph.nodes.length === 0) return 1;
+  const u = quantile(
+    graph.nodes.map((n) => Math.min(n.box.w, n.box.h)),
+    0.5,
+  );
+  return u > 0 ? u : 1;
+}
+
+/** The crossings of a set of drawn segments and their angles (R1 and R2 of MEAS0). */
+export interface CrossingAngles {
+  /** The number of crossings (R1). It is the same value as `crossings` of `measureQuality`. */
+  readonly crossings: number;
+  /** This value is true when the values come from a sample of the segments. */
+  readonly estimated: boolean;
+  /** The mean angle of a crossing, divided by 90 degrees (R2). The scale is 0 to 1, and higher is better. A set without crossings gives 1. */
+  readonly mean: number;
+  /** The smallest angle of a crossing, in degrees from 0 to 90 (R2). Higher is better. A set without crossings gives 90. */
+  readonly min: number;
+}
+
+const EXACT_CROSSINGS = 20_000;
+const SAMPLE = 2_000;
+
+/** This function gives the angle between two segments, in degrees from 0 to 90. */
+export function crossingAngle(a: Point, b: Point, c: Point, d: Point): number {
+  const ux = b.x - a.x;
+  const uy = b.y - a.y;
+  const vx = d.x - c.x;
+  const vy = d.y - c.y;
+  const l = Math.hypot(ux, uy) * Math.hypot(vx, vy);
+  if (l === 0) return 0;
+  return (Math.acos(Math.min(1, Math.abs(ux * vx + uy * vy) / l)) * 180) / Math.PI;
+}
+
+/**
+ * This function measures the crossings of a set of segments and their angles (R1 and R2 of MEAS0).
+ * It uses the grid and the sample of `countCrossings`. Above 20 000 segments, a seeded sample of 2 000 segments gives an estimate.
+ * The cost is `n log n`.
+ */
+export function crossingAngles(segs: readonly DrawnSegment[]): CrossingAngles {
+  if (segs.length < 2) return { crossings: 0, estimated: false, mean: 1, min: 90 };
+  const len = segs.reduce((s, [a, b]) => s + dist(a, b), 0) / segs.length;
+  const grid = new Grid<number>(Math.max(20, len));
+  segs.forEach(([a, b], i) => grid.addSegment(i, a, b));
+  const exact = segs.length <= EXACT_CROSSINGS;
+  const R = rng(segs.length);
+  const pick = exact ? segs.map((_, i) => i) : Array.from({ length: SAMPLE }, () => Math.floor(R() * segs.length));
+  let count = 0;
+  let sum = 0;
+  let min = 90;
+  for (const i of pick) {
+    const [a, b] = segs[i]!;
+    grid.querySegment(a, b, 0, (j) => {
+      if (exact && j <= i) return;
+      if (j === i) return;
+      const [c, d] = segs[j]!;
+      if (!segmentsCrossInside(a, b, c, d)) return;
+      count++;
+      const t = crossingAngle(a, b, c, d);
+      sum += t;
+      min = Math.min(min, t);
+    });
+  }
+  const crossings = exact ? count : Math.round((count * segs.length) / (2 * pick.length));
+  return { crossings, estimated: !exact, mean: count ? sum / count / 90 : 1, min: count ? min : 90 };
+}
+
+const orient = (a: Point, b: Point, c: Point): number => (b.x - a.x) * (c.y - a.y) - (b.y - a.y) * (c.x - a.x);
+
+/** This test is the test of `segmentsCross`, so the count of `crossingAngles` is the count of `countCrossings`. */
+function segmentsCrossInside(a: Point, b: Point, c: Point, d: Point): boolean {
+  return orient(c, d, a) * orient(c, d, b) < 0 && orient(a, b, c) * orient(a, b, d) < 0;
+}
+
+/** The total turn of the routes (R4 of MEAS0). */
+export interface TotalTurn {
+  /** The mean over the routes of `T(r) = Σ abs(φ_i) / π`, in half turns. Lower is better. */
+  readonly mean: number;
+  /** The largest turn at one vertex of a route, in degrees from 0 to 180. Lower is better. */
+  readonly max: number;
+}
+
+/** This function measures the total turn of the routes (R4 of MEAS0). A path that goes straight on has 0. The cost is linear. */
+export function totalTurn(routes: readonly Route[]): TotalTurn {
+  let sum = 0;
+  let max = 0;
+  for (const r of routes) {
+    let t = 0;
+    for (const phi of turns(r.points)) {
+      t += Math.abs(phi);
+      max = Math.max(max, Math.abs(phi));
+    }
+    sum += t / Math.PI;
+  }
+  return { mean: routes.length ? sum / routes.length : 0, max: (max * 180) / Math.PI };
+}
+
+/** The spread of the detour of the routes (R5 of MEAS0). */
+export interface DetourSpread {
+  /** The median of `δ(e) = L(r_e) / span(e)`. */
+  readonly median: number;
+  /** The `0.95` quantile of `δ(e)`: the tail of bad routes. */
+  readonly q95: number;
+  readonly mean: number;
+}
+
+/**
+ * This function measures the spread of the detour `δ(e) = L(r_e) / span(e)` of the routes (R5 of MEAS0).
+ * A route with ends nearer than 1 unit does not count. Each value is 1 or more, and lower is better. The cost is linear.
+ */
+export function detourSpread(routes: readonly Route[]): DetourSpread {
+  const d: number[] = [];
+  for (const r of routes) {
+    const p = r.points;
+    if (p.length < 2) continue;
+    const span = dist(p[0]!, p[p.length - 1]!);
+    if (span > 1) d.push(polylineLength(p) / span);
+  }
+  if (d.length === 0) return { median: 1, q95: 1, mean: 1 };
+  return { median: quantile(d, 0.5), q95: quantile(d, 0.95), mean: d.reduce((s, x) => s + x, 0) / d.length };
+}
+
+/** The spacing of the plugs on the sides of the boxes (R11 of MEAS0). */
+export interface PlugSpacing {
+  /** The smallest spacing of a side. The scale is 0 to 1, and higher is better. A value of 1 is even spacing. */
+  readonly min: number;
+  /** The `0.05` quantile of the spacing of the sides. */
+  readonly q05: number;
+  /** The number of sides with two plugs or more. */
+  readonly sides: number;
+}
+
+/**
+ * This function measures the spacing of the plugs on each side of each box (R11 of MEAS0), the angular resolution of a box.
+ * For a side with `k` distinct plugs, `ps = min gap / (side / (k + 1))`, with a limit of 1.
+ * Two ends nearer than `TOLERANCE` are one plug, because a bundle shares its plug. An end farther than 1 unit from the side does not count.
+ * Without a side with two plugs, each value is 1. The cost is `n log n`.
+ */
+export function plugSpacing(graph: Graph, routes: readonly Route[]): PlugSpacing {
+  const byId = nodeIndex(graph);
+  const edges = new Map(graph.edges.map((e) => [e.id, e]));
+  const at = new Map<string, number[]>();
+  const add = (nodeId: string, p: Point): void => {
+    const n = byId.get(nodeId);
+    if (!n) return;
+    const b = n.box;
+    const side = nearestSide(b, p);
+    const off = side === "north" ? Math.abs(p.y - b.y) : side === "south" ? Math.abs(p.y - b.y - b.h) : side === "west" ? Math.abs(p.x - b.x) : Math.abs(p.x - b.x - b.w);
+    if (off > 1) return;
+    const pos = side === "north" || side === "south" ? p.x - b.x : p.y - b.y;
+    const k = `${nodeId}\u0000${side}`;
+    const list = at.get(k);
+    if (list) list.push(pos);
+    else at.set(k, [pos]);
+  };
+  for (const r of routes) {
+    const e = edges.get(r.edge);
+    const p = r.points;
+    if (!e || p.length < 2) continue;
+    add(e.source.node, p[0]!);
+    add(e.target.node, p[p.length - 1]!);
+  }
+  const values: number[] = [];
+  for (const [k, list] of at) {
+    const node = byId.get(k.slice(0, k.indexOf("\u0000")))!;
+    const side = k.slice(k.indexOf("\u0000") + 1);
+    const length = side === "north" || side === "south" ? node.box.w : node.box.h;
+    list.sort((a, b) => a - b);
+    const plugs: number[] = [];
+    for (const x of list) if (plugs.length === 0 || x - plugs[plugs.length - 1]! > TOLERANCE) plugs.push(x);
+    if (plugs.length < 2 || length <= 0) continue;
+    let gap = Infinity;
+    for (let i = 1; i < plugs.length; i++) gap = Math.min(gap, plugs[i]! - plugs[i - 1]!);
+    values.push(Math.min(1, gap / (length / (plugs.length + 1))));
+  }
+  if (values.length === 0) return { min: 1, q05: 1, sides: 0 };
+  return { min: values.reduce((m, x) => Math.min(m, x), 1), q05: quantile(values, 0.05), sides: values.length };
+}

package/src/bench/measures/stability.ts

@@ -0,0 +1,104 @@
+import { inflate, type Box } from "../../geom.ts";
+import { rng } from "../../fixtures.ts";
+import type { Edge, Graph, Node, Result } from "../../model.ts";
+import { measureStability } from "../quality.ts";
+import { boardUnit } from "./routes.ts";
+
+/** A small change of a graph, for the stability measures Z10 and G9 of MEAS0. */
+export interface GraphChange {
+  /** The graph after the change. It keeps the order of the nodes. */
+  readonly graph: Graph;
+  /** The node that moved by one unit, if a free place was found. */
+  readonly moved?: string;
+  /** The new edge, if the graph has two nodes without an edge between them. */
+  readonly added?: string;
+  /** The edge that the change removed. */
+  readonly removed?: string;
+}
+
+/**
+ * This function makes a seeded small change of a graph: one node moves by `boardUnit`, one edge goes and one new edge comes.
+ * The moved box keeps a gap of 4 units to the other boxes. The same graph and the same seed give the same change.
+ */
+export function changeGraph(graph: Graph, seed: number): GraphChange {
+  const R = rng(seed * 2654435761 + 97);
+  const n = graph.nodes.length;
+  const u = boardUnit(graph);
+  let nodes: readonly Node[] = graph.nodes;
+  let moved: string | undefined;
+  if (n > 0) {
+    const i = Math.floor(R() * n);
+    const v = graph.nodes[i]!;
+    const free = (b: Box): boolean => {
+      const g = inflate(b, 4);
+      return graph.nodes.every((o, j) => j === i || o.box.x >= g.x + g.w || g.x >= o.box.x + o.box.w || o.box.y >= g.y + g.h || g.y >= o.box.y + o.box.h);
+    };
+    const start = Math.floor(R() * 4);
+    for (let k = 0; k < 4 && moved === undefined; k++) {
+      const [dx, dy] = [
+        [u, 0],
+        [0, u],
+        [-u, 0],
+        [0, -u],
+      ][(start + k) % 4]!;
+      const box = { ...v.box, x: v.box.x + dx!, y: v.box.y + dy! };
+      if (free(box)) {
+        nodes = graph.nodes.map((o, j) => (j === i ? { ...o, box } : o));
+        moved = v.id;
+      }
+    }
+  }
+  let edges: Edge[] = [...graph.edges];
+  let removed: string | undefined;
+  let added: string | undefined;
+  if (edges.length > 1) {
+    const j = Math.floor(R() * edges.length);
+    const gone = edges[j]!;
+    removed = gone.id;
+    edges.splice(j, 1);
+    const linked = new Set(graph.edges.flatMap((e) => [`${e.source.node}\u0000${e.target.node}`, `${e.target.node}\u0000${e.source.node}`]));
+    for (let t = 0; t < 64 && added === undefined && n > 1; t++) {
+      const a = graph.nodes[Math.floor(R() * n)]!.id;
+      const b = graph.nodes[Math.floor(R() * n)]!.id;
+      if (a === b || linked.has(`${a}\u0000${b}`)) continue;
+      added = `${gone.id}~`;
+      edges = [...edges, { id: added, source: { node: a }, target: { node: b }, ...(gone.data ? { data: gone.data } : {}) }];
+    }
+  }
+  return { graph: { nodes, edges }, ...(moved ? { moved } : {}), ...(added ? { added } : {}), ...(removed ? { removed } : {}) };
+}
+
+/** The route stability of a router (Z10 of MEAS0). */
+export interface RouteStability {
+  /** The mean Fréchet distance between the two routes of an edge, divided by the unit of the board. */
+  readonly mean: number;
+  /** The largest Fréchet distance, divided by the unit of the board. */
+  readonly max: number;
+  /** The share of the routes that moved more than 1 unit of length. */
+  readonly moved: number;
+}
+
+/** The options of `routeStability`. */
+export interface RouteStabilityOptions {
+  /** Above this number of routes, a seeded sample of this size serves. The default is 2000. */
+  readonly sample?: number;
+  readonly seed?: number;
+}
+
+/**
+ * This function measures the route stability of a router (Z10 of MEAS0) with `measureStability`.
+ * It compares the routes of the edges that both results have. Each distance is divided by the unit of the board.
+ * The cost is quadratic for each route, so a seeded sample serves above `sample` routes.
+ */
+export function routeStability(graph: Graph, before: Result, after: Result, options: RouteStabilityOptions = {}): RouteStability {
+  const max = options.sample ?? 2000;
+  const prev = new Set(before.routes.map((r) => r.edge));
+  let routes = after.routes.filter((r) => prev.has(r.edge));
+  if (routes.length > max) {
+    const R = rng(options.seed ?? 1);
+    routes = Array.from({ length: max }, () => routes[Math.floor(R() * routes.length)]!);
+  }
+  const s = measureStability(before, { routes });
+  const u = boardUnit(graph);
+  return { mean: s.mean / u, max: s.max / u, moved: s.moved };
+}

package/src/bench/measures/stats.ts

@@ -0,0 +1,114 @@
+import { rng } from "../../fixtures.ts";
+
+/**
+ * This function gives the `p` quantile of the values, with a linear step between two ranks (type 7 of Hyndman and Fan).
+ * The result is `NaN` for an empty list.
+ */
+export function quantile(values: readonly number[], p: number): number {
+  if (values.length === 0) return Number.NaN;
+  const s = [...values].sort((a, b) => a - b);
+  const at = Math.max(0, Math.min(1, p)) * (s.length - 1);
+  const lo = Math.floor(at);
+  const hi = Math.min(s.length - 1, lo + 1);
+  return s[lo]! + (s[hi]! - s[lo]!) * (at - lo);
+}
+
+/** The spread of a measure over the seeds of a fixture family. */
+export interface Spread {
+  /** The number of values. */
+  readonly n: number;
+  readonly median: number;
+  /** The `0.25` quantile. */
+  readonly q1: number;
+  /** The `0.75` quantile. */
+  readonly q3: number;
+  /** The interquartile range: `q3 - q1`. */
+  readonly iqr: number;
+  readonly min: number;
+  readonly max: number;
+}
+
+/** This function gives the median, the quartiles, the interquartile range, the smallest and the largest value of a list. */
+export function summarize(values: readonly number[]): Spread {
+  const v = values.filter((x) => !Number.isNaN(x));
+  const q1 = quantile(v, 0.25);
+  const q3 = quantile(v, 0.75);
+  return {
+    n: v.length,
+    median: quantile(v, 0.5),
+    q1,
+    q3,
+    iqr: q3 - q1,
+    min: v.length ? v.reduce((m, x) => Math.min(m, x), Infinity) : Number.NaN,
+    max: v.length ? v.reduce((m, x) => Math.max(m, x), -Infinity) : Number.NaN,
+  };
+}
+
+/** The largest number of values for which `kendallTau` examines each pair. Above it, the function examines a seeded sample of pairs. */
+export const KENDALL_EXACT = 1500;
+const KENDALL_SAMPLE = 200_000;
+
+/**
+ * This function gives the Kendall tau-b of two lists of the same length (Kendall, 1938).
+ * The value is from -1 to 1. A value of 1 means the same order. A pair with a tie in both lists does not count.
+ * When one list has only ties, the value is 1. Above `KENDALL_EXACT` values, a seeded sample of 200 000 pairs gives an estimate.
+ */
+export function kendallTau(a: readonly number[], b: readonly number[], seed = 1): number {
+  const n = Math.min(a.length, b.length);
+  if (n < 2) return 1;
+  let concordant = 0;
+  let discordant = 0;
+  let tieA = 0;
+  let tieB = 0;
+  const visit = (i: number, j: number): void => {
+    const da = Math.sign(a[i]! - a[j]!);
+    const db = Math.sign(b[i]! - b[j]!);
+    if (da === 0 && db === 0) return;
+    if (da === 0) tieA++;
+    else if (db === 0) tieB++;
+    else if (da === db) concordant++;
+    else discordant++;
+  };
+  if (n <= KENDALL_EXACT) {
+    for (let i = 0; i < n; i++) for (let j = i + 1; j < n; j++) visit(i, j);
+  } else {
+    const R = rng(seed);
+    for (let k = 0; k < KENDALL_SAMPLE; k++) {
+      const i = Math.floor(R() * n);
+      const j = Math.floor(R() * n);
+      if (i !== j) visit(i, j);
+    }
+  }
+  const den = Math.sqrt((concordant + discordant + tieA) * (concordant + discordant + tieB));
+  return den === 0 ? 1 : (concordant - discordant) / den;
+}
+
+const pairs = (k: number): number => (k * (k - 1)) / 2;
+
+/**
+ * This function gives the adjusted Rand index of two groupings of the same items (Hubert and Arabie, 1985).
+ * The item `i` is in the group `a[i]` of the first grouping and in the group `b[i]` of the second grouping.
+ * The value is 1 for the same grouping, and near 0 for a random grouping. Two groupings with one group each give 1.
+ */
+export function adjustedRandIndex(a: readonly (string | number)[], b: readonly (string | number)[]): number {
+  const n = Math.min(a.length, b.length);
+  if (n < 2) return 1;
+  const cells = new Map<string, number>();
+  const rows = new Map<string | number, number>();
+  const cols = new Map<string | number, number>();
+  for (let i = 0; i < n; i++) {
+    const key = `${String(a[i])}\u0000${String(b[i])}`;
+    cells.set(key, (cells.get(key) ?? 0) + 1);
+    rows.set(a[i]!, (rows.get(a[i]!) ?? 0) + 1);
+    cols.set(b[i]!, (cols.get(b[i]!) ?? 0) + 1);
+  }
+  let index = 0;
+  for (const c of cells.values()) index += pairs(c);
+  let sa = 0;
+  let sb = 0;
+  for (const c of rows.values()) sa += pairs(c);
+  for (const c of cols.values()) sb += pairs(c);
+  const expected = (sa * sb) / pairs(n);
+  const top = (sa + sb) / 2;
+  return top === expected ? 1 : (index - expected) / (top - expected);
+}

package/src/bench/properties.ts

@@ -1,6 +1,6 @@
 import { dist, inflate, pointBoxDistance, segmentHitsBox, type Box, type Point } from "../geom.ts";
 import { Grid } from "../grid.ts";
-import { fixedPortPoint, nodeIndex, type Graph, type Node, type Result } from "../model.ts";
+import { fixedPortPoint, nodeIndex, type Graph, type Level, type Node, type Result } from "../model.ts";
 
 /** A broken hard rule. A correct router has none. */
 export interface Violation {
@@ -89,7 +89,23 @@ export function checkProperties(graph: Graph, result: Result, limit = 100): Viol
         if (add({ rule: "run-shared", edge: id, detail: `run ${run.id}: the route does not hold the points of the run in a row` })) return out;
     }
   }
-  for (const level of result.levels ?? []) {
+  out.push(...checkLevels(graph, result.levels ?? [], limit - out.length));
+  return out;
+}
+
+/**
+ * This function checks the hard rules of the zoom levels. The counts of each level add up (`counts-sum`).
+ * Each link of a level starts on the box of its source and ends on the box of its target (`link-ends`).
+ * The function gives at most `limit` violations.
+ */
+export function checkLevels(graph: Graph, levels: readonly Level[], limit = 100): Violation[] {
+  const out: Violation[] = [];
+  const add = (v: Violation): boolean => {
+    out.push(v);
+    return out.length >= limit;
+  };
+  if (limit <= 0) return out;
+  for (const level of levels) {
     const itemOf = new Map<string, string>();
     for (const it of level.items) for (const n of it.nodes) itemOf.set(n, it.id);
     if (itemOf.size !== graph.nodes.length)