{"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,"search_vec":"'10x':42 '2.0.0':30 '64':56 'aarch64':57 'algorithm':8 'armadillo':23,72 'avail':52 'backend':24,82 'batch':10,74 'batch-correct':73 'bioinformat':80 'built':49 'c':22,71,81 'cell':15,78 'complet':33 'correct':11,75 'current':28 'data':19 'featur':20 'harmoni':7,79 'harmony2':39 'harmonypi':1 'high':26 'improv':44 'intermitt':62 'linux':54 'maco':59 'major':64 'match':36 'packag':40 'perform':27 'port':4 'pre':48 'pre-built':47 'python':3 'pytorch':68 'r':38 'releas':60 'rewrit':34,65 'rna':17 'rna-seq':16 'seq':18 'singl':14,77 'single-cel':13,76 'speed':43 'v0.1.0':46 'v0.2.0':67 'v2.0.0':70 'version':29 'wheel':50 'x86':55","created_at":"2026-05-01T08:09:54.327933+00:00","updated_at":"2026-05-01T08:09:54.327933+00:00","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,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.0.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/slowkow/harmonypy","docs":null,"changelog":"https://github.com/slowkow/harmonypy/blob/master/CHANGELOG.md","pypi":"https://pypi.org/project/harmonypy/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-29","last_verified":"2026-06-29","next_check":"2026-07-29","install_tag":null}}