relaxed_modularity

hypercoil.functional.graph.relaxed_modularity(A: Tensor, C: Tensor, C_o: Tensor | None = None, L: Tensor | None = None, exclude_diag: bool = True, gamma: float = 1, null: ~typing.Callable = <function girvan_newman_null>, normalise_modularity: bool = True, normalise_coaffiliation: bool = True, directed: bool = False, sign: ~typing.Literal['+', '-'] | None = '+', **params) → Tensor

A relaxation of the modularity of a network given a community partition.

This relaxation supports non-deterministic assignments of vertices to communities and non-assortative linkages between communities. It reverts to standard behaviour when the inputs it is provided are standard.

The relaxed modularity is defined as the sum of all entries in the Hadamard (elementwise) product between the modularity matrix and the coaffiliation matrix.

\(Q = \mathbf{1}^\intercal \left( B \circ H \right) \mathbf{1}\)

Dimension:

Input : \((N, *, I, O)\)

N denotes batch size, * denotes any number of intervening dimensions, I denotes number of vertices in the source set and O denotes number of vertices in the sink set. If the same set of vertices emits and receives edges, then \(I = O\).

C_i : \((*, I, C)\)

* denotes any number of preceding dimensions, I denotes number of vertices in the source set, and C denotes the total number of communities in the proposed partition.

C_o : \((*, I, C)\)

O denotes number of vertices in the sink set. If the same set of vertices emits and receives edges, then \(I = O\).

L : \((*, C, C)\)

As above.

Output : \((N, *)\)

As above.

Parameters:

ATensor

Block of adjacency matrices for which the quantity of interest is to be computed.

CTensor

Community affiliation of vertices in the source set. Each slice is a matrix \(C^{(i)} \in \mathbb{R}^{I \ times C}\) that encodes the uncertainty in each vertex’s community assignment. \(C^{(i)}_{jk}\) denotes the probability that vertex j is assigned to community k. If this is binary-valued, then it reflects a deterministic assignment.

C_oTensor or None (default None)

Community affiliation of vertices in the sink set. If None, then it is assumed that the source and sink sets are the same, and C_o is set equal to C_i.

LTensor or None (default None)

The inter-community coupling matrix \(\Omega\), mapping the probability of affiliation between communities. Each entry \(L_{ij}\) encodes the probability of a vertex in community i connecting with a vertex in community j. If None, then a strictly assortative structure is assumed (equivalent to L equals identity), under which nodes in the same community preferentially coaffiliate while nodes in different communities remain disaffiliated.

exclude_diagbool (default True)

Indicates that self-links are not factored into the coaffiliation.

normalise_coaffiliationbool (default False)

Normalise all community assignment weights to max out at 1.

directedbool (default False)

Indicates that the input adjacency matrices should be considered as a directed graph.

gammanonnegative float (default 1)

Resolution parameter for the modularity matrix. A smaller value assigns maximum modularity to partitions with large communities, while a larger value assigns maximum modularity to partitions with many small communities.

nullcallable(A) (default girvan_newman_null)

Function of A that returns, for each adjacency matrix in the input tensor block, a suitable null model. By default, the Girvan-Newman null model is used.

normalise_modularitybool (default False)

Indicates that the resulting matrix should be normalised by the total matrix degree. This may not be necessary for many use cases – for instance, where the arg max of a function of the modularity matrix is desired.

sign'+', '-', or None (default '+')

Sign of connections to be considered in the modularity.

**params

Any additional parameters are passed to the null model.

Returns:

QTensor

Modularity of each input adjacency matrix.