# Documentation

### This is machine translation

Translated by
Mouseover text to see original. Click the button below to return to the English version of the page.

# layout

Change layout of graph plot

## Syntax

``layout(H)``
``layout(H,method)``
``layout(H,method,Name,Value)``

## Description

example

````layout(H)` changes the layout of graph plot `H` by using an automatic choice of layout method based on the structure of the graph. The `layout` function modifies the `XData` and `YData` properties of `H`.```

example

````layout(H,method)` optionally specifies the layout method. `method` can be `'circle'`, `'force'`, `'layered'`, `'subspace'`, `'force3'`, or `'subspace3'`.```

example

````layout(H,method,Name,Value)` uses additional options specified by one or more Name-Value pair arguments. For example, `layout(H,'force','Iterations',N)` specifies the number of iterations to use in computing the force layout, and `layout(H,'layered','Sources',S)` uses a layered layout with source nodes `S` included in the first layer.```

## Examples

collapse all

Create and plot a graph using the `'force'` layout.

```s = [1 1 1 1 1 6 6 6 6 6]; t = [2 3 4 5 6 7 8 9 10 11]; G = graph(s,t); h = plot(G,'Layout','force');```

Change the layout to be the default that `plot` determines based on the structure and properties of the graph. The result is the same as using `plot(G)`.

`layout(h)`

Create and plot a graph using the `'layered'` layout.

```s = [1 1 1 2 2 3 3 4 5 5 6 7]; t = [2 4 5 3 6 4 7 8 6 8 7 8]; G = graph(s,t); h = plot(G,'Layout','layered');```

Change the layout of the graph to use the `'subspace'` method.

`layout(h,'subspace')`

Create and plot a graph using the `'layered'` layout method.

```s = [1 1 1 2 3 3 3 4 4]; t = [2 4 5 6 2 4 7 8 1]; G = digraph(s,t); h = plot(G,'Layout','layered');```

Use the `layout` function to refine the hierarchical layout by specifying source nodes and a horizontal orientation.

`layout(h,'layered','Direction','right','Sources',[1 4])`

## Input Arguments

collapse all

Input graph plot, specified as a `GraphPlot` object. Use the `graph` or `digraph` functions to create a graph, and then use `plot` with an output argument to return a `GraphPlot` object.

Example: `H = plot(G)`

Layout method, specified as one of the options in the table. The table also lists compatible Name-Value pairs to further refine each layout method.

OptionDescriptionName-Value Pairs
`'auto'` (default)

Automatic choice of layout method based on the size and structure of the graph.

`'circle'`

Circular layout. Places the graph nodes on a circle centered at the origin with radius 1.

`'force'`

Force-directed layout [1]. Uses attractive forces between adjacent nodes and repulsive forces between distant nodes.

`'Iterations'`

`'XStart'`

`'YStart'`

`'layered'`

Layered layout [2], [3], [4]. Places the graph nodes into a set of layers, revealing hierarchical structure. By default the layers progress downwards (the arrows of a directed acyclic graph point down).

`'Direction'`

`'Sources'`

`'Sinks'`

`'AssignLayers'`

`'subspace'`

Subspace embedding layout [5]. Plots the graph nodes in a high-dimensional embedded subspace, and then projects the positions back into 2-D. By default the subspace dimension is either 100 or the total number of nodes, whichever is smaller.

`'Dimension'`

`'force3'`3-D force-directed layout.

`'Iterations'`

`'XStart'`

`'YStart'`

`'ZStart'`

`'subspace3'`3-D subspace embedding layout.

`'Dimension'`

Example: `layout(H,'layered')`

Example: `layout(H,'force3','Iterations',10)`

Example: `layout(H,'subspace','Dimension',50)`

### Name-Value Pair Arguments

Specify optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside single quotes (`' '`). You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

Example: `layout(H,'subspace','Dimension',200)`

#### Force

collapse all

Number of force-directed layout iterations, specified as the comma-separated pair consisting of `'Iterations'` and a positive scalar integer.

This option is available only when `method` is `'force'` or `'force3'`.

Example: `layout(H,'force','Iterations',250)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Starting x-coordinates for nodes, specified as the comma-separated pair consisting of `'XStart'` and a vector of node coordinates. Use this option together with `'YStart'` to specify 2-D starting coordinates (or with `'YStart'` and `'ZStart'` to specify 3-D starting coordinates) before iterations of the force-directed algorithm change the node positions.

This option is available only when `method` is `'force'` or `'force3'`.

Example: `layout(H,'force','XStart',x,'YStart',y)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Starting y-coordinates for nodes, specified as the comma-separated pair consisting of `'YStart'` and a vector of node coordinates. Use this option together with `'XStart'` to specify 2-D starting coordinates (or with `'XStart'` and `'ZStart'` to specify 3-D starting coordinates) before iterations of the force-directed algorithm change the node positions.

This option is available only when `method` is `'force'` or `'force3'`.

Example: `layout(H,'force','XStart',x,'YStart',y)`

Example: `layout(H,'force','XStart',x,'YStart',y,'ZStart',z)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

Starting z-coordinates for nodes, specified as the comma-separated pair consisting of `'ZStart'` and a vector of node coordinates. Use this option together with `'XStart'` and `'YStart'` to specify the starting x, y, and z node coordinates before iterations of the force-directed algorithm change the node positions.

This option is available only when `method` is `'force3'`.

Example: `layout(H,'force','XStart',x,'YStart',y,'ZStart',z)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

#### Layered

collapse all

Direction of layers, specified as the comma-separated pair consisting of `'Direction'` and either `'down'`, `'up'`, `'left'` or `'right'`. For directed acyclic (DAG) graphs, the arrows point in the indicated direction.

This option is available only when `method` is `'layered'`.

Example: `layout(H,'layered','Direction','up')`

Nodes to include in first the layer, specified as the comma-separated pair consisting of `'Sources'` and either a vector of node indices or a cell array of character vectors containing node names.

This option is available only when `method` is `'layered'`.

Example: ```layout(H,'layered','Sources',[1 3 5])```

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `cell`

Nodes to include in the last layer, specified as the comma-separated pair consisting of `'Sinks'` and either a vector of node indices or a cell array of character vectors containing node names.

This option is available only when `method` is `'layered'`.

Example: ```layout(H,'layered','Sinks',[2 4 6])```

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64` | `cell`

Layer assignment method, specified as the comma-separated pair consisting of `'AssignLayers'` and one of the options in this table.

OptionDescription
`'auto'` (default)Node assignment uses either `'asap'` or `'alap'`, whichever is more compact.
`'asap'`As soon as possible. Each node is assigned to the first possible layer, given the constraint that all its predecessors must be in earlier layers.
`'alap'`As late as possible. Each node is assigned to the last possible layer, given the constraint that all its successors must be in later layers.

This option is available only when `method` is `'layered'`.

Example: `layout(H,'layered','AssignLayers','alap')`

#### Subspace

collapse all

Dimension of embedded subspace, specified as the comma-separated pair consisting of `'Dimension'` and a positive scalar integer.

• The default integer value is ```min([100, numnodes(G)])```.

• For the `'subspace'` layout, the integer must be greater than or equal to 2.

• For the `'subspace3'` layout, the integer must be greater than or equal to 3.

• In both cases, the integer must be less than the number of nodes.

This option is available only when `method` is `'subspace'` or `'subspace3'`.

Example: `layout(H,'subspace','Dimension',d)`

Data Types: `single` | `double` | `int8` | `int16` | `int32` | `int64` | `uint8` | `uint16` | `uint32` | `uint64`

## Tips

• Use the `Layout` name-value pair to change the layout of a graph when you plot it. For example, `plot(G,'Layout','circle')` plots the graph `G` with a circular layout.

• When using the `'force'` or `'force3'` layout methods, a best practice is to use more iterations with the algorithm instead of using `XStart`, `YStart`, and `ZStart` to restart the algorithm using previous outputs. The result of executing the algorithm with 100 iterations is different in comparison to executing 50 iterations, and then restarting the algorithm from the ending positions to execute 50 more iterations.

## References

[1] Fruchterman, T., and E. Reingold,. “Graph Drawing by Force-directed Placement.” Software — Practice & Experience. Vol. 21 (11), 1991, pp. 1129–1164.

[2] Gansner, E., E. Koutsofios, S. North, and K.-P Vo. “A Technique for Drawing Directed Graphs.” IEEE Transactions on Software Engineering. Vol.19, 1993, pp. 214–230.

[3] Barth, W., M. Juenger, and P. Mutzel. “Simple and Efficient Bilayer Cross Counting.” Journal of Graph Algorithms and Applications. Vol.8 (2), 2004, pp. 179–194.

[4] Brandes, U., and B. Koepf. “Fast and Simple Horizontal Coordinate Assignment.” LNCS. Vol. 2265, 2002, pp. 31–44.

[5] Y. Koren. “Drawing Graphs by Eigenvectors: Theory and Practice.” Computers and Mathematics with Applications. Vol. 49, 2005, pp. 1867–1888.