addedge

Add new edge to graph

Syntax

H = addedge(G,s,t)

H = addedge(G,s,t,w)

H = addedge(G,s,t,EdgeTable)

H = addedge(G,EdgeTable)

Description

H = addedge(G,s,t) adds an edge to graph G between nodes s and t. If a node specified by s or t is not present in G, then that node is added. The new graph, H, is equivalent to G, but includes the new edge and any required new nodes.

H = addedge(G,s,t,w) also specifies weights, w, for the edges between s and t.

H = addedge(G,s,t,EdgeTable) adds edges between the nodes s and t with attributes specified by the table, EdgeTable.

H = addedge(G,EdgeTable) adds edges with attributes specified by the table, EdgeTable. The EdgeTable input must be able to be concatenated with G.Edges.

Examples

Add Edges to Graph

Add two new edges to an existing graph. Since one of the new edges references a node that does not exist, addedge automatically adds the required fourth node to the graph.

G = graph([1 2],[2 3])

G = 
  graph with properties:

    Edges: [2x1 table]
    Nodes: [3x0 table]

G = addedge(G,[2 1],[4 3])

G = 
  graph with properties:

    Edges: [4x1 table]
    Nodes: [4x0 table]

Add Weighted Edges to Graph

Create a directed graph with weighted edges.

G = digraph({'A' 'B' 'C'}, {'D' 'C' 'D'}, [10 20 45])

G = 
  digraph with properties:

    Edges: [3x2 table]
    Nodes: [4x1 table]

Add three new weighted edges to the graph. addedge also automatically adds any required new nodes to the graph.

G = addedge(G, {'A' 'D' 'E'}, {'E' 'B' 'D'}, [5 30 5])

G = 
  digraph with properties:

    Edges: [6x2 table]
    Nodes: [5x1 table]

Add Edges with Attributes to Graph

Create a graph whose edges have the attributes Weight and Power. Use an edge table to create the graph.

EdgeTable = table([1 2; 2 3; 2 4; 2 5; 5 6; 5 7; 5 8], ...
    {'on','off','off','on','on','on','off'}',[10 20 20 10 10 10 20]', ...
    'VariableNames',{'EndNodes','Power','Weight'});
G = graph(EdgeTable)

G = 
  graph with properties:

    Edges: [7x3 table]
    Nodes: [8x0 table]

Add two new edges to the graph by creating a smaller table that can be concatenated to G.Edges. Note that this smaller table must use the same order of variables as G.Edges.

NewEdges = table([5 9; 3 6], {'on' 'off'}', [10 20]', ...
    'VariableNames',{'EndNodes','Power','Weight'});
G = addedge(G,NewEdges)

G = 
  graph with properties:

    Edges: [9x3 table]
    Nodes: [9x0 table]

View the new edge list of the graph, which includes the added edges.

G.Edges

ans=9×3 table
    EndNodes    Power    Weight
    ________    _____    ______

     1    2     'on'       10  
     2    3     'off'      20  
     2    4     'off'      20  
     2    5     'on'       10  
     3    6     'off'      20  
     5    6     'on'       10  
     5    7     'on'       10  
     5    8     'off'      20  
     5    9     'on'       10  

Input Arguments

G — Input graph

graph object | digraph object

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])

s,t — Node pairs (as separate arguments)

node indices | node names

Node pairs, specified as separate arguments of node indices or node names. Similarly located elements in s and t specify the source and target nodes for edges in the graph.

If you add edges using node names that are not already present in the graph, then addedge adds the new node names to the bottom of the g.Nodes.Name table. If s and t are categorical arrays, then the categories of s and t are used as node names. This can include categories that are not elements in s or t.

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

Form	Single Node	Multiple 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"]
	Categorical array Example: categorical("A")	Categorical array Example: categorical(["A" "B" "C"])

Example: G = addedge(G, [1 2], [3 4]) adds two edges to the graph: one from node 1 to node 3, and one from node 2 to node 4.

Example: G = addedge(G, {'a' 'a'; 'b' 'c'}, {'b' 'c'; 'c' 'e'}) adds four edges to the graph, the first of which goes from 'a' to 'b'.

w — Edge weights

scalar | vector | matrix

Edge weights, specified as a scalar, vector, or matrix.

• If w is a scalar or row vector, then it is scalar expanded to specify a weight for each edge in s and t.

• If w is a column vector, then it must have the same length as s(:) and t(:).

• If w is a matrix, then it must have the same number of elements as s(:) and t(:).

Example: G = addedge(G, [2 2], [4 5], [1 100]') adds two edges with weights of 1 and 100.

Data Types: single | double
Complex Number Support: Yes

EdgeTable — Edge attributes

table

Edge attributes, specified as a table. If you do not specify s and t to define the graph edges being added, then the first variable in EdgeTable is required to be a two-column matrix called EndNodes that defines the graph edges being added.

EdgeTable must have these general properties:

• For weighted graphs, EdgeTable must contain a variable Weight.

• If the graph has other edge attributes, then EdgeTable must contain all of the same variables as G.Edges to ensure compatibility.

• The order of variables in EdgeTable must be the same as that of G.Edges.

Data Types: table

Output Arguments

H — Output graph

graph object | digraph object

Output graph, returned as a graph or digraph object.

Compatibility Considerations

Change in handling of duplicate edges

Behavior changed in R2018a

graph, digraph, and addedge no longer produce errors when they encounter duplicate edges. Instead, the duplicate edges are added to the graph and the result is a multigraph. The ismultigraph function is useful to detect this situation, and simplify provides an easy way to remove the extra edges.