spectral-embedding-dimension-reduction-parameters

Spectral-embedding dimension reduction parameters

Summary

Configure and apply matrix-free spectral embedding for dimension reduction on single-cell ATAC-seq and multi-omics data, selecting appropriate similarity metrics and embedding parameters to preserve cell-state structure prior to clustering and visualization.

When to use

After generating a tile matrix or feature count matrix from single-cell ATAC-seq, RNA-seq, Hi-C, or methylation data, before clustering or UMAP visualization, when you need unsupervised dimension reduction that scales to millions of cells and is agnostic to the underlying data modality. Apply this step when the raw feature matrix is too high-dimensional for downstream clustering or when you need to integrate multi-modal single-cell data.

When NOT to use

• Input data is already a low-dimensional embedding (e.g., pre-computed PCA or UMAP coordinates); apply clustering directly instead.
• Single-cell ATAC-seq data has not been preprocessed (e.g., barcodes not yet assigned, fragments not imported); run pp.import_fragments and pp.add_tile_matrix first.
• You require a linear embedding for interpretability of feature contributions; PCA or factor analysis may be more appropriate than spectral methods.

Inputs

• AnnData object with tile matrix (pp.add_tile_matrix) or count matrix (pp.make_peak_matrix, pp.make_gene_matrix)
• Paired-end ATAC-seq fragment counts or equivalent feature counts for other modalities
• Optional: multiple aligned count matrices for co-embedding

Outputs

• Spectral eigenvectors stored in adata.obsm (typically 'X_spectral')
• UMAP coordinates derived from spectral embedding (adata.obsm['X_umap'])
• Leiden cluster assignments using spectral eigenvectors as input

How to apply

Call tl.spectral on the tile matrix or count matrix, specifying the similarity metric (e.g., cosine similarity for ATAC-seq) and the number of dimensions to retain. The matrix-free algorithm avoids materializing the full feature matrix, making it suitable for large datasets. The resulting eigenvectors become the input to UMAP visualization or clustering algorithms (e.g., Leiden). For multi-omics integration, use tl.multi_spectral with aligned modality matrices to produce a joint embedding. Verify that the spectral eigenvectors capture expected biological structure by checking that subsequent UMAP coordinates and Leiden cluster assignments match reference cell-type annotations.