Graph I/O#
This page covers importing and exporting the Graph object from and
to different (file) formats using the ragraph.io module. Among the available
formats are:
The importing and exporting of JSON is probably the most extensive implementation,
closely followed by CSV. Some formats are only partly supported, where in most cases it
features either importing to a Graph or merely exporting one.
JSON#
A Graph can be translated both from and to a JSON file or encoded
JSON string. These are all based on the JSON dictionary representations of the objects
in the graph and handled by the ragraph.io.json module. Let’s show a suitable
JSON file.
{
"annotations": {},
"edges": {
"00000000-0000-0000-0000-000000000008": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "ab",
"source": "00000000-0000-0000-0000-000000000002",
"target": "00000000-0000-0000-0000-000000000003",
"uuid": "00000000-0000-0000-0000-000000000008",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-000000000009": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "ac",
"source": "00000000-0000-0000-0000-000000000002",
"target": "00000000-0000-0000-0000-000000000004",
"uuid": "00000000-0000-0000-0000-000000000009",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-00000000000a": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "ae",
"source": "00000000-0000-0000-0000-000000000002",
"target": "00000000-0000-0000-0000-000000000006",
"uuid": "00000000-0000-0000-0000-00000000000a",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-00000000000b": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "ba",
"source": "00000000-0000-0000-0000-000000000003",
"target": "00000000-0000-0000-0000-000000000002",
"uuid": "00000000-0000-0000-0000-00000000000b",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-00000000000c": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "be",
"source": "00000000-0000-0000-0000-000000000003",
"target": "00000000-0000-0000-0000-000000000006",
"uuid": "00000000-0000-0000-0000-00000000000c",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-00000000000d": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "ca",
"source": "00000000-0000-0000-0000-000000000004",
"target": "00000000-0000-0000-0000-000000000002",
"uuid": "00000000-0000-0000-0000-00000000000d",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-00000000000e": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "ce",
"source": "00000000-0000-0000-0000-000000000004",
"target": "00000000-0000-0000-0000-000000000006",
"uuid": "00000000-0000-0000-0000-00000000000e",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-00000000000f": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "de",
"source": "00000000-0000-0000-0000-000000000005",
"target": "00000000-0000-0000-0000-000000000006",
"uuid": "00000000-0000-0000-0000-00000000000f",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-000000000010": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "ea",
"source": "00000000-0000-0000-0000-000000000006",
"target": "00000000-0000-0000-0000-000000000002",
"uuid": "00000000-0000-0000-0000-000000000010",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-000000000011": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "eb",
"source": "00000000-0000-0000-0000-000000000006",
"target": "00000000-0000-0000-0000-000000000003",
"uuid": "00000000-0000-0000-0000-000000000011",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-000000000012": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "ec",
"source": "00000000-0000-0000-0000-000000000006",
"target": "00000000-0000-0000-0000-000000000004",
"uuid": "00000000-0000-0000-0000-000000000012",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-000000000013": {
"annotations": {},
"kind": "edge",
"labels": [
"default"
],
"name": "ed",
"source": "00000000-0000-0000-0000-000000000006",
"target": "00000000-0000-0000-0000-000000000005",
"uuid": "00000000-0000-0000-0000-000000000013",
"weights": {
"default": 1
}
}
},
"kind": "default",
"labels": [
"default"
],
"name": "simple",
"nodes": {
"00000000-0000-0000-0000-000000000002": {
"annotations": {},
"children": [],
"is_bus": false,
"kind": "node",
"labels": [
"default"
],
"name": "a",
"parent": null,
"uuid": "00000000-0000-0000-0000-000000000002",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-000000000003": {
"annotations": {},
"children": [],
"is_bus": false,
"kind": "node",
"labels": [
"default"
],
"name": "b",
"parent": null,
"uuid": "00000000-0000-0000-0000-000000000003",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-000000000004": {
"annotations": {},
"children": [],
"is_bus": false,
"kind": "node",
"labels": [
"default"
],
"name": "c",
"parent": null,
"uuid": "00000000-0000-0000-0000-000000000004",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-000000000005": {
"annotations": {},
"children": [],
"is_bus": false,
"kind": "node",
"labels": [
"default"
],
"name": "d",
"parent": null,
"uuid": "00000000-0000-0000-0000-000000000005",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-000000000006": {
"annotations": {},
"children": [],
"is_bus": false,
"kind": "node",
"labels": [
"default"
],
"name": "e",
"parent": null,
"uuid": "00000000-0000-0000-0000-000000000006",
"weights": {
"default": 1
}
},
"00000000-0000-0000-0000-000000000007": {
"annotations": {},
"children": [],
"is_bus": false,
"kind": "node",
"labels": [
"default"
],
"name": "f",
"parent": null,
"uuid": "00000000-0000-0000-0000-000000000007",
"weights": {
"default": 1
}
}
},
"uuid": "00000000-0000-0000-0000-000000000001",
"weights": {
"default": 1
}
}
Which may seem relatively verbose, but is little more than a JSON dump of the
json_dict property of an otherwise simple
Graph.
Importing it is as simple as:
>>> from ragraph.io.json import from_json
>>> g = from_json(path) # Path points to the JSON file above.
Which loads a Graph into g with six nodes ("a" through
"f") with a couple of edges between them.
If you already have a JSON encoded string loaded into a variable, you can also supply
this by using: from_json(enc=my_string_variable).
Exporting the graph is equally simple:
>>> from ragraph.io.json import to_json
>>> enc = to_json(g, path=None)
Which by setting path=None will give you a JSON string representation of the graph.
When actually setting the path to a filepath, the string will not be returned and
written to that filepath instead.
CSV#
The CSV format is probably one of the most compact formats we support. To import from
CSV you need both a nodes and an edges file. The functionality is included in
the ragraph.io.csv module.
The minimum requirement to a nodes file is that each node has a name. A basic
nodes file thus looks like:
name
a
b
c
d
e
f
This file will generate six nodes named "a" through "f" when imported, with all
other Node arguments left to their defaults.
The minimum edges file needs a source and a target column. These should refer to
the source and target node of each edge, such as:
source;target
a;b
b;a
a;c
c;a
e;a
e;b
e;c
e;d
a;e
b;e
c;e
d;e
Importing these can be done using the following snippet:
>>> from ragraph.io.csv import from_csv
>>> g = from_csv(nodes_path, edges_path) # paths to simple_nodes.csv and simple_edges.csv
You can tweak some additional settings in the from_csv method
like the CSV delimiter and some parameters to indicate which column includes which
metadata.
Matrix#
A Graph and its adjacency matrix are closely related. To
facilitate quick transitions between these representations, we included the
ragraph.io.matrix module. This allows you to transition back and forth from a
list of lists or nested numpy array and a Graph object. A small
example:
>>> from ragraph.io.matrix import from_matrix
>>> A = [[0, 1, 0], [2, 0, 1], [9, 9, 9]]
>>> g = from_matrix(A)
And the other way around:
>>> from ragraph.io.matrix import to_matrix
>>> to_matrix(g, loops=False)
array([[0., 1., 0.],
[2., 0., 1.],
[9., 9., 0.]])
We usually default to leaving out edges that are self-loops (e.g. the diagonal is 0),
but if you would like to include them, just set loops=True. There are some tweaks
for hierarchical graphs, too. Please refer to the ~ragraph.io.matrix module’s
documentation for that.
ESL (Elephant Specification Language)#
The ESL format is supported in an import-only fashion, as arbitrary
Graph objects have no ESL equivalent. However, we can derive a
dependency graph from the imported ESL files.