Graphology Force layout

JavaScript implementation of a basic force directed layout algorithm for graphology.

In some few cases, for very small graphs, ForceAtlas2 can be “too efficient”. This simpler force algorithm cannot spatialize larger networks, but will offer more organic movements which are more suited to some interactions with the graph such as drag and drop etc.

Installation

npm install graphology-layout-force

Usage

• Pre-requisite
• Settings
• Synchronous layout
• Supervisor

Pre-requisites

Each node’s starting position must be set before running the force layout algorithm. Two attributes called x and y must therefore be defined for all the graph nodes.

Note also that the algorithm has an edge-case where the layout cannot be computed if all of your nodes starts with x=0 and y=0.

Settings

• attraction ?number 0.0005: importance of the attraction force, that attracts each pair of connected nodes like elastics.
• repulsion ?number 0.1: importance of the repulsion force, that attracts each pair of nodes like magnets.
• gravity ?number 0.0001: importance of the gravity force, that attracts all nodes to the center.
• inertia ?number 0.6: percentage of a node vector displacement that is preserved at each step. 0 means no inertia, 1 means no friction.
• maxMove ?number 200: Maximum length a node can travel at each step, in pixel.

Synchronous layout

import forceLayout from 'graphology-layout-force';

const positions = forceLayout(graph, {maxIterations: 50});

// With settings:
const positions = forceLayout(graph, {
  maxIterations: 50,
  settings: {
    gravity: 10
  }
});

// To directly assign the positions to the nodes:
forceLayout.assign(graph);

Arguments

• graph Graph: target graph.
• options object: options:
  • nodeXAttribute ?string x: name of the x position attribute for nodes.
  • nodeYAttribute ?string y: name of the y position attribute for edges.
  • isNodeFixed ?string|function fixed: name of the fixed attribute for nodes or a function getting a node entry (key, attributes) and returning whether the node is fixed.
  • shouldSkipNode ?function: function returning whether the layout computations should skip this node.
  • shouldSkipEdge ?function: function returning whether the layout computations should skip this edge.
  • maxIterations ?number 500: maximum number of iterations to perform before stopping. Note that the algorithm will also stop as soon as converged.
  • settings ?object: the layout’s settings (see #settings).

Supervisor

Layout supervisor relying on window.requestAnimationFrame to run the layout live without hampering the UI thread.

Example

import ForceSupervisor from 'graphology-layout-force/worker';

const layout = new ForceSupervisor(graph, params);

// To start the layout. It will automatically stop when converged
layout.start();

// To stop the layout
layout.stop();

// To kill the layout and release attached memory and listeners
layout.kill();

// Assess whether the layout is currently running
layout.isRunning();