C

TreeMapLayout

Show Usages
This layout algorithm produces tree map layouts.
ImplementsInheritance Hierarchy

Remarks

Layout Style

Tree maps are suitable to visualize hierarchical data structures. They use nested rectangles to do so, where the size of the rectangles encodes its weight. More generally, the area of a rectangle is proportional to a specific dimension of data associated with it.

Tree maps can, for example, be used to show a file structure on a hard disk, where the dimension of data is the size of the files/folders. There are many other use cases where the tree map can show the distribution of the dimension of data among the entities in a hierarchy.

A tree map with four different sub-groups - node labels define the weight; note that there are no edges in a tree map

Concept

TreeMapLayout offers implementations of the well-known treemapping algorithms Slice-and-Dice and SQUARIFIED. These tiling strategies divide a rectangle with a given size into multiple sub-rectangles. Speaking in terms of graphs, this means that nodes are placed in a nested fashion such that child nodes are placed inside the parent node.

Importantly, node sizes are changed by this layout algorithm to show the proportional weight of a node in the map. The weight is specified via layout data property nodeWeights.

Features

The input can be specified in two ways:

  1. As a hierarchical grouping structure that defines the nesting. Note that for group nodes, the specified padding are considered (see GROUP_NODE_PADDING_DATA_KEY). If the graph is a tree graph, then the grouping structure is ignored - see second input variant. To continue using the hierarchy information of the grouping structure on a tree graph, one can temporarily hide the tree edges before running the layout.
  2. As a directed tree graph. The parent-child relation is directly taken from the graph's tree structure. If the graph also contains group nodes, the hierarchy relation induced by them is ignored. If necessary, an undirected tree can be (temporarily) directed prior to the layout run by using makeTreeDirected. The tree needs to be directed from the root (top-level hierarchy) to the children (lower-level hierarchies). Note that a forest graph is no valid input.

The offered tiling strategies produce drawings with a quite different style. SLICE_AND_DICE offers results that have a stable, clear ordering but the rectangles have a high aspect ratio. On the other hand, SQUARIFIED tries to create rectangles close to a given aspect ratio - in consequence, the ordering of neighbor nodes might not be clearly predictable.

Default Values of Properties

NameDefaultDescription
minimumNodeSizeSize
Minimum width and height are 10.0.
preferredSizeSize
Preferred width and height are 600.
spacing5
tilingStrategyTilingStrategy.SQUARIFIED

See Also

Developer's Guide

Members

Show:

Constructors

TreeMapLayout

()
Initializes a new instance of the TreeMapLayout class with default settings.

Parameters

Properties

aspectRatio

: number
Gets or sets the target aspect ratio of the SQUARIFIED tiling strategy.

The aspect ratio must be greater than or equal to 1. A ratio of 1 means that the node rectangles should ideally be squares. The orientation of the rectangles does not matter. For example, a ratio of 2 means that rectangles with an aspect ratio of 1:2 or also 2:1 are desired.

This setting affects the ratio of a single node rectangle. To create a tree map with a certain overall aspect ratio, the preferredSize can be specified accordingly.

This setting only has an effect if SQUARIFIED is specified as tilingStrategy.
final

Property Value

the target aspect ratio for the squarified tiling strategy

Throws

Exception ({ name: 'ArgumentError' })
if the given aspect ratio is smaller than 1

Default Value

The default value is: 1
The target is to draw square nodes.

See Also

Developer's Guide
API
SQUARIFIED

minimumNodeSize

: Size
Gets or sets the minimum size (height and width) a node in the tree map must have.
If the weight data induces that a node would get a width/height smaller than specified by the minimum size to fit into the preferredSize, then the output size will be increased until all nodes fulfill the minimum size requirement. This scenario will mostly occur if the weights of nodes have a large range or if the specified preferred output size is small.
conversionfinal

Property Value

the minimum node size

Throws

Exception ({ name: 'ArgumentError' })
if the width or height of the given size is smaller than 5

Default Value

The default value is: Size
Minimum width and height are 10.0.

See Also

Developer's Guide

preferredSize

: Size
Gets or sets the desired dimension of the root rectangle into which all nodes are placed.
If it is possible to arrange all nodes such that they fit into the preferred size, then the final result will exactly have this size. However, satisfying the specified spacing and minimumNodeSize has higher priority. This means that the final output might become larger if necessary. On the other hand, it will never be smaller, even if it would be possible to generate a smaller result.
It is a good idea to specify a rather large size in the first place, except when having only a really small diagram. Otherwise, a valid size needs to be computed iteratively to satisfy minimum node width/height.
conversionfinal

Property Value

the preferred size of the root rectangle

Throws

Exception ({ name: 'ArgumentError' })
if width/height value of the given size is less than or equal to zero

Default Value

The default value is: Size
Preferred width and height are 600.

See Also

Developer's Guide

spacing

: number
Gets or sets the spacing between nodes of the same hierarchy.
This spacing enables to insert a padding between all nodes/rectangles on the same hierarchy. It is not inserted between a group node (border) and its children - use group node padding for that use case.
final

Property Value

the non-negative spacing between nodes

Throws

Exception ({ name: 'ArgumentError' })
if the given spacing is negative

Default Value

The default value is: 5

Sample Graphs

ShownSetting: Spacing 5

See Also

Developer's Guide

tilingStrategy

: TilingStrategy
Gets or sets the TilingStrategy that defines how the input is divided into sub-rectangles.
conversionfinal

Property Value

The tiling strategy

Default Value

The default value is: TilingStrategy.SQUARIFIED

See Also

Developer's Guide

Methods

applyLayout

(graph: LayoutGraph)
Arranges the given input graph as a tree map.
To create meaningful tree maps, the graph should either contain hierarchical grouping information or be a tree graph that defines the hierarchy.
The given graph will not be copied during the layout process and the layout will be immediately applied to the given graph. Node sizes will be changed to create the tree map layout.

Parameters

graph: LayoutGraph
the input graph

createLayoutData

(graph: LayoutGraph): TreeMapLayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
Returns an instance of LayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel> that can be used to perform item-specific configurations for the TreeMapLayout.
The generic type arguments of the created layout data are compatible with instances of LayoutGraph, but the layout data is not bound to a specific graph instance. Therefore, the created layout data still has to be passed as an argument of applyLayout in order to be applied.

Parameters

graph: LayoutGraph
the graph that determines the generic type arguments of the created layout data

Return Value

TreeMapLayoutData<LayoutNode, LayoutEdge, LayoutNodeLabel, LayoutEdgeLabel>
an instance of layout data that can be used to perform item-specific configurations for the given TreeMapLayout.

createLayoutData

(graph?: IGraph): TreeMapLayoutData<INode, IEdge, ILabel, ILabel>
Returns an instance of LayoutData<TNode, TEdge, TNodeLabel, TEdgeLabel> that can be used to perform item-specific configurations for the TreeMapLayout.
The generic type arguments of the created layout data are compatible with instances of IGraph, but the layout data is not bound to a specific graph instance. Therefore, the created layout data still has to be passed as an argument of applyLayout in order to be applied.
This method is not available unless the module view-layout-bridge is loaded. Either load the module 'view-layout-bridge' explicitly or ensure that the LayoutExecutor type is available at runtime.

Parameters

graph?: IGraph
the graph that determines the generic type arguments of the created layout data

Return Value

TreeMapLayoutData<INode, IEdge, ILabel, ILabel>
an instance of layout data that can be used to perform item-specific configurations for the given TreeMapLayout.

See Also

Developer's Guide

Constants

All constants are filtered. Go to Filters.