src/science/network.ts

Functions

Imports

It imports src/render/data.ts, src/render/figure.ts, src/render/plot.ts, src/render/series.ts, src/render/size.ts. Imported by src/science/index.ts.

Source

1import * as Plot from "@observablehq/plot";
2import {
3  forceCollide,
4  forceLink,
5  forceManyBody,
6  forceSimulation,
7  forceX,
8  forceY,
9  type SimulationLinkDatum,
10  type SimulationNodeDatum,
11} from "d3-force";
12import { maxOf, minOf } from "../render/data.js";
13import { type FigureOptions, figure, type SeriesColor, validateFigure } from "../render/figure.js";
14import { keyed, renderPlot } from "../render/plot.js";
15import { planSeries } from "../render/series.js";
16import { DEFAULT_WIDTH } from "../render/size.js";
17
18/** A node in a {@link networkChart}. */
19export interface NetworkNode {
20  /** Unique within the chart. */
21  readonly id: string;
22  /** The text shown beside the node; defaults to `id`. */
23  readonly label?: string;
24  /** A group the node belongs to, colored as a series and listed in the legend. */
25  readonly group?: string;
26}
27
28/** A link between two nodes, by id. */
29export interface NetworkLink {
30  readonly source: string;
31  readonly target: string;
32}
33
34/** Options for {@link networkChart}. */
35export interface NetworkChartOptions extends FigureOptions {
36  readonly nodes: readonly NetworkNode[];
37  readonly links: readonly NetworkLink[];
38  /** Every group in display and color order. Without it, first-seen order. */
39  readonly groupDomain?: readonly string[];
40  readonly colors?: Readonly<Record<string, SeriesColor>>;
41  /** Print node labels (default true when there are 40 nodes or fewer). */
42  readonly nodeLabels?: boolean;
43  /** Simulation steps; more settles a large network further (default 300). */
44  readonly iterations?: number;
45}
46
47interface LaidOutNode extends SimulationNodeDatum {
48  readonly id: string;
49  readonly label: string;
50  readonly group: string;
51  degree: number;
52}
53
54const KIND = "networkChart";
55const RADIUS = 6;
56
57/**
58 * A force-directed network, laid out on the server with d3-force so it needs no script and draws
59 * the same every time: collaborators, co-authorship, transmission clusters. Groups are colored
60 * as series; the data table lists every node with its connections.
61 *
62 * @example
63 * networkChart({
64 *   nodes: [{ id: "a", group: "Lab" }, { id: "b", group: "Clinic" }],
65 *   links: [{ source: "a", target: "b" }],
66 *   alt: "Two collaborators ...",
67 * });
68 */
69export function networkChart(options: NetworkChartOptions): string {
70  const { nodes, links } = options;
71  validateFigure(KIND, options);
72  if (nodes.length === 0) throw new Error(`${KIND}: nodes is empty`);
73  const width = options.width ?? DEFAULT_WIDTH;
74  const height = options.height ?? 420;
75  const ungrouped = "Nodes";
76  const grouped = nodes.some((n) => n.group !== undefined);
77
78  const byId = new Map<string, LaidOutNode>();
79  nodes.forEach((n, i) => {
80    if (n.id === "") throw new Error(`${KIND}: node ${i + 1} has an empty id`);
81    if (byId.has(n.id)) throw new Error(`${KIND}: two nodes have id "${n.id}"`);
82    byId.set(n.id, { id: n.id, label: n.label ?? n.id, group: n.group ?? ungrouped, degree: 0 });
83  });
84  const laidOut = [...byId.values()];
85  const edges = links.map(
86    (l, i): SimulationLinkDatum<LaidOutNode> & { a: LaidOutNode; b: LaidOutNode } => {
87      const a = byId.get(l.source);
88      const b = byId.get(l.target);
89      if (!a || !b) {
90        throw new Error(
91          `${KIND}: link ${i + 1} names "${a ? l.target : l.source}", which is not a node`,
92        );
93      }
94      a.degree += 1;
95      b.degree += 1;
96      return { source: a, target: b, a, b };
97    },
98  );
99
100  const groupNames = options.groupDomain
101    ? [...options.groupDomain]
102    : [...new Set(laidOut.map((n) => n.group))];
103  for (const n of laidOut) {
104    if (!groupNames.includes(n.group)) {
105      throw new Error(`${KIND}: group "${n.group}" is missing from groupDomain`);
106    }
107  }
108  const plan = planSeries(KIND, groupNames, options.colors);
109
110  // d3-force seeds its layout deterministically, so the same data always yields the same drawing.
111  const simulation = forceSimulation<LaidOutNode>(laidOut)
112    .force("link", forceLink<LaidOutNode, (typeof edges)[number]>(edges).distance(40))
113    .force("charge", forceManyBody().strength(-90))
114    .force("x", forceX(0).strength(0.06))
115    .force("y", forceY(0).strength(0.06 * (width / height)))
116    .force("collide", forceCollide(RADIUS + 3))
117    .stop();
118  simulation.tick(options.iterations ?? 300);
119
120  const xs = laidOut.map((n) => n.x ?? 0);
121  const ys = laidOut.map((n) => n.y ?? 0);
122  const pad = 1;
123  const span = (values: number[]): [number, number] => {
124    const lo = minOf(values);
125    const hi = maxOf(values);
126    return lo === hi ? [lo - pad, hi + pad] : [lo, hi];
127  };
128  const showLabels = options.nodeLabels ?? laidOut.length <= 40;
129  const describe = (n: LaidOutNode): string =>
130    `${n.label}${grouped ? ` (${n.group})` : ""}: ${n.degree} connection${n.degree === 1 ? "" : "s"}`;
131
132  const marks: Plot.Markish[] = [
133    Plot.link(edges, {
134      x1: (e: (typeof edges)[number]) => e.a.x ?? 0,
135      y1: (e: (typeof edges)[number]) => e.a.y ?? 0,
136      x2: (e: (typeof edges)[number]) => e.b.x ?? 0,
137      y2: (e: (typeof edges)[number]) => e.b.y ?? 0,
138      stroke: "var(--enarratio-text-muted)",
139      strokeOpacity: 0.5,
140    }),
141    Plot.dot(laidOut, {
142      x: (n: LaidOutNode) => n.x ?? 0,
143      y: (n: LaidOutNode) => n.y ?? 0,
144      r: RADIUS,
145      fill: "group",
146      stroke: "var(--enarratio-background)",
147      strokeWidth: 1.5,
148      title: describe,
149      render: keyed(laidOut, (n) => ({
150        key: n.id,
151        column: laidOut.indexOf(n),
152        row: 0,
153        filter: grouped ? { field: "group", value: n.group } : { field: "id", value: n.id },
154        x: n.label,
155        ...(grouped ? { series: n.group } : {}),
156      })),
157    }),
158  ];
159  if (showLabels) {
160    marks.push(
161      Plot.text(laidOut, {
162        x: (n: LaidOutNode) => n.x ?? 0,
163        y: (n: LaidOutNode) => n.y ?? 0,
164        text: "label",
165        dx: RADIUS + 3,
166        textAnchor: "start",
167        fill: "var(--enarratio-text)",
168        stroke: "var(--enarratio-background)",
169        strokeWidth: 3,
170        paintOrder: "stroke",
171      }),
172    );
173  }
174
175  const { svg } = renderPlot(
176    {
177      width,
178      height,
179      margin: 16,
180      marginRight: showLabels ? 96 : 16,
181      x: { domain: span(xs), axis: null },
182      y: { domain: span(ys), axis: null },
183      color: { domain: groupNames, range: [...plan.range] },
184      marks,
185    },
186    options.alt,
187  );
188
189  const neighbors = new Map<string, string[]>(laidOut.map((n) => [n.id, []]));
190  for (const e of edges) {
191    neighbors.get(e.a.id)?.push(e.b.label);
192    neighbors.get(e.b.id)?.push(e.a.label);
193  }
194
195  return figure(options, {
196    kind: "network",
197    svg,
198    legend: grouped ? plan.legend : [],
199    ...(grouped ? { seriesField: "group" } : {}),
200    slotColors: plan.slotColors,
201    table: {
202      columns: ["Node", ...(grouped ? ["Group"] : []), "Connected to"],
203      rows: laidOut.map((n) => [
204        n.label,
205        ...(grouped ? [n.group] : []),
206        (neighbors.get(n.id) ?? []).join(", ") || "none",
207      ]),
208    },
209  });
210}