v2.0.0

Complete rewrite with C++ backend (Armadillo + nanobind), matching the R harmony2 package step-by-step.

Highlights

• ~10x faster than v0.1.0: 858k cells in ~36s on Apple M1 Ultra (vs ~340s previously)
• Matches R harmony2: correlation ≥0.998 across all PCs
• Minimal dependencies: only numpy at runtime
• Pre-built wheels for Linux (x86_64, aarch64) and macOS (x86_64, arm64), Python 3.9–3.13

New

• C++ backend with BLAS-accelerated dense matrix ops (Accelerate on macOS, OpenBLAS on Linux)
• Custom scatter/gather kernels replace all sparse matrix operations
• K-means initialization matches R exactly (Gumbel-max cosine-distance sampling)
• ncores parameter to control BLAS thread count
• batch_prop_cutoff parameter for underrepresented batch handling
• Arrowhead matrix inverse for fast single-covariate correction
• Accepts pandas DataFrame, dict of arrays, or NumPy array for meta_data
• C++ progress messages routed through Python logging for proper integration with downstream packages (thanks @yakirr)

Breaking changes

• lamb defaults to automatic estimation (was fixed 1). Pass lamb=1 for old behavior.
• Default parameters changed to match R harmony2: max_iter_kmeans 20→4, epsilon_cluster 1e-5→1e-3, epsilon_harmony 1e-4→1e-2
• Only numpy required at runtime (previously pandas, scipy, scikit-learn)

See CHANGELOG.md for full details.

harmonypy v0.2.0

This release uses PyTorch for faster GPU and CPU performance. This version of harmonypy should produce the same results as the harmony_1.2.4 R package.

If you need a NumPy-only version, please use release v0.1.0.

harmonypy v0.1.0

This release should produce similar results to the R package harmony_1.2.4.

harmonypy version 0.0.10

• Use hatch instead of setup.py to ease development and include multiple authors.

harmonypy version 0.0.9

• Stop excluding README.md from the build, because setup.py depends on this file.

harmonypy version 0.0.8

• Replace scipy.cluster.vq.kmeans2 with the faster function sklearn.cluster.KMeans. Thanks to @johnarevalo for providing details about the running time with both functions in PR #20.

harmonypy version 0.0.6

• Replace scipy.cluster.vq.kmeans with scipy.cluster.vq.kmeans2 to address
  issue #10 where we learned that kmeans does not always return k centroids,
  but kmeans2 does return k centroids. Thanks to @onionpork and @DennisPost10
  for reporting this.

harmonypy version 0.0.5

Released on 2020-08-11

• Expose max_iter_harmony as a new top-level argument, in addition to the
  previously exposed max_iter_kmeans. This more closely resembles the
  original interface in the harmony R package. Thanks to @pinin4fjords
  for pull request #8

(This release was originally posted on 2020-08-11. Now, I am trying to re-post the same release again, in the hope that it gets automatically picked up by Zenodo).

harmonypy version 0.0.4

Released on 2020-03-02

• Fix a bug in the LISI code that sometimes causes computation to break. Thanks
  to @tariqdaouda for reporting it in issue #1

• Fix a bug that prevents controlling the number of iterations. Thanks to
  @liboxun for reporting it in issue #3

• Fix a bug causing slightly different results than expected. Thanks to
  @bli25broad for pull request #2

• Add support for multiple categorical batch variables.