Main Content

layoutcoords

Graph node and edge layout coordinates

Since R2024b

collapse all in page

Syntax

nodeCoords = layoutcoords(G)
[nodeCoords,edgeCoords] = layoutcoords(G)
[___] = layoutcoords(G,method)
[___] = layoutcoords(G,method,Name=Value)

Description

nodeCoords = layoutcoords(G) calculates the coordinates of the nodes of graph G using an automatic choice of layout method based on the structure of the graph.

example

[nodeCoords,edgeCoords] = layoutcoords(G) also calculates the coordinates of the graph edges.

example

[___] = layoutcoords(G,method) optionally specifies the layout method. method can be "auto", "circle", "force", "layered", "subspace", "force3", or "subspace3".

example

[___] = layoutcoords(G,method,Name=Value) specifies additional options using one or more name-value arguments. Which name-value arguments are supported depends on the choice of layout method. For example, layoutcoords(G,"force",Iterations=N) specifies the number of iterations to use in computing the force layout, and layoutcoords(G,"layered",Sources=S) uses a layered layout with source nodes S included in the first layer.

example

Examples

collapse all

Open Live Script

Create a graph with eight nodes and twelve edges.

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)
G = 
  graph with properties:

    Edges: [12x1 table]
    Nodes: [8x0 table]

Calculate the coordinates of the nodes and edges using an automatic choice of layout method.

[nodeCoords, edgeCoords] = layoutcoords(G)
nodeCoords = 8×2

   -0.0495   -2.0789
   -0.0119   -0.5215
   -1.5285    0.8917
   -1.5694   -0.8184
    1.5285   -0.8917
    1.5694    0.8184
    0.0495    2.0789
    0.0119    0.5215


edgeCoords=12×1 cell array
    {2x2 double}
    {2x2 double}
    {2x2 double}
    {2x2 double}
    {2x2 double}
    {2x2 double}
    {2x2 double}
    {2x2 double}
    {2x2 double}
    {2x2 double}
    {2x2 double}
    {2x2 double}
Open Live Script

Create a graph with 10 nodes and 12 edges.

s = [1 1 1 1 1 1 1 1 4 1 9 8];
t = [2 3 4 5 6 7 8 9 10 10 10 9];
g = graph(s,t)
g = 
  graph with properties:

    Edges: [12x1 table]
    Nodes: [10x0 table]

Calculate the coordinates of the nodes and edges using a layered layout method. Specify Sources=1 to use the first node in the first layer.

[nodeCoords, edgeCoords] = layoutcoords(g,"layered",Sources=1)
nodeCoords = 10×2

    5.0000    5.0000
    1.0000    4.0000
    2.0000    4.0000
    4.0000    4.0000
    7.0000    4.0000
    8.0000    4.0000
    9.0000    4.0000
    4.5000    1.0000
    5.0000    2.0000
    4.5000    3.0000


edgeCoords=12×1 cell array
    { 2x2 double}
    { 2x2 double}
    { 2x2 double}
    { 2x2 double}
    { 2x2 double}
    { 2x2 double}
    {41x2 double}
    {31x2 double}
    {21x2 double}
    { 2x2 double}
    { 2x2 double}
    { 2x2 double}

Plot the graph nodes and edges using the coordinates in nodeCoords and edgeCoords. Use a for-loop to plot the entries in edgeCoords one at a time.

xn = nodeCoords(:,1);
yn = nodeCoords(:,2);
plot(xn,yn,"bo","MarkerFaceColor","b")
hold on
for k = 1:numedges(g)
    e = edgeCoords{k};
    plot(e(:,1),e(:,2),"r-")
end
hold off

Figure contains an axes object. The axes object contains 13 objects of type line. One or more of the lines displays its values using only markers

Input Arguments

collapse all

Input graph, specified as either a graph or digraph object. Use graph to create an undirected graph or digraph to create a directed graph.

Example: G = graph(1,2)

Example: G = digraph([1 2],[2 3])

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.

OptionDescriptionLayout-Specific Name-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.

"Center" — Center node in circular layout

"force"

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

"Iterations" — Number of force-directed layout iterations

"WeightEffect" — Effect of edge weights on layout

"UseGravity" — Gravity toggle for layouts with multiple components

"XStart" — Starting x-coordinates for nodes

"YStart" — Starting y-coordinates for nodes

"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" — Direction of layers

"Sources" — Nodes to include in the first layer

"Sinks" — Nodes to include in the last layer

"AssignLayers" — Layer assignment method

"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" — Dimension of embedded subspace

"force3"3-D force-directed layout.

"Iterations" — Number of force-directed layout iterations

"WeightEffect" — Effect of edge weights on layout

"UseGravity" — Gravity toggle for layouts with multiple components

"XStart" — Starting x-coordinates for nodes

"YStart" — Starting y-coordinates for nodes

"ZStart" — Starting z-coordinates for nodes

"subspace3"3-D subspace embedding layout.

"Dimension" — Dimension of embedded subspace

Example: layoutcoords(G,"layered")

Example: layoutcoords(G,"force3","Iterations",10)

Example: layoutcoords(G,"subspace","Dimension",50)

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: layoutcoords(G,"subspace","Dimension",200)

Force/Force3

collapse all

Number of force-directed layout iterations, specified as a positive scalar integer.

This option is available only when method is "force" or "force3".

Example: layoutcoords(G,"force",Iterations=250)

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

Effect of edge weights on layout, specified as one of the values in this table. If there are multiple edges between two nodes (as in a directed graph with an edge in each direction, or a multigraph), then the weights are summed before computing WeightEffect.

This option is available only when method is "force" or "force3".

Value

Description

"none" (default)

Edge weights do not affect the layout.

"direct"

Edge length is proportional to the edge weight, G.Edges.Weight. Larger edge weights produce longer edges.

"inverse"

Edge length is inversely proportional to the edge weight, 1./G.Edges.Weight. Larger edge weights produce shorter edges.

Example: layoutcoords(G,"force",WeightEffect="inverse")

Gravity toggle for layouts with multiple components, specified as either "off", "on", true, or false. A value of "on" is equivalent to true, and "off" is equivalent to false.

By default, MATLAB® lays out graphs with multiple components on a grid. The grid can obscure the details of larger components since they are given the same amount of space as smaller components. With UseGravity set to "on" or true, multiple components are instead laid out radially around the origin. This layout spreads out the components in a more natural way, and provides more space for larger components.

This option is available only when method is "force" or "force3".

Example: layoutcoords(G,"force",UseGravity=true)

Data Types: char | logical

Starting x-coordinates for nodes, specified as 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: layoutcoords(G,"force",XStart=x,YStart=y)

Example: layoutcoords(G,"force3",XStart=x,YStart=y,ZStart=z)

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

Starting y-coordinates for nodes, specified as 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: layoutcoords(G,"force",XStart=x,YStart=y)

Example: layoutcoords(G,"force3",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 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: layoutcoords(G,"force3",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 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: layoutcoords(G,"layered",Direction="up")

Nodes to include in the first layer, specified as one or more node indices or node names.

This table shows the different ways to refer to one or more nodes either by their numeric node indices or by their node names.

FormSingle NodeMultiple Nodes
Node index

Scalar

Example: 1

Vector

Example: [1 2 3]

Node name

Character vector

Example: 'A'

Cell array of character vectors

Example: {'A' 'B' 'C'}

String scalar

Example: "A"

String array

Example: ["A" "B" "C"]

This option is available only when method is "layered".

Example: layoutcoords(G,"layered",Sources=[1 3 5])

Nodes to include in the last layer, specified as one or more node indices or node names.

This option is available only when method is "layered".

Example: layoutcoords(G,"layered",Sinks=[2 4 6])

Layer assignment method, specified as 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: layoutcoords(G,"layered",AssignLayers="alap")

Subspace/Subspace3

collapse all

Dimension of embedded subspace, specified as 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: layoutcoords(G,"subspace",Dimension=d)

Example: layoutcoords(G,"subspace3",Dimension=d)

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

Circle

collapse all

Center node in circular layout, specified as one of the values in this table.

ValueExample
Scalar node index1
Character vector node name'A'
String scalar node name"A"

This option is available only when method is "circle".

Example: layoutcoords(G,"circle",Center=3) places node three at the center.

Example: layoutcoords(G,"circle",Center="Node1") places the node named "Node1" at the center.

Output Arguments

collapse all

Node layout coordinates, returned as a matrix with a number of rows equal to numnodes(G). For 2-D layouts the matrix has two columns, while for 3-D layouts the matrix has three columns. Each row of the matrix gives the x-, y-, and optionally z-coordinates of each node in the layout.

Edge layout coordinates, returned as a cell array of size numedges(G)-by-1. Each element of the cell array contains a matrix giving the x-, y-, and optionally z-coordinates of each point on the edge. Each edge has at least two points.

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.

Version History

Introduced in R2024b

See Also

Functions

Objects

Topics