{"id":23840,"library":"harmonypy","title":"harmonypy","description":"A Python port of the Harmony algorithm for batch correction of single-cell RNA-seq data, featuring a C++ Armadillo backend for high performance. Current version 2.0.0 is a complete rewrite that matches the R harmony2 package with ~10x speed improvement over v0.1.0. Pre-built wheels are available for Linux (x86_64, aarch64) and macOS. Releases are intermittent, with major rewrites at v0.2.0 (PyTorch) and v2.0.0 (C++ Armadillo).","status":"active","version":"2.0.0","language":"python","source_language":"en","source_url":"https://github.com/slowkow/harmonypy","tags":["batch-correction","single-cell","harmony","bioinformatics","c++-backend"],"install":[{"cmd":"pip install harmonypy","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Only runtime dependency for v2.0.0 (C++ backend eliminates need for PyTorch/scipy)","package":"numpy","optional":false}],"imports":[{"note":"In v2.0.0, the function has been moved to the top-level package; older versions used a different path.","wrong":"from harmonypy.harmony import run_harmony","symbol":"run_harmony","correct":"from harmonypy import run_harmony"},{"note":"For the class-based API in v2.0.0.","wrong":"","symbol":"Harmony","correct":"from harmonypy import Harmony"},{"note":"Common mistake: trying to import the package name as a module.","wrong":"from harmonypy import harmonypy","symbol":"harmonypy","correct":"import harmonypy"}],"quickstart":{"code":"import numpy as np\nimport harmonypy\n\n# Simulate data\nnp.random.seed(0)\nZ = np.random.randn(500, 20)  # 500 cells, 20 PCs\nmeta = np.array([0]*250 + [1]*250)  # two batches\n\n# Run harmony\nho = harmonypy.run_harmony(Z, meta, ['batch'], max_iter_harmony=10, random_state=0)\ncorrected = ho.Z_corr\nprint(corrected.shape)","lang":"python","description":"Basic harmony batch correction on simulated PCA embeddings."},"warnings":[{"fix":"Update imports: `from harmonypy import run_harmony`. The API is similar but may have minor differences; refer to the README.","message":"v2.0.0 is a complete rewrite with a C++ Armadillo backend and nanobind. It does not support PyTorch (v0.2.0) or the pure Python/NumPy path (v0.1.0). All existing code using older versions must be updated.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade to v2.0.0: `pip install harmonypy>=2`.","message":"v0.2.0 (PyTorch backend) is no longer maintained. Pre-built wheels are only available for v2.0.0 and later.","severity":"deprecated","affected_versions":"0.2.0"},{"fix":"Set random_state when calling run_harmony to ensure reproducibility.","message":"random_state parameter: In v2.0.0, it is passed to run_harmony() as a keyword argument. Older versions used a different mechanism or ignored it.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use `np.array(ho.Z_corr)` if needed for compatibility.","message":"The output `ho.Z_corr` in v2.0.0 is a NumPy array; in v0.1.0 it was a list of lists. Check array dimensions: (cells, PCs).","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run `pip install harmonypy==2.0.0` and ensure you are using Python >=3.9.","cause":"The package is not installed or the Python environment is incorrect.","error":"ModuleNotFoundError: No module named 'harmonypy'"},{"fix":"Upgrade to v2.0.0: `pip install harmonypy>=2`. Then use `from harmonypy import run_harmony`.","cause":"You are using an older version of harmonypy (v0.1.0 or v0.2.0) where the function was located under a different import path or not available.","error":"AttributeError: module 'harmonypy' has no attribute 'run_harmony'"},{"fix":"In v2.0.0, the HarmonyResult object has a `Z_corr` attribute. Refer to the README for current API.","cause":"Using old API expecting the old attribute name (e.g., `Z_corrected`) or wrong class.","error":"harmonypy.harmony.Harmony object has no attribute 'Z_corr'"},{"fix":"Verify that meta has exactly the same number of rows as Z (cells).","cause":"The `meta` array or DataFrame does not have the same length as the number of cells in the PCA matrix.","error":"ValueError: The number of cells in meta does not match the number of rows in Z"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}