Skip to content

Transforms

Admissible post-kernel transformations.

A transformation T is admissible when it maps symmetric positive semidefinite (PSD) matrices to symmetric PSD matrices and is equivariant to re-indexing the objects, T(P G P^T) = P T(G) P^T. Admissible transformations are closed under composition, which Transform exposes as >> (left to right)::

component = angular >> shift(1.0)      # T_a, then (G + J) / 2
final     = center >> trace_normalize  # T_c, then T_tr

All entry-wise and row/column-mean transformations here cost O(n^2); the spectral ones (whiten, spectral, psd_project) need an eigendecomposition, O(n^3).

Transform

Transform(fn: Callable[[ndarray], ndarray], name: str)

A named admissible transformation; a >> b applies a and then b.

Source code in src\fannar\transforms.py
def __init__(self, fn: Callable[[np.ndarray], np.ndarray], name: str) -> None:
    self.fn, self.name = fn, name

Constant transforms

name effect
fa.identity G
fa.center H G H, with H = I − J/n, in O(n²)
fa.trace_normalize G / tr G (requires a positive trace)
fa.frobenius_normalize G / ‖G‖_F
fa.max_eig_normalize G / λ_max

Parametrised transforms

angular

angular(eps: float = 1e-12) -> Transform

T_a(G) = D^{-1/2} G D^{-1/2}: cosine similarity, unit diagonal (0 for null objects).

Source code in src\fannar\transforms.py
def angular(eps: float = 1e-12) -> Transform:
    """``T_a(G) = D^{-1/2} G D^{-1/2}``: cosine similarity, unit diagonal (0 for null objects)."""
    return Transform(_angular_fn(eps), "angular")

shift

shift(c: float = 1.0) -> Transform

(G + c J) / (1 + c). Adding the rank-one PSD matrix J keeps G PSD; with c = 1 a cosine Gram moves into [0, 1], which keeps a Hadamard product of several components from collapsing to the identity.

Source code in src\fannar\transforms.py
def shift(c: float = 1.0) -> Transform:
    """``(G + c J) / (1 + c)``. Adding the rank-one PSD matrix ``J`` keeps ``G`` PSD; with
    ``c = 1`` a cosine Gram moves into ``[0, 1]``, which keeps a Hadamard product of several
    components from collapsing to the identity."""
    if c < 0:
        raise ValueError("shift must be >= 0 to stay admissible")
    return Transform(lambda G: (G + c) / (1.0 + c), f"shift({c:g})")

whiten

whiten(tol: float = 1e-10) -> Transform

T_w: projector onto the range of G (all positive eigenvalues set to 1).

Source code in src\fannar\transforms.py
def whiten(tol: float = 1e-10) -> Transform:
    """``T_w``: projector onto the range of ``G`` (all positive eigenvalues set to 1)."""
    def fn(G):
        vals, vecs = _eigh(G)
        keep = vals > tol * max(vals.max(), 1e-300)
        v = vecs[:, keep]
        return v @ v.T
    return Transform(fn, "whiten")

spectral

spectral(f: Callable[[ndarray], ndarray], name: str = 'spectral') -> Transform

V f(Lambda) V^T for a function with f(lambda) >= 0 on lambda >= 0.

Source code in src\fannar\transforms.py
def spectral(f: Callable[[np.ndarray], np.ndarray], name: str = "spectral") -> Transform:
    """``V f(Lambda) V^T`` for a function with ``f(lambda) >= 0`` on ``lambda >= 0``."""
    def fn(G):
        vals, vecs = _eigh(G)
        fv = np.asarray(f(np.maximum(vals, 0.0)), dtype=np.float64)
        if np.any(fv < 0):
            raise ValueError("spectral function must be non-negative to stay admissible")
        return (vecs * fv) @ vecs.T
    return Transform(fn, name)

psd_project

psd_project() -> Transform

Nearest PSD matrix in Frobenius norm (negative eigenvalues set to zero).

Source code in src\fannar\transforms.py
def psd_project() -> Transform:
    """Nearest PSD matrix in Frobenius norm (negative eigenvalues set to zero)."""
    return spectral(lambda v: v, "psd_project")

hadamard_power

hadamard_power(p: float) -> Transform

Entry-wise power G ** p. PSD is guaranteed only for integer p (or p large enough); use it followed by psd_project for fractional powers.

Source code in src\fannar\transforms.py
def hadamard_power(p: float) -> Transform:
    """Entry-wise power ``G ** p``. PSD is guaranteed only for integer ``p`` (or ``p`` large
    enough); use it followed by :func:`psd_project` for fractional powers."""
    return Transform(lambda G: np.sign(G) * np.abs(G) ** p, f"power({p:g})")

discarded_mass

discarded_mass(G) -> float

Fraction of the spectral mass in negative eigenvalues (what a PSD projection throws away).

Source code in src\fannar\transforms.py
def discarded_mass(G) -> float:
    """Fraction of the spectral mass in negative eigenvalues (what a PSD projection throws away)."""
    vals = np.linalg.eigvalsh(0.5 * (np.asarray(G, float) + np.asarray(G, float).T))
    return float(-vals[vals < 0].sum() / max(np.abs(vals).sum(), 1e-300))