easygraph.classes package

Submodules

easygraph.classes.base module

easygraph.classes.directed_graph module

class easygraph.classes.directed_graph.DiGraph(incoming_graph_data=None, **graph_attr)

Bases: Graph

Base class for directed graphs.

Nodes are allowed for any hashable Python objects, including int, string, dict, etc. Edges are stored as Python dict type, with optional key/value attributes.

Parameters

graph_attr (keywords arguments, optional (default : None)) – Attributes to add to graph as key=value pairs.

See also

Graph

Examples

Create an empty directed graph with no nodes and edges.

>>> G = eg.DiGraph()

Create a deep copy graph G2 from existing Graph G1.

>>> G2 = G1.copy()

Create an graph with attributes.

>>> G = eg.DiGraph(name='Karate Club', date='2020.08.21')

Attributes:

Returns the adjacency matrix of the graph.

>>> G.adj

Returns all the nodes with their attributes.

>>> G.nodes

Returns all the edges with their attributes.

>>> G.edges

add_edge(u_of_edge, v_of_edge, **edge_attr)

Add a directed edge.

Parameters

• u_of_edge (object) – The start end of this edge

• v_of_edge (object) – The destination end of this edge

• edge_attr (keywords arguments, optional) – The attribute of the edge.

Notes

Nodes of this edge will be automatically added to the graph, if they do not exist.

See also

add_edges

Examples

>>> G.add_edge(1,2)
>>> G.add_edge('Jack', 'Tom', weight=10)

Add edge with attributes, edge weight, for example,

>>> G.add_edge(1, 2, **{
...     'weight': 20
... })

add_edges(edges_for_adding, edges_attr: List[Dict] = [])

Add a list of edges.

Parameters

• edges_for_adding (list of 2-element tuple) – The edges for adding. Each element is a (u, v) tuple, and u, v are start end and destination end, respectively.

• edges_attr (list of dict, optional) – The corresponding attributes for each edge in edges_for_adding.

Examples

Add a list of edges into G

>>> G.add_edges([
...     (1, 2),
...     (3, 4),
...     ('Jack', 'Tom')
... ])

Add edge with attributes, for example, edge weight,

>>> G.add_edges([(1,2), (2, 3)], edges_attr=[
...     {
...         'weight': 20
...     },
...     {
...         'weight': 15
...     }
... ])

add_edges_from(ebunch_to_add, **attr)

Add all the edges in ebunch_to_add.

Parameters

• ebunch_to_add (container of edges) – Each edge given in the container will be added to the graph. The edges must be given as 2-tuples (u, v) or 3-tuples (u, v, d) where d is a dictionary containing edge data.

• attr (keyword arguments, optional) – Edge data (or labels or objects) can be assigned using keyword arguments.

See also

add_edge

add a single edge

add_weighted_edges_from

convenient way to add weighted edges

Notes

Adding the same edge twice has no effect but any edge data will be updated when each duplicate edge is added.

Edge attributes specified in an ebunch take precedence over attributes specified via keyword arguments.

Examples

>>> G = eg.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G.add_edges_from([(0, 1), (1, 2)])  # using a list of edge tuples
>>> e = zip(range(0, 3), range(1, 4))
>>> G.add_edges_from(e)  # Add the path graph 0-1-2-3

Associate data to edges

>>> G.add_edges_from([(1, 2), (2, 3)], weight=3)
>>> G.add_edges_from([(3, 4), (1, 4)], label="WN2898")

add_edges_from_file(file, weighted=False)

Added edges from file For example, txt files,

Each line is in form like: a b 23.0 which denotes an edge a → b with weight 23.0.

Parameters

• file (string) – The file path.

• weighted (boolean, optional (default : False)) – If the file consists of weight information, set True. The weight key will be set as ‘weight’.

Examples

If ./club_network.txt is:

Jack Mary 23.0

Mary Tom 15.0

Tom Ben 20.0

Then add them to G

>>> G.add_edges_from_file(file='./club_network.txt', weighted=True)

add_node(node_for_adding, **node_attr)

Add one node

Add one node, type of which is any hashable Python object, such as int, string, dict, or even Graph itself. You can add with node attributes using Python dict type.

Parameters

• node_for_adding (any hashable Python object) – Nodes for adding.

• node_attr (keywords arguments, optional) – The node attributes. You can customize them with different key-value pairs.

See also

add_nodes

Examples

>>> G.add_node('a')
>>> G.add_node('hello world')
>>> G.add_node('Jack', age=10)

>>> G.add_node('Jack', **{
...     'age': 10,
...     'gender': 'M'
... })

add_nodes(nodes_for_adding: list, nodes_attr: List[Dict] = [])

Add nodes with a list of nodes.

Parameters

• nodes_for_adding (list) –

• nodes_attr (list of dict) – The corresponding attribute for each of nodes_for_adding.

See also

add_node

Examples

Add nodes with a list of nodes. You can add with node attributes using a list of Python dict type, each of which is the attribute of each node, respectively.

>>> G.add_nodes([1, 2, 'a', 'b'])
>>> G.add_nodes(range(1, 200))

>>> G.add_nodes(['Jack', 'Tom', 'Lily'], nodes_attr=[
...     {
...         'age': 10,
...         'gender': 'M'
...     },
...     {
...         'age': 11,
...         'gender': 'M'
...     },
...     {
...         'age': 10,
...         'gender': 'F'
...     }
... ])

add_nodes_from(nodes_for_adding, **attr)

Add multiple nodes.

Parameters

• nodes_for_adding (iterable container) – A container of nodes (list, dict, set, etc.). OR A container of (node, attribute dict) tuples. Node attributes are updated using the attribute dict.

• attr (keyword arguments, optional (default= no attributes)) – Update attributes for all nodes in nodes. Node attributes specified in nodes as a tuple take precedence over attributes specified via keyword arguments.

See also

add_node

Examples

>>> G = eg.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G.add_nodes_from("Hello")
>>> K3 = eg.Graph([(0, 1), (1, 2), (2, 0)])
>>> G.add_nodes_from(K3)
>>> sorted(G.nodes(), key=str)
[0, 1, 2, 'H', 'e', 'l', 'o']

Use keywords to update specific node attributes for every node.

>>> G.add_nodes_from([1, 2], size=10)
>>> G.add_nodes_from([3, 4], weight=0.4)

Use (node, attrdict) tuples to update attributes for specific nodes.

>>> G.add_nodes_from([(1, dict(size=11)), (2, {"color": "blue"})])
>>> G.nodes[1]["size"]
11
>>> H = eg.Graph()
>>> H.add_nodes_from(G.nodes(data=True))
>>> H.nodes[1]["size"]
11

add_weighted_edge(u_of_edge, v_of_edge, weight)

Add a weighted edge

Parameters

• u_of_edge (start node) –

• v_of_edge (end node) –

• weight (weight value) –

Examples

Add a weighted edge

>>> G.add_weighted_edge( 1 , 3 , 1.0)

property adj

Return the adjacency matrix

adjlist_inner_dict_factory

alias of dict

adjlist_outer_dict_factory

alias of dict

all_neighbors(node)

Returns an iterator of a node’s neighbors, including both successors and predecessors.

Parameters

node (Hashable) – The target node.

Returns

neighbors – An iterator of a node’s neighbors, including both successors and predecessors.

Return type

iterator

Examples

>>> G = eg.Graph()
>>> G.add_edges([(1,2), (2,3), (2,4)])
>>> for neighbor in G.all_neighbors(node=2):
...     print(neighbor)

copy()

Return a deep copy of the graph.

Returns

copy – A deep copy of the original graph.

Return type

easygraph.DiGraph

Examples

G2 is a deep copy of G1

>>> G2 = G1.copy()

cpp()

degree(weight='weight')

Returns the weighted degree of each node, i.e. sum of out/in degree.

Parameters

weight (string, optional (default : 'weight')) – Weight key of the original weighted graph.

Returns

degree – Each node’s (key) weighted in degree (value). For directed graph, it returns the sum of out degree and in degree.

Return type

dict

Notes

If the graph is not weighted, all the weights will be regarded as 1.

See also

out_degree, in_degree

Examples

>>> G.degree()
>>> G.degree(weight='weight')

or you can customize the weight key

>>> G.degree(weight='weight_1')

edge_attr_dict_factory

alias of dict

property edges

Return an edge list

ego_subgraph(center)

Returns an ego network graph of a node.

Parameters

center (object) – The center node of the ego network graph

Returns

ego_subgraph – The ego network graph of center.

Return type

easygraph.Graph

Examples

>>> G = eg.Graph()
>>> G.add_edges([
...     ('Jack', 'Maria'),
...     ('Maria', 'Andy'),
...     ('Jack', 'Tom')
... ])
>>> G.ego_subgraph(center='Jack')

gnn_data_dict_factory

alias of dict

graph_attr_dict_factory

alias of dict

has_edge(u, v)

Returns whether an edge exists

Parameters

• u (start node) –

• v (end node) –

Returns

Bool

Return type

True (exist) or False (not exists)

has_node(node)

Returns whether a node exists

Parameters

node –

Returns

Bool

Return type

True (exist) or False (not exists)

in_degree(weight='weight')

Returns the weighted in degree of each node.

Parameters

weight (string, optional (default : 'weight')) – Weight key of the original weighted graph.

Returns

in_degree – Each node’s (key) weighted in degree (value).

Return type

dict

Notes

If the graph is not weighted, all the weights will be regarded as 1.

See also

out_degree, degree

Examples

>>> G.in_degree(weight='weight')

property index2node

Assign an integer index for each node (start from 0)

is_directed()

Returns True if graph is a directed_graph, False otherwise.

is_multigraph()

Returns True if graph is a multigraph, False otherwise.

property name

String identifier of the graph.

This graph attribute appears in the attribute dict G.graph keyed by the string “name”. as well as an attribute (technically a property) G.name. This is entirely user controlled.

nbunch_iter(nbunch=None)

Returns an iterator over nodes contained in nbunch that are also in the graph.

The nodes in nbunch are checked for membership in the graph and if not are silently ignored.

Parameters

nbunch (single node, container, or all nodes (default= all nodes)) – The view will only report edges incident to these nodes.

Returns

niter – An iterator over nodes in nbunch that are also in the graph. If nbunch is None, iterate over all nodes in the graph.

Return type

iterator

Raises

EasyGraphError – If nbunch is not a node or sequence of nodes. If a node in nbunch is not hashable.

See also

Graph.__iter__

Notes

When nbunch is an iterator, the returned iterator yields values directly from nbunch, becoming exhausted when nbunch is exhausted.

To test whether nbunch is a single node, one can use “if nbunch in self:”, even after processing with this routine.

If nbunch is not a node or a (possibly empty) sequence/iterator or None, a EasyGraphError is raised. Also, if any object in nbunch is not hashable, a EasyGraphError is raised.

property ndata

neighbors(node)

Returns an iterator of a node’s neighbors (successors).

Parameters

node (Hashable) – The target node.

Returns

neighbors – An iterator of a node’s neighbors (successors).

Return type

iterator

Examples

>>> G = eg.Graph()
>>> G.add_edges([(1,2), (2,3), (2,4)])
>>> for neighbor in G.neighbors(node=2):
...     print(neighbor)

node_attr_dict_factory

alias of dict

node_dict_factory

alias of dict

property node_index

Assign an integer index for each node (start from 0)

node_index_dict

alias of dict

property nodes

return [node for node in self._node]

nodes_subgraph(from_nodes: list)

Returns a subgraph of some nodes

Parameters

from_nodes (list of object) – The nodes in subgraph.

Returns

nodes_subgraph – The subgraph consisting of from_nodes.

Return type

easygraph.Graph

Examples

>>> G = eg.Graph()
>>> G.add_edges([(1,2), (2,3), (2,4), (4,5)])
>>> G_sub = G.nodes_subgraph(from_nodes= [1,2,3])

number_of_edges(u=None, v=None)

Returns the number of edges between two nodes.

Parameters

• u (nodes, optional (default=all edges)) – If u and v are specified, return the number of edges between u and v. Otherwise return the total number of all edges.

• v (nodes, optional (default=all edges)) – If u and v are specified, return the number of edges between u and v. Otherwise return the total number of all edges.

Returns

nedges – The number of edges in the graph. If nodes u and v are specified return the number of edges between those nodes. If the graph is directed, this only returns the number of edges from u to v.

Return type

int

See also

size

Examples

For undirected graphs, this method counts the total number of edges in the graph:

>>> G = eg.path_graph(4)
>>> G.number_of_edges()
3

If you specify two nodes, this counts the total number of edges joining the two nodes:

>>> G.number_of_edges(0, 1)
1

For directed graphs, this method can count the total number of directed edges from u to v:

>>> G = eg.DiGraph()
>>> G.add_edge(0, 1)
>>> G.add_edge(1, 0)
>>> G.number_of_edges(0, 1)
1

number_of_nodes()

Returns the number of nodes.

Returns

number_of_nodes – The number of nodes.

Return type

int

out_degree(weight='weight')

Returns the weighted out degree of each node.

Parameters

weight (string, optional (default : 'weight')) – Weight key of the original weighted graph.

Returns

out_degree – Each node’s (key) weighted out degree (value).

Return type

dict

Notes

If the graph is not weighted, all the weights will be regarded as 1.

See also

in_degree, degree

Examples

>>> G.out_degree(weight='weight')

property pred

Return the pred of each node

predecessors(node)

Returns an iterator of a node’s neighbors (predecessors).

Parameters

node (Hashable) – The target node.

Returns

neighbors – An iterator of a node’s neighbors (predecessors).

Return type

iterator

Examples

>>> G = eg.Graph()
>>> G.add_edges([(1,2), (2,3), (2,4)])
>>> for predecessor in G.predecessors(node=2):
...     print(predecessor)

remove_edge(u, v)

Remove one edge from your graph.

Parameters

• u (object) – The start end of the edge.

• v (object) – The destination end of the edge.

See also

remove_edges

Examples

Remove edge (1,2) from G

>>> G.remove_edge(1,2)

remove_edges(edges_to_remove: [<class 'tuple'>])

Remove a list of edges from your graph.

Parameters

edges_to_remove (list of tuple) – The list of edges you want to remove, Each element is (u, v) tuple, which denote the start and destination end of the edge, respectively.

See also

remove_edge

Examples

Remove the edges (‘Jack’, ‘Mary’) amd (‘Mary’, ‘Tom’) from G

>>> G.remove_edge([
...     ('Jack', 'Mary'),
...     ('Mary', 'Tom')
... ])

remove_edges_from(ebunch)

Remove all edges specified in ebunch.

Parameters

ebunch (list or container of edge tuples) –

Each edge given in the list or container will be removed from the graph. The edges can be:

• 2-tuples (u, v) edge between u and v.

• 3-tuples (u, v, k) where k is ignored.

See also

remove_edge

remove a single edge

Notes

Will fail silently if an edge in ebunch is not in the graph.

Examples

>>> G = eg.path_graph(4)  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> ebunch = [(1, 2), (2, 3)]
>>> G.remove_edges_from(ebunch)

remove_node(node_to_remove)

Remove one node from your graph.

Parameters

node_to_remove (object) – The node you want to remove.

See also

remove_nodes

Examples

Remove node Jack from G

>>> G.remove_node('Jack')

remove_nodes(nodes_to_remove: list)

Remove nodes from your graph.

Parameters

nodes_to_remove (list of object) – The list of nodes you want to remove.

See also

remove_node

Examples

Remove node [1, 2, ‘a’, ‘b’] from G

>>> G.remove_nodes([1, 2, 'a', 'b'])

size(weight=None)

Returns the number of edges or total of all edge weights.

Parameters

weight (String or None, optional) – The weight key. If None, it will calculate the number of edges, instead of total of all edge weights.

Returns

size – The number of edges or total of all edge weights.

Return type

int or float, optional (default: None)

Examples

Returns the number of edges in G:

>>> G.size()

Returns the total of all edge weights in G:

>>> G.size(weight='weight')

successors(node)

Returns an iterator of a node’s neighbors (successors).

Parameters

node (Hashable) – The target node.

Returns

neighbors – An iterator of a node’s neighbors (successors).

Return type

iterator

Examples

>>> G = eg.Graph()
>>> G.add_edges([(1,2), (2,3), (2,4)])
>>> for neighbor in G.neighbors(node=2):
...     print(neighbor)

to_index_node_graph(begin_index=0)

Returns a deep copy of graph, with each node switched to its index.

Considering that the nodes of your graph may be any possible hashable Python object, you can get an isomorphic graph of the original one, with each node switched to its index.

Parameters

begin_index (int) – The begin index of the index graph.

Returns

• G (easygraph.Graph) – Deep copy of graph, with each node switched to its index.

• index_of_node (dict) – Index of node

• node_of_index (dict) – Node of index

Examples

The following method returns this isomorphic graph and index-to-node dictionary as well as node-to-index dictionary.

>>> G = eg.Graph()
>>> G.add_edges([
...     ('Jack', 'Maria'),
...     ('Maria', 'Andy'),
...     ('Jack', 'Tom')
... ])
>>> G_index_graph, index_of_node, node_of_index = G.to_index_node_graph()

class easygraph.classes.directed_graph.DiGraphC

Bases: DiGraph

cflag = 1

easygraph.classes.directed_multigraph module

class easygraph.classes.directed_multigraph.MultiDiGraph(incoming_graph_data=None, multigraph_input=None, **attr)

Bases: MultiGraph, DiGraph

add_edge(u_for_edge, v_for_edge, key=None, **attr)

Add an edge between u and v.

The nodes u and v will be automatically added if they are not already in the graph.

Edge attributes can be specified with keywords or by directly accessing the edge’s attribute dictionary. See examples below.

Parameters

• u_for_edge (nodes) – Nodes can be, for example, strings or numbers. Nodes must be hashable (and not None) Python objects.

• v_for_edge (nodes) – Nodes can be, for example, strings or numbers. Nodes must be hashable (and not None) Python objects.

• key (hashable identifier, optional (default=lowest unused integer)) – Used to distinguish multiedges between a pair of nodes.

• attr (keyword arguments, optional) – Edge data (or labels or objects) can be assigned using keyword arguments.

Return type

The edge key assigned to the edge.

See also

add_edges_from

add a collection of edges

Notes

To replace/update edge data, use the optional key argument to identify a unique edge. Otherwise a new edge will be created.

EasyGraph algorithms designed for weighted graphs cannot use multigraphs directly because it is not clear how to handle multiedge weights. Convert to Graph using edge attribute ‘weight’ to enable weighted graph algorithms.

Default keys are generated using the method new_edge_key(). This method can be overridden by subclassing the base class and providing a custom new_edge_key() method.

Examples

The following all add the edge e=(1, 2) to graph G:

>>> G = eg.MultiDiGraph()
>>> e = (1, 2)
>>> key = G.add_edge(1, 2)  # explicit two-node form
>>> G.add_edge(*e)  # single edge as tuple of two nodes
1
>>> G.add_edges_from([(1, 2)])  # add edges from iterable container
[2]

Associate data to edges using keywords:

>>> key = G.add_edge(1, 2, weight=3)
>>> key = G.add_edge(1, 2, key=0, weight=4)  # update data for key=0
>>> key = G.add_edge(1, 3, weight=7, capacity=15, length=342.7)

For non-string attribute keys, use subscript notation.

>>> ekey = G.add_edge(1, 2)
>>> G[1][2][0].update({0: 5})
>>> G.edges[1, 2, 0].update({0: 5})

>>>
>>>

property degree

Returns the weighted degree of each node, i.e. sum of out/in degree.

Parameters

weight (string, optional (default : 'weight')) – Weight key of the original weighted graph.

Returns

degree – Each node’s (key) weighted in degree (value). For directed graph, it returns the sum of out degree and in degree.

Return type

dict

Notes

If the graph is not weighted, all the weights will be regarded as 1.

See also

out_degree, in_degree

Examples

>>> G.degree()
>>> G.degree(weight='weight')

or you can customize the weight key

>>> G.degree(weight='weight_1')

edge_key_dict_factory

alias of dict

property edges

Return an edge list

property in_degree

Returns the weighted in degree of each node.

Parameters

weight (string, optional (default : 'weight')) – Weight key of the original weighted graph.

Returns

in_degree – Each node’s (key) weighted in degree (value).

Return type

dict

Notes

If the graph is not weighted, all the weights will be regarded as 1.

See also

out_degree, degree

Examples

>>> G.in_degree(weight='weight')

property in_edges

is_directed()

Returns True if graph is directed, False otherwise.

is_multigraph()

Returns True if graph is a multigraph, False otherwise.

property out_degree

Returns the weighted out degree of each node.

Parameters

weight (string, optional (default : 'weight')) – Weight key of the original weighted graph.

Returns

out_degree – Each node’s (key) weighted out degree (value).

Return type

dict

Notes

If the graph is not weighted, all the weights will be regarded as 1.

See also

in_degree, degree

Examples

>>> G.out_degree(weight='weight')

property out_edges

Return an edge list

remove_edge(u, v, key=None)

Remove an edge between u and v.

Parameters

• u (nodes) – Remove an edge between nodes u and v.

• v (nodes) – Remove an edge between nodes u and v.

• key (hashable identifier, optional (default=None)) – Used to distinguish multiple edges between a pair of nodes. If None remove a single (arbitrary) edge between u and v.

Raises

EasyGraphError – If there is not an edge between u and v, or if there is no edge with the specified key.

See also

remove_edges_from

remove a collection of edges

Examples

>>> G = eg.MultiDiGraph()
>>> G.add_edges_from([(1, 2), (1, 2), (1, 2)])  # key_list returned
[0, 1, 2]
>>> G.remove_edge(1, 2)  # remove a single (arbitrary) edge

For edges with keys

>>> G = eg.MultiDiGraph()
>>> G.add_edge(1, 2, key="first")
'first'
>>> G.add_edge(1, 2, key="second")
'second'
>>> G.remove_edge(1, 2, key="second")

reverse(copy=True)

Returns the reverse of the graph.

The reverse is a graph with the same nodes and edges but with the directions of the edges reversed.

Parameters

copy (bool optional (default=True)) – If True, return a new DiGraph holding the reversed edges. If False, the reverse graph is created using a view of the original graph.

to_undirected(reciprocal=False)

Returns an undirected representation of the multidigraph.

Parameters

reciprocal (bool (optional)) – If True only keep edges that appear in both directions in the original digraph.

Returns

G – An undirected graph with the same name and nodes and with edge (u, v, data) if either (u, v, data) or (v, u, data) is in the digraph. If both edges exist in digraph and their edge data is different, only one edge is created with an arbitrary choice of which edge data to use. You must check and correct for this manually if desired.

Return type

MultiGraph

See also

MultiGraph, add_edge, add_edges_from

Notes

This returns a “deepcopy” of the edge, node, and graph attributes which attempts to completely copy all of the data and references.

This is in contrast to the similar D=MultiDiGraph(G) which returns a shallow copy of the data.

See the Python copy module for more information on shallow and deep copies, https://docs.python.org/3/library/copy.html.

Warning: If you have subclassed MultiDiGraph to use dict-like objects in the data structure, those changes do not transfer to the MultiGraph created by this method.

Examples

>>> G = eg.path_graph(2)  # or MultiGraph, etc
>>> H = G.to_directed()
>>> list(H.edges)
[(0, 1), (1, 0)]
>>> G2 = H.to_undirected()
>>> list(G2.edges)
[(0, 1)]

easygraph.classes.graph module

class easygraph.classes.graph.Graph(incoming_graph_data=None, extra_selfloop=False, **graph_attr)

Bases: object

Base class for undirected graphs.

Nodes are allowed for any hashable Python objects, including int, string, dict, etc. Edges are stored as Python dict type, with optional key/value attributes.

Parameters

graph_attr (keywords arguments, optional (default : None)) – Attributes to add to graph as key=value pairs.

See also

DiGraph

Examples

Create an empty undirected graph with no nodes and edges.

>>> G = eg.Graph()

Create a deep copy graph G2 from existing Graph G1.

>>> G2 = G1.copy()

Create an graph with attributes.

>>> G = eg.Graph(name='Karate Club', date='2020.08.21')

Attributes:

Returns the adjacency matrix of the graph.

>>> G.adj

Returns all the nodes with their attributes.

>>> G.nodes

Returns all the edges with their attributes.

>>> G.edges

property A

Return the adjacency matrix \(\mathbf{A}\) of the sample graph with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property D_v

Return the diagonal matrix of vertex degree \(\mathbf{D}_v\) with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property D_v_neg_1_2

Return the normalized diagonal matrix of vertex degree \(\mathbf{D}_v^{-\frac{1}{2}}\) with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

property L_GCN

Return the GCN Laplacian matrix \(\mathcal{L}_{GCN}\) of the graph with torch.sparse_coo_tensor format. Size \((|\mathcal{V}|, |\mathcal{V}|)\).

\[\mathcal{L}_{GCN} = \mathbf{\hat{D}}_v^{-\frac{1}{2}} \mathbf{\hat{A}} \mathbf{\hat{D}}_v^{-\frac{1}{2}}\]

N_v(v_idx: int) → Tuple[List[int], List[float]]

add_edge(u_of_edge, v_of_edge, **edge_attr)

Add one edge.

Parameters

• u_of_edge (object) – One end of this edge

• v_of_edge (object) – The other one end of this edge

• edge_attr (keywords arguments, optional) – The attribute of the edge.

Notes

Nodes of this edge will be automatically added to the graph, if they do not exist.

See also

add_edges

Examples

>>> G.add_edge(1,2)
>>> G.add_edge('Jack', 'Tom', weight=10)

Add edge with attributes, edge weight, for example,

>>> G.add_edge(1, 2, **{
...     'weight': 20
... })

add_edges(edges_for_adding, edges_attr: List[Dict] = [])

Add a list of edges.

Parameters

• edges_for_adding (list of 2-element tuple) – The edges for adding. Each element is a (u, v) tuple, and u, v are two ends of the edge.

• edges_attr (list of dict, optional) – The corresponding attributes for each edge in edges_for_adding.

Examples

Add a list of edges into G

>>> G.add_edges([
...     (1, 2),
...     (3, 4),
...     ('Jack', 'Tom')
... ])

Add edge with attributes, for example, edge weight,

>>> G.add_edges([(1,2), (2, 3)], edges_attr=[
...     {
...         'weight': 20
...     },
...     {
...         'weight': 15
...     }
... ])

add_edges_from(ebunch_to_add, **attr)

Add all the edges in ebunch_to_add.

Parameters

• ebunch_to_add (container of edges) – Each edge given in the container will be added to the graph. The edges must be given as 2-tuples (u, v) or 3-tuples (u, v, d) where d is a dictionary containing edge data.

• attr (keyword arguments, optional) – Edge data (or labels or objects) can be assigned using keyword arguments.

See also

add_edge

add a single edge

add_weighted_edges_from

convenient way to add weighted edges

Notes

Adding the same edge twice has no effect but any edge data will be updated when each duplicate edge is added.

Edge attributes specified in an ebunch take precedence over attributes specified via keyword arguments.

Examples

>>> G = eg.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G.add_edges_from([(0, 1), (1, 2)])  # using a list of edge tuples
>>> e = zip(range(0, 3), range(1, 4))
>>> G.add_edges_from(e)  # Add the path graph 0-1-2-3

Associate data to edges

>>> G.add_edges_from([(1, 2), (2, 3)], weight=3)
>>> G.add_edges_from([(3, 4), (1, 4)], label="WN2898")

add_edges_from_file(file, weighted=False)

Added edges from file For example, txt files,

Each line is in form like: a b 23.0 which denotes an edge (a, b) with weight 23.0.

Parameters

• file (string) – The file path.

• weighted (boolean, optional (default : False)) – If the file consists of weight information, set True. The weight key will be set as ‘weight’.

Examples

If ./club_network.txt is:

Jack Mary 23.0

Mary Tom 15.0

Tom Ben 20.0

Then add them to G

>>> G.add_edges_from_file(file='./club_network.txt', weighted=True)

add_extra_selfloop()

Add extra selfloops to the graph.

add_node(node_for_adding, **node_attr)

Add one node

Add one node, type of which is any hashable Python object, such as int, string, dict, or even Graph itself. You can add with node attributes using Python dict type.

Parameters

• node_for_adding (any hashable Python object) – Nodes for adding.

• node_attr (keywords arguments, optional) – The node attributes. You can customize them with different key-value pairs.

See also

add_nodes

Examples

>>> G.add_node('a')
>>> G.add_node('hello world')
>>> G.add_node('Jack', age=10)

>>> G.add_node('Jack', **{
...     'age': 10,
...     'gender': 'M'
... })

add_nodes(nodes_for_adding: list, nodes_attr: List[Dict] = [])

Add nodes with a list of nodes.

Parameters

• nodes_for_adding (list) –

• nodes_attr (list of dict) – The corresponding attribute for each of nodes_for_adding.

See also

add_node

Examples

Add nodes with a list of nodes. You can add with node attributes using a list of Python dict type, each of which is the attribute of each node, respectively.

>>> G.add_nodes([1, 2, 'a', 'b'])
>>> G.add_nodes(range(1, 200))

>>> G.add_nodes(['Jack', 'Tom', 'Lily'], nodes_attr=[
...     {
...         'age': 10,
...         'gender': 'M'
...     },
...     {
...         'age': 11,
...         'gender': 'M'
...     },
...     {
...         'age': 10,
...         'gender': 'F'
...     }
... ])

add_nodes_from(nodes_for_adding, **attr)

Add multiple nodes.

Parameters

• nodes_for_adding (iterable container) – A container of nodes (list, dict, set, etc.). OR A container of (node, attribute dict) tuples. Node attributes are updated using the attribute dict.

• attr (keyword arguments, optional (default= no attributes)) – Update attributes for all nodes in nodes. Node attributes specified in nodes as a tuple take precedence over attributes specified via keyword arguments.

See also

add_node

Examples

>>> G = eg.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G.add_nodes_from("Hello")
>>> K3 = eg.Graph([(0, 1), (1, 2), (2, 0)])
>>> G.add_nodes_from(K3)
>>> sorted(G.nodes(), key=str)
[0, 1, 2, 'H', 'e', 'l', 'o']

Use keywords to update specific node attributes for every node.

>>> G.add_nodes_from([1, 2], size=10)
>>> G.add_nodes_from([3, 4], weight=0.4)

Use (node, attrdict) tuples to update attributes for specific nodes.

>>> G.add_nodes_from([(1, dict(size=11)), (2, {"color": "blue"})])
>>> G.nodes[1]["size"]
11
>>> H = eg.Graph()
>>> H.add_nodes_from(G.nodes(data=True))
>>> H.nodes[1]["size"]
11

add_weighted_edge(u_of_edge, v_of_edge, weight)

Add a weighted edge

Parameters

• u_of_edge (start node) –

• v_of_edge (end node) –

• weight (weight value) –

Examples

Add a weighted edge

>>> G.add_weighted_edge( 1 , 3 , 1.0)

add_weighted_edges_from(ebunch_to_add, weight='weight', **attr)

Add weighted edges in ebunch_to_add with specified weight attr

Parameters

• ebunch_to_add (container of edges) – Each edge given in the list or container will be added to the graph. The edges must be given as 3-tuples (u, v, w) where w is a number.

• weight (string, optional (default= 'weight')) – The attribute name for the edge weights to be added.

• attr (keyword arguments, optional (default= no attributes)) – Edge attributes to add/update for all edges.

See also

add_edge

add a single edge

add_edges_from

add multiple edges

Notes

Adding the same edge twice for Graph/DiGraph simply updates the edge data. For MultiGraph/MultiDiGraph, duplicate edges are stored.

Examples

>>> G = eg.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G.add_weighted_edges_from([(0, 1, 3.0), (1, 2, 7.5)])

property adj

Return the adjacency matrix

adjlist_inner_dict_factory

alias of dict

adjlist_outer_dict_factory

alias of dict

all_neighbors(node)

Returns an iterator of a node’s neighbors.

Parameters

node (Hashable) – The target node.

Returns

neighbors – An iterator of a node’s neighbors.

Return type

iterator

Examples

>>> G = eg.Graph()
>>> G.add_edges([(1,2), (2,3), (2,4)])
>>> for neighbor in G.neighbors(node=2):
...     print(neighbor)

clone()

Clone the graph.

copy()

Return a deep copy of the graph.

Returns

copy – A deep copy of the original graph.

Return type

easygraph.Graph

Examples

G2 is a deep copy of G1

>>> G2 = G1.copy()

cpp()

degree(weight='weight')

Returns the weighted degree of of each node.

Parameters

weight (string, optional (default: 'weight')) – Weight key of the original weighted graph.

Returns

degree – Each node’s (key) weighted degree (value).

Return type

dict

Notes

If the graph is not weighted, all the weights will be regarded as 1.

Examples

You can call with no attributes, if ‘weight’ is the weight key:

>>> G.degree()

if you have customized weight key ‘weight_1’.

>>> G.degree(weight='weight_1')

property e: Tuple[List[List[int]], List[float]]

Return the edge list, weight list and property list in the graph.

property e_both_side: Tuple[List[List], List[float]]

Return the list of edges including both directions.

edge_attr_dict_factory

alias of dict

property edges

Return an edge list

ego_subgraph(center)

Returns an ego network graph of a node.

Parameters

center (object) – The center node of the ego network graph

Returns

ego_subgraph – The ego network graph of center.

Return type

easygraph.Graph

Examples

>>> G = eg.Graph()
>>> G.add_edges([
...     ('Jack', 'Maria'),
...     ('Maria', 'Andy'),
...     ('Jack', 'Tom')
... ])
>>> G.ego_subgraph(center='Jack')

gnn_data_dict_factory

alias of dict

graph_attr_dict_factory

alias of dict

has_edge(u, v)

Returns whether an edge exists

Parameters

• u (start node) –

• v (end node) –

Returns

Bool

Return type

True (exist) or False (not exists)

has_node(node)

Returns whether a node exists

Parameters

node –

Returns

Bool

Return type

True (exist) or False (not exists)

property index2node

Assign an integer index for each node (start from 0)

is_directed()

Returns True if graph is a directed_graph, False otherwise.

is_multigraph()

Returns True if graph is a multigraph, False otherwise.

property name

String identifier of the graph.

This graph attribute appears in the attribute dict G.graph keyed by the string “name”. as well as an attribute (technically a property) G.name. This is entirely user controlled.

nbr_v(v_idx: int) → Tuple[List[int], List[float]]

Return a vertex list of the neighbors of the vertex v_idx.

Parameters

v_idx (int) – The index of the vertex.

nbunch_iter(nbunch=None)

Returns an iterator over nodes contained in nbunch that are also in the graph.

The nodes in nbunch are checked for membership in the graph and if not are silently ignored.

Parameters

nbunch (single node, container, or all nodes (default= all nodes)) – The view will only report edges incident to these nodes.

Returns

niter – An iterator over nodes in nbunch that are also in the graph. If nbunch is None, iterate over all nodes in the graph.

Return type

iterator

Raises

EasyGraphError – If nbunch is not a node or sequence of nodes. If a node in nbunch is not hashable.

See also

Graph.__iter__

Notes

When nbunch is an iterator, the returned iterator yields values directly from nbunch, becoming exhausted when nbunch is exhausted.

To test whether nbunch is a single node, one can use “if nbunch in self:”, even after processing with this routine.

If nbunch is not a node or a (possibly empty) sequence/iterator or None, a EasyGraphError is raised. Also, if any object in nbunch is not hashable, a EasyGraphError is raised.

property ndata

neighbors(node)

Returns an iterator of a node’s neighbors.

Parameters

node (Hashable) – The target node.

Returns

neighbors – An iterator of a node’s neighbors.

Return type

iterator

Examples

>>> G = eg.Graph()
>>> G.add_edges([(1,2), (2,3), (2,4)])
>>> for neighbor in G.neighbors(node=2):
...     print(neighbor)

node_attr_dict_factory

alias of dict

node_dict_factory

alias of dict

property node_index

Assign an integer index for each node (start from 0)

node_index_dict

alias of dict

property nodes

return [node for node in self._node]

nodes_subgraph(from_nodes: list)

Returns a subgraph of some nodes

Parameters

from_nodes (list of object) – The nodes in subgraph.

Returns

nodes_subgraph – The subgraph consisting of from_nodes.

Return type

easygraph.Graph

Examples

>>> G = eg.Graph()
>>> G.add_edges([(1,2), (2,3), (2,4), (4,5)])
>>> G_sub = G.nodes_subgraph(from_nodes= [1,2,3])

number_of_edges(u=None, v=None)

Returns the number of edges between two nodes.

Parameters

• u (nodes, optional (default=all edges)) – If u and v are specified, return the number of edges between u and v. Otherwise return the total number of all edges.

• v (nodes, optional (default=all edges)) – If u and v are specified, return the number of edges between u and v. Otherwise return the total number of all edges.

Returns

nedges – The number of edges in the graph. If nodes u and v are specified return the number of edges between those nodes. If the graph is directed, this only returns the number of edges from u to v.

Return type

int

See also

size

Examples

For undirected graphs, this method counts the total number of edges in the graph:

>>> G = eg.path_graph(4)
>>> G.number_of_edges()
3

If you specify two nodes, this counts the total number of edges joining the two nodes:

>>> G.number_of_edges(0, 1)
1

For directed graphs, this method can count the total number of directed edges from u to v:

>>> G = eg.DiGraph()
>>> G.add_edge(0, 1)
>>> G.add_edge(1, 0)
>>> G.number_of_edges(0, 1)
1

number_of_nodes()

Returns the number of nodes.

Returns

number_of_nodes – The number of nodes.

Return type

int

order()

Returns the number of nodes in the graph.

Returns

nnodes – The number of nodes in the graph.

Return type

int

See also

number_of_nodes

identical method

__len__

identical method

Examples

>>> G = eg.path_graph(3)  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G.order()
3

raw_selfloop_dict

alias of dict

remove_edge(u, v)

Remove one edge from your graph.

Parameters

• u (object) – One end of the edge.

• v (object) – The other end of the edge.

See also

remove_edges

Examples

Remove edge (1,2) from G

>>> G.remove_edge(1,2)

remove_edges(edges_to_remove: [<class 'tuple'>])

Remove a list of edges from your graph.

Parameters

edges_to_remove (list of tuple) – The list of edges you want to remove, Each element is (u, v) tuple, which denote the two ends of the edge.

See also

remove_edge

Examples

Remove the edges (‘Jack’, ‘Mary’) and (‘Mary’, ‘Tom’) from G

>>> G.remove_edge([
...     ('Jack', 'Mary'),
...     ('Mary', 'Tom')
... ])

remove_extra_selfloop()

Remove extra selfloops from the graph.

remove_node(node_to_remove)

Remove one node from your graph.

Parameters

node_to_remove (object) – The node you want to remove.

See also

remove_nodes

Examples

Remove node Jack from G

>>> G.remove_node('Jack')

remove_nodes(nodes_to_remove: list)

Remove nodes from your graph.

Parameters

nodes_to_remove (list of object) – The list of nodes you want to remove.

See also

remove_node

Examples

Remove node [1, 2, ‘a’, ‘b’] from G

>>> G.remove_nodes([1, 2, 'a', 'b'])

remove_nodes_from(nodes)

Remove multiple nodes.

Parameters

nodes (iterable container) – A container of nodes (list, dict, set, etc.). If a node in the container is not in the graph it is silently ignored.

See also

remove_node

Examples

>>> G = eg.path_graph(3)  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> e = list(G.nodes)
>>> e
[0, 1, 2]
>>> G.remove_nodes_from(e)
>>> list(G.nodes)
[]

remove_selfloop()

Remove all selfloops from the graph.

size(weight=None)

Returns the number of edges or total of all edge weights.

Parameters

weight (String or None, optional) – The weight key. If None, it will calculate the number of edges, instead of total of all edge weights.

Returns

size – The number of edges or total of all edge weights.

Return type

int or float, optional (default: None)

Examples

Returns the number of edges in G:

>>> G.size()

Returns the total of all edge weights in G:

>>> G.size(weight='weight')

smoothing_with_GCN(X, drop_rate=0.0)

Return the smoothed feature matrix with GCN Laplacian matrix \(\mathcal{L}_{GCN}\).

Parameters

• X (torch.Tensor) – Vertex feature matrix. Size \((|\mathcal{V}|, C)\).

• drop_rate (float) – Dropout rate. Randomly dropout the connections in adjacency matrix with probability drop_rate. Default: 0.0.

to_directed()

Creates and returns a directed graph from self.

Returns

G – A directed graph with identical name and nodes. Each undirected edge (u, v, data) in the original graph is replaced by two directed edges (u, v, data) and (v, u, data).

Return type

DiGraph

Notes

This function returns a deepcopy of the original graph, including all nodes, edges, and graph. As a result, it fully duplicates the data and references in the original graph.

This function differs from D=DiGraph(G) which returns a shallow copy.

For more details on shallow and deep copies, refer to the Python copy module: https://docs.python.org/3/library/copy.html.

Warning: If the original graph is a subclass of Graph using custom dict-like objects for its data structure, those customizations will not be preserved in the DiGraph created by this function.

Examples

Converting an undirected graph to a directed graph:

>>> G = eg.Graph()  # or MultiGraph, etc
>>> G.add_edge(0, 1)
>>> H = G.to_directed()
>>> list(H.edges)
[(0, 1), (1, 0)]

Creating a deep copy of an already directed graph:

>>> G = eg.DiGraph()  # or MultiDiGraph, etc
>>> G.add_edge(0, 1)
>>> H = G.to_directed()
>>> list(H.edges)
[(0, 1)]

to_directed_class()

Returns the class to use for empty directed copies.

If you subclass the base classes, use this to designate what directed class to use for to_directed() copies.

to_index_node_graph(begin_index=0)

Returns a deep copy of graph, with each node switched to its index.

Considering that the nodes of your graph may be any possible hashable Python object, you can get an isomorphic graph of the original one, with each node switched to its index.

Parameters

begin_index (int) – The begin index of the index graph.

Returns

• G (easygraph.Graph) – Deep copy of graph, with each node switched to its index.

• index_of_node (dict) – Index of node

• node_of_index (dict) – Node of index

Examples

The following method returns this isomorphic graph and index-to-node dictionary as well as node-to-index dictionary.

>>> G = eg.Graph()
>>> G.add_edges([
...     ('Jack', 'Maria'),
...     ('Maria', 'Andy'),
...     ('Jack', 'Tom')
... ])
>>> G_index_graph, index_of_node, node_of_index = G.to_index_node_graph()

class easygraph.classes.graph.GraphC

Bases: Graph

cflag = 1

easygraph.classes.graphviews module

easygraph.classes.graphviews.reverse_view(G)

easygraph.classes.hypergraph module

easygraph.classes.multigraph module

Base class for MultiGraph.

class easygraph.classes.multigraph.MultiGraph(incoming_graph_data=None, multigraph_input=None, **attr)

Bases: Graph

add_edge(u_for_edge, v_for_edge, key=None, **attr)

Add an edge between u and v.

The nodes u and v will be automatically added if they are not already in the graph.

Edge attributes can be specified with keywords or by directly accessing the edge’s attribute dictionary. See examples below.

Parameters

• u_for_edge (nodes) – Nodes can be, for example, strings or numbers. Nodes must be hashable (and not None) Python objects.

• v_for_edge (nodes) – Nodes can be, for example, strings or numbers. Nodes must be hashable (and not None) Python objects.

• key (hashable identifier, optional (default=lowest unused integer)) – Used to distinguish multiedges between a pair of nodes.

• attr (keyword arguments, optional) – Edge data (or labels or objects) can be assigned using keyword arguments.

Return type

The edge key assigned to the edge.

See also

add_edges_from

add a collection of edges

Notes

To replace/update edge data, use the optional key argument to identify a unique edge. Otherwise a new edge will be created.

EasyGraph algorithms designed for weighted graphs cannot use multigraphs directly because it is not clear how to handle multiedge weights. Convert to Graph using edge attribute ‘weight’ to enable weighted graph algorithms.

Default keys are generated using the method new_edge_key(). This method can be overridden by subclassing the base class and providing a custom new_edge_key() method.

Examples

The following all add the edge e=(1, 2) to graph G:

>>> G = eg.MultiGraph()
>>> e = (1, 2)
>>> ekey = G.add_edge(1, 2)  # explicit two-node form
>>> G.add_edge(*e)  # single edge as tuple of two nodes
1
>>> G.add_edges_from([(1, 2)])  # add edges from iterable container
[2]

Associate data to edges using keywords:

>>> ekey = G.add_edge(1, 2, weight=3)
>>> ekey = G.add_edge(1, 2, key=0, weight=4)  # update data for key=0
>>> ekey = G.add_edge(1, 3, weight=7, capacity=15, length=342.7)

For non-string attribute keys, use subscript notation.

>>> ekey = G.add_edge(1, 2)
>>> G[1][2][0].update({0: 5})
>>> G.edges[1, 2, 0].update({0: 5})

add_edges_from(ebunch_to_add, **attr)

Add all the edges in ebunch_to_add.

Parameters

• ebunch_to_add (container of edges) –

  Each edge given in the container will be added to the graph. The edges can be:

  • 2-tuples (u, v) or

  • 3-tuples (u, v, d) for an edge data dict d, or

  • 3-tuples (u, v, k) for not iterable key k, or

  • 4-tuples (u, v, k, d) for an edge with data and key k

• attr (keyword arguments, optional) – Edge data (or labels or objects) can be assigned using keyword arguments.

Return type

A list of edge keys assigned to the edges in ebunch.

See also

add_edge

add a single edge

add_weighted_edges_from

convenient way to add weighted edges

Notes

Adding the same edge twice has no effect but any edge data will be updated when each duplicate edge is added.

Edge attributes specified in an ebunch take precedence over attributes specified via keyword arguments.

Default keys are generated using the method new_edge_key(). This method can be overridden by subclassing the base class and providing a custom new_edge_key() method.

Examples

>>> G = eg.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G.add_edges_from([(0, 1), (1, 2)])  # using a list of edge tuples
>>> e = zip(range(0, 3), range(1, 4))
>>> G.add_edges_from(e)  # Add the path graph 0-1-2-3

Associate data to edges

>>> G.add_edges_from([(1, 2), (2, 3)], weight=3)
>>> G.add_edges_from([(3, 4), (1, 4)], label="WN2898")

copy()

Returns a copy of the graph.

The copy method by default returns an independent shallow copy of the graph and attributes. That is, if an attribute is a container, that container is shared by the original an the copy. Use Python’s copy.deepcopy for new containers.

Notes

All copies reproduce the graph structure, but data attributes may be handled in different ways. There are four types of copies of a graph that people might want.

Deepcopy – A “deepcopy” copies the graph structure as well as all data attributes and any objects they might contain. The entire graph object is new so that changes in the copy do not affect the original object. (see Python’s copy.deepcopy)

Data Reference (Shallow) – For a shallow copy the graph structure is copied but the edge, node and graph attribute dicts are references to those in the original graph. This saves time and memory but could cause confusion if you change an attribute in one graph and it changes the attribute in the other. EasyGraph does not provide this level of shallow copy.

Independent Shallow – This copy creates new independent attribute dicts and then does a shallow copy of the attributes. That is, any attributes that are containers are shared between the new graph and the original. This is exactly what dict.copy() provides. You can obtain this style copy using:

>>> G = eg.path_graph(5)
>>> H = G.copy()
>>> H = eg.Graph(G)
>>> H = G.__class__(G)

Fresh Data – For fresh data, the graph structure is copied while new empty data attribute dicts are created. The resulting graph is independent of the original and it has no edge, node or graph attributes. Fresh copies are not enabled. Instead use:

>>> H = G.__class__()
>>> H.add_nodes_from(G)
>>> H.add_edges_from(G.edges)

See the Python copy module for more information on shallow and deep copies, https://docs.python.org/3/library/copy.html.

Returns

G – A copy of the graph.

Return type

Graph

See also

to_directed

return a directed copy of the graph.

Examples

>>> G = eg.path_graph(4)  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> H = G.copy()

property degree

Returns the weighted degree of of each node.

Parameters

weight (string, optional (default: 'weight')) – Weight key of the original weighted graph.

Returns

degree – Each node’s (key) weighted degree (value).

Return type

dict

Notes

If the graph is not weighted, all the weights will be regarded as 1.

Examples

You can call with no attributes, if ‘weight’ is the weight key:

>>> G.degree()

if you have customized weight key ‘weight_1’.

>>> G.degree(weight='weight_1')

edge_key_dict_factory

alias of dict

property edges

Return an edge list

get_edge_data(u, v, key=None, default=None)

Returns the attribute dictionary associated with edge (u, v).

This is identical to G[u][v][key] except the default is returned instead of an exception is the edge doesn’t exist.

Parameters

• u (nodes) –

• v (nodes) –

• default (any Python object (default=None)) – Value to return if the edge (u, v) is not found.

• key (hashable identifier, optional (default=None)) – Return data only for the edge with specified key.

Returns

edge_dict – The edge attribute dictionary.

Return type

dictionary

Examples

>>> G = eg.MultiGraph()  # or MultiDiGraph
>>> key = G.add_edge(0, 1, key="a", weight=7)
>>> G[0][1]["a"]  # key='a'
{'weight': 7}
>>> G.edges[0, 1, "a"]  # key='a'
{'weight': 7}

Warning: we protect the graph data structure by making G.edges and G[1][2] read-only dict-like structures. However, you can assign values to attributes in e.g. G.edges[1, 2, ‘a’] or G[1][2][‘a’] using an additional bracket as shown next. You need to specify all edge info to assign to the edge data associated with an edge.

>>> G[0][1]["a"]["weight"] = 10
>>> G.edges[0, 1, "a"]["weight"] = 10
>>> G[0][1]["a"]["weight"]
10
>>> G.edges[1, 0, "a"]["weight"]
10

>>> G = eg.MultiGraph()  # or MultiDiGraph
>>> G = eg.complete_graph(4, create_using=eg.MultiDiGraph)
>>> G.get_edge_data(0, 1)
{0: {}}
>>> e = (0, 1)
>>> G.get_edge_data(*e)  # tuple form
{0: {}}
>>> G.get_edge_data("a", "b", default=0)  # edge not in graph, return 0
0

has_edge(u, v, key=None)

Returns True if the graph has an edge between nodes u and v.

This is the same as v in G[u] or key in G[u][v] without KeyError exceptions.

Parameters

• u (nodes) – Nodes can be, for example, strings or numbers.

• v (nodes) – Nodes can be, for example, strings or numbers.

• key (hashable identifier, optional (default=None)) – If specified return True only if the edge with key is found.

Returns

edge_ind – True if edge is in the graph, False otherwise.

Return type

bool

Examples

Can be called either using two nodes u, v, an edge tuple (u, v), or an edge tuple (u, v, key).

>>> G = eg.MultiGraph()  # or MultiDiGraph
>>> G = eg.complete_graph(4, create_using=eg.MultiDiGraph)
>>> G.has_edge(0, 1)  # using two nodes
True
>>> e = (0, 1)
>>> G.has_edge(*e)  #  e is a 2-tuple (u, v)
True
>>> G.add_edge(0, 1, key="a")
'a'
>>> G.has_edge(0, 1, key="a")  # specify key
True
>>> e = (0, 1, "a")
>>> G.has_edge(*e)  # e is a 3-tuple (u, v, 'a')
True

The following syntax are equivalent:

>>> G.has_edge(0, 1)
True
>>> 1 in G[0]  # though this gives :exc:`KeyError` if 0 not in G
True

is_directed()

Returns True if graph is directed, False otherwise.

is_multigraph()

Returns True if graph is a multigraph, False otherwise.

new_edge_key(u, v)

Returns an unused key for edges between nodes u and v.

The nodes u and v do not need to be already in the graph.

Notes

In the standard MultiGraph class the new key is the number of existing edges between u and v (increased if necessary to ensure unused). The first edge will have key 0, then 1, etc. If an edge is removed further new_edge_keys may not be in this order.

Parameters

• u (nodes) –

• v (nodes) –

Returns

key

Return type

int

number_of_edges(u=None, v=None)

Returns the number of edges between two nodes.

Parameters

• u (nodes, optional (Gefault=all edges)) – If u and v are specified, return the number of edges between u and v. Otherwise return the total number of all edges.

• v (nodes, optional (Gefault=all edges)) – If u and v are specified, return the number of edges between u and v. Otherwise return the total number of all edges.

Returns

nedges – The number of edges in the graph. If nodes u and v are specified return the number of edges between those nodes. If the graph is directed, this only returns the number of edges from u to v.

Return type

int

See also

size

Examples

For undirected multigraphs, this method counts the total number of edges in the graph:

>>> G = eg.MultiGraph()
>>> G.add_edges_from([(0, 1), (0, 1), (1, 2)])
[0, 1, 0]
>>> G.number_of_edges()
3

If you specify two nodes, this counts the total number of edges joining the two nodes:

>>> G.number_of_edges(0, 1)
2

For directed multigraphs, this method can count the total number of directed edges from u to v:

>>> G = eg.MultiDiGraph()
>>> G.add_edges_from([(0, 1), (0, 1), (1, 0)])
[0, 1, 0]
>>> G.number_of_edges(0, 1)
2
>>> G.number_of_edges(1, 0)
1

remove_edge(u, v, key=None)

Remove an edge between u and v.

Parameters

• u (nodes) – Remove an edge between nodes u and v.

• v (nodes) – Remove an edge between nodes u and v.

• key (hashable identifier, optional (default=None)) – Used to distinguish multiple edges between a pair of nodes. If None remove a single (arbitrary) edge between u and v.

Raises

EasyGraphError – If there is not an edge between u and v, or if there is no edge with the specified key.

See also

remove_edges_from

remove a collection of edges

Examples

For multiple edges

>>> G = eg.MultiGraph()  # or MultiDiGraph, etc
>>> G.add_edges_from([(1, 2), (1, 2), (1, 2)])  # key_list returned
[0, 1, 2]
>>> G.remove_edge(1, 2)  # remove a single (arbitrary) edge

For edges with keys

>>> G = eg.MultiGraph()  # or MultiDiGraph, etc
>>> G.add_edge(1, 2, key="first")
'first'
>>> G.add_edge(1, 2, key="second")
'second'
>>> G.remove_edge(1, 2, key="second")

remove_edges_from(ebunch)

Remove all edges specified in ebunch.

Parameters

ebunch (list or container of edge tuples) –

Each edge given in the list or container will be removed from the graph. The edges can be:

• 2-tuples (u, v) All edges between u and v are removed.

• 3-tuples (u, v, key) The edge identified by key is removed.

• 4-tuples (u, v, key, data) where data is ignored.

See also

remove_edge

remove a single edge

Notes

Will fail silently if an edge in ebunch is not in the graph.

Examples

Removing multiple copies of edges

>>> G = eg.MultiGraph()
>>> keys = G.add_edges_from([(1, 2), (1, 2), (1, 2)])
>>> G.remove_edges_from([(1, 2), (1, 2)])
>>> list(G.edges())
[(1, 2)]
>>> G.remove_edges_from([(1, 2), (1, 2)])  # silently ignore extra copy
>>> list(G.edges)  # now empty graph
[]

to_directed()

Returns a directed representation of the graph.

Returns

G – A directed graph with the same name, same nodes, and with each edge (u, v, data) replaced by two directed edges (u, v, data) and (v, u, data).

Return type

MultiDiGraph

Notes

This returns a “deepcopy” of the edge, node, and graph attributes which attempts to completely copy all of the data and references.

This is in contrast to the similar D=DiGraph(G) which returns a shallow copy of the data.

See the Python copy module for more information on shallow and deep copies, https://docs.python.org/3/library/copy.html.

Warning: If you have subclassed MultiGraph to use dict-like objects in the data structure, those changes do not transfer to the MultiDiGraph created by this method.

Examples

>>> G = eg.Graph()  # or MultiGraph, etc
>>> G.add_edge(0, 1)
>>> H = G.to_directed()
>>> list(H.edges)
[(0, 1), (1, 0)]

If already directed, return a (deep) copy

>>> G = eg.DiGraph()  # or MultiDiGraph, etc
>>> G.add_edge(0, 1)
>>> H = G.to_directed()
>>> list(H.edges)
[(0, 1)]

easygraph.classes.operation module

easygraph.classes.operation.add_path(G_to_add_to, nodes_for_path, **attr)

Add a path to the Graph G_to_add_to.

Parameters

• G_to_add_to (graph) – A EasyGraph graph

• nodes_for_path (iterable container) – A container of nodes. A path will be constructed from the nodes (in order) and added to the graph.

• attr (keyword arguments, optional (default= no attributes)) – Attributes to add to every edge in path.

See also

add_star, add_cycle

Examples

>>> G = eg.Graph()
>>> eg.add_path(G, [0, 1, 2, 3])
>>> eg.add_path(G, [10, 11, 12], weight=7)

easygraph.classes.operation.density(G)

Returns the density of a graph.

The density for undirected graphs is

\[d = \frac{2m}{n(n-1)},\]

and for directed graphs is

\[d = \frac{m}{n(n-1)},\]

where n is the number of nodes and m is the number of edges in G.

Notes

The density is 0 for a graph without edges and 1 for a complete graph. The density of multigraphs can be higher than 1.

Self loops are counted in the total number of edges so graphs with self loops can have density higher than 1.

easygraph.classes.operation.number_of_selfloops(G)

Returns the number of selfloop edges.

A selfloop edge has the same node at both ends.

Returns

nloops – The number of selfloops.

Return type

int

See also

nodes_with_selfloops, selfloop_edges

Examples

>>> G = eg.Graph()  # or DiGraph, MultiGraph, MultiDiGraph, etc
>>> G.add_edge(1, 1)
>>> G.add_edge(1, 2)
>>> eg.number_of_selfloops(G)
1

easygraph.classes.operation.selfloop_edges(G, data=False, keys=False, default=None)

Returns an iterator over selfloop edges.

A selfloop edge has the same node at both ends.

Parameters

• G (graph) – A EasyGraph graph.

• data (string or bool, optional (default=False)) – Return selfloop edges as two tuples (u, v) (data=False) or three-tuples (u, v, datadict) (data=True) or three-tuples (u, v, datavalue) (data=’attrname’)

• keys (bool, optional (default=False)) – If True, return edge keys with each edge.

• default (value, optional (default=None)) – Value used for edges that don’t have the requested attribute. Only relevant if data is not True or False.

Returns

edgeiter – An iterator over all selfloop edges.

Return type

iterator over edge tuples

See also

nodes_with_selfloops, number_of_selfloops

Examples

>>> G = eg.MultiGraph()  # or Graph, DiGraph, MultiDiGraph, etc
>>> ekey = G.add_edge(1, 1)
>>> ekey = G.add_edge(1, 2)
>>> list(eg.selfloop_edges(G))
[(1, 1)]
>>> list(eg.selfloop_edges(G, data=True))
[(1, 1, {})]
>>> list(eg.selfloop_edges(G, keys=True))
[(1, 1, 0)]
>>> list(eg.selfloop_edges(G, keys=True, data=True))
[(1, 1, 0, {})]

easygraph.classes.operation.set_edge_attributes(G, values, name=None)

Sets edge attributes from a given value or dictionary of values.

Warning

The call order of arguments values and name switched between v1.x & v2.x.

Parameters

• G (EasyGraph Graph) –

• values (scalar value, dict-like) –

  What the edge attribute should be set to. If values is not a dictionary, then it is treated as a single attribute value that is then applied to every edge in G. This means that if you provide a mutable object, like a list, updates to that object will be reflected in the edge attribute for each edge. The attribute name will be name.

  If values is a dict or a dict of dict, it should be keyed by edge tuple to either an attribute value or a dict of attribute key/value pairs used to update the edge’s attributes. For multigraphs, the edge tuples must be of the form (u, v, key), where u and v are nodes and key is the edge key. For non-multigraphs, the keys must be tuples of the form (u, v).

• name (string (optional, default=None)) – Name of the edge attribute to set if values is a scalar.

Examples

After computing some property of the edges of a graph, you may want to assign a edge attribute to store the value of that property for each edge:

>>> G = eg.path_graph(3)
>>> bb = eg.edge_betweenness_centrality(G, normalized=False)
>>> eg.set_edge_attributes(G, bb, "betweenness")
>>> G.edges[1, 2]["betweenness"]
2.0

If you provide a list as the second argument, updates to the list will be reflected in the edge attribute for each edge:

>>> labels = []
>>> eg.set_edge_attributes(G, labels, "labels")
>>> labels.append("foo")
>>> G.edges[0, 1]["labels"]
['foo']
>>> G.edges[1, 2]["labels"]
['foo']

If you provide a dictionary of dictionaries as the second argument, the entire dictionary will be used to update edge attributes:

>>> G = eg.path_graph(3)
>>> attrs = {(0, 1): {"attr1": 20, "attr2": "nothing"}, (1, 2): {"attr2": 3}}
>>> eg.set_edge_attributes(G, attrs)
>>> G[0][1]["attr1"]
20
>>> G[0][1]["attr2"]
'nothing'
>>> G[1][2]["attr2"]
3

Note that if the dict contains edges that are not in G, they are silently ignored:

>>> G = eg.Graph([(0, 1)])
>>> eg.set_edge_attributes(G, {(1, 2): {"weight": 2.0}})
>>> (1, 2) in G.edges()
False

easygraph.classes.operation.set_node_attributes(G, values, name=None)

Sets node attributes from a given value or dictionary of values.

Warning

The call order of arguments values and name switched between v1.x & v2.x.

Parameters

• G (EasyGraph Graph) –

• values (scalar value, dict-like) –

  What the node attribute should be set to. If values is not a dictionary, then it is treated as a single attribute value that is then applied to every node in G. This means that if you provide a mutable object, like a list, updates to that object will be reflected in the node attribute for every node. The attribute name will be name.

  If values is a dict or a dict of dict, it should be keyed by node to either an attribute value or a dict of attribute key/value pairs used to update the node’s attributes.

• name (string (optional, default=None)) – Name of the node attribute to set if values is a scalar.

Examples

After computing some property of the nodes of a graph, you may want to assign a node attribute to store the value of that property for each node:

>>> G = eg.path_graph(3)
>>> bb = eg.betweenness_centrality(G)
>>> isinstance(bb, dict)
True
>>> eg.set_node_attributes(G, bb, "betweenness")
>>> G.nodes[1]["betweenness"]
1.0

If you provide a list as the second argument, updates to the list will be reflected in the node attribute for each node:

>>> G = eg.path_graph(3)
>>> labels = []
>>> eg.set_node_attributes(G, labels, "labels")
>>> labels.append("foo")
>>> G.nodes[0]["labels"]
['foo']
>>> G.nodes[1]["labels"]
['foo']
>>> G.nodes[2]["labels"]
['foo']

If you provide a dictionary of dictionaries as the second argument, the outer dictionary is assumed to be keyed by node to an inner dictionary of node attributes for that node:

>>> G = eg.path_graph(3)
>>> attrs = {0: {"attr1": 20, "attr2": "nothing"}, 1: {"attr2": 3}}
>>> eg.set_node_attributes(G, attrs)
>>> G.nodes[0]["attr1"]
20
>>> G.nodes[0]["attr2"]
'nothing'
>>> G.nodes[1]["attr2"]
3
>>> G.nodes[2]
{}

Note that if the dictionary contains nodes that are not in G, the values are silently ignored:

>>> G = eg.Graph()
>>> G.add_node(0)
>>> eg.set_node_attributes(G, {0: "red", 1: "blue"}, name="color")
>>> G.nodes[0]["color"]
'red'
>>> 1 in G.nodes
False

easygraph.classes.operation.topological_sort(G)

Module contents