Hypergraph Visualization

A hypergraph generalizes a graph: a hyperedge connects any number of vertices, not just two. Nodus visualizes hypergraphs through the nodus.hypergraph module, which implements a scalable rendering pipeline — set data, simplify, lay out, and render hyperedges as regions around their vertices. This guide walks the practical pipeline end to end. For the concepts behind it, see Hypergraphs.

The pipeline is chainable:

setData(data) → simplify(opts?) → layout(opts?) → render(opts?)

Try it live — the full set→simplify→layout→render pipeline running end to end:

The hypergraph pipeline Open in new tab ↗

1. Provide the data

A hypergraph is a set of vertices and a set of hyperedges, where each hyperedge lists the vertex ids it contains:

nodus.hypergraph.setData({
  vertices: [
    { id: 'alice' },
    { id: 'bob' },
    { id: 'carol' },
    { id: 'dave' },
  ],
  hyperedges: [
    { id: 'paper-1', vertices: ['alice', 'bob', 'carol'] },
    { id: 'paper-2', vertices: ['carol', 'dave'] },
  ],
});

A vertex may optionally carry a nodeId (to tie it to a node in your main graph) and arbitrary data; a hyperedge may carry data too.

From an existing graph

If you already have a graph loaded, build a hypergraph from it with fromNodesAndEdges. Provide a groupBy function that returns, for each node, the list of hyperedge ids it belongs to:

nodus.hypergraph.fromNodesAndEdges({
  // Group nodes into hyperedges by some attribute of your data.
  groupBy: (node) => node.getData()?.communities ?? [],
});

Both setData and fromNodesAndEdges return the module, so you can chain.

2. Simplify

simplify(opts?) reduces visual clutter by merging and scaling the structure. It returns { scales, operations }.

const { scales, operations } = nodus.hypergraph.simplify({
  alpha: 1,
  beta: 1,
  gamma: 1,
  stopWhen: 'noForbidden',
});

simplify options

Option	Meaning
alpha, beta, gamma	Weights that balance the simplification objective.
adjacencyT	Adjacency threshold used while simplifying.
maxScales	Cap on how many scales to produce.
stopWhen	Stopping rule: 'linear', 'noForbidden', 'targetVertices', 'targetHyperedges', or 'manual'.
targetVertexCount	Target vertex count when stopWhen: 'targetVertices'.
targetHyperedgeCount	Target hyperedge count when stopWhen: 'targetHyperedges'.
forbiddenSubgraphs	Subgraph patterns to avoid.
betweennessRefreshEvery	How often to refresh betweenness during simplification.

// Simplify down to a target number of hyperedges.
nodus.hypergraph.simplify({
  stopWhen: 'targetHyperedges',
  targetHyperedgeCount: 12,
});

3. Lay out

layout(opts?) positions the vertices and hyperedge regions. It’s a Promise and resolves with { totalEnergy, overlapCount } so you can judge quality.

const result = await nodus.hypergraph.layout({
  weights: {
    regularity: 1,
    area: 1,
    separation: 1,
    intersection: 1,
    coordination: 1,
  },
  separationIters: 200,
  regularityIters: 200,
  solver: 'lbfgs',
  onProgress: (info) => console.log('layout progress', info),
});

console.log('energy', result.totalEnergy, 'overlaps', result.overlapCount);

layout options

Option	Meaning
weights	Per-term weights: regularity, area, separation, intersection, coordination.
separationIters	Iterations spent pushing regions apart.
regularityIters	Iterations spent regularizing region shapes.
solver	'lbfgs' or 'adam'.
optimizeDual	Also optimize the dual layout.
targetAreaPerCardinality(k)	Target area for a hyperedge of cardinality k.
bufferDistance	Padding kept around regions.
useWorker	Run in a Web Worker (default true).
progressEvery / onProgress(info)	Progress reporting cadence and callback.

4. Render

render(opts?) draws the result. It returns { primal?, dual? }.

nodus.hypergraph.render({
  view: 'primal',
  palette: ['#0ea5e9', '#f97316', '#22c55e', '#a855f7'],
  showVertices: true,
  position: 'below',
  fillOpacity: 0.25,
  strokeOpacity: 0.8,
});

render options

Option	Meaning
view	'primal', 'dual', 'both', or '2.5d'.
palette	Colors used for hyperedge regions.
showVertices	Draw the vertices themselves.
showIncidenceEdges	Draw vertex–hyperedge incidence edges.
position	Draw 'below' or 'above' the graph.
layer	Render on the 'canvas' or 'svg' layer.
fillOpacity / strokeOpacity	Region fill and stroke opacity.
vertexRadius	Radius of drawn vertices.
interactive	Enable hover/selection interaction.
hoverFillOpacityScale / hoverStrokeWidth	Hover emphasis.
selectionStrokeColor / selectionStrokeWidth / selectionDash	Selected-region styling.
levelOf / levelSpacing / obliqueTilt	Layout of the '2.5d' view.
vertexTag	Tagging used when drawing vertices.

The '2.5d' view stacks hyperedges on tilted levels for a layered look:

nodus.hypergraph.render({
  view: '2.5d',
  levelSpacing: 40,
  obliqueTilt: 0.5,
});

Try it live — switch between the primal and dual views of the same hypergraph:

Primal & dual views Open in new tab ↗

Querying the result

Read back positions and quality metrics:

const positions = nodus.hypergraph.getVertexPositions(); // Map<id, {x, y}>
const xy = positions.get('alice');

const metrics = nodus.hypergraph.getQualityMetrics();
// { overlapCount, overlapArea, avgRegularity, forbiddenSubgraphCount }
console.log('regularity', metrics.avgRegularity);

You can also get a hyperedge’s outline polygon to draw or hit-test yourself:

const polygon = nodus.hypergraph.getHyperedgePolygon('paper-1'); // {x, y}[]

Selection and events

When you render with interactive: true, the module tracks hovered and selected hyperedges and vertices. Toggle selection programmatically, and read it back:

nodus.hypergraph.setSelected({ hyperedges: ['paper-1'], replace: true });
nodus.hypergraph.toggleSelected({ vertex: 'carol' });

const selected = nodus.hypergraph.getSelectedHyperedges();
nodus.hypergraph.clearSelection();

Subscribe to interaction with on(event, cb):

nodus.hypergraph.on('hyperedgeClick', (e) => {
  console.log('clicked hyperedge', e);
});

nodus.hypergraph.on('vertexHover', (v) => highlight(v));
nodus.hypergraph.on('selectionChanged', () => updatePanel());

The available events are simplifyStart, simplifyEnd, layoutStart, layoutPhase, layoutIter, layoutEnd, render, viewChanged, hyperedgeHover, hyperedgeOut, hyperedgeClick, vertexHover, vertexOut, vertexClick, and selectionChanged. Remove a handler with off(cb).

Switching views and lifecycle

nodus.hypergraph.setActiveView('dual'); // 'primal' | 'dual' | 'both'
nodus.hypergraph.refresh();
nodus.hypergraph.hide();
nodus.hypergraph.show();
nodus.hypergraph.destroy();

Putting it together

import { Nodus } from '@kortexya/nodus';

const nodus = new Nodus({ container: document.getElementById('graph') });

await nodus.hypergraph
  .setData({
    vertices: [{ id: 'a' }, { id: 'b' }, { id: 'c' }, { id: 'd' }],
    hyperedges: [
      { id: 'h1', vertices: ['a', 'b', 'c'] },
      { id: 'h2', vertices: ['c', 'd'] },
    ],
  })
  .simplify({ stopWhen: 'noForbidden' })
  .layout({ solver: 'lbfgs', separationIters: 200, regularityIters: 200 });

nodus.hypergraph.render({
  view: 'both',
  showVertices: true,
  palette: ['#0ea5e9', '#f97316'],
  interactive: true,
});

nodus.hypergraph.on('hyperedgeClick', (e) => console.log('clicked', e));

Next

• Hypergraphs — the model and the ideas behind the pipeline.
• API: Hypergraph — the full module reference.
• Applying Layouts — ordinary graph layouts for the non-hypergraph case.