# 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

## 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 | 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.