d3-force

What is d3-force?

The d3-force npm package is a module in the D3 (Data-Driven Documents) suite that provides a force-directed graph layout algorithm. It is used to simulate physical forces on particles and links in network graphs, enabling the creation of dynamic visualizations where nodes and links adjust their positions according to specified forces.

What are d3-force's main functionalities?

Force Simulation

This feature allows the creation of a force simulation for nodes and links. Nodes act like charged particles repelling each other while links act like springs connecting nodes. This code initializes a simulation with forces that affect node positioning and link connections.

const d3 = require('d3-force');
const simulation = d3.forceSimulation(nodes)
  .force('link', d3.forceLink(links).id(d => d.id))
  .force('charge', d3.forceManyBody())
  .force('center', d3.forceCenter(width / 2, height / 2));

Collision Detection

Collision detection prevents nodes from overlapping in the visualization. The 'forceCollide' function is used to keep nodes apart by specifying a radius for each node that determines its collision boundary.

const d3 = require('d3-force');
const simulation = d3.forceSimulation(nodes)
  .force('collision', d3.forceCollide().radius(d => d.radius));

Positioning Forces

This feature allows the application of forces that push nodes towards a specific position on the x and y axes. The strength of the force can be adjusted to control how aggressively nodes move towards the target position.

const d3 = require('d3-force');
const simulation = d3.forceSimulation(nodes)
  .force('x', d3.forceX(width / 2).strength(0.05))
  .force('y', d3.forceY(height / 2).strength(0.05));

Other packages similar to d3-force

cola

Cola.js, also known as WebCoLa, is a JavaScript constraint-based layout library that extends the force-directed graph layout paradigm. It supports additional constraints like alignment and distribution, which are not natively supported by d3-force. Cola.js can be integrated with D3.js but offers more layout customization options.

cytoscape

Cytoscape.js is a graph theory library that enables the analysis and visualization of complex networks. It includes various layout algorithms, including force-directed layouts. Compared to d3-force, Cytoscape.js provides a broader range of features for interaction and analysis, making it suitable for more complex applications.

README

d3-force

…

Installing

If you use NPM, npm install d3-force. Otherwise, download the latest release. You can also load directly from d3js.org, either as a standalone library or as part of D3 4.0 alpha. AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3_force global is exported:

<script src="https://d3js.org/d3-collection.v0.1.min.js"></script>
<script src="https://d3js.org/d3-dispatch.v0.4.min.js"></script>
<script src="https://d3js.org/d3-quadtree.v0.7.min.js"></script>
<script src="https://d3js.org/d3-timer.v0.4.min.js"></script>
<script src="https://d3js.org/d3-force.v0.3.min.js"></script>
<script>

var simulation = d3_force.forceSimulation(nodes);

</script>

Try d3-force in your browser.

API Reference

…

Simulation

…

# d3.forceSimulation([nodes])

…

# simulation.restart()

…

# simulation.stop()

…

# simulation.tick()

…

The exact number of iterations needed to terminate the simulation naturally is ⌈log(alphaMin) / -alphaDecay⌉. For example, to run the simulation manually:

for (var i = 0, n = Math.ceil(Math.log(simulation.alphaMin()) / -simulation.alphaDecay()); i < n; ++i) {
  simulation.tick();
}

This may be useful for computing static force-directed layouts, such as in a background web worker or on the server.

# simulation.nodes([nodes])

…

• index - the node’s zero-based index into nodes
• x - the node’s current x-position
• y - the node’s current y-position
• vx - the node’s current x-velocity
• vy - the node’s current y-velocity

# simulation.alphaMin([alpha])

…

# simulation.alphaDecay([decay])

…

# simulation.drag([drag])

…

# simulation.force(name[, force])

…

# simulation.on(typenames, [callback])

…

Forces

Simulations compose multiple arbitrary forces. By default, simulations have no bound forces; add or remove a force using simulation.force. This module provides several built-in forces:

• Centering
• Circle Collision
• Circle Containment
• Links
• Many-Body
• Positioning

You may also implement your own custom force. A force is simply a function that takes the simulation’s current alpha value and then modifies nodes’ positions or velocities. Forces may optionally implement force.initialize to receive the simulation’s array of nodes.

# force(alpha)

…

# force.initialize(nodes)

…

Centering

The centering force moves nodes so that their center of mass (assuming all nodes are equal-weight) is at the given position ⟨x,y⟩. (These parameters are only recomputed when the force is initialized, not on every application.)

# d3.forceCenter([x, y])

…

# center.x([x])

…

# center.y([y])

…

Circle Collision

The circle collision force prevents circular nodes with a given radius from overlapping. More formally, two nodes a and b are separated so that the distance between a and b is at least radius(a) + radius(b). To reduce jitter, this is by default a “soft” constraint with a configurable strength. (These parameters are only recomputed when the force is initialized, not on every application.)

# d3.forceCollide([radius])

…

# collide.radius([radius])

…

# collide.strength([strength])

…

Circle Containment

The circle containment force constrains nodes to fit within a circle of a given radius and center ⟨x,y⟩. The radius and center can be specified on a per-node basis. (These parameters are only recomputed when the force is initialized, not on every application.)

# d3.forceContain([radius[, x, y]])

…

# contain.radius([radius])

…

# contain.x([x])

…

# contain.y([y])

…

Links

The link force pushes linked nodes closer together or farther apart according to the desired link distance, which may be specified on a per-node basis. (These parameters are only recomputed when the force is initialized, not on every application.)

# d3.forceLink([links])

…

# link.links([links])

…

• index - the zero-based index into links
• source - the link’s source node; see simulation.nodes
• target - the link’s target node; see simulation.nodes

The source and target properties may be initialized using link.id.

# link.id([id])

…

# link.strength([strength])

…

# link.distance([distance])

…

Many-Body

The many-body (or n-body) force applies mutally amongst all nodes. It can be used to simulate gravity (attraction) if the strength is positive, or eletrical charge (repulsion) if the strength is negative. This implementation uses quadtrees and the Barnes–Hut approximation to greatly improve performance; the accuracy can be customized using the theta parameter. The strength can be specified on a per-node basis. (This parameter is only recomputed when the force is initialized, not on every application.)

# d3.forceManyBody()

…

# manyBody.strength([strength])

…

# manyBody.theta([theta])

…

# manyBody.distanceMin([distance])

…

# manyBody.distanceMax([distance])

…

Positioning

The positioning force pushes nodes towards a desired position ⟨x,y⟩. The position and strength can be specified on a per-node basis. (These parameters are only recomputed when the force is initialized, not on every application.)

# d3.forcePosition([x, y])

…

# position.strength([strength])

…

# position.x([x])

…

# position.y([y])

…