cosine-similarity-metric-application

cosine-similarity-metric-application

Summary

Apply cosine similarity as the distance metric in matrix-free spectral embedding to compute cell-to-cell similarities in high-dimensional single-cell omics data. This metric is the default choice in SnapATAC2's spectral embedding algorithm and is suitable for sparse count matrices across ATAC-seq, RNA-seq, Hi-C, and methylation modalities.

When to use

You are performing dimensionality reduction on a sparse single-cell count matrix (in CSR format) and need to compute pairwise cell similarities before spectral decomposition. Cosine similarity is the appropriate choice when your input is an unscaled or log-normalized count matrix and you want metric-agnostic behavior that treats zero entries uniformly. Choose this metric if you are working with SnapATAC2 Release 2.3.0 or later, where it is the default similarity metric.

When NOT to use

• Input is a dense matrix or already a distance/similarity matrix (cosine similarity should be computed on raw counts, not post-hoc on existing similarities)
• You require a custom distance metric that is not cosine (e.g., Euclidean, Manhattan, Pearson) — use tl.spectral with explicit metric parameter instead
• Your matrix is already heavily preprocessed into a different coordinate space where cosine distance semantics do not apply

Inputs

• sparse count matrix in CSR (compressed sparse row) format
• single-cell omics data (ATAC-seq, RNA-seq, Hi-C, or methylation)
• cell-by-feature or cell-by-tile matrix (≥10 million cells supported)

Outputs

• low-dimensional cell embedding (weighted eigenvectors from spectral decomposition)
• eigenvalues associated with computed eigenvectors
• runtime and peak memory metrics for scalability verification

How to apply

Initialize your single-cell count matrix in compressed sparse row (CSR) format compatible with SnapATAC2's backend. Call tl.spectral() without explicitly specifying the similarity metric argument, relying on the default cosine similarity metric (Release 2.3.0+), or explicitly pass metric='cosine' to ensure reproducibility. The spectral embedding algorithm will compute pairwise cosine similarities among all cells, then perform eigendecomposition on the resulting similarity matrix to extract the dominant eigenvectors. The returned eigenvectors are weighted by their corresponding eigenvalues by default, producing a low-dimensional embedding suitable for downstream clustering and visualization. Monitor both runtime and peak memory usage during execution to verify linear complexity scaling; cosine similarity computation is matrix-free, so memory overhead should be proportional to the number of cells and features, not their product.