Hierarchical distribution matching enables comprehensive characterization of common and condition-specific cell niches in spatial omics data

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.