digraph

Create directed graph

collapse all in page

Syntax

  • G = digraph(s,t)
    example
  • G = digraph(s,t,weights)
    example
  • G = digraph(s,t,weights,nodenames)
    example
  • G = digraph(s,t,weights,num)
    example
  • G = digraph(s,t,___,'OmitSelfLoops')
  • G = digraph(EdgeTable)
    example
  • G = digraph(EdgeTable,NodeTable)
    example
  • G = digraph(EdgeTable,___,'OmitSelfLoops')

Description

example

G = digraph creates an empty directed graph object, G, which has no nodes or edges.

example

G = digraph(A) creates a weighted directed graph using a square adjacency matrix, A. The location of each nonzero entry in A specifies an edge for the graph, and the weight of the edge is equal to the value of the entry. For example, if A(2,1) = 10, then G contains an edge from node 2 to node 1 with a weight of 10.

example

G = digraph(A,nodenames) additionally specifies node names using the cell array of character vectors, nodenames. The number of elements in nodenames must be equal to size(A,1).

example

G = digraph(A,___,'OmitSelfLoops') ignores the diagonal elements of A and returns a graph without any self-loops. You must specify A, and optionally can specify nodenames.

example

G = digraph(s,t) specifies directed graph edges (s,t) in pairs to represent the source and target nodes. s and t can be numeric, character vectors, or cell arrays of character vectors with the same number of elements.

example

G = digraph(s,t,weights) also specifies edge weights with the array, weights.

example

G = digraph(s,t,weights,nodenames) additionally specifies all node names using the cell array of character vectors, nodenames. The s and t inputs cannot contain node names that are not in nodenames.

example

G = digraph(s,t,weights,num) specifies the number of nodes in the graph with the numeric scalar num.

G = digraph(s,t,___,'OmitSelfLoops') does not add any self-loops to the graph. That is, any k that satisfies s(k) == t(k) is ignored. You must specify s and t and optionally can specify weights, nodenames, or num.

example

G = digraph(EdgeTable) uses the table, EdgeTable, to define the graph. The first variable in EdgeTable must be EndNodes, and it must be a two-column array defining the edge list of the graph. EdgeTable can contain any number of other table variables to define attributes of the graph edges.

example

G = digraph(EdgeTable,NodeTable) additionally uses the table, NodeTable, to define attributes of the graph nodes. NodeTable can contain any number of table variables to define attributes of the graph nodes.

G = digraph(EdgeTable,___,'OmitSelfLoops') does not add self-loops to the graph. That is, any k that satisfies EdgeTable.EndNodes(k,1) == EdgeTable.EndNodes(k,2) is ignored. You must specify EdgeTable and optionally can specify NodeTable.

Examples

collapse all

Open Script

Create a symmetric adjacency matrix, A, that creates a complete directed graph of order 4. Use a logical adjacency matrix to create a graph without weights.

A = ones(4) - diag([1 1 1 1])

A =

     0     1     1     1
     1     0     1     1
     1     1     0     1
     1     1     1     0


G = digraph(A~=0)

G = 

  digraph with properties:

    Edges: [12×1 table]
    Nodes: [4×0 table]

View the edge list of the graph.

G.Edges

ans = 

    EndNodes
    ________

    1    2  
    1    3  
    1    4  
    2    1  
    2    3  
    2    4  
    3    1  
    3    2  
    3    4  
    4    1  
    4    2  
    4    3
Open Script

Create an adjacency matrix.

A = magic(4);
A(A>10) = 0

A =

     0     2     3     0
     5     0    10     8
     9     7     6     0
     4     0     0     1

Create a graph with named nodes using the adjacency matrix. Specify 'OmitSelfLoops' to ignore the entries on the diagonal of A.

names = {'alpha' 'beta' 'gamma' 'delta'};
G = digraph(A,names,'OmitSelfLoops')

G = 

  digraph with properties:

    Edges: [8×2 table]
    Nodes: [4×1 table]

View the edge and node information.

G.Edges

ans = 

         EndNodes         Weight
    __________________    ______

    'alpha'    'beta'      2    
    'alpha'    'gamma'     3    
    'beta'     'alpha'     5    
    'beta'     'gamma'    10    
    'beta'     'delta'     8    
    'gamma'    'alpha'     9    
    'gamma'    'beta'      7    
    'delta'    'alpha'     4    


G.Nodes

ans = 

     Name  
    _______

    'alpha'
    'beta' 
    'gamma'
    'delta'
Open Script

Create and plot a cube graph using a list of the end nodes of each edge.

s = [1 1 1 2 2 3 3 4 5 5 6 7];
t = [2 4 8 3 7 4 6 5 6 8 7 8];
G = digraph(s,t)

G = 

  digraph with properties:

    Edges: [12×1 table]
    Nodes: [8×0 table]


plot(G,'Layout','force')

Open Script

Create and plot a cube graph using a list of the end nodes of each edge. Specify node names and edge weights as separate inputs.

s = [1 1 1 2 2 3 3 4 5 5 6 7];
t = [2 4 8 3 7 4 6 5 6 8 7 8];
weights = [10 10 1 10 1 10 1 1 12 12 12 12];
names = {'A' 'B' 'C' 'D' 'E' 'F' 'G' 'H'};
G = digraph(s,t,weights,names)

G = 

  digraph with properties:

    Edges: [12×2 table]
    Nodes: [8×1 table]


plot(G,'Layout','force','EdgeLabel',G.Edges.Weight)

Open Script

Create a weighted graph using a list of the end nodes of each edge. Specify that the graph should contain a total of 10 nodes.

s = [1 1 1 1 1];
t = [2 3 4 5 6];
weights = [5 5 5 6 9];
G = digraph(s,t,weights,10)

G = 

  digraph with properties:

    Edges: [5×2 table]
    Nodes: [10×0 table]

Plot the graph. The extra nodes are disconnected from the primary connected component.

plot(G)

Open Script

Create an empty digraph object, G.

G = digraph;

Add three nodes and three edges to the graph. The corresponding entries in s and t define the source and target nodes of the edges. addedge automatically adds the appropriate nodes to the graph if they are not already present.

s = [1 2 1];
t = [2 3 3];
G = addedge(G,s,t)

G = 

  digraph with properties:

    Edges: [3×1 table]
    Nodes: [3×0 table]

View the edge list. Each row describes an edge in the graph.

G.Edges

ans = 

    EndNodes
    ________

    1    2  
    1    3  
    2    3

For the best performance, construct graphs all at once using a single call to digraph. Adding nodes or edges in a loop can be slow for large graphs.

Open Script

Create an edge table that contains the variables EndNodes, Weight, and Code. Then create a node table that contains the variables Name and Country. The variables in each table specify properties of the graph nodes and edges.

s = [1 1 1 2 2 3];
t = [2 3 4 3 4 4];
weights = [6 6.5 7 11.5 12 17]';
code = {'1/44' '1/49' '1/33' '44/49' '44/33' '49/33'}';
EdgeTable = table([s' t'],weights,code, ...
    'VariableNames',{'EndNodes' 'Weight' 'Code'})

EdgeTable = 

    EndNodes    Weight     Code  
    ________    ______    _______

    1    2         6      '1/44' 
    1    3       6.5      '1/49' 
    1    4         7      '1/33' 
    2    3      11.5      '44/49'
    2    4        12      '44/33'
    3    4        17      '49/33'


names = {'USA' 'GBR' 'DEU' 'FRA'}';
country_code = {'1' '44' '49' '33'}';
NodeTable = table(names,country_code,'VariableNames',{'Name' 'Country'})

NodeTable = 

    Name     Country
    _____    _______

    'USA'    '1'    
    'GBR'    '44'   
    'DEU'    '49'   
    'FRA'    '33'

Create a graph using the node and edge tables. Plot the graph using the country codes as node and edge labels.

G = digraph(EdgeTable,NodeTable);
plot(G,'NodeLabel',G.Nodes.Country,'EdgeLabel',G.Edges.Code)

Related Examples

Input Arguments

collapse all

Adjacency matrix, specified as a full or sparse, numeric matrix. The entries in A specify the network of connections (edges) between the nodes of the graph. The location of each nonzero entry in A specifies an edge between two nodes. The value of that entry provides the edge weight. A logical adjacency matrix results in an unweighted graph.

Nonzero entries on the main diagonal of A specify self-loops, or nodes that are connected to themselves with an edge. Use the 'OmitSelfLoops' input option to ignore diagonal entries.

Example: A = [0 1 0; 0 0 0; 5 0 0] describes a graph with three nodes and two edges. The edge from node 1 to node 2 has a weight of 1, and the edge from node 3 to node 1 has a weight of 5.

Data Types: single | double | logical

Node names, specified as a cell array of character vectors. nodenames must contain a nonempty, unique name for each node in the graph (its length must be equal to numnodes(G)).

Example: G = digraph(A,{'n1','n2','n3'}) specifies three node names for a 3-by-3 adjacency matrix, A.

Data Types: cell

Source and target node pairs, specified as scalars, vectors, matrices, multidimensional arrays, character vectors, or cell arrays of character vectors. digraph creates directed edges between the corresponding nodes in s and t, which must both be numeric, or both be character vectors or cell arrays of character vectors. In each case, s and t must have the same number of elements.

  • If s and t are numeric, then they correspond to indices of graph nodes. Numeric node indices must be positive integers greater than or equal to 1.

  • If s and t are character vectors or cell arrays of character vectors, then they specify names for the nodes. The Nodes property of the graph is a table containing a Name variable with the node names, G.Nodes.Name.

  • s and t cannot specify duplicate edges. For directed graphs, digraph([1 2],[2 1]) specifies two unique edges, but digraph([1 1],[2 2]) specifies a duplicate edge with node 1 as the source and node 2 as the target.

Example: G = digraph([1 2 3],[2 4 5]) creates a graph with five nodes and three edges.

Example: G = digraph({'Boston' 'New York' 'Washington D.C.'},{'New York' 'New Jersey' 'Pittsburgh'}) creates a graph with five named nodes and three edges.

Edge weights, specified as a scalar, vector, matrix, or multidimensional array. weights can be a scalar or an array with the same number of elements as s and t.

digraph stores the edge weights as a Weight variable in the G.Edges property table. To add or change weights after creating a graph, you can modify the table variable directly, for example, G.Edges.Weight = [25 50 75]'.

Example: G = digraph([1 2],[2 3],[100 200]) creates a graph with three nodes and two edges. The edges have weights of 100 and 200.

Data Types: single | double

Number of graph nodes, specified as a positive scalar integer. num must be greater than or equal to the largest elements in s and t.

Example: G = digraph([1 2],[2 3],[],5) creates a graph with three connected nodes and two isolated nodes.

Table of edge information. The first variable in EdgeTable is required to be a two-column matrix called EndNodes, but you can have any number of other variables to describe attributes of the graph edges. For edge weights, use the variable Weight, since this table variable name is used by some graph functions. If there is a variable Weight, then it must be a numeric column vector. See table for more information on constructing a table.

After creating a graph, query the edge information table using G.Edges.

Example: EdgeTable = table([1 2; 2 3; 3 5; 4 5],'VariableNames',{'EndNodes'})

Data Types: table

Table of node information. NodeTable can contain any number of variables to describe attributes of the graph nodes. For node names, use the variable Name, since this variable name is used by some graph functions. If there is a variable Name, then it must be a column cell array of nonempty, unique character vectors. See table for more information on constructing a table.

After the graph is created, query the node information table using G.Nodes.

Example: NodeTable = table({'a'; 'b'; 'c'; 'd'},'VariableNames',{'Name'})

Data Types: table

Output Arguments

collapse all

Directed graph, returned as a digraph object. For more information, see digraph.

More About

See Also

Introduced in R2015b

Was this topic helpful?
MATLAB Documentation
Other Documentation
Support