Primitives

Graph transformation primitives.

This package contains a collection of utils for various transformations on regraph.Graph objects. Attributes: regraph.attribute_sets

regraph.primitives.add_edge(graph, s, t, attrs=None, **attr)

Add an edge to a graph.

Parameters

graphregraph.Graph

shashable, source node id.

thashable, target node id.

attrsdict

Edge attributes.

Raises

ReGraphError

If attrs is not a dictionary

GraphError

If either one of the nodes does not exist in the graph or an edge between s and t already exists.

regraph.primitives.add_edge_attrs(graph, s, t, attrs)

Add attributes of an edge in a graph.

Parameters

graphregraph.Graph

shashable, source node id.

thashable, target node id.

attrsdict

Dictionary with attributes to remove.

Raises

GraphError

If an edge between s and t does not exist.

regraph.primitives.add_edges_from(graph, edge_list)

Add edges from an edge list.

Parameters

graphregraph.Graph

edge_listiterable

Iterable containing a collection of edges, optionally, with their attributes

Raises

ReGraphError

If an element of the collection is neither a tuple of size 2 (containing a source and a target of an edge), not a tuple of size 3 (containing a source, a target and attributes of an edge).

Examples

>>> import networkx as nx
>>> from regraph.primitives import add_nodes_from, add_edges_from
>>> G = nx.Graph()
>>> add_nodes_from(G, [1, 2, 3])
>>> add_edges_from(G, [(1, 2), (2, 3, {"a": 1})])

regraph.primitives.add_node(graph, node_id, attrs={})

Add a node to a graph.

Parameters

graphregraph.Graph

node_idhashable

Prefix that is prepended to the new unique name.

attrsdict, optional

Node attributes.

Raises

regraph.exceptions.GraphError

Raises an error if node already exists in the graph.

regraph.primitives.add_node_attrs(graph, node, attrs)

Add new attributes to a node.

Parameters

graphregraph.Graph

nodehashable

Id of a node to add attributes to.

attrsdict

Attributes to add.

Raises

GraphError

If a node with the specified id does not exist.

regraph.primitives.add_node_new_id(graph, node_id, attrs=None)

Create a new node id if node_id already exists.

regraph.primitives.add_nodes_from(graph, node_list)

Add nodes from a node list.

Parameters

graphregraph.Graph

node_listiterable

Iterable containing a collection of nodes, optionally, with their attributes

Examples

>>> import networkx as nx
>>> from regraph.primitives import add_nodes_from
>>> G = nx.Graph()
>>> add_nodes_from(G, [1, (2, {"a": 1}), 3])

regraph.primitives.append_to_node_names(graph, token)

Append a token to the node names.

regraph.primitives.clone_node(graph, node_id, name=None)

Clone node.

Create a new node, a copy of a node with node_id, and reconnect it with all the adjacent nodes of node_id.

Parameters

graphregraph.Graph

node_idid of a node to clone.

nameid for the clone, optional

If is not specified, new id will be generated.

Returns

new_nodehashable, clone’s id

Raises

GraphError

If node wiht node_id does not exists or a node with name (clone’s name) already exists.

Examples

>>> g = nx.DiGraph()
>>> add_nodes_from(g, [1, 2, 3])
>>> add_edges_from(g, [(1, 2), (3, 2)])
>>> clone_node(g, 2, "2_clone")
>>> g.nodes()
[1, 2, "2_clone", 3]
>>> g.edges()
[(1, 2), (1, "2_clone"), (3, 2), (3, "2_clone")]

regraph.primitives.copy_node(graph, node_id)

Copy node.

Create a copy of a node in a graph. A new id for the copy is generated by regraph.primitives.unique_node_id.

Parameters

graphregraph.Graph

node_idhashable, node to copy.

Returns

new_name

Id of the copy node.

regraph.primitives.equal(graph1, graph2)

Eqaulity of two graphs.

Parameters

graph1regraph.Graph

graph2regraph.Graph

Returns

bool

True if two graphs are equal, False otherwise.

regraph.primitives.exists_edge(graph, s, t)

Check if an edge exists.

Parameters

graphregraph.Graph

shashable, source node id.

thashable, target node id.

regraph.primitives.export_graph(graph, filename)

Export graph to JSON file.

Parameters

graphregraph.Graph

filenamestr

Name of the file to save the json serialization of the graph

regraph.primitives.filter_edges_by_attributes(graph, attr_key, attr_cond)

Filter graph edges by attributes.

Removes all the edges of the graph (inplace) that do not satisfy attr_cond.

Parameters

graphregraph.Graph

attrs_keyattribute key

attrs_condcallable

Condition for an attribute to satisfy: callable that returns True if condition is satisfied, False otherwise.

regraph.primitives.find_matching(graph, pattern, nodes=None)

Find matching of a pattern in a graph.

Parameters

graphregraph.Graph

patternregraph.Graph

Pattern graph to search for

nodesiterable, optional

Subset of nodes to search for matching

Returns

instanceslist of dict’s

List of instances of matching found in the graph, every instance is represented with a dictionary where keys are nodes of the pattern, and values are corresponding nodes of the graph.

Examples

Suppose you are given the following graph:

>>> g = networkx.DiGraph()
>>> add_nodes_from(g, [(1, {"color": {"red"}}), 2, (3, {"color": {"blue"}})])
>>> add_edges_from(g, [(1, 1), (1, 2), (3, 3), (3, 2)])

And you would like to match the following pattern:

>>> pattern = networkx.DiGraph()
>>> add_nodes_from(pattern, [("x", {"color": "blue"}), "y"])
>>> add_edges_from(pattern, [("x", "x"), ("x", "y")])

Matching instances can be found as follows:

>>> instances = find_matching(g, pattern)
>>> instances
[{"x": 3, "y": 2}]

regraph.primitives.get_edge(graph, s, t)

Get edge attributes.

Parameters

graphregraph.Graph

shashable, source node id.

thashable, target node id.

regraph.primitives.get_node(graph, n)

Get node attributes.

Parameters

graphregraph.Graph or regraph.neo4j.Neo4jGraph

shashable, source node id.

thashable, target node id.

regraph.primitives.get_relabeled_graph(graph, mapping)

Return a graph with node labeling specified in the mapping.

Parameters

graphnetworkx.(Di)Graph

mapping: dict

A dictionary with keys being old node ids and their values being new id’s of the respective nodes.

Returns

gnetworkx.(Di)Graph

New graph object isomorphic to the graph with the relabled nodes.

Raises

ReGraphError

If new id’s do not define a set of distinct node id’s.

See also

regraph.primitives.relabel_nodes

regraph.primitives.graph_to_d3_json(graph, attrs=True, node_attrs_to_attach=None, edge_attrs_to_attach=None, nodes=None)

Create a JSON representation of a graph.

regraph.primitives.graph_to_json(graph)

Create a JSON representation of a graph.

regraph.primitives.load_networkx_graph(filename, directed=True)

Load a NetworkX graph from a JSON file.

Create a regraph.Graph object from a JSON representation stored in a file.

Parameters

filenamestr

Name of the file to load the json serialization of the graph

directedbool, optional

True if the graph to load is directed, False otherwise. Default value True.

Returns

regraph.Graph object

Raises

ReGraphError

If was not able to load the file

regraph.primitives.merge_nodes(graph, nodes, node_id=None, method='union', edge_method='union')

Merge a list of nodes.

Parameters

graphregraph.Graph

nodesiterable

Collection of node id’s to merge.

node_idhashable, optional

Id of a new node corresponding to the result of merge.

methodoptional

Method of node attributes merge: if “union” the resulting node will contain the union of all attributes of the merged nodes, if “intersection”, the resulting node will contain their intersection. Default value is “union”.

edge_methodoptional

Method of edge attributes merge: if “union” the edges that were merged will contain the union of all attributes, if “intersection” – their ntersection. Default value is “union”.

Returns

node_idhashable

Id of a new node corresponding to the result of merge.

Raises

ReGraphError

If unknown merging method is provided

GraphError

If some nodes from nodes do not exist in the graph.

Examples

>>> g = nx.DiGraph()
>>> add_nodes_from(g, [(1, {"a": 1, "b": 1}), 2, (3, {"a": 3, "c": 3})])
>>> add_edges_from(g, [(1, 3), (1, 2), (2, 3)])
>>> merge_nodes(g, [1, 3], "merged_node")
>>> g.nodes()
["merged_node", 2]
>>> g.edges()
[("merged_node", "merged_node"), ("merged_node", 2), (2, "merged_node")]
>>> g.node["merged_node"]
{"a": {1, 3}, "b": {1}, "c": {3}}

regraph.primitives.networkx_from_json(j_data)

Create a NetworkX graph from a json-like dictionary.

regraph.primitives.print_graph(graph)

Util for pretty graph printing.

regraph.primitives.relabel_node(graph, node_id, new_id)

Relabel a node in the graph.

Parameters

graphregraph.Graph

node_idid of a node to relabel.

new_idhashable, new label of a node.

regraph.primitives.relabel_nodes(graph, mapping)

Relabel graph nodes inplace given a mapping.

Similar to networkx.relabel.relabel_nodes: https://networkx.github.io/documentation/development/_modules/networkx/relabel.html

Parameters

graphregraph.Graph

mapping: dict

A dictionary with keys being old node ids and their values being new id’s of the respective nodes.

Raises

ReGraphError

If new id’s do not define a set of distinct node id’s.

regraph.primitives.remove_edge(graph, s, t)

Remove edge from a graph.

Parameters

graphregraph.Graph

shashable, source node id.

thashable, target node id.

Raises

GraphError

If edge between s and t does not exist.

regraph.primitives.remove_edge_attrs(graph, s, t, attrs)

Remove attrs of an edge specified by attrs.

Parameters

graphregraph.Graph

shashable, source node id.

thashable, target node id.

attrsdict

Dictionary with attributes to remove.

Raises

GraphError

If an edge between s and t does not exist.

regraph.primitives.remove_node(graph, node_id)

Remove node.

Parameters

graphregraph.Graph

node_idhashable, node to remove.

Raises

GraphError

If a node with the specified id does not exist.

regraph.primitives.remove_node_attrs(graph, node_id, attrs)

Remove attrs of a node specified by attrs_dict.

Parameters

graphregraph.Graph

node_idhashable

Node whose attributes to remove.

attrsdict

Dictionary with attributes to remove.

Raises

GraphError

If a node with the specified id does not exist.

regraph.primitives.set_edge(graph, s, t, attrs, normalize=True)

Set edge attrs.

Parameters

graphregraph.Graph

shashable, source node id.

thashable, target node id.

attrsdictionary

Dictionary with attributes to set.

Raises

GraphError

If an edge between s and t does not exist.

regraph.primitives.subtract(a, b, ba_mapping)

Subtract graphs provided node mapping.

Subtract graph B from A having mapping of nodes from B to nodes from A specified.

Parameters

aregraph.Graph

bregraph.Graph

ba_mappingdict

Returns

Graph representing the difference a - b.

Examples

>>> a = nx.DiGraph()
>>> add_nodes_from(a, [1, 2, 3])
>>> add_edges_from(a, [(1, 2), (2, 2), (2, 3)])
>>> b = nx.DiGraph()
>>> add_nodes_from(b, ['x', 'y'])
>>> ba_mapping = {'x': 1, 'y': 3}
>>> diff = subtract(a, b, ba_mapping)
>>> diff.nodes()
[2]
>>> diff.edges()
[(2, 2)]

regraph.primitives.update_edge_attrs(graph, s, t, attrs, normalize=True)

Update attributes of an edge.

Parameters

graphregraph.Graph

shashable, source node id.

thashable, target node id.

attrsdict

New attributes to assign to the edge

Raises

GraphError

If an edge between s and t does not exist.

regraph.primitives.update_node_attrs(graph, node_id, attrs, normalize=True)

Update attributes of a node.

Parameters

graphregraph.Graph

node_idhashable, node to update.

attrsdict

New attributes to assign to the node

Raises

GraphError

If a node with the specified id does not exist.