HAT Documentation
Submodules
HAT.Hypergraph module
- class HAT.Hypergraph.Hypergraph(im, ew=None, nw=None)[source]
Bases:
object
This is the base class representing a Hypergraph object. It is the primary entry point and provides an interface to functions implemented in HAT’s other modules. The underlying data structure of this class is an incidence matrix, but many methods exploit tensor representation of uniform hypergraphs.
Formally, a Hypergraph \(H=(V,E)\) is a set of vertices \(V\) and a set of edges \(E\) where each edge \(e\in E\) is defined \(e\subseteq V.\) In contrast to a graph, a hypergraph edge \(e\) can contain any number of vertices, which allows for efficient representation of multi-way relationships.
In a uniform Hypergraph, all edges contain the same number of vertices. Uniform hypergraphs are represnted as tensors, which precisely model multi-way interactions.
- Parameters
im – Incidence matrix
ew – Edge weight vector
nw – Node weight vector
- draw(shadeRows=True, connectNodes=True, dpi=200, edgeColors=None)[source]
This function draws the incidence matrix of the hypergraph object. It calls the function
HAT.draw.incidencePlot
, but is provided to generate the plot directly from the object.- Parameters
shadeRows – shade rows (bool)
connectNodes – connect nodes in each hyperedge (bool)
dpi – the resolution of the image (int)
edgeColors – The colors of edges represented in the incidence matrix. This is random by default
- Returns
matplotlib
axes with figure drawn on to it
- dual()[source]
The dual hypergraph is constructed.
- Returns
Hypergraph object
- Return type
Hypergraph
Let \(H=(V,E)\) be a hypergraph. In the dual hypergraph each original edge \(e\in E\) is represented as a vertex and each original vertex \(v\in E\) is represented as an edge. Numerically, the transpose of the incidence matrix of a hypergraph is the incidence matrix of the dual hypergraph.
References
- 1
Yang, Chaoqi, et al. “Hypergraph learning with line expansion.” arXiv preprint arXiv:2005.04843 (2020).
- cliqueGraph()[source]
The clique expansion graph is constructed.
- Returns
Clique expanded graph
- Return type
networkx.graph
The clique expansion algorithm constructs a graph on the same set of vertices as the hypergraph by defining an edge set where every pair of vertices contained within the same edge in the hypergraph have an edge between them in the graph. Given a hypergraph \(H=(V,E_h)\), then the corresponding clique graph is \(C=(V,E_c)\) where \(E_c\) is defined
\[E_c = \{(v_i, v_j) |\ \exists\ e\in E_h \text{ where } v_i, v_j\in e\}.\]This is called clique expansion because the vertices contained in each \(h\in E_h\) forms a clique in \(C\). While the map from \(H\) to \(C\) is well-defined, the transformation to a clique graph is a lossy process, so the hypergraph structure of \(H\) cannot be uniquely recovered from the clique graph \(C\) alone [1].
References
- *
Amit Surana, Can Chen, and Indika Rajapakse. Hypergraph similarity measures. IEEE Transactions on Network Science and Engineering, pages 1-16, 2022.
- †
Yang, Chaoqi, et al. “Hypergraph learning with line expansion.” arXiv preprint arXiv:2005.04843 (2020).
- lineGraph()[source]
The line graph, which is the clique expansion of the dual graph, is constructed.
- Returns
Line graph
- Return type
networkx.graph
References
- 1
Yang, Chaoqi, et al. “Hypergraph learning with line expansion.” arXiv preprint arXiv:2005.04843 (2020).
- starGraph()[source]
The star graph representation is constructed.
- Returns
Star graph
- Return type
networkx.graph
The star expansion of \({H}=({V},{E}_h)\) constructs a bipartite graph \({S}=\{{V}_s,{E}_s\}\) by introducing a new set of vertices \({V}_s={V}\cup {E}_h\) where some vertices in the star graph represent hyperedges of the original hypergraph. There exists an edge between each vertex \(v,e\in {V}_s\) when \(v\in {V}\), \(e\in {E}_h,\) and \(v\in e\). Each hyperedge in \({E}_h\) induces a star in \(S\). This is a lossless process, so the hypergraph structure of \(H\) is well-defined] given a star graph \(S\).
References
- 1
Yang, Chaoqi, et al. “Hypergraph learning with line expansion.” arXiv preprint arXiv:2005.04843 (2020).
- laplacianMatrix(type='Bolla')[source]
This function returns a version of the higher order Laplacian matrix of the hypergraph.
- Parameters
type (str, optional) – Indicates which version of the Laplacin matrix to return. It defaults to
Bolla
[1], butRodriguez
[2,3] andZhou
[4] are valid arguments as well.- Returns
Laplacian matrix
- Return type
ndarray
Several version of the hypergraph Laplacian are defined in [1-4]. These aim to capture the higher order structure as a matrix. This function serves as a wrapper to call functions that generate different specific Laplacians (See
bollaLaplacian()
,rodriguezLaplacian()
, andzhouLaplacian()
).References
- 1
Bolla, M. (1993). Spectra, euclidean representations and clusterings of hypergraphs. Discrete Mathematics, 117. https://www.sciencedirect.com/science/article/pii/0012365X9390322K
- 2
Rodriguez, J. A. (2002). On the Laplacian eigenvalues and metric parameters of hypergraphs. Linear and Multilinear Algebra, 50(1), 1-14. https://www.tandfonline.com/doi/abs/10.1080/03081080290011692
- 3
Rodriguez, J. A. (2003). On the Laplacian spectrum and walk-regular hypergraphs. Linear and Multilinear Algebra, 51, 285–297. https://www.tandfonline.com/doi/abs/10.1080/0308108031000084374
- 4
Zhou, D., Huang, J., & Schölkopf, B. (2005). Beyond pairwise classification and clustering using hypergraphs. (Equation 3.3) https://dennyzhou.github.io/papers/hyper_tech.pdf
- bollaLaplacian()[source]
This function constructs the hypergraph Laplacian according to [1].
- Returns
Bolla Laplacian matrix
- Return type
ndarray
References
- 1
Bolla, M. (1993). Spectra, euclidean representations and clusterings of hypergraphs. Discrete Mathematics, 117. https://www.sciencedirect.com/science/article/pii/0012365X9390322K
- rodriguezLaplacian()[source]
This function constructs the hypergraph Laplacian according to [1, 2].
- Returns
Rodriguez Laplacian matrix
- Return type
ndarray
References
- 1
Rodriguez, J. A. (2002). On the Laplacian eigenvalues and metric parameters of hypergraphs. Linear and Multilinear Algebra, 50(1), 1-14. https://www.tandfonline.com/doi/abs/10.1080/03081080290011692
- 2
Rodriguez, J. A. (2003). On the Laplacian spectrum and walk-regular hypergraphs. Linear and Multilinear Algebra, 51, 285–297. https://www.tandfonline.com/doi/abs/10.1080/0308108031000084374
- zhouLaplacian()[source]
This function constructs the hypergraph Laplacian according to [1].
- Returns
Zhou Laplacian matrix
- Return type
ndarray
References
- 1
Zhou, D., Huang, J., & Schölkopf, B. (2005). Beyond pairwise classification and clustering using hypergraphs. (Equation 3.3) https://dennyzhou.github.io/papers/hyper_tech.pdf
- adjTensor()[source]
This constructs the adjacency tensor for uniform hypergraphs.
- Returns
Adjacency Tensor
- Return type
ndarray
The adjacency tensor \(A\) of a \(k-\) is the multi-way, hypergraph analog of the pairwise, graph adjacency matrix. It is defined as a \(k-\) mode tensor ( \(k-\) dimensional matrix):
\[\begin{split}A \in \mathbf{R}^{ \overbrace{n \times \dots \times n}^{k \text{ times}}} \text{ where }{A}_{j_1\dots j_k} = \begin{cases} \frac{1}{(k-1)!} & \text{if }(j_1,\dots,j_k)\in {E}_h \\ 0 & \text{otherwise} \end{cases},\end{split}\]as found in equation 8 of [1].
References
- 1
C. Chen and I. Rajapakse, Tensor Entropy for Uniform Hypergraphs, IEEE TRANSACTIONS ON NETWORK SCIENCE AND ENGINEERING (2020) (Equation 8) https://arxiv.org/pdf/1912.09624.pdf
- degreeTensor()[source]
This constructs the degree tensor for uniform hypergraphs.
- Returns
Degree Tensor
- Return type
ndarray
- The degree tensor \(D\) is the hypergraph analog of the degree matrix. For a \(k-\) order hypergraph
\(H=(V,E)\) the degree tensor \(D\) is a diagonal supersymmetric tensor defined
\[D \in \mathbf{R}^{ \overbrace{n \times \dots \times n}^{k \text{ times}}} \text{ where }{D}_{i\dots i} = degree(v_i) \text{ for all } v_i\in V\]References
- 1
C. Chen and I. Rajapakse, Tensor Entropy for Uniform Hypergraphs, IEEE TRANSACTIONS ON NETWORK SCIENCE AND ENGINEERING (2020) https://arxiv.org/pdf/1912.09624.pdf
- laplacianTensor()[source]
This constructs the Laplacian tensor for uniform hypergraphs.
- Returns
Laplcian Tensor
- Return type
ndarray
The Laplacian tensor is the tensor analog of the Laplacian matrix for graphs, and it is defined equivalently. For a hypergraph \(H=(V,E)\) with an adjacency tensor \(A\) and degree tensor \(D\), the Laplacian tensor is
\[L = D - A\]References
- 1
C. Chen and I. Rajapakse, Tensor Entropy for Uniform Hypergraphs, IEEE TRANSACTIONS ON NETWORK SCIENCE AND ENGINEERING (2020) (Equation 9) https://arxiv.org/pdf/1912.09624.pdf
- tensorEntropy()[source]
Computes hypergraph entropy based on the singular values of the Laplacian tensor.
- Returns
tensor entropy
- Return type
float
Uniform hypergraph entropy is defined as the entropy of the higher order singular values of the Laplacian matrix [1].
References
- 1
C. Chen and I. Rajapakse, Tensor Entropy for Uniform Hypergraphs, IEEE TRANSACTIONS ON NETWORK SCIENCE AND ENGINEERING (2020) (Definition 7, Algorithm 1) https://arxiv.org/pdf/1912.09624.pdf
- matrixEntropy(type='Rodriguez')[source]
Computes hypergraph entropy based on the eigenvalues values of the Laplacian matrix.
- Parameters
type (str, optional) – Type of hypergraph Laplacian matrix. This defaults to ‘Rodriguez’ and other choices inclue ‘Bolla’ and ‘Zhou’ (See:
laplacianMatrix()
).- Returns
Matrix based hypergraph entropy
- Return type
float
Matrix entropy of a hypergraph is defined as the entropy of the eigenvalues of the hypergraph Laplacian matrix [1]. This may be applied to any version of the Laplacian matrix.
References
- 1
C. Chen and I. Rajapakse, Tensor Entropy for Uniform Hypergraphs, IEEE TRANSACTIONS ON NETWORK SCIENCE AND ENGINEERING (2020) (Equation 1) https://arxiv.org/pdf/1912.09624.pdf
- avgDistance()[source]
Computes the average pairwise distance between any 2 vertices in the hypergraph.
- Returns
avgDist
- Return type
float
The hypergraph is clique expanded to a graph object, and the average shortest path on the clique expanded graph is returned.
- ctrbk(inputVxc)[source]
Compute the reduced controllability matrix for \(k-\) uniform hypergraphs.
- Parameters
inputVxc (ndarray) – List of vertices that may be controlled
- Returns
Controllability matrix
- Return type
ndarray
References
- 1
Chen C, Surana A, Bloch A, Rajapakse I. “Controllability of Hypergraphs.” IEEE Transactions on Network Science and Engineering, 2021. https://drive.google.com/file/d/12aReE7mE4MVbycZUxUYdtICgrAYlzg8o/view
- bMatrix(inputVxc)[source]
Constructs controllability \(B\) matrix commonly used in the linear control system
\[\frac{dx}{dt} = Ax+Bu\]- Parameters
inputVxc (ndarray) – a list of input control nodes
- Returns
control matrix
- Return type
ndarray
References
- 1
Can Chen, Amit Surana, Anthony M Bloch, and Indika Rajapakse. Controllability of hypergraphs. IEEE Transactions on Network Science and Engineering, 8(2):1646–1657, 2021. https://drive.google.com/file/d/12aReE7mE4MVbycZUxUYdtICgrAYlzg8o/view
- clusteringCoef()[source]
Computes clustering average clustering coefficient of the hypergraph.
- Returns
average clustering coefficient
- Return type
float
For a uniform hypergraph, the clustering coefficient of a vertex \(v_i\) is defined as the number of edges the vertex participates in (i.e. \(deg(v_i)\)) divided by the number of \(k-\) and its neighbors (See equation 31 in [1]). This is written
\[C_i = \frac{deg(v_i)}{\binom{|N_i|}{k}}\]where \(N_i\) is the set of neighbors or vertices adjacent to \(v_i\). The hypergraph clustering coefficient computed here is the average clustering coefficient for all vertices, written
\[C=\sum_{i=1}^nC_i\]References
- 1
Surana, Amit, Can Chen, and Indika Rajapakse. “Hypergraph Similarity Measures.” IEEE Transactions on Network Science and Engineering (2022). https://drive.google.com/file/d/1JUYIQ2_u9YX7ky0U7QptUbJyjEMSYNNR/view
- centrality(tol=0.0001, maxIter=3000, model='LogExp', alpha=10)[source]
Computes node and edge centralities.
- Parameters
tol (int, optional) – threshold tolerance for the convergence of the centrality measures, defaults to 1e-4
maxIter (int, optional) – maximum number of iterations for the centrality measures to converge in, defaults to 3000
model (str, optional) – the set of functions used to compute centrality. This defaults to ‘LogExp’, and other choices include ‘Linear’, ‘Max’ or a list of 4 custom function handles (See [1]).
alpha (int, optional) – Hyperparameter used for computing centrality (See [1]), defaults to 10
- Returns
vxcCentrality
- Return type
ndarray containing centrality scores for each vertex in the hypergraph
- Returns
edgeCentrality
- Return type
ndarray containing centrality scores for each edge in the hypergraph
References
- 1
Tudisco, F., Higham, D.J. Node and edge nonlinear eigenvector centrality for hypergraphs. Commun Phys 4, 201 (2021). https://doi.org/10.1038/s42005-021-00704-2
HAT.HAT module
- HAT.HAT.directSimilarity(HG1, HG2, measure='Hamming')[source]
This function computes the direct similarity between two uniform hypergraphs.
- Parameters
HG1 (Hypergraph) – Hypergraph 1
HG2 (Hypergraph) – Hypergraph 2
measure (str, optional) – This sepcifies which similarity measure to apply. It defaults to
Hamming
, andSpectral-S
andCentrality
are available as other options as well.
- Returns
Hypergraph similarity
- Return type
float
References
- 1
Amit Surana, Can Chen, and Indika Rajapakse. Hypergraph similarity measures. IEEE Transactions on Network Science and Engineering, pages 1-16, 2022.
- HAT.HAT.indirectSimilarity(G1, G2, measure='Hamming', eps=0.01)[source]
This function computes the indirect similarity between two hypergraphs.
- Parameters
G1 (nx.Graph or ndarray) – Hypergraph 1 expansion
G2 (nx.Graph or ndarray) – Hypergraph 2 expansion
measure (str, optional) – This specifies which similarity measure to apply. It defaults to
Hamming
, andJaccard
,deltaCon
,Spectral
, andCentrality
are provided as well. WhenCentrality
is used as the similarity measure,G1
andG2
should ndarray s of centrality values; OtherwiseG1
andG2
are nx.Graph*s or *ndarray* s as adjacency matrices.eps (float, optional) – a hyperparameter required for deltaCon similarity, defaults to 10e-3
- Returns
similarity measure
- Return type
float
References
- 1
Amit Surana, Can Chen, and Indika Rajapakse. Hypergraph similarity measures. IEEE Transactions on Network Science and Engineering, pages 1-16, 2022.
- HAT.HAT.multicorrelations(D, order, mtype='Drezner', idxs=None)[source]
This function computes the multicorrelation among pairwise or 2D data.
- Parameters
D (ndarray) – 2D or pairwise data
order (int) – order of the multi-way interactions
mtype (str) – This specifies which multicorrelation measure to use. It defaults to
Drezner
[1], butWang
[2] andTaylor
[3] are options as well.idxs (ndarray, optional) – specify which indices of
D
to compute multicorrelations of. The default isNone
, in which case all combinations oforder
indices are computed.
- Returns
A vector of the multicorrelation scores computed and a vector of the column indices of
D
used to compute each multicorrelation.- Return type
(ndarray, ndarray)
References
- 1
Zvi Drezner. Multirelation—a correlation among more than two variables. Computational Statistics & Data Analysis, 19(3):283–292, 1995.
- 2
Jianji Wang and Nanning Zheng. Measures of correlation for multiple variables. arXiv preprint arXiv:1401.4827, 2014.
- 3
Benjamin M Taylor. A multi-way correlation coefficient. arXiv preprint arXiv:2003.02561, 2020.
- HAT.HAT.uniformErdosRenyi(v, e, k)[source]
This function generates a uniform, random hypergraph.
- Parameters
v (int) – number of vertices
e (int) – number of edges
k (int) – order of hypergraph
- Returns
Hypergraph
- Return type
Hypergraph
- HAT.HAT.load(dataset='Karate')[source]
This function loads built-in datasets. Currently only one dataset is available and we are working to expand this.
- Parameters
dataset (str, optional) – sets which dataset to load in, defaults to ‘Karate’
- Returns
graph object
- Return type
nx.Graph
- HAT.HAT.hyperedges2IM(edgeSet)[source]
This function constructs an incidence matrix from an edge set.
- Parameters
edgeSet (ndarray) – a \(e imes k\) matrix where each row contains \(k\) integers that are contained within the same hyperedge
- Returns
a \(n imes e\) incidence matrix where each row of the edge set corresponds to a column of the incidence matrix. \(n\) is the number of nodes contained in the edgeset.
- Return type
ndarray
HAT.draw module
- HAT.draw.incidencePlot(H, shadeRows=True, connectNodes=True, dpi=200, edgeColors=None)[source]
Plot the incidence matrix of a hypergraph.
- Parameters
H – a HAT.hypergraph object
shadeRows – shade rows (bool)
connectNodes – connect nodes in each hyperedge (bool)
dpi – the resolution of the image (int)
edgeColors – The colors of edges represented in the incidence matrix. This is random by default
- Returns
matplotlib axes with figure drawn on to it
HAT.multilinalg module
- HAT.multilinalg.hosvd(T, M=True, uniform=False, sym=False)[source]
Higher Order Singular Value Decomposition
- Parameters
uniform – Indicates if T is a uniform tensor
sym – Indicates if T is a super symmetric tensor
M – Indicates if the factor matrices are required as well as the core tensor
- Returns
The singular values of the core diagonal tensor and the factor matrices.
- HAT.multilinalg.supersymHosvd(T)[source]
Computes the singular values of a uniform, symetric tensor. See Algorithm 1 in [1].
- Parameters
T – A uniform, symmetric multidimensional array
- Returns
The singular values that compose the core tensor of the HOSVD on T.
References
- 1
Chen and I. Rajapakse, Tensor Entropy for Uniform Hypergraphs, IEEE TRANSACTIONS ON NETWORK SCIENCE AND ENGINEERING (2020)
- HAT.multilinalg.HammingSimilarity(A1, A2)[source]
Computes the Spectral-S similarity of 2 Adjacency tensors [1].
- Parameters
A1 (ndarray) – adjacency tensor 1
A2 (ndarray) – adjacency tensor 2
- Returns
Hamming similarity measure
- Return type
float
References
- 1
Amit Surana, Can Chen, and Indika Rajapakse. Hypergraph similarity measures. IEEE Transactions on Network Science and Engineering, pages 1-16, 2022.
- HAT.multilinalg.SpectralHSimilarity(L1, L2)[source]
Computes the Spectral-S similarity of 2 Laplacian tensors [1].
- Parameters
L1 (ndarray) – Laplacian tensor 1
L2 (ndarray) – Laplacian tensor 2
- Returns
Spectral-S similarity measure
- Return type
float
References
- 1
Amit Surana, Can Chen, and Indika Rajapakse. Hypergraph similarity measures. IEEE Transactions on Network Science and Engineering, pages 1-16, 2022.
- HAT.multilinalg.kronExponentiation(M, x)[source]
Kronecker Product Exponential.
- Parameters
M (ndarray) – a matrix
x (int) – power of exponentiation
- Returns
Krnoecker Product exponentiation of M a total of x times
- Return type
ndarray
This function performs the Kronecker Product on a matrix \(M\) a total of \(x\) times. The Kronecker product is defined for two matrices \(A\in\mathbf{R}^{l \times m}, B\in\mathbf{R}^{m \times n}\) as the matrix
\[\begin{split}A \bigotimes B= \begin{pmatrix} A_{1,1}B & A_{1,2}B & \dots & A_{1,m}B \\ A_{2,1}B & A_{2,2}B & \dots & A_{2,m}B \\ \vdots & \vdots & \ddots & \vdots \\ A_{l,1}B & A_{l,2}B & \dots & A_{l,n}B \end{pmatrix}\end{split}\]
Bug Reporting
Please report all bugs or defects in HAT to this page.