Force Transform

The force transform computes a force-directed layout. Force-directed layout uses a model in which data objects act as charged particles (or nodes), optionally connected by a set of edges (or links). A set of forces are used to drive a physics simulation that determines the node positions. This transform uses the d3-force module.

To fix a node at a given position, you may set two special fields on a node object:

  • fx - the node’s fixed x-position
  • fy - the node’s fixed y-position

The force transform modifies the input node data only. It does not modify any properties of link data. Instead, use a lookup transform to join the node data with the link data. Then, use a transform such as linkpath to layout the links.

Example

View Source Export PNG Export SVG

Transform Parameters

Property Type Description
static Boolean Indicates if the simulation should be computed in batch to produce a static layout (true) or should be animated (false). The default is false.
restart Boolean Indicates if the simulation should restart when node object fields are modified (default false).
iterations Number The number of iterations to run the simulation when in static mode (default 300).
alpha Number A value representing the current energy level or “temperature” of the simulation. Alpha values lie in the range [0, 1]. Internally, the simulation will decrease the alpha value over time, causing the magnitude of updates to diminish.
alphaMin Number The minimum amount by which to lower the alpha value on each simulation iteration (default 0.001).
alphaTarget Number The target alpha value to which the simulation converges (default 0).
velocityDecay Number The velocity decay factor is akin to atmospheric friction; after the application of any forces during an iteration, each node’s velocity is multiplied by 1 - velocityDecay (default 0.4).
forces Force[ ] An array of objects defining the forces to include in the simulation. See the forces reference for more.
as String[ ] The output fields to which node positions and velocities are written. The default is ["x", "y", "vx", "vy"].

Forces Reference

# center

A force that pulls all nodes toward a shared [x, y] center point.

Property Type Description
force String The value "center".
x Number The center x-coordinate.
y Number The center y-coordinate.

# collide

A collision detection force that pushes apart nodes whose circular radii overlap.

Property Type Description
force String The value "collide".
radius Number | Expr The radius of the node.
strength Number The relative strength of this force (default 0.7).
iterations Number The number of iterations to run collision detection (default 1).

# nbody

An n-body force that causes nodes to either attract or repel each other.

Property Type Description
force String The value "nbody".
strength Number | Expr The relative strength of this force (default -30). Negative values cause nodes to repel, positive values to attract.
theta Number Approximation parameter for aggregating more distance forces (default 0.9).
distanceMin Number The minimum distance over which this force acts. If two nodes are close than distanceMin, the exerted forces will be as if they are distanceMin apart (default 1).
distanceMax Number The maximum distance over which this force acts. If two nodes exceed distanceMax, they will not exert forces on each other.

# link

Adds link constraints that causes nodes to be pushed apart towards a target separation distance. Link objects must be provided in a secondary data stream with data objects containing source and target fields to indicate nodes. If an id field parameter is provided, it is used to related link objects and node objects. Otherwise, the source and target fields should provide indices into the array of node objects.

Property Type Description
force String The value "link".
links Data The data set containing the link data objects. Each link should contain source and target fields indicating the node objects.
id Field An optional data field for a node’s unique identifier. If provided, the source and target fields of each link should use these values to indicate nodes.
distance Number | Expr The distance in pixels by which the link constraint should separate nodes (default 30).
strength Number | Expr The relative strength of the link constraint.
iterations Number The number of iterations to run link constraints (default 1).

# x

Attracts nodes to a particular x-coordinate, on a per-node basis.

Property Type Description
force String The value "x".
x Field The x-coordinate value that should attract the node.
strength Number The relative strength of this force (default 0.1).

# y

Attracts nodes to a particular y-coordinate, on a per-node basis.

Property Type Description
force String The value "y".
y Field The y-coordinate value that should attract the node.
strength Number The relative strength of this force (default 0.1).

Usage

{
  "type": "force",
  "forces": [
    {
      "force": "center",
      "x": {"signal": "width / 2"},
      "y": {"signal": "height / 2"}
    },
    {
      "force": "nbody",
      "strength": -10
    },
    {
      "force": "link",
      "links": "edges",
      "distance": 25
    },
    {
      "force": "collide",
      "radius": 10
    }
  ]
}

Perform force-directed layout of a network. The layout is centered in the middle of the view, nodes repel each other, and a data set edges defines link constraints with a 25 pixel distance. Finally, collision detection is performed on nodes with a radius of 10 pixels.

{
  "type": "force",
  "static": true,
  "forces": [
    {
      "force": "x",
      "x": "xfocus"
    },
    {
      "force": "y",
      "y": "yfocus"
    },
    {
      "force": "collide",
      "radius": {"field": "radius"}
    }
  ]
}

Compute a beeswarm layout of nodes. Each node is attracted to an [x, y] coordinate given by the xfocus and yfocus fields. Collision detection is performed, using the radius data field of each node to determine the radius.