Spectral layout improvements

[karlmoresco]

Diffusion map

Overview

This is an experimental added option to the spectral layout algorithm that returns the diffusion map coordinates as opposed to the standard spectral layout coordinates. This should theoretically produce layouts where nodes that are truly (via "heat flow") proximate are placed near closely in the layout. If diffusion_time isn't passed specifically, the function behaves the same as before.

Diffusion map (bottom equation):

The "time" parameter

There's a variable parameter diffusion_time ("t" in the equations) that govern the behavior of this coordinate mapping, and refining this layout step includes finding the appropriate range for this parameter. At too high diffusion_time, the coordinates collapse to the origin (as can be seen from the equations). Note that the t-scales for normalize=True and normalize=False are not the same, as the lower spectrum of the normalized laplacian usually has smaller eigenvalues compared to the non-normalized. Also, the heat kernel correspond to different things for the normalized and non-normalized Laplacian:

"Though, it is important to note, that the underlying dynamics of the degree-normalized Laplacians correspond more closely to stochastic diffusion, i.e., modelling the transition probabilities of discrete ’walkers’, rather than the physical diffusion of ’heat’ governed by the discrete ∇2 operator". (source)

Approximation

Keep in mind this method is based on an approximation of the heat kernel:

Heat kernel:

Where N=4 in the approximation, as opposed to the exact definition where N is the number of eigenvectors of the Laplacian. Observing the diffusion distance definition ("heat distance" above), it's clear that the approximation is justified as the terms of the sum decay exponentially. Still, this diffusion map approach might not create meaningful results because of its approximate nature.

Docstring

This PR also updates the docstring of spectral_layout with more details and a full Google style docstring signature. There's a separate PR for only the docstring change.

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

PR checklist:

• This comment contains a description of changes.
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• I have added tests that prove my fix is effective or that my feature works
• I have checked my code and documentation and corrected any misspellings

---

Note

Medium Risk
Changes numerical behavior of the psvd spectral path and adds a new layout mode; public return type is unchanged but coordinates can differ when diffusion_time is set or via the svds fix.

Overview
Adds an optional diffusion_time argument to spectral_layout, so embeddings can use diffusion-map coordinates (eigenvector axes scaled by exp(-λ t)) instead of plain Laplacian eigenvectors. _spectral_layout_eigen and _spectral_layout_psvd now return the selected eigenvalues alongside raw coordinates to support that step; negative diffusion_time is rejected.

For the bipartite psvd path, svds is called with which="LM", and Laplacian eigenvalues are derived as 1.0 - s from the retained singular values. The spectral_layout docstring is expanded to a full Google-style description of behavior, parameters, and errors. Default behavior when diffusion_time is omitted is unchanged.

^{Reviewed by Cursor Bugbot for commit 8f244f0. Bugbot is set up for automated code reviews on this repo. Configure here.}