Source code

Download source archive ↓

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