Layout Basics

Contents

• Introduction
• Running a layout
• Force-directed layouts
• Organic
• Structural
• Lens
• Level layouts
• Sequential
• Radial
• Packing of components
• Arrangements - layouts inside combos
• Performance
• Layout Options
  • Adaptive behaviour
  • Sequential layout options

Introduction

KeyLines transforms connected data into charts that highlight connections, patterns or outliers which would be difficult to spot in the raw data.

Visualising a dataset involves a layout algorithm that lays out the nodes and links in optimal positions to create readable, unobstructed and insightful view of the data. This allows chart users to analyse the data at a glance and quickly reveal the key insights. There are several layouts available, each with multiple customisation options.

Depending on the data, a chart can depict a single connected component, or even multiple separate components (for example, two company departments that don't interact at all).

Running a layout

When data is first loaded into KeyLines, nodes are given default coordinates. To avoid overlapping nodes, it's almost always a good idea to call chart.layout() after the data is loaded:

// pass layout name as the first argument of the layout() function
chart.layout('layout name');

If you're adding new data and want to minimise the movement of existing nodes as much as possible, consider using chart.expand(), which uses adaptive behaviour by default.

See our Layouts demo to compare the layouts and the layout options API to explore the options you can use to customise your layouts.

Force-directed layouts

Force-directed layouts position nodes by running a simulation of three forces - repulsion, springs, and network energy. These calculations repel unconnected nodes apart, attract connected nodes together, and move all nodes to optimal positions.

Level layouts

Level layouts visualise data that is organised in tiers and hierarchies, or that flows from one level to another. They can use different mechanisms to assign levels to nodes:

• Assigning levels automatically to minimise link crossings and maximise the use of available space. If links have arrows, their direction is used to infer the levels.
• Assigning levels according to the content of the level option.
• Assigning top (sequential) / root (radial) node(s) to those specified in the top option. This only lays out the component(s) for which top is specified.

Packing of components

Packing is a step run during the layout that determines how unconnected chart components are placed relative to each other. It takes the unconnected components and packs them together on the chart to minimise any large gaps.

Packing is available for all layouts except the lens layout. Different layouts have different default packing, but you can also control it manually using the packing option.

'circle'

Default for organic, structural and radial layouts. Lays out the components in a circular pattern. Great for space efficiency. Also suitable for sequential layout when hierarchy levels between unconnected components are irrrelevant as it makes better use of screen space.

'rectangle'

Lays out the components in a grid-like rectangular pattern. Great for space efficiency and use with other rectangle-biased features such as rectangular combos. Also suitable for sequential layout when hierarchy levels between unconnected components are irrrelevant as it makes better use of screen space.

'aligned'

Default for sequential layout. Lays out the components in a single line with same level items aligned to preserve the information about hierarchy of levels.

'adaptive'

Minimally adjusts positions of components to make space for new items or to use space created by removed items. See also Adaptive behaviour.

Arrangements - layouts inside combos

Items inside open combos are laid out using arrangements. Some arrangements are based on existing layouts (e.g. 'lens' or 'sequential'), others are for combos only (e.g. 'concentric' or 'grid').

See Arranging nodes inside open combos for more details.

Performance

Our default organic layout offers the best overall performance for any size of dataset. It is especially suitable for very large charts and would be our first recommendation for most datasets.

If you need to visualise very large hierarchical data, we recommend using the sequential layout with the top or level options specified. This makes layout calculations faster than if the levels are assigned automatically.

For more tips and details, see also the Performance documentation.

Layout options

Layout options can be used to fine-tune the appearance and behaviour of layouts. Options are set in the second argument of the layout API:

// brings the nodes closer together
chart.layout('layout name', { tightness: 10 });

Note that not all layout options apply to every layout.

{ 
  id: 'node1', 
  type: 'node',
  d: { levelProperty: 1 }   // this node will be in the first level
}, 
{ 
  id: 'node2', 
  type: 'node',
  d: { levelProperty: 2 }   // this node will be in the subsequent level
}

chart.layout('sequential', { level: 'levelProperty' })
// puts node1 above node2 in the hierarchy

chart.layout(
  'sequential', {
    orderBy: { property: 'orderByProperty', sortBy: 'ascending' },
    stacking: { arrange: 'grid' },
})

See layout options for a full list of sequential layout options.