structboost.gene_variance_shares

structboost.gene_variance_shares(X, w, scores)

Each gene’s share of one latent dimension’s variance. Sums to 1 exactly.

From Var(s) = Cov(s, s) with s = X @ w:

Var(s) = Cov(sum_g w_g X_g, s) = sum_g w_g Cov(X_g, s)

so w_g Cov(X_g, s) / Var(s) is an exact additive decomposition, needing no orthogonality assumption and handling correlated genes correctly – two redundant genes split a share rather than both claiming it.

This is the honest ranking of genes within a dimension. |w_g| is not, because it ignores how much the gene actually varies: measured on one dataset the two rankings agree on 8.6 of 10 genes per dimension, and where they differ |w| promotes genes that barely move – SCT ranked #4 by weight and #35 of 38 by share, being near-absent in the tissue.

The result is a magnitude: because a negative-weight gene is anti-correlated with the score, the product is positive either way, and only about 1% of genes come out negative (a suppressor, whose weight opposes its own correlation with the finished score). Direction lives in the sign of w, not here.

Parameters:

• X (ndarray) – (n_cells, n_genes) expression the encoder was fitted on.

• w (ndarray) – (n_genes,) encoder weights for one latent dimension.

• scores (ndarray) – (n_cells,) that dimension’s latent scores.

Returns:

ndarray – (n_genes,) shares, summing to 1 over a dimension’s selected genes.

Return type:

ndarray