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.
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
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.
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
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].
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\).
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], but Rodriguez [2,3] and Zhou [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(),
and zhouLaplacian()).
This constructs the adjacency tensor for uniform hypergraphs.
Returns:
Adjacency Tensor
Return type:
ndarray
The adjacency tensor \(A\) of a \(k-`order hypergraph :math:`H\) is the multi-way, hypergraph analog of the pairwise, graph
adjacency matrix. It is defined as a \(k-\) mode tensor ( \(k-\) dimensional matrix):
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\]
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
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.
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-`way edges that could exist among vertex :math:`v_i\) 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
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
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, and Spectral-S and Centrality are available as other options
as well.
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 , and
Jaccard , deltaCon , Spectral , and Centrality are provided as well. When Centrality
is used as the similarity measure, G1 and G2 should ndarray s of centrality values; Otherwise
G1 and G2 are nx.Graph*s or *ndarray* s as adjacency matrices.
eps (float, optional) – a hyperparameter required for deltaCon similarity, defaults to 10e-3
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], but Wang [2] and Taylor [3] are options as well.
idxs (ndarray, optional) – specify which indices of D to compute multicorrelations of. The default is None, in which case
all combinations of order 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.
This function constructs an incidence matrix from an edge set.
Parameters:
edgeSet (ndarray) – a \(e \times 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.
This function computes the hyperedge homophily score according to the below methods. The homophily score is the average score based on
structural similarity of the vertices in hypredge H in the clique expanded graph G. This function is an interface from HAT to networkx
link prediction algorithms.
Parameters:
G (networkx.Graph) – a pairwise hypergraph expansion
H (ndarray) – hyperedge containing individual vertices within the edge
method – specifies which structural similarity method to use. This defaults to CN common neighbors.
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