Welcome to the documentation for Harmonics!
Harmonics: Hierarchical distribution matching enables comprehensive characterization of common and condition-specific cell niches in spatial omics data
Contents
- Installation
- Usage
- Import the package
- Initialize the model
- Construct cell representations
- Over-clustering initialization (whole dataset / control group / reference)
- Perform HDM to find solution
- Select the solution
- Over-clustering initialization (case group)
- Perform HDM to find solution (case group)
- Select the solution (case group)
- Label transfer
- Cell type enrichment test
- Cell-cell interaction enrichment test
- Niche-niche colocalization enrichment test
- Niche-niche colocalization matrix
- Niche-niche colocalization patterns differential test between groups
- Condition-agnostic studies
- Case-control studies
Overview
Deciphering cell niches in complex tissues is essential for understanding tissue structure and disease. Recent advances in spatial omics have enabled subcellular resolution and accurate cell identity mapping. However, robust delineation of cell niches and disease-associated spatial patterns remains difficult. We introduce Harmonics, a novel computational framework that systematically identifies both common and condition-specific cell niches from spatial omics data through hierarchical distribution matching. Harmonics also includes a suite of downstream modules that facilitate comprehensive niche characterization. We demonstrate its scalability, accuracy and generalizability across datasets spanning diverse species, tissues, diseases, spatial modalities, and technological platforms. For condition-agnostic datasets, Harmonics outperforms baseline methods in both accuracy and robustness, and further demonstrates the capability to resolve niche structures at finer granularity. Across diverse diseases including pulmonary fibrosis, triple-negative breast cancer, and colorectal cancer, Harmonics enables precise identification of condition-specific niches and reveals disease-associated dynamics, subtype-specific spatial patterns, and structured immune architectures. We envision Harmonics as a practical and versatile tool for spatial niche analysis that can be applied across a wide range of biological contexts and seamlessly integrated with existing spatial omics workflows.