All versions of this documentation



Ogma includes a range of layouts to help the user spot different structure patterns from different prospectives. In this tutorial we'll cover some basic layouts and the tutorial will be progressively improved to cover more and more layouts.

Force layout

Force layout is the algorithm that treats the graph as a physical system, where nodes are represented by charged particles and edges - by elastic springs. This type of simulations is known for being able to produce visually pleasing layouts of good readability from most sorts of graphs.

  .then(function () {
    // done

Force layout has few parameters that can influence the resulting picture in different ways.


Using charge, you can control how much nodes are repelling each other and thus, the surface of the resulting layout. The hubs will also be put further from each other.

charge = 5 vs. charge = 50


Gravity force is applied to all the nodes of the graph in order to pull them together and towards the center of mass of the graph. It makes sure that the weakly connected components of smaller size would not be pushed too far away by the bigger "core". That also helps to straighen the "branches" if they appear in the structure.

gravity=0 vs. gravity=0.01


Sometimes, in order to get a quick view on a bigger graph you might be interested in just running few iterations fast to see the shape of it and the main hubs, or maybe you don't care too much about the node overlap.

You can get a combination of parameters that would give you a result very quickly, here are the results for 50 and 300 steps (default value):

To control the amount of steps, use the steps parameter. On top of that, you can completely skip the overlap removal step, which can also win you some time.

  steps: 50,
  elasticity: 0

Hierarchical layout

The hierarchical layout makes easy to find hierarchies within the graph data such dependencies, control chains and flow analysis. As per the ForceLink layout also the hierarchy layout function returns a Promise handler to control the code flow:

  duration: 400
}).then( function (){
    // do something else after the layout

It is possible to control the spacing in the layout using the nodeDistance and levelDistance numeric properties. nodeDistance controls the minimum distance between nodes within each rank: if the layout is too crowded it is a good idea to increase this parameter. levelDistance controls the minimum gap distance between each layer in the hierarchy.

By default the layout will workout the best layering structure in terms of "compactness" of the vertical height. While this is useful to discover structural patterns in your data, sometimes it is required to set some "constraints" to the layout to make it respect some business expectation. These constraints will hints the layout algorithm where to position specific nodes in the layering structure so that the expectations are correct for the business case.

Constraints can be set directly on the nodes, using a special layer data property, as shown in the example below:

// With the layer property we're forcing the algorithm to invert
// the layering structure
var data = {
  nodes: [
    {id: 'n1', data: {layer: 0}},
    {id: 'n2', data: {layer: 1}},
    {id: 'n3', data: {layer: 2}},
  edges: [
    {id: 'e1', source: 'n3', target: 'n2'},
    {id: 'e2', source: 'n2', target: 'n1'},

    return ogma.layouts.hierarchical({
      duration: 400

Layers start from 0 (top layer) to any positive number. The layout will do its best to respect the assigned layer, while avoiding possible conflicts - anyway lower layers will always be on top of higher layers.

This parameter opens a new world of potential discoveries:

Hierarchical custom layering

To see and example of this layout in action taken a look at: