teneto.communitydetection

Spectral

Temporal community detection by fitting a Grassmannian geodesic to spectral embeddings.

temporal_spectral(tnet, ke: int, kc: int | list[int] | str = 'auto', mode: str = 'simple-nsc', stable_communities: bool = False, smoothing_filter: str | None = None, smoothing_parameter: float | None = None, return_embeddings: bool = False, use_intermediate_iterations: bool = False, num_intermediate_iterations: int = 20, which_eig: str = 'smallest', **mode_kwargs) → ndarray | Tuple[ndarray, List[ndarray]][source]

Detect temporal communities by geodesically modeling spectral embeddings.

Parameters:

  • tnet (array | dict | TemporalNetwork) – Temporal network input accepted by teneto.utils.process_input().

  • ke (int) – The dimension of the learned spectral embeddings. Should be an upper bound on the expected number of communities at any time. (In classical static spectral clustering, ke is chosen to be equal to the target number of communities kc .)

  • kc (int | list[int] | 'auto') – Number of communities to detect per snapshot. Either a single int to detect a fixed given number of communities at every snapshot, a list of ints coindexed with the snapshots, or ‘auto’ to select per snapshot using a benefit curve.

  • mode (str) – Algorithm mode, e.g. 'simple-nsc' (normalized spectral clustering, default), 'simple-usc' (unnormalized), 'simple-smm' (spectral modularity maximization).

  • stable_communities (bool) – If True and kc='auto', a single community count is enforced across time by maximizing the benefit curve aggregated over all snapshots.

  • smoothing_filter (str | None) – 'median' or 'gaussian' to optionally smooth the benefit-vs-k curve when kc='auto' toward (slightly) more stable community counts.

  • smoothing_parameter (float | None) – Parameter for the selected smoothing filter (kernel size or sigma).

  • return_embeddings (bool) – If True, also return the per-time embeddings used for clustering.

  • use_intermediate_iterations (bool) – If True, keep intermediate geodesic-fitting iterations and concatenate their embeddings.

  • num_intermediate_iterations (int) – Number of intermediate iterations retained if use_intermediate_iterations is set. The idea is that since MM algorithms monotonically improve their objective, intermediate fits may also be useful as ‘softer regularization’ than the final geodesic fit.

  • which_eig (str) – Controls which eigensolver is used inside the base smoother ('smallest', 'largest', 'svd').

  • mode_kwargs – Additional keyword arguments forwarded to the smoother subclass.

Returns:

  • communities (ndarray (nodes, time)) – node,time array of community assignment

  • embeddings (list[np.ndarray], optional) – Returned when return_embeddings is True.

References

Hume, J. and Balzano, L. (2025). A Spectral Framework for Tracking Communities in Evolving Networks. In Proceedings of the Third Learning on Graphs Conference (LoG 2024), Proceedings of Machine Learning Research, vol. 269, pp. 9:1–9:34. Available at https://proceedings.mlr.press/v269/hume25a.html.

Louvain

make_consensus_matrix(com_membership, th=0.5)[source]

Makes the consensus matrix.

From multiple iterations, finds a consensus partition.

.
com_membershiparray

Shape should be node, time, iteration.

thfloat

threshold to cancel noisey edges

Darray

consensus matrix

make_temporal_consensus(com_membership)[source]

Matches community labels accross time-points.

Jaccard matching is in a greedy fashiong. Matching the largest community at t with the community at t-1.

Parameters:

com_membership (array) – Shape should be node, time.

Returns:

D – temporal consensus matrix using Jaccard distance

Return type:

array

temporal_louvain(tnet, resolution=1, intersliceweight=1, n_iter=100, negativeedge='ignore', randomseed=None, consensus_threshold=0.5, temporal_consensus=True, njobs=1)[source]

Louvain clustering for a temporal network.

Parameters:

  • tnet (array, dict, TemporalNetwork) – Input network

  • resolution (int) – resolution of Louvain clustering ($gamma$)

  • intersliceweight (int) – interslice weight of multilayer clustering ($omega$). Must be positive.

  • n_iter (int) – Number of iterations to run louvain for

  • randomseed (int) – Set for reproduceability

  • negativeedge (str) – If there are negative edges, what should be done with them. Options: ‘ignore’ (i.e. set to 0). More options to be added.

  • consensus (float (0.5 default)) – When creating consensus matrix to average over number of iterations, keep values when the consensus is this amount.

Returns:

communities – node,time array of community assignment

Return type:

array (node,time)

Notes

References