TreeMapLayout

This layout algorithm produces tree map layouts.

Inheritance Hierarchy

TreeMapLayout

Implemented Interfaces

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:

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.
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

minimumNodeSize	Size	Minimum width and height are `10.0`.
preferredSize	Size	Preferred width and height are `600`.
spacing	`5`
tilingStrategy	SQUARIFIED

Type Details

yFiles module: algorithms

If the range of the provided weights is large, i.e., a large difference between the minimum and maximum weight value, then the resulting tree map might become really large, making readability bad. The reason is that the relative weight differences need to be considered while still satisfying the minimumNodeSize for the nodes with low weight. A solution would be to scale/interpolate the weight values before running the layout.

Due to padding specified at parent nodes of different hierarchies and the inter-node padding defined by the spacing, nodes that have the same actual weight can get slightly different sizes - especially if they are on different hierarchy levels. This is necessary to satisfy the specified distances and padding. If exact same sizes throughout hierarchies is a requirement, set the spacing to 0 and do not specify padding for the group nodes that have children (if input is specified as grouping structure).

Edges are generally not routed by this layout algorithm. If there are any, their paths will be reset such that they become straight lines. If defining the input as a tree graph, edges can be removed after the layout run to get a clean tree map drawing without any edges across the map. If defining the input via grouping, no edges are necessary whatsoever.

This layout algorithm does not consider margins assigned to nodes.

Constructors

TreeMapLayout

()

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

ParametersOptions Overload

options - Object
A map of options to pass to the method.

tilingStrategy - TilingStrategy: The TilingStrategy that defines how the input is divided into sub-rectangles. This option sets the tilingStrategy property on the created object.
minimumNodeSize - Size: The minimum size (height and width) a node in the tree map must have. This option sets the minimumNodeSize property on the created object.
preferredSize - Size: The desired dimension of the root rectangle into which all nodes are placed. This option sets the preferredSize property on the created object.
aspectRatio - number: The target aspect ratio of the SQUARIFIED tiling strategy. This option sets the aspectRatio property on the created object.
spacing - number: The spacing between nodes of the same hierarchy. This option sets the spacing property on the created object.

Properties

aspectRatio

: number

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

Remarks

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.

Default Value

The default value is 1.

The target is to draw square nodes.

Property Value

the target aspect ratio for the squarified tiling strategy

Throws

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

minimumNodeSize

: Size

Gets or sets the minimum size (height and width) a node in the tree map must have.

Remarks

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.

Default Value

The default value is Size.

Minimum width and height are 10.0.

Property Value

the minimum node size

Throws

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

preferredSize

: Size

Gets or sets the desired dimension of the root rectangle into which all nodes are placed.

Remarks

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.

Default Value

The default value is Size.

Preferred width and height are 600.

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

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.

spacing

: number

Gets or sets the spacing between nodes of the same hierarchy.

Remarks

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.

Default Value

The default value is 5.

Property Value

the non-negative spacing between nodes

Throws

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

Sample Graphs

tilingStrategy

: TilingStrategy

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

Default Value

The default value is SQUARIFIED.

Property Value

The tiling strategy

Methods

applyLayout

(graph: LayoutGraph)

Arranges the given input graph as a tree map.

Remarks

To create meaningful tree maps, the graph should either contain hierarchical grouping information or be a tree graph that defines the hierarchy.

Parameters

options - Object
A map of options to pass to the method.

graph - LayoutGraph: the input graph

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.

Implements

ILayoutAlgorithm

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.

Remarks

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

options - Object
A map of options to pass to the method.

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

Returns

↪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.

Remarks

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.

Parameters

options - Object
A map of options to pass to the method.

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

Returns

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

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.

Constants

NODE_WEIGHT_DATA_KEY

: NodeDataKey<number>

A data key for specifying the weight of the nodes.

Remarks

The weight of a node defines the area assigned to the node inside the available parent area with respect to the other child nodes. Child nodes with the same weight get the same area, they do not necessarily get equal width and height values.

All leaf nodes (nodes without further children, including empty group nodes) must have a weight greater than 0. Non-leaf nodes do not need to have a weight. They will basically get the sum of the weight of their children. If they have a weight on their own, some free space is generated inside the representative rectangle (i.e. the parent node is larger than the combined children).

TreeMapLayout

Remarks

Layout Style

Concept

Features

Default Values of Properties

Type Details

Constructors

TreeMapLayout

ParametersOptions Overload

Properties

aspectRatio

Remarks

Default Value

Property Value

Throws

See Also

minimumNodeSize

Remarks

Default Value

Property Value

Throws

preferredSize

Remarks

Default Value

Property Value

Throws

spacing

Remarks

Default Value

Property Value

Throws

Sample Graphs

tilingStrategy

Default Value

Property Value

Methods

applyLayout

Remarks

Parameters

Implements

createLayoutData

Remarks

Parameters

Returns

createLayoutData

Remarks

Parameters

Returns

Constants

NODE_WEIGHT_DATA_KEY

Remarks

See Also