scanpy.pp.harmony_integrate

scanpy.pp.harmony_integrate(adata, key, *, basis='X_pca', adjusted_basis='X_pca_harmony', dtype=<class 'numpy.float64'>, flavor='harmony2', n_clusters=None, max_iter_harmony=10, max_iter_clustering=None, tol_harmony=None, tol_clustering=None, sigma=0.1, theta=2.0, tau=0, ridge_lambda=1.0, alpha=0.2, batch_prune_threshold=1e-05, correction_method='fast', block_proportion=0.05, rng=None)

Integrate different experiments using the Harmony algorithm [Korsunsky et al., 2019, Patikas et al., 2026].

Integration adjusts a PCA embedding to reduce experiment-specific technical variation, allowing cells from different experiments to be compared. This CPU implementation is based on the rapids-singlecell and harmony-pytorch packages. Multiple batch variables follow the per-covariate formulation described in the Harmony papers: each key is modeled separately instead of combining all keys into one joint category. As Harmony works by adjusting the principal components, this function should be run after performing PCA but before computing the neighbor graph.

By default, the Harmony2 algorithm is used, which includes a stabilized diversity penalty, dynamic per-cluster-per-batch ridge regularization, and automatic batch pruning. To revert to the original Harmony behavior:

sc.pp.harmony_integrate(adata, key, flavor="harmony1")

Array type support

Array type	supported	… experimentally in dask Array
numpy.ndarray	✅	❌
scipy.sparse.{csr,csc}_{array,matrix}	❌	❌

Parameters:

adata AnnData

The annotated data matrix.

key str | Sequence[str]

The key(s) of the column(s) in adata.obs that differentiate(s) among experiments/batches. Multiple keys are modeled as separate batch variables, with one active categorical level per variable and cell.

basis str (default: 'X_pca')

The name of the field in adata.obsm where the PCA table is stored.

adjusted_basis str (default: 'X_pca_harmony')

The name of the field in adata.obsm where the adjusted PCA table will be stored.

dtype type | str | dtype | _SupportsDType[dtype] | tuple[Any, Any] | list[Any] | _DTypeDict (default: <class 'numpy.float64'>)

The data type to use for Harmony computation. If you use 32-bit you may experience numerical instability.

flavor Literal['harmony2', 'harmony1'] (default: 'harmony2')

Which version of the Harmony algorithm to use. "harmony2" (default) enables the stabilized diversity penalty, dynamic per-cluster-per-batch ridge regularization, and automatic batch pruning from [Patikas et al., 2026]. "harmony1" uses the original algorithm from [Korsunsky et al., 2019].

n_clusters int | None (default: None)

Number of clusters used for soft k-means in the Harmony algorithm. If None, uses min(100, N / 30). More clusters capture finer-grained structure but increase computation time.

max_iter_harmony int (default: 10)

Maximum number of outer Harmony iterations (each consisting of a clustering step followed by a correction step).

max_iter_clustering int | None (default: None)

Maximum iterations for the clustering step within each Harmony iteration. If None, uses the value of the reference implementation for the chosen flavor: 4 for "harmony2", 200 for "harmony1".

tol_harmony float | None (default: None)

Convergence tolerance for the Harmony objective function. The algorithm stops when the relative change in objective falls below this value. If None, 1e-2 for "harmony2" and 1e-4 for "harmony1".

tol_clustering float | None (default: None)

Convergence tolerance for the clustering step within each Harmony iteration. If None, 1e-3 for "harmony2" and 1e-5 for "harmony1".

sigma float (default: 0.1)

Width of the soft-clustering kernel. Controls the entropy of cluster assignments: smaller values produce harder assignments (cells assigned to fewer clusters), while larger values produce softer assignments (cells spread across more clusters).

theta float | Sequence[float] (default: 2.0)

Diversity penalty weight per batch variable. Controls how strongly Harmony encourages each cluster to contain a balanced representation of all batches. Higher values (e.g. 4) produce more aggressive mixing; lower values (e.g. 0.5) allow more batch-specific clusters. Set to 0 to disable the diversity penalty for a batch variable. A scalar is applied to every key. A sequence may contain one value per key, expanded over that key’s categorical levels, or one value per categorical level across all keys.

tau int (default: 0)

Discounting factor on theta. When tau > 0, the diversity penalty is down-weighted for batches with fewer cells, preventing over-correction of small batches. By default (0), there is no discounting.

ridge_lambda float (default: 1.0)

Ridge regression regularization for the correction step. Larger values produce more conservative (smaller) corrections, preventing over-fitting. Must be finite and greater than zero. Only used with flavor="harmony1".

alpha float (default: 0.2)

Scaling factor for the dynamic per-cluster-per-batch ridge regularization. The effective regularization for each cluster-batch pair is alpha * E_kb where E_kb is the expected number of cells. Larger values produce more conservative corrections. Only used with flavor="harmony2".

batch_prune_threshold float | None (default: 1e-05)

Fraction threshold below which a batch-cluster pair is pruned (correction suppressed). When the fraction of a batch’s cells assigned to a cluster (O_kb / N_b) falls below this threshold, that batch-cluster pair receives no correction, preventing spurious adjustments. Only used with flavor="harmony2". Set to None to disable pruning.

correction_method Literal['fast'] (default: 'fast')

Method for the correction step. "fast" uses a precomputed factorization that avoids the full inversion, which can be faster for datasets with many batches. Multiple keys automatically use the exact general-design solve, because this optimization only applies to a single batch variable.

block_proportion float (default: 0.05)

Proportion of cells updated per clustering sub-iteration. Smaller values produce more stochastic updates. Larger values are faster but may converge to different solutions.

rng int | integer | Sequence[int] | SeedSequence | Generator | BitGenerator | None (default: None)

Random number generator or seed for deterministic behavior.

Return type:

None

Returns:

Updates adata with the field adata.obsm[adjusted_basis], containing principal components adjusted by Harmony such that different experiments are integrated.