xgi.linalg.hypergraph_matrix

General matrices associated to hypergraphs.

Note that the order of the rows and columns of the matrices in this module correspond to the order in which nodes/edges are added to the hypergraph or simplicial complex. If the node and edge IDs are able to be sorted, the following is an example to sort by the node and edge IDs.

>>> import xgi
>>> import pandas as pd
>>> H = xgi.Hypergraph([[1, 2, 3, 7], [4], [5, 6, 7]])
>>> I, nodedict, edgedict = xgi.incidence_matrix(H, sparse=False, index=True)
>>> # Sorting the resulting numpy array:
>>> sortedI = I.copy()
>>> sortedI = sortedI[sorted(nodedict, key=nodedict.get), :]
>>> sortedI = sortedI[:, sorted(edgedict, key=edgedict.get)]
>>> sortedI
array([[1, 0, 0],
       [1, 0, 0],
       [1, 0, 0],
       [0, 1, 0],
       [0, 0, 1],
       [0, 0, 1],
       [1, 0, 1]])
>>> # Indexing a Pandas dataframe by the node/edge IDs
>>> df = pd.DataFrame(I, index=nodedict.values(), columns=edgedict.values())

If the nodes are already sorted, this order can be preserved by adding the nodes to the hypergraph prior to adding edges. For example,

>>> import xgi
>>> H = xgi.Hypergraph()
>>> H.add_nodes_from(range(1, 8))
>>> H.add_edges_from([[1, 2, 3, 7], [4], [5, 6, 7]])
>>> xgi.incidence_matrix(H, sparse=False)
array([[1, 0, 0],
       [1, 0, 0],
       [1, 0, 0],
       [0, 1, 0],
       [0, 0, 1],
       [0, 0, 1],
       [1, 0, 1]])

Functions

xgi.linalg.hypergraph_matrix.adjacency_matrix(H, order=None, sparse=True, s=1, weighted=False, index=False)[source]

A function to generate an adjacency matrix (N,N) from a Hypergraph object.

Parameters:

H (Hypergraph object) – The hypergraph of interest
order (int, optional) – Order of interactions to use. If None (default), all orders are used. If int, must be >= 1.
sparse (bool, default: True) – Specifies whether the output matrix is a scipy sparse matrix or a numpy matrix
s (int, default: 1) – Specifies the number of overlapping edges to be considered connected.
weighted (bool) – If True, entry (i, j) [and (j, i)] is the number of edges that connect i and j. If False, entry (i, j) [and (j, i] is 1 if i and j share at least one edge and 0 otherwise. By default, False.
index (bool, default: False) – Specifies whether to output disctionaries mapping the node IDs to indices

Returns:

if index is True – return A, rowdict
else – return A

Warns:

warn – If there are isolated nodes and the matrix is sparse.

xgi.linalg.hypergraph_matrix.clique_motif_matrix(H, sparse=True, index=False)[source]

A function to generate a weighted clique motif matrix from a Hypergraph object.

Parameters:

H (Hypergraph object) – The hypergraph of interest
sparse (bool, default: True) – Specifies whether the output matrix is a scipy sparse matrix or a numpy matrix
index (bool, default: False) – Specifies whether to output dictionaries mapping the node and edge IDs to indices

Returns:

if index is True – return W, rowdict
else – return W

References

“Higher-order organization of complex networks” by Austin Benson, David Gleich, and Jure Leskovic https://doi.org/10.1126/science.aad9029

xgi.linalg.hypergraph_matrix.degree_matrix(H, order=None, index=False)[source]

Returns the degree of each node as an array

Parameters:

H (Hypergraph object) – The hypergraph of interest
order (int, optional) – Order of interactions to use. If None (default), all orders are used. If int, must be >= 1.
index (bool, default: False) – Specifies whether to output disctionaries mapping the node and edge IDs to indices.

Returns:

if index is True – return K, rowdict
else – return K

xgi.linalg.hypergraph_matrix.incidence_matrix(H, order=None, sparse=True, index=False, weight=<function <lambda>>)[source]

A function to generate a weighted incidence matrix from a Hypergraph object, where the rows correspond to nodes and the columns correspond to edges.

Parameters:

H (Hypergraph object) – The hypergraph of interest
order (int, optional) – Order of interactions to use. If None (default), all orders are used. If int, must be >= 1.
sparse (bool, default: True) – Specifies whether the output matrix is a scipy sparse matrix or a numpy matrix
index (bool, default: False) – Specifies whether to output dictionaries mapping the node and edge IDs to indices.
weight (lambda function, default=lambda function outputting 1) – A function specifying the weight, given a node and edge

Returns:

I (numpy.ndarray or scipy csr_array) – The incidence matrix, has dimension (n_nodes, n_edges)
rowdict (dict) – The dictionary mapping indices to node IDs, if index is True
coldict (dict) – The dictionary mapping indices to edge IDs, if index is True

xgi.linalg.hypergraph_matrix.intersection_profile(H, order=None, sparse=True, index=False)[source]

A function to generate an intersection profile from a Hypergraph object.

Parameters:

H (Hypergraph object) – The hypergraph of interest
order (int, optional) – Order of interactions to use. If None (default), all orders are used. If int, must be >= 1.
sparse (bool, default: True) – Specifies whether the output matrix is a scipy sparse matrix or a numpy matrix
index (bool, default: False) – Specifies whether to output dictionaries mapping the edge IDs to indices

Returns:

if index is True – return P, rowdict, coldict
else – return P