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

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.

adjacency_tensor(H, order, normalized=True, index=False)[source]#

Compute the order-d adjacency tensor of a hypergraph from its incidence matrix.

The order-d adjacency tensor B is defined as B[i1, i2, …, id] = 1 if there exists a hyperedge containing nodes (i1, i2, …, id), and 0 otherwise.

Parameters:

H (xgi.Hypergraph) – The input hypergraph.
order (int) – The order of interactions to consider.
index (bool, default: True) – Specifies whether to output disctionaries mapping the node IDs to indices

Returns:

B – Adjacency tensor

Return type:

np.ndarray

References

Liqun Qi and Ziyan Luo (2017) “Tensor Analysis: Spectral Theory and Special Tensors” Chapter 1: Introduction https://doi.org/10.1137/1.9781611974751.ch1

Galuppi, F., Mulas, R., & Venturello, L. (2023). “Spectral theory of weighted hypergraphs via tensors” Linear and Multilinear Algebra, 71(3), 317-347. https://doi.org/10.1080/03081087.2022.2030659

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

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

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

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

xgi.linalg.hypergraph_matrix#

This Page