0
# Graph Building Utilities
1

2
Utility functions for creating graphs from various data structures including edge lists, adjacency matrices, and incidence matrices. These functions provide convenient ways to convert common data representations into pydot graphs.
3

4
## Capabilities
5

6
### Graph from Edge List
7

8
Create graphs from lists of node pairs representing edges.
9

10
```python { .api }
11
def graph_from_edges(edge_list, node_prefix='', directed=False):
12
    """
13
    Creates graph from edge list.
14
    
15
    Parameters:
16
    - edge_list (Sequence): List of tuples representing edges [(src, dst), ...]
17
    - node_prefix (str): Prefix to add to node names (default: '')
18
    - directed (bool): Create directed graph if True, undirected if False
19
    
20
    Returns:
21
    Dot: Graph object with nodes and edges from the edge list
22
    """
23
```
24

25
### Graph from Adjacency Matrix
26

27
Create graphs from square matrices where entry (i,j) indicates edge presence/weight.
28

29
```python { .api }
30
def graph_from_adjacency_matrix(matrix, node_prefix='', directed=False):
31
    """
32
    Creates graph from adjacency matrix.
33
    
34
    Parameters:
35
    - matrix (Sequence[Sequence]): Square matrix where matrix[i][j] represents
36
      connection from node i to node j. Non-zero values create edges.
37
    - node_prefix (str): Prefix to add to node names (default: '')  
38
    - directed (bool): Create directed graph if True, undirected if False
39
    
40
    Returns:
41
    Dot: Graph object representing the adjacency relationships
42
    """
43
```
44

45
### Graph from Incidence Matrix
46

47
Create graphs from matrices where rows represent nodes and columns represent edges.
48

49
```python { .api }
50
def graph_from_incidence_matrix(matrix, node_prefix='', directed=False):
51
    """
52
    Creates graph from incidence matrix.
53
    
54
    Parameters:
55
    - matrix (Sequence[Sequence]): Matrix where rows are nodes and columns are edges.
56
      Non-zero entries indicate node participation in edges.
57
    - node_prefix (str): Prefix to add to node names (default: '')
58
    - directed (bool): Create directed graph if True, undirected if False
59
    
60
    Returns:
61
    Dot: Graph object representing the incidence relationships
62
    """
63
```
64

65
### Utility Support Functions
66

67
Additional utility functions used internally and available for advanced use cases.
68

69
```python { .api }
70
def call_graphviz(program, arguments, working_dir, **kwargs):
71
    """
72
    Call GraphViz programs directly.
73
    
74
    Parameters:
75
    - program (str): GraphViz program name ('dot', 'neato', etc.)
76
    - arguments (list[str]): Command line arguments
77
    - working_dir (str|bytes): Working directory for execution
78
    - **kwargs: Additional subprocess parameters
79
    
80
    Returns:
81
    tuple[str, str, subprocess.Popen]: (stdout, stderr, process)
82
    """
83

84
def quote_id_if_necessary(s, unquoted_keywords=None):
85
    """
86
    Enclose identifier in quotes if needed for DOT syntax.
87
    
88
    Parameters:
89
    - s (str): String to potentially quote
90
    - unquoted_keywords (Sequence[str], optional): Keywords that don't need quoting
91
    
92
    Returns:
93
    str: Quoted string if necessary, original string otherwise
94
    """
95

96
def quote_attr_if_necessary(s):
97
    """
98
    Enclose attribute value in quotes if needed.
99
    
100
    Parameters:
101
    - s (str): Attribute value to potentially quote
102
    
103
    Returns:
104
    str: Quoted string if necessary
105
    """
106
```
107

108
## Usage Examples
109

110
### Creating Graph from Edge List
111

112
```python
113
import pydot
114

115
# Simple edge list
116
edges = [
117
    ('A', 'B'),
118
    ('B', 'C'), 
119
    ('C', 'D'),
120
    ('D', 'A')
121
]
122

123
# Create undirected graph
124
graph = pydot.graph_from_edges(edges, directed=False)
125
graph.write_png("cycle_graph.png")
126

127
# Create directed graph with node prefix
128
directed_graph = pydot.graph_from_edges(edges, node_prefix="node_", directed=True)
129
print(directed_graph.to_string())
130
```
131

132
### Creating Graph from Adjacency Matrix
133

134
```python
135
import pydot
136

137
# Define adjacency matrix (4x4 nodes)
138
# 0 = no connection, 1 = connection exists
139
adjacency = [
140
    [0, 1, 0, 1],  # Node 0 connects to nodes 1 and 3
141
    [1, 0, 1, 0],  # Node 1 connects to nodes 0 and 2  
142
    [0, 1, 0, 1],  # Node 2 connects to nodes 1 and 3
143
    [1, 0, 1, 0]   # Node 3 connects to nodes 0 and 2
144
]
145

146
# Create graph from matrix
147
graph = pydot.graph_from_adjacency_matrix(adjacency, node_prefix="v")
148
graph.set_layout("neato")  # Good for symmetric graphs
149
graph.write_png("adjacency_graph.png")
150

151
# Weighted adjacency matrix
152
weighted_adjacency = [
153
    [0, 5, 0, 3],
154
    [5, 0, 2, 0],
155
    [0, 2, 0, 4],
156
    [3, 0, 4, 0]
157
]
158

159
weighted_graph = pydot.graph_from_adjacency_matrix(weighted_adjacency)
160
# Edge weights can be accessed through the edges
161
for edge in weighted_graph.get_edges():
162
    # Weight information is embedded in the graph structure
163
    pass
164
```
165

166
### Creating Graph from Incidence Matrix
167

168
```python
169
import pydot
170

171
# Incidence matrix: rows=nodes, columns=edges
172
# Entry (i,j) = 1 if node i is incident to edge j
173
incidence = [
174
    [1, 1, 0, 0],  # Node 0 incident to edges 0,1
175
    [1, 0, 1, 0],  # Node 1 incident to edges 0,2
176
    [0, 1, 1, 1],  # Node 2 incident to edges 1,2,3
177
    [0, 0, 0, 1]   # Node 3 incident to edge 3
178
]
179

180
graph = pydot.graph_from_incidence_matrix(incidence, node_prefix="n")
181
graph.write_svg("incidence_graph.svg")
182
```
183

184
### Working with Network Data
185

186
```python
187
import pydot
188

189
# Example: Social network connections
190
social_network = [
191
    ('Alice', 'Bob'),
192
    ('Alice', 'Charlie'),
193
    ('Bob', 'Diana'),
194
    ('Charlie', 'Diana'),
195
    ('Diana', 'Eve'),
196
    ('Charlie', 'Eve')
197
]
198

199
# Create social network graph
200
social_graph = pydot.graph_from_edges(social_network, directed=False)
201

202
# Style the graph
203
social_graph.set_bgcolor("lightblue")
204
social_graph.set_layout("fdp")  # Force-directed layout for social networks
205

206
# Style nodes (people)
207
for node in social_graph.get_nodes():
208
    node.set_shape("circle")
209
    node.set_style("filled")
210
    node.set_fillcolor("lightgreen")
211

212
# Style edges (relationships)
213
for edge in social_graph.get_edges():
214
    edge.set_color("darkblue")
215
    edge.set_penwidth("2")
216

217
social_graph.write_png("social_network.png")
218
```
219

220
### Converting from NetworkX
221

222
```python
223
# If you have NetworkX graphs, you can convert to edge list first
224
import networkx as nx
225
import pydot
226

227
# Create NetworkX graph
228
nx_graph = nx.erdos_renyi_graph(10, 0.3)
229

230
# Convert to edge list
231
edge_list = list(nx_graph.edges())
232

233
# Create pydot graph
234
pydot_graph = pydot.graph_from_edges(edge_list, node_prefix="node_")
235
pydot_graph.write_png("random_graph.png")
236
```