graphit.graph_combinatorial package¶
graphit.graph_combinatorial.graph_setlike_operations module¶
file: graph_setlike_operations.py
Functions to perform Python [set-like](https://docs.python.org/3/library/ stdtypes.html#set-types-set-frozenset) operation on graphs.
These functions aim to return a view-based result graph (subgraph) as often as possible by checking if the input graphs share te same origin graph. If returning a view is not possible or explicitly not requested the returned graph is based on a deep copy of the first graph provided as argument to the function.
The set-like combinatorial operations are based on (dis)-similarity in node and edge ID’s regardless of the auto_nid setting. Set-like operations based on node and/or edge attributes is possible by first performing a node/edge query followed by the set operation.
A general concept in (graphit) Graphs is that nodes do not need to have edges but edges cannot exist without their respective nodes. While union and intersection operations will always return graphs that meet these requirements, difference operations do not. If the difference between two graphs is an edge returning that edge alone as Graph object without the corresponding nodes is not allowed. Therefore, by default, the difference functions are node oriented. In calculating the difference between a sub graph and its parent graph this approach will result in a desired graph subtraction operation where the edges linking sub graph and parent are removed. However, these functions have a edge_diff flag that will switch the function to calculate the edge oriented difference that will include nodes to return a valid graph.
Note
These functions do not update node and/or edge attributes in the resulting graph as might be required in for instance a union or intersection operation.
-
graphit.graph_combinatorial.graph_setlike_operations.graph_union(*args, **kwargs)¶ Return a graph with the union of the input graphs
The union represents the combined unique nodes and edges present in the graphs. Similarity is based on ID.
Nodes and edges are added without updating the respective attributes. The latter can be done by calling the update function afterwards.
If the graphs share a common origin graph and return_copy is False the returned intersection graph will be a view on the origin, else it is a new graph. In both cases, the first graph in the argument list is used as basis for the returned union graph.
- Parameters
args (:py:list) – graphs to return the union for
return_copy (:py:bool) – force return a new graph as deep copy based on graph1
- Returns
union graph
- Return type
:graphit:Graph
- Raises
AttributeError, if arguments no instance of Graph class
-
graphit.graph_combinatorial.graph_setlike_operations.graph_intersection(graph1, graph2, return_copy=False)¶ Return a graph with the intersection in nodes and edges between the two input graphs
The intersection represents the nodes and edges connecting them present in both graphs. Node and edge similarity is based on ID.
If the graphs share a common origin graph and return_copy is False the returned intersection graph will be a view on the origin, else it is a new graph.
- Parameters
graph1 (:graphit:Graph) – first graph
graph2 (:graphit:Graph) – second graph
return_copy (:py:bool) – force return a new graph as deep copy based on graph1
- Returns
intersection graph
- Return type
:graphit:Graph
- Raises
AttributeError, if arguments no instance of Graph class
-
graphit.graph_combinatorial.graph_setlike_operations.graph_difference(graph1, graph2, edge_diff=False, return_copy=False)¶ Return a graph with the difference in nodes and edges of graph1 with respect to graph2.
The difference represents the nodes and edges connecting them that are present in graph1 but not in graph2. Difference is based on ID. The difference is node driven resulting in edges being removed when the nodes on either end are removed. Use the edge_diff argument to switch to an edge driven difference calculation,
If the graphs share a common origin graph and return_copy is False the returned intersection graph will be a view on the origin, else it is a new graph.
- Parameters
graph1 (:graphit:Graph) – first graph
graph2 (:graphit:Graph) – second graph
edge_diff (:py:bool) – switch from node to edge driven difference calculation
return_copy (:py:bool) – force return a new graph as deep copy based on graph1
- Returns
difference graph
- Return type
:graphit:Graph
- Raises
AttributeError, if arguments no instance of Graph class
-
graphit.graph_combinatorial.graph_setlike_operations.graph_issubset(graph1, graph2)¶ Test if graph1 is a subset of graph2 two in terms of nodes and edges.
- Parameters
graph1 (:graphit:Graph) – first graph
graph2 (:graphit:Graph) – second graph
- Returns
issubset or not
- Return type
:py:bool
- Raises
AttributeError, if arguments no instance of Graph class
-
graphit.graph_combinatorial.graph_setlike_operations.graph_issuperset(graph1, graph2)¶ Test if graph1 is a superset of graph2 two in terms of nodes and edges.
- Parameters
graph1 (:graphit:Graph) – first graph
graph2 (:graphit:Graph) – second graph
- Returns
issuperset or not
- Return type
:py:bool
- Raises
AttributeError, if arguments no instance of Graph class
-
graphit.graph_combinatorial.graph_setlike_operations.graph_symmetric_difference(graph1, graph2, edge_diff=False, return_copy=False)¶ Return a new graph with the symmetric difference in nodes and edges of two graphs.
The symmetric difference represents the nodes and edges connecting them that are present in graph1 but not in graph2 and vice versa. It is thus the opposite of the graph_intersection. The difference is node driven resulting in edges being removed when the nodes on either end are removed. Use the edge_diff argument to switch to an edge driven difference calculation,
If the graphs share a common origin graph and return_copy is False the returned intersection graph will be a view on the origin, else it is a new graph.
- Parameters
graph1 (:graphit:Graph) – first graph
graph2 (:graphit:Graph) – second graph
edge_diff (:py:bool) – switch from node to edge driven difference calculation
return_copy (:py:bool) – force return a new grpah as deep copy based on graph1
- Returns
symmetric difference graph
- Return type
:graphit:Graph
- Raises
AttributeError, if arguments no instance of Graph class
graphit.graph_combinatorial.graph_split_join_operations module¶
file: graph_split_join_operations.py
Functions to split or combine graphs.
-
graphit.graph_combinatorial.graph_split_join_operations.graph_join(graph1, graph2, links=None, run_node_new=True, run_edge_new=True)¶ Add graph2 as subgraph to graph1
All nodes and edges of graph 2 are added to graph 1. Final links between nodes in graph 1 and newly added nodes of graph 2 are defined by the edges in the links list.
- Parameters
graph1 (GraphAxis) – graph to add to
graph2 (GraphAxis) – graph added
links (:py:list) – links between nodes in graph1 and graph2
run_edge_new (py:bool) – run the custom initiation method (new method) of the new edge once.
run_node_new (:py:bool) – run the custom initiation method (new method) of the new node once.
- Returns
node mapping
- Return type
:py:dict
graphit.graph_combinatorial.graph_update_operations module¶
file: graph_update_operations.py
Functions that return new graphs with updated nodes and edges including their attributes based on node/edge ID’s.
These functions have equivalents in the graph_setlike_operations library where the focus is on returning views as often as possible and attributes are not updated.
-
graphit.graph_combinatorial.graph_update_operations.graph_add(*args, **kwargs)¶ Add graphs together
Using the first graph as base graph, add all nodes and edges in the remaining graphs to the first graph based on node and edge ID. Attributes are updated for nodes and edges already in the graph one or multiple times. Node and edge attribute update can be switched on/off using the update_node_attributes and update_edge_attributes respectively.
Note
in case multiple graphs are added together that have overlapping nodes or edges defining similar attributes the final value of the attribute in the result graph equals the last input graph that defines that attribute.
Please use the graph_setlike_operations.graph_union function to create a union between input graphs that will not update attributes and return views in case of a common origin graph.
Note
This function will not create any new nodes or edges that are not already available in on of the input graphs. This may yield a result graph with isolated sub graphs.
- Parameters
args (:py:list) – graphs to add together
update_node_attributes (:py:bool) – update existing node attributes
update_edge_attributes (:py:bool) – update existing edge attributes
- Returns
new Graph joining input graphs
- Return type
:graphit:Graph
-
graphit.graph_combinatorial.graph_update_operations.graph_subtract(graph1, graph2)¶ Subtract the second graph from the first
Subtracting equals calculating the graph difference between graph1 and graph2 using a node oriented difference and returning a copy.
- Parameters
graph1 (:graphit:Graph) – first graph
graph2 (:graphit:Graph) – second graph
- Returns
new Graph with differences between graph1, graph2
- Return type
:graphit:Graph
-
graphit.graph_combinatorial.graph_update_operations.graph_update(graph1, graph2, update_edges=True, update_nodes=True)¶ Update graph1 with the content of graph2
Requires graph2 to be fully contained in graph1 based on graph topology measured as equality between nodes and edges assessed by node and edge ID.
