Similarity API¶

Shesha Similarity: Representational Similarity Metrics

This module provides metrics for measuring similarity between representations, complementing the stability metrics in shesha.core. While stability measures intrinsic geometric robustness, similarity measures extrinsic alignment.

Key distinction from the paper: - Similarity is an extrinsic property (how one representation aligns with another) - Stability is an intrinsic property (how robust a representation’s geometry is) - These are empirically uncorrelated (ρ ≈ 0.01)

shesha.sim.cka(X, Y, debiased=False, n_bootstrap_ci=None, ci=0.95, seed=None)[source]¶

Centered Kernel Alignment (CKA) - Unified interface.

Convenience function that selects between standard and debiased CKA.

Parameters:

X (np.ndarray) – First representation matrix of shape (n_samples, n_features_x).
Y (np.ndarray) – Second representation matrix of shape (n_samples, n_features_y).
debiased (bool, default=False) – If True, use debiased estimator. Recommended for small sample sizes.
n_bootstrap_ci (int, optional) – If provided, compute bootstrap confidence interval by resampling the input data this many times.
ci (float, default=0.95) – Confidence level for the interval.
seed (int, optional) – Random seed for bootstrap reproducibility.

Returns:

If n_bootstrap_ci is None: CKA similarity score in [0, 1]. If n_bootstrap_ci is set: dict with keys ‘mean’, ‘ci_low’, ‘ci_high’, ‘std’, ‘n_bootstraps’, ‘ci_level’.

Return type:

float or dict

Examples

>>> from shesha.similarity import cka
>>>
>>> X = np.random.randn(100, 50)
>>> Y = np.random.randn(100, 30)
>>>
>>> # Standard CKA (default, faster)
>>> sim = cka(X, Y)
>>>
>>> # Debiased CKA (more accurate for small n)
>>> sim_debiased = cka(X, Y, debiased=True)
>>>
>>> # With bootstrap CI
>>> result = cka(X, Y, n_bootstrap_ci=1000)

See also

cka_linear: Standard CKA implementation
cka_debiased: Debiased CKA implementation

shesha.sim.cka_debiased(X, Y, n_bootstrap_ci=None, ci=0.95, seed=None)[source]¶

Debiased Centered Kernel Alignment (CKA).

Unbiased estimator of CKA that corrects for finite sample effects. More accurate for small sample sizes but computationally more expensive.

Parameters:

X (np.ndarray) – First representation matrix of shape (n_samples, n_features_x).
Y (np.ndarray) – Second representation matrix of shape (n_samples, n_features_y). Must have same number of samples as X.
n_bootstrap_ci (int, optional) – If provided, compute bootstrap confidence interval by resampling the input data this many times.
ci (float, default=0.95) – Confidence level for the interval.
seed (int, optional) – Random seed for bootstrap reproducibility.

Returns:

If n_bootstrap_ci is None: debiased CKA similarity score in [0, 1]. If n_bootstrap_ci is set: dict with keys ‘mean’, ‘ci_low’, ‘ci_high’, ‘std’, ‘n_bootstraps’, ‘ci_level’.

Return type:

float or dict

Examples

>>> import numpy as np
>>> from shesha.similarity import cka_debiased
>>>
>>> # For small sample sizes, debiased version is more accurate
>>> X = np.random.randn(50, 20)
>>> Y = np.random.randn(50, 15)
>>>
>>> # Compare standard vs debiased
>>> from shesha.similarity import cka_linear
>>> std_cka = cka_linear(X, Y)
>>> debiased_cka = cka_debiased(X, Y)
>>>
>>> print(f"Standard: {std_cka:.3f}")
>>> print(f"Debiased: {debiased_cka:.3f}")

Notes

For n < 4, falls back to standard CKA as debiasing is not well-defined.

The debiased estimator uses the unbiased HSIC estimator from Kornblith et al. (2019), which removes diagonal terms and applies correction factors.

Recommended when: - Sample size is small (n < 100) - Exact statistical properties are important - Computing statistical significance

References

Kornblith, S., Norouzi, M., Lee, H., & Hinton, G. (2019). Similarity of neural network representations revisited. ICML 2019.

shesha.sim.cka_linear(X, Y, n_bootstrap_ci=None, ci=0.95, seed=None)[source]¶

Linear Centered Kernel Alignment (CKA) - Standard version.

Measures similarity between two representations using linear kernels. This is the standard (non-debiased) version which is simpler and more numerically stable, recommended for most use cases.

Parameters:

X (np.ndarray) – First representation matrix of shape (n_samples, n_features_x).
Y (np.ndarray) – Second representation matrix of shape (n_samples, n_features_y). Must have same number of samples as X.
n_bootstrap_ci (int, optional) – If provided, compute bootstrap confidence interval by resampling the input data this many times.
ci (float, default=0.95) – Confidence level for the interval.
seed (int, optional) – Random seed for bootstrap reproducibility.

Returns:

If n_bootstrap_ci is None: CKA similarity score in [0, 1]. If n_bootstrap_ci is set: dict with keys ‘mean’, ‘ci_low’, ‘ci_high’, ‘std’, ‘n_bootstraps’, ‘ci_level’.

Return type:

float or dict

Examples

>>> import numpy as np
>>> from shesha.similarity import cka_linear
>>>
>>> # Two representations of the same data
>>> X = np.random.randn(100, 50)
>>> Y = np.random.randn(100, 30)
>>>
>>> similarity = cka_linear(X, Y)
>>> print(f"CKA: {similarity:.3f}")
>>>
>>> # With bootstrap CI
>>> result = cka_linear(X, Y, n_bootstrap_ci=1000)
>>> print(f"{result['mean']:.3f} [{result['ci_low']:.3f}, {result['ci_high']:.3f}]")

Notes

CKA is invariant to: - Orthogonal transformations - Isotropic scaling

CKA measures the similarity of Gram matrices (X @ X.T and Y @ Y.T), which capture the pairwise similarities between samples in each representation space.

References

Kornblith, S., Norouzi, M., Lee, H., & Hinton, G. (2019). Similarity of neural network representations revisited. ICML 2019.

shesha.sim.procrustes_similarity(X, Y, center=True, scale=True, n_bootstrap_ci=None, ci=0.95, seed=None)[source]¶

Procrustes similarity between two representations.

Finds the optimal orthogonal transformation that aligns Y to X and returns the similarity (1 - disparity). Unlike CKA, Procrustes attempts to directly align the representations in their original spaces.

Parameters:

X (np.ndarray) – First representation matrix of shape (n_samples, n_features).
Y (np.ndarray) – Second representation matrix of shape (n_samples, n_features). Must have same shape as X.
center (bool, default=True) – If True, center both matrices before alignment.
scale (bool, default=True) – If True, scale to unit Frobenius norm before alignment.
n_bootstrap_ci (int, optional) – If provided, compute bootstrap confidence interval by resampling the input data this many times.
ci (float, default=0.95) – Confidence level for the interval.
seed (int, optional) – Random seed for bootstrap reproducibility.

Returns:

If n_bootstrap_ci is None: Procrustes similarity in [0, 1]. If n_bootstrap_ci is set: dict with keys ‘mean’, ‘ci_low’, ‘ci_high’, ‘std’, ‘n_bootstraps’, ‘ci_level’.

Return type:

float or dict

Examples

>>> import numpy as np
>>> from shesha.similarity import procrustes_similarity
>>>
>>> # Two representations that differ by a rotation
>>> X = np.random.randn(100, 50)
>>> Q = np.linalg.qr(np.random.randn(50, 50))[0]  # Random rotation
>>> Y = X @ Q
>>>
>>> similarity = procrustes_similarity(X, Y)
>>> print(f"Procrustes: {similarity:.3f}")  # Should be ~1.0

Notes

Procrustes is more sensitive to outliers and noise than CKA, which can be both an advantage (detects small changes) and disadvantage (more false alarms). The paper shows CKA is often preferred for representation analysis.

If dimensions don’t match, returns NaN. Unlike CKA, Procrustes requires representations to live in the same dimensional space.

References

Schönemann, P. H. (1966). A generalized solution of the orthogonal Procrustes problem. Psychometrika, 31(1), 1-10.

shesha.sim.rdm_similarity(X, Y, metric='cosine', method='spearman', n_bootstrap_ci=None, ci=0.95, seed=None)[source]¶

RDM-based similarity using correlation of pairwise distances.

Computes Representational Dissimilarity Matrices (RDMs) for X and Y, then measures their correlation. This is the same approach used in shesha.rdm_similarity but available here for comparison with CKA.

Parameters:

X (np.ndarray) – First representation matrix of shape (n_samples, n_features_x).
Y (np.ndarray) – Second representation matrix of shape (n_samples, n_features_y). Must have same number of samples as X.
metric (str, default="cosine") – Distance metric for RDM: ‘cosine’, ‘correlation’, or ‘euclidean’.
method (str, default="spearman") – Correlation method: ‘spearman’ (rank-based) or ‘pearson’ (linear).
n_bootstrap_ci (int, optional) – If provided, compute bootstrap confidence interval by resampling the input data this many times.
ci (float, default=0.95) – Confidence level for the interval.
seed (int, optional) – Random seed for bootstrap reproducibility.

Returns:

If n_bootstrap_ci is None: RDM similarity in [-1, 1]. If n_bootstrap_ci is set: dict with keys ‘mean’, ‘ci_low’, ‘ci_high’, ‘std’, ‘n_bootstraps’, ‘ci_level’.

Return type:

float or dict

Examples

>>> import numpy as np
>>> from shesha.similarity import rdm_similarity
>>>
>>> X = np.random.randn(100, 50)
>>> Y = np.random.randn(100, 30)
>>>
>>> # Spearman correlation (robust, rank-based)
>>> sim_spearman = rdm_similarity(X, Y, method='spearman')
>>>
>>> # Pearson correlation (linear)
>>> sim_pearson = rdm_similarity(X, Y, method='pearson')

Notes

RDM similarity is similar to RSA (Representational Similarity Analysis). Spearman correlation is preferred as it’s robust to monotonic transformations of distances and less sensitive to outliers.

Unlike CKA, RDM similarity operates on pairwise distances rather than Gram matrices, making it more interpretable but potentially less sensitive.