src/rdflib/extras/external_graph_libs.py
1"""Convert (to and) from rdflib graphs to other well known graph libraries.
2
3Currently the following libraries are supported:
4
5- networkx: MultiDiGraph, DiGraph, Graph
6- graph_tool: Graph
7
8Doctests in this file are all skipped, as we can't run them conditionally if
9networkx or graph_tool are available and they would err otherwise.
10see `../../test/test_extras_external_graph_libs.py` for conditional tests
11"""
12
13from __future__ import annotations
14
15import logging
16from typing import TYPE_CHECKING, Any, Dict, List
17
18if TYPE_CHECKING:
19 from rdflib.graph import Graph
20
21
22logger = logging.getLogger(__name__)
23
24
25def _identity(x):
26 return x
27
28
29def _rdflib_to_networkx_graph(
30 graph: Graph,
31 nxgraph,
32 calc_weights: bool,
33 edge_attrs,
34 transform_s=_identity,
35 transform_o=_identity,
36):
37 """Helper method for multidigraph, digraph and graph.
38
39 Modifies nxgraph in-place!
40
41 Args:
42 graph: an rdflib.Graph.
43 nxgraph: a networkx.Graph/DiGraph/MultiDigraph.
44 calc_weights: If True adds a 'weight' attribute to each edge according
45 to the count of s,p,o triples between s and o, which is meaningful
46 for Graph/DiGraph.
47 edge_attrs: Callable to construct edge data from s, p, o.
48 'triples' attribute is handled specially to be merged.
49 'weight' should not be generated if calc_weights==True.
50 (see invokers below!)
51 transform_s: Callable to transform node generated from s.
52 transform_o: Callable to transform node generated from o.
53 """
54 assert callable(edge_attrs)
55 assert callable(transform_s)
56 assert callable(transform_o)
57 import networkx as nx
58
59 for s, p, o in graph:
60 ts, to = transform_s(s), transform_o(o) # apply possible transformations
61 data = nxgraph.get_edge_data(ts, to)
62 if data is None or isinstance(nxgraph, nx.MultiDiGraph):
63 # no edge yet, set defaults
64 data = edge_attrs(s, p, o)
65 if calc_weights:
66 data["weight"] = 1
67 nxgraph.add_edge(ts, to, **data)
68 else:
69 # already have an edge, just update attributes
70 if calc_weights:
71 data["weight"] += 1
72 if "triples" in data:
73 d = edge_attrs(s, p, o)
74 data["triples"].extend(d["triples"])
75
76
77def rdflib_to_networkx_multidigraph(
78 graph: Graph, edge_attrs=lambda s, p, o: {"key": p}, **kwds
79):
80 r"""Converts the given graph into a networkx.MultiDiGraph.
81
82 The subjects and objects are the later nodes of the MultiDiGraph.
83 The predicates are used as edge keys (to identify multi-edges).
84
85 Args:
86 graph: a rdflib.Graph.
87 edge_attrs: Callable to construct later edge_attributes. It receives
88 3 variables (s, p, o) and should construct a dictionary that is
89 passed to networkx's add_edge(s, o, \*\*attrs) function.
90
91 By default this will include setting the MultiDiGraph key=p here.
92 If you don't want to be able to re-identify the edge later on, you
93 can set this to `lambda s, p, o: {}`. In this case MultiDiGraph's
94 default (increasing ints) will be used.
95
96 Returns:
97 networkx.MultiDiGraph
98
99 Example:
100 ```python
101 >>> from rdflib import Graph, URIRef, Literal
102 >>> g = Graph()
103 >>> a, b, l = URIRef('a'), URIRef('b'), Literal('l')
104 >>> p, q = URIRef('p'), URIRef('q')
105 >>> edges = [(a, p, b), (a, q, b), (b, p, a), (b, p, l)]
106 >>> for t in edges:
107 ... g.add(t)
108 ...
109 >>> mdg = rdflib_to_networkx_multidigraph(g)
110 >>> len(mdg.edges())
111 4
112 >>> mdg.has_edge(a, b)
113 True
114 >>> mdg.has_edge(a, b, key=p)
115 True
116 >>> mdg.has_edge(a, b, key=q)
117 True
118
119 >>> mdg = rdflib_to_networkx_multidigraph(g, edge_attrs=lambda s,p,o: {})
120 >>> mdg.has_edge(a, b, key=0)
121 True
122 >>> mdg.has_edge(a, b, key=1)
123 True
124 ```
125 """
126 import networkx as nx
127
128 mdg = nx.MultiDiGraph()
129 _rdflib_to_networkx_graph(graph, mdg, False, edge_attrs, **kwds)
130 return mdg
131
132
133def rdflib_to_networkx_digraph(
134 graph: Graph,
135 calc_weights: bool = True,
136 edge_attrs=lambda s, p, o: {"triples": [(s, p, o)]},
137 **kwds,
138):
139 r"""Converts the given graph into a networkx.DiGraph.
140
141 As an rdflib.Graph() can contain multiple edges between nodes, by default
142 adds the a 'triples' attribute to the single DiGraph edge with a list of
143 all triples between s and o.
144 Also by default calculates the edge weight as the length of triples.
145
146 Args:
147 graph: a rdflib.Graph.
148 calc_weights: If true calculate multi-graph edge-count as edge 'weight'
149 edge_attrs: Callable to construct later edge_attributes. It receives
150 3 variables (s, p, o) and should construct a dictionary that is passed to
151 networkx's add_edge(s, o, \*\*attrs) function.
152
153 By default this will include setting the 'triples' attribute here,
154 which is treated specially by us to be merged. Other attributes of
155 multi-edges will only contain the attributes of the first edge.
156 If you don't want the 'triples' attribute for tracking, set this to
157 `lambda s, p, o: {}`.
158
159 Returns: networkx.DiGraph
160
161 Example:
162 ```python
163 >>> from rdflib import Graph, URIRef, Literal
164 >>> g = Graph()
165 >>> a, b, l = URIRef('a'), URIRef('b'), Literal('l')
166 >>> p, q = URIRef('p'), URIRef('q')
167 >>> edges = [(a, p, b), (a, q, b), (b, p, a), (b, p, l)]
168 >>> for t in edges:
169 ... g.add(t)
170 ...
171 >>> dg = rdflib_to_networkx_digraph(g)
172 >>> dg[a][b]['weight']
173 2
174 >>> sorted(dg[a][b]['triples']) == [(a, p, b), (a, q, b)]
175 True
176 >>> len(dg.edges())
177 3
178 >>> dg.size()
179 3
180 >>> dg.size(weight='weight')
181 4.0
182
183 >>> dg = rdflib_to_networkx_graph(g, False, edge_attrs=lambda s,p,o:{})
184 >>> 'weight' in dg[a][b]
185 False
186 >>> 'triples' in dg[a][b]
187 False
188 ```
189 """
190 import networkx as nx
191
192 dg = nx.DiGraph()
193 _rdflib_to_networkx_graph(graph, dg, calc_weights, edge_attrs, **kwds)
194 return dg
195
196
197def rdflib_to_networkx_graph(
198 graph: Graph,
199 calc_weights: bool = True,
200 edge_attrs=lambda s, p, o: {"triples": [(s, p, o)]},
201 **kwds,
202):
203 r"""Converts the given graph into a networkx.Graph.
204
205 As an [`rdflib.Graph()`][rdflib.Graph] can contain multiple directed edges between nodes, by
206 default adds the a 'triples' attribute to the single DiGraph edge with a list of triples between s and o in graph.
207 Also by default calculates the edge weight as the `len(triples)`.
208
209 Args:
210 graph: a rdflib.Graph.
211 calc_weights: If true calculate multi-graph edge-count as edge 'weight'
212 edge_attrs: Callable to construct later edge_attributes. It receives
213 3 variables (s, p, o) and should construct a dictionary that is
214 passed to networkx's add_edge(s, o, \*\*attrs) function.
215
216 By default this will include setting the 'triples' attribute here,
217 which is treated specially by us to be merged. Other attributes of
218 multi-edges will only contain the attributes of the first edge.
219 If you don't want the 'triples' attribute for tracking, set this to
220 `lambda s, p, o: {}`.
221
222 Returns:
223 networkx.Graph
224
225 Example:
226 ```python
227 >>> from rdflib import Graph, URIRef, Literal
228 >>> g = Graph()
229 >>> a, b, l = URIRef('a'), URIRef('b'), Literal('l')
230 >>> p, q = URIRef('p'), URIRef('q')
231 >>> edges = [(a, p, b), (a, q, b), (b, p, a), (b, p, l)]
232 >>> for t in edges:
233 ... g.add(t)
234 ...
235 >>> ug = rdflib_to_networkx_graph(g)
236 >>> ug[a][b]['weight']
237 3
238 >>> sorted(ug[a][b]['triples']) == [(a, p, b), (a, q, b), (b, p, a)]
239 True
240 >>> len(ug.edges())
241 2
242 >>> ug.size()
243 2
244 >>> ug.size(weight='weight')
245 4.0
246
247 >>> ug = rdflib_to_networkx_graph(g, False, edge_attrs=lambda s,p,o:{})
248 >>> 'weight' in ug[a][b]
249 False
250 >>> 'triples' in ug[a][b]
251 False
252 ```
253 """
254 import networkx as nx
255
256 g = nx.Graph()
257 _rdflib_to_networkx_graph(graph, g, calc_weights, edge_attrs, **kwds)
258 return g
259
260
261def rdflib_to_graphtool(
262 graph: Graph,
263 v_prop_names: List[str] = ["term"],
264 e_prop_names: List[str] = ["term"],
265 transform_s=lambda s, p, o: {"term": s},
266 transform_p=lambda s, p, o: {"term": p},
267 transform_o=lambda s, p, o: {"term": o},
268):
269 """Converts the given graph into a graph_tool.Graph().
270
271 The subjects and objects are the later vertices of the Graph.
272 The predicates become edges.
273
274 Args:
275 graph: a rdflib.Graph.
276 v_prop_names: a list of names for the vertex properties. The default is set
277 to ['term'] (see transform_s, transform_o below).
278 e_prop_names: a list of names for the edge properties.
279 transform_s: callable with s, p, o input. Should return a dictionary
280 containing a value for each name in v_prop_names. By default is set
281 to {'term': s} which in combination with v_prop_names = ['term']
282 adds s as 'term' property to the generated vertex for s.
283 transform_p: similar to transform_s, but wrt. e_prop_names. By default
284 returns {'term': p} which adds p as a property to the generated
285 edge between the vertex for s and the vertex for o.
286 transform_o: similar to transform_s.
287
288 Returns: graph_tool.Graph()
289
290 Example:
291 ```python
292 >>> from rdflib import Graph, URIRef, Literal
293 >>> g = Graph()
294 >>> a, b, l = URIRef('a'), URIRef('b'), Literal('l')
295 >>> p, q = URIRef('p'), URIRef('q')
296 >>> edges = [(a, p, b), (a, q, b), (b, p, a), (b, p, l)]
297 >>> for t in edges:
298 ... g.add(t)
299 ...
300 >>> mdg = rdflib_to_graphtool(g)
301 >>> len(list(mdg.edges()))
302 4
303 >>> from graph_tool import util as gt_util
304 >>> vpterm = mdg.vertex_properties['term']
305 >>> va = gt_util.find_vertex(mdg, vpterm, a)[0]
306 >>> vb = gt_util.find_vertex(mdg, vpterm, b)[0]
307 >>> vl = gt_util.find_vertex(mdg, vpterm, l)[0]
308 >>> (va, vb) in [(e.source(), e.target()) for e in list(mdg.edges())]
309 True
310 >>> epterm = mdg.edge_properties['term']
311 >>> len(list(gt_util.find_edge(mdg, epterm, p))) == 3
312 True
313 >>> len(list(gt_util.find_edge(mdg, epterm, q))) == 1
314 True
315
316 >>> mdg = rdflib_to_graphtool(
317 ... g,
318 ... e_prop_names=[str('name')],
319 ... transform_p=lambda s, p, o: {str('name'): unicode(p)})
320 >>> epterm = mdg.edge_properties['name']
321 >>> len(list(gt_util.find_edge(mdg, epterm, unicode(p)))) == 3
322 True
323 >>> len(list(gt_util.find_edge(mdg, epterm, unicode(q)))) == 1
324 True
325 ```
326 """
327 # pytype error: Can't find module 'graph_tool'.
328 import graph_tool as gt # pytype: disable=import-error
329
330 g = gt.Graph()
331
332 vprops = [(vpn, g.new_vertex_property("object")) for vpn in v_prop_names]
333 for vpn, vprop in vprops:
334 g.vertex_properties[vpn] = vprop
335 eprops = [(epn, g.new_edge_property("object")) for epn in e_prop_names]
336 for epn, eprop in eprops:
337 g.edge_properties[epn] = eprop
338 node_to_vertex: Dict[Any, Any] = {}
339 for s, p, o in graph:
340 sv = node_to_vertex.get(s)
341 if sv is None:
342 v = g.add_vertex()
343 node_to_vertex[s] = v
344 tmp_props = transform_s(s, p, o)
345 for vpn, vprop in vprops:
346 vprop[v] = tmp_props[vpn]
347 sv = v
348
349 ov = node_to_vertex.get(o)
350 if ov is None:
351 v = g.add_vertex()
352 node_to_vertex[o] = v
353 tmp_props = transform_o(s, p, o)
354 for vpn, vprop in vprops:
355 vprop[v] = tmp_props[vpn]
356 ov = v
357
358 e = g.add_edge(sv, ov)
359 tmp_props = transform_p(s, p, o)
360 for epn, eprop in eprops:
361 eprop[e] = tmp_props[epn]
362 return g