Class pv.Layout.Force

Extends pv.Layout.Network.
Implements force-directed network layout as a node-link diagram. This layout uses the Fruchterman-Reingold algorithm, which applies an attractive spring force between neighboring nodes, and a repulsive electrical charge force between all nodes. An additional drag force improves stability of the simulation. See pv.Force.spring, pv.Force.drag and {@link pv.Force.charge} for more details; note that the n-body charge force is approximated using the Barnes-Hut algorithm.

This layout is implemented on top of pv.Simulation, which can be used directly for more control over simulation parameters. The simulation uses Position Verlet integration, which does not compute velocities explicitly, but allows for easy geometric constraints, such as bounding the nodes within the layout panel. Many of the configuration properties supported by this layout are simply passed through to the underlying forces and constraints of the simulation.

Force layouts are typically interactive. The gradual movement of the nodes as they stabilize to a local stress minimum can help reveal the structure of the network, as can pv.Behavior.drag, which allows the user to pick up nodes and reposition them while the physics simulation continues. This layout can also be used with pan & zoom behaviors for interaction.

To facilitate interaction, this layout by default automatically re-renders using a setInterval every 42 milliseconds. This can be disabled via the iterations property, which if non-null specifies the number of simulation iterations to run before the force-directed layout is finalized. Be careful not to use too high an iteration count, as this can lead to an annoying delay on page load.

As with other network layouts, the network data can be updated dynamically, provided the property cache is reset. See pv.Layout.Network for details. New nodes are initialized with random positions near the center. Alternatively, positions can be specified manually by setting the x and y attributes on nodes.
Defined in: Force.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	pv.Layout.Force() Constructs a new, empty force-directed layout.

Field Summary
Field Attributes	Field Name and Description
	bound The bound parameter; true if nodes should be constrained within the layout panel.
	chargeConstant The charge constant, which should be a negative number.
	chargeMaxDistance The maximum distance at which charge forces are applied.
	chargeMinDistance The minimum distance at which charge forces are applied.
	chargeTheta The Barnes-Hut approximation factor.
	defaults Default properties for force-directed layouts.
	dragConstant The drag constant, in the range [0,1].
	iterations The number of simulation iterations to run, or null if this layout is interactive.
	springConstant The spring constant, which should be a positive number.
	springDamping The spring damping factor, in the range [0,1].
	springLength The spring rest length.

Fields borrowed from class pv.Layout.Network:: label, link, node
Fields borrowed from class pv.Panel:: canvas, children, overflow, transform
Fields borrowed from class pv.Bar:: fillStyle, height, lineWidth, strokeStyle, width
Fields borrowed from class pv.Mark:: bottom, childIndex, cursor, data, events, index, left, parent, proto, reverse, right, root, scale, title, top, type, visible

Methods borrowed from class pv.Layout.Network:: reset
Methods borrowed from class pv.Panel:: add, anchor
Methods borrowed from class pv.Mark:: anchorTarget, def, event, extend, margin, mouse, render

Class Detail

pv.Layout.Force()

Constructs a new, empty force-directed layout. Layouts are not typically constructed directly; instead, they are added to an existing panel via pv.Mark#add.

See:: "Graph Drawing by Force-directed Placement" by T. Fruchterman & E. Reingold, Software--Practice & Experience, November 1991.

Field Detail

{boolean} bound

The bound parameter; true if nodes should be constrained within the layout panel. Bounding is disabled by default. Currently the layout does not observe the radius of the nodes; strictly speaking, only the center of the node is constrained to be within the panel, with an additional 6-pixel offset for padding. A future enhancement could extend the bound constraint to observe the node's radius, which would also support bounding for variable-size nodes.

Note that if this layout is used in conjunction with pan & zoom behaviors, those behaviors should have their bound parameter set to the same value.

{number} chargeConstant

The charge constant, which should be a negative number. The default value is -40; more negative values will result in a stronger repulsive force, which may lead to faster convergence at the risk of instability. Too strong repulsive charge forces can cause comparatively weak springs to be stretched well beyond their rest length, emphasizing global structure over local structure. A nonnegative value will break the Fruchterman-Reingold algorithm, and is for entertainment purposes only.

See:: pv.Force.charge#constant

{number} chargeMaxDistance

The maximum distance at which charge forces are applied. This improves performance by ignoring weak charge forces at great distances. Note that this parameter is partly redundant, as the Barnes-Hut algorithm for n-body forces already improves performance for far-away particles through approximation.

See:: pv.Force.charge#domain

{number} chargeMinDistance

The minimum distance at which charge forces are applied. The default minimum distance of 2 avoids applying forces that are two strong; because the physics simulation is run at discrete time intervals, it is possible for two same- charged particles to become very close or even a singularity! Since the charge force is inversely proportional to the square of the distance, very small distances can break the simulation.

In rare cases, two particles can become stuck on top of each other, as a minimum distance threshold will prevent the charge force from repelling them. However, this occurs very rarely because other forces and momentum typically cause the particles to become separated again, at which point the repulsive charge force kicks in.

See:: pv.Force.charge#domain

{number} chargeTheta

The Barnes-Hut approximation factor. The Barnes-Hut approximation criterion is the ratio of the size of the quadtree node to the distance from the point to the node's center of mass is beneath some threshold. The default value is 0.9.

See:: pv.Force.charge#theta

{pv.Layout.Force} defaults

Default properties for force-directed layouts. The default drag constant is 0.1, the default charge constant is -40 (with a domain of [2, 500] and theta of 0.9), and the default spring constant is 0.1 (with a damping of 0.3 and a rest length of 20).

{number} dragConstant

The drag constant, in the range [0,1]. A value of 0 means no drag (a perfectly frictionless environment), while a value of 1 means friction immediately cancels all momentum. The default value is 0.1, which provides a minimum amount of drag that helps stabilize bouncy springs; lower values may result in excessive bounciness, while higher values cause the simulation to take longer to converge.

See:: pv.Force.drag#constant

{number} iterations

The number of simulation iterations to run, or null if this layout is interactive. Force-directed layouts are interactive by default, using a setInterval to advance the physics simulation and re-render automatically.

{number} springConstant

The spring constant, which should be a positive number. The default value is 0.1; greater values will result in a stronger attractive force, which may lead to faster convergence at the risk of instability. Too strong spring forces can cause comparatively weak charge forces to be ignored, emphasizing local structure over global structure. A nonpositive value will break the Fruchterman-Reingold algorithm, and is for entertainment purposes only.

The spring tension is automatically normalized using the inverse square root of the maximum link degree of attached nodes.

See:: pv.Force.spring#constant

{number} springDamping

The spring damping factor, in the range [0,1]. Damping functions identically to drag forces, damping spring bounciness by applying a force in the opposite direction of attached nodes' velocities. The default value is 0.3.

The spring damping is automatically normalized using the inverse square root of the maximum link degree of attached nodes.

See:: pv.Force.spring#damping

{number} springLength

The spring rest length. The default value is 20 pixels. Larger values may be appropriate if the layout panel is larger, or if the nodes are rendered larger than the default dot size of 20.

See:: pv.Force.spring#length

Classes

Class pv.Layout.Force