Utility¶
Transformations¶

graspologic.utils.
pass_to_ranks
(graph, method='simplenonzero')[source]¶ Rescales edge weights of an adjacency matrix based on their relative rank in the graph.
Parameters: graph: array_like or networkx.Graph
Adjacency matrix
method: {'simplenonzero' (default), 'simpleall', 'zeroboost'} string, optional
 'simplenonzero'
 assigns ranks to all nonzero edges, settling ties using the average. Ranks are then scaled by \(\frac{rank(\text{nonzero edges})}{\text{total nonzero edges} + 1}\)
 'simpleall'
 assigns ranks to all nonzero edges, settling ties using the average. Ranks are then scaled by \(\frac{rank(\text{nonzero edges})}{n^2 + 1}\) where n is the number of nodes
 'zeroboost'
 preserves the edge weight for all 0s, but ranks the other edges as if the ranks of all 0 edges has been assigned. If there are 10 0valued edges, the lowest nonzero edge gets weight 11 / (number of possible edges). Ties settled by the average of the weight that those edges would have received. Number of possible edges is determined by the type of graph (loopless or looped, directed or undirected).
Returns: graph: numpy.ndarray, shape(n_vertices, n_vertices)
Adjacency matrix of graph after being passed to ranks
See also

graspologic.utils.
to_laplace
(graph, form='DAD', regularizer=None)[source]¶ A function to convert graph adjacency matrix to graph Laplacian.
Currently supports IDAD, DAD, and RDAD Laplacians, where D is the diagonal matrix of degrees of each node raised to the 1/2 power, I is the identity matrix, and A is the adjacency matrix.
RDAD is regularized Laplacian: where \(D_t = D + regularizer*I\).
Parameters: graph: object
Either arraylike, (n_vertices, n_vertices) numpy array, or an object of type networkx.Graph.
form: {'IDAD' (default), 'DAD', 'RDAD'}, string, optional
 'IDAD'
 Computes \(L = I  D_i*A*D_i\)
 'DAD'
 Computes \(L = D_o*A*D_i\)
 'RDAD'
 Computes \(L = D_o^r*A*D_i^r\) where \(D_o^r = D_o + regularizer * I\) and likewise for \(D_i\)
regularizer: int, float or None, optional (default=None)
Constant to add to the degree vector(s). If None, average node degree is added. If int or float, must be >= 0. Only used when
form
== 'RDAD'.Returns: L : numpy.ndarray
2D (n_vertices, n_vertices) array representing graph Laplacian of specified form
References
[1] Qin, Tai, and Karl Rohe. "Regularized spectral clustering under the degreecorrected stochastic blockmodel." In Advances in Neural Information Processing Systems, pp. 31203128. 2013 [2] Rohe, Karl, Tai Qin, and Bin Yu. "Coclustering directed graphs to discover asymmetries and directional communities." Proceedings of the National Academy of Sciences 113.45 (2016): 1267912684. Examples
>>> a = np.array([ ... [0, 1, 1], ... [1, 0, 0], ... [1, 0, 0]]) >>> to_laplace(a, "DAD") array([[0. , 0.70710678, 0.70710678], [0.70710678, 0. , 0. ], [0.70710678, 0. , 0. ]])

graspologic.utils.
augment_diagonal
(graph, weight=1)[source]¶ Replaces the diagonal of an adjacency matrix with \(\frac{d}{nverts  1}\) where \(d\) is the degree vector for an unweighted graph and the sum of magnitude of edge weights for each node for a weighted graph. For a directed graph the in/out \(d\) is averaged.
Parameters: graph: nx.Graph, nx.DiGraph, nx.MultiDiGraph, nx.MultiGraph, np.ndarray
Input graph in any of the above specified formats. If np.ndarray, interpreted as an \(n \times n\) adjacency matrix
weight: float/int
scalar value to multiply the new diagonal vector by
Returns: graph : np.array
Adjacency matrix with average degrees added to the diagonal.
Examples
>>> a = np.array([ ... [0, 1, 1], ... [1, 0, 0], ... [1, 0, 0]]) >>> augment_diagonal(a) array([[1. , 1. , 1. ], [1. , 0.5, 0. ], [1. , 0. , 0.5]])

graspologic.utils.
symmetrize
(graph, method='avg')[source]¶ A function for forcing symmetry upon a graph.
Parameters: graph: object
Either arraylike, (n_vertices, n_vertices) numpy matrix, or an object of type networkx.Graph.
method: {'avg' (default), 'triu', 'tril',}, optional
An option indicating which half of the edges to retain when symmetrizing.
 'avg'
 Retain the average weight between the upper and lower right triangle, of the adjacency matrix.
 'triu'
 Retain the upper right triangle.
 'tril'
 Retain the lower left triangle.
Returns: graph: arraylike, shape (n_vertices, n_vertices)
Graph with asymmetries removed.
Examples
>>> a = np.array([ ... [0, 1, 1], ... [0, 0, 1], ... [0, 0, 1]]) >>> symmetrize(a, method="triu") array([[0, 1, 1], [1, 0, 1], [1, 1, 1]])

graspologic.utils.
remove_loops
(graph)[source]¶ A function to remove loops from a graph.
Parameters: graph: object
Either arraylike, (n_vertices, n_vertices) numpy matrix, or an object of type networkx.Graph.
Returns: graph: arraylike, shape(n_vertices, n_vertices)
the graph with selfloops (edges between the same node) removed.
Connected Components¶

graspologic.utils.
is_fully_connected
(graph)[source]¶ Checks whether the input graph is fully connected in the undirected case or weakly connected in the directed case.
Connected means one can get from any vertex u to vertex v by traversing the graph. For a directed graph, weakly connected means that the graph is connected after it is converted to an unweighted graph (ignore the direction of each edge)
Parameters: graph: nx.Graph, nx.DiGraph, nx.MultiDiGraph, nx.MultiGraph, np.ndarray
Input graph in any of the above specified formats. If np.ndarray, interpreted as an \(n \times n\) adjacency matrix
Returns:  boolean: True if the entire input graph is connected
References
http://mathworld.wolfram.com/ConnectedGraph.html http://mathworld.wolfram.com/WeaklyConnectedDigraph.html
Examples
>>> a = np.array([ ... [0, 1, 0], ... [1, 0, 0], ... [0, 0, 0]]) >>> is_fully_connected(a) False

graspologic.utils.
get_lcc
(graph, return_inds=False)[source]¶ Finds the largest connected component for the input graph.
The largest connected component is the fully connected subgraph which has the most nodes.
Parameters: graph: nx.Graph, nx.DiGraph, nx.MultiDiGraph, nx.MultiGraph, np.ndarray
Input graph in any of the above specified formats. If np.ndarray, interpreted as an \(n \times n\) adjacency matrix
return_inds: boolean, default: False
Whether to return a np.ndarray containing the indices in the original adjacency matrix that were kept and are now in the returned graph. Ignored when input is networkx object
Returns: graph: nx.Graph, nx.DiGraph, nx.MultiDiGraph, nx.MultiGraph, np.ndarray
New graph of the largest connected component of the input parameter.
inds: (optional)
Indices from the original adjacency matrix that were kept after taking the largest connected component.

graspologic.utils.
get_multigraph_union_lcc
(graphs, return_inds=False)[source]¶ Finds the union of all multiple graphs, then compute the largest connected component.
Parameters: graphs: list or np.ndarray
List of arraylike, (n_vertices, n_vertices), or list of np.ndarray nx.Graph, nx.DiGraph, nx.MultiDiGraph, nx.MultiGraph.
return_inds: boolean, default: False
Whether to return a np.ndarray containing the indices in the original adjacency matrix that were kept and are now in the returned graph. Ignored when input is networkx object
Returns: out : list or np.ndarray
If input was a list

graspologic.utils.
get_multigraph_intersect_lcc
(graphs, return_inds=False)[source]¶ Finds the intersection of multiple graphs's largest connected components.
Computes the largest connected component for each graph that was input, and takes the intersection over all of these resulting graphs. Note that this does not guarantee finding the largest graph where every node is shared among all of the input graphs.
Parameters: graphs: list or np.ndarray
if list, each element must be an \(n \times n\) np.ndarray adjacency matrix
return_inds: boolean, default: False
Whether to return a np.ndarray containing the indices in the original adjacency matrix that were kept and are now in the returned graph. Ignored when input is networkx object
Returns: graph: nx.Graph, nx.DiGraph, nx.MultiDiGraph, nx.MultiGraph, np.ndarray
New graph of the largest connected component of the input parameter.
inds: (optional)
Indices from the original adjacency matrix that were kept after taking the largest connected component
IO¶

graspologic.utils.
import_graph
(graph, copy=True)[source]¶ A function for reading a graph and returning a shared data type.
Parameters: graph: object
Either arraylike, shape (n_vertices, n_vertices) numpy array, or an object of type networkx.Graph.
copy: bool, (default=True)
Whether to return a copied version of array. If False and input is np.array, the output returns the original input.
Returns: out: arraylike, shape (n_vertices, n_vertices)
A graph.
See also
networkx.Graph
,numpy.array

graspologic.utils.
import_edgelist
(path, extension='edgelist', delimiter=None, nodetype=<class 'int'>, return_vertices=False)[source]¶ Function for reading a single or multiple edgelists. When importing multiple edgelists, the union of vertices from all graphs is computed so that each output graph have matched vertex set. The order of nodes are sorted by node values.
Parameters: path : str, Path object, or iterable
If
path
is a directory, then the importing order will be sorted in alphabetical order.extension : str, optional
If
path
is a directory, then the function will convert all files with matching extension.delimiter : str or None, default=None, optional
Delimiter of edgelist. If None, the delimiter is whitespace.
nodetype : int (default), float, str, Python type, optional
Convert node data from strings to specified type.
return_vertices : bool, default=False, optional
Returns the union of all ind
Returns: out : list of arraylike, or arraylike, shape (n_vertices, n_vertices)
If
path
is a directory, a list of arrays is returned. Ifpath
is a file, an array is returned.vertices : arraylike, shape (n_vertices, )
If
return_vertices
== True, then returns an array of all vertices that were included in the output graphs.