modularity_matrix

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

Modularity matrices for a tensor block.

The modularity matrix is defined as a normalised, weighted difference between the adjacency matrix and a suitable null model. For a weight \(\gamma\), an adjacency matrix \(A\), a null model \(P\), and total edge weight \(2m\), the modularity matrix is computed as

\(B = \frac{1}{2m} \left( A - \gamma P \right)\)

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\).

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

As above.

Parameters:

ATensor

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

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:

BTensor

Block comprising modularity matrices corresponding to each input adjacency matrix.

See also

relaxed_modularity

Compute the modularity given a community structure.