Contrastive Embeddings¶

All contrastive modules share the same setup. Let \(X_t\) be the scaled expression matrix for target (perturbed) cells and \(X_b\) the scaled matrix for background (control) cells, with covariances

Both matrices are standardized independently before the covariances are formed, and the pipeline skips scaling if a block already has mean \(\approx 0\) and standard deviation \(\approx 1\).

The methods differ in how they combine \(C_t\) and \(C_b\) into a single matrix whose eigenvectors become the embedding.

The two objectives¶

Choosing α automatically¶

With transform_mode: "auto" (the default), the pipeline does not pick a single \(\alpha\). It picks four, by spectral clustering over the whole grid:

flowchart TB
    A["Evaluate Σ(α) for all 40 α values"] --> B[Each α gives a subspace<br/>of top eigenvectors]
    B --> C[Affinity matrix:<br/>pairwise subspace similarity]
    C --> D[Spectral clustering<br/>into 4 clusters]
    D --> E[One exemplar α per cluster]
    E --> F[Return 4 representative α<br/>and their embeddings]

The idea is that as \(\alpha\) sweeps its range, the resulting subspace does not change smoothly — it stays roughly fixed, then snaps to a different regime. Clustering the grid by subspace similarity finds those regimes and returns one representative from each, so you get a spread of qualitatively distinct embeddings rather than 40 near-duplicates.

The two objectives handle the endpoints differently:

Output columns are named for the \(\alpha\) that produced them, e.g. alpha_0.271_pc_1, so every component remains traceable to its regularization level.

Manual mode¶

To fix a single \(\alpha\):

transform_mode: "manual"
manual_alpha: 0.5

This runs one decomposition and skips the clustering entirely. Useful when you have already identified a good \(\alpha\) and want reproducible, cheaper runs across many perturbations.

Kernel variants¶

kcpca and kcontrapc use the same two objectives, but replace the gene-gene covariances with RBF kernels between genes, so two genes count as similar when their expression profiles across cells are close, not only when they are linearly correlated.

Each group is first min-max scaled per cell, a step skipped if its values already lie in \([0, 1]\). Every gene \(g\) is then represented by its profile across that group's \(n\) cells, \(x_g \in \mathbb{R}^{n}\), and mapped to \(D\) random features \(\phi(x_g)\) with the Fastfood transform (sklearn_extra.kernel_approximation.Fastfood), chosen so that \(\phi(x_g)^\top \phi(x_h)\) approximates the RBF kernel \(k(x_g, x_h)\). Stacking the features into \(\Phi_t \in \mathbb{R}^{D \times G}\), one column per gene, gives

both \(G \times G\), with \(D = 2n\) features per bandwidth. \(K_t\) and \(K_b\) take the place of \(C_t\) and \(C_b\) in both objectives, so the eigenvectors are still gene loadings, and cells are projected onto them as in the linear modules, using the min-max scaled expression. When choosing \(\alpha\), candidate subspaces are compared on the random features \(\Phi_t\) rather than on the cells.

Giving several bandwidths sums the kernels, one per value. Kernel modules search 20 \(\alpha\) values rather than 40, since each evaluation is more expensive.

Preprocessing and guards¶

Applied inside every contrastive module before fitting:

No cell or gene filtering happens at this stage, so filter the .h5ad beforehand if you need it.

Projection scope¶

project_which controls which cells are projected into the learned space:

Hotspot consumes the projection, so this choice determines which cells the gene programs are learned from.