mantispy.pp.tvn

Contents

mantispy.pp.tvn#

mantispy.pp.tvn(adata, batch_key='Metadata_Batch', reference='negcon', use_rep='X_pca', key_added='X_tvn', epsilon=0.5, copy=False)#

Typical variation normalization, then align each batch’s controls onto the pooled controls [Celik et al., 2024].

The controls define what an untreated well looks like, so they are what the transform is fitted on: the profiles are centred and scaled on them, rotated onto the principal components of the controls alone, and centred and scaled on them again within each batch. The last step is CORAL — each batch is whitened by the covariance of its own controls and recoloured with the covariance of all of them, so a batch whose typical variation points in an unusual direction is brought onto the others rather than merely recentred.

Parameters:

  • adata (AnnData) – Object holding the profiles, usually one row per well.

  • batch_key (str (default: 'Metadata_Batch')) – obs column naming the batches to align. Each needs at least two reference rows.

  • reference (str | None (default: 'negcon')) – Rows the transform is fitted on: "negcon" for the controls, None for everything, or the name of a boolean obs column.

  • use_rep (str | None (default: 'X_pca')) – Embedding to align, as harmony() takes one, or None to align X itself. Fitting the rotation on the controls of a wide feature matrix is expensive, so the default expects a reduction first, normally sc.pp.pca.

  • key_added (str (default: 'X_tvn')) – obsm key for the result.

  • epsilon (float (default: 0.5)) – Added to the diagonal of every covariance before it is inverted. The profiles are on the controls’ own scale by then, so their variances are near one and the reference value of 0.5 is a substantial shrink toward isotropy.

  • copy (bool (default: False)) – Return a modified copy instead of writing in place.

Return type:

AnnData | None

Returns:

None, or the modified copy. Writes obsm[key_added].

Raises:

  • KeyError – obs has no column batch_key or no column named by reference, or obsm holds nothing under use_rep.

  • ValueError – reference selects no rows, or fewer than two in some batch, which leaves that batch’s covariance undefined.

  • ValueError – A control covariance is singular even after epsilon, so it cannot be inverted. Reachable by passing epsilon=0.

Notes

The rotation is fitted on the controls, so it keeps min(n_controls, n_features) components. With fewer controls than features the result is narrower than the input, which is why this writes obsm and never X: var would no longer describe the columns.

Batch correction methods disagree with each other often enough that one metric is not evidence. Compare this with harmony() on the same object using evaluate_correction(), and on a screen with annotated perturbations also known_relationships(), which is the measure Celik et al. [2024] selects it by.

Measured that way, it tends to trade replicate consistency for relationship recall, where harmony() trades the other way. Neither buys the other’s gain, so which of the two readouts the screen is for is the question to answer before running either.

What it needs is controls, per batch and not in total, because the covariance it whitens each batch by is estimated from that batch’s controls alone. A batch with fewer controls than the rotation has components cannot span the space, and the warning that says so is the sign to reduce to fewer components or to pool smaller batches together.

Contents