--- a
+++ b/README.md
@@ -0,0 +1,29 @@
+<img src="https://github.com/Lotfollahi-lab/nichecompass/blob/main/docs/_static/nichecompass_logo_readme.png" width="800" alt="nichecompass-logo">
+
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://github.com/Lotfollahi-lab/nichecompass/blob/main/LICENSE)
+[![Stars](https://img.shields.io/github/stars/Lotfollahi-lab/nichecompass?logo=GitHub&color=yellow)](https://github.com/Lotfollahi-lab/nichecompass/stargazers)
+[![PyPI](https://img.shields.io/pypi/v/nichecompass.svg)](https://pypi.org/project/nichecompass)
+[![PyPIDownloads](https://static.pepy.tech/badge/nichecompass)](https://pepy.tech/project/nichecompass)
+[![Docs](https://readthedocs.org/projects/nichecompass/badge/?version=latest)](https://nichecompass.readthedocs.io/en/stable/?badge=stable)
+[![Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![PyPI](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
+
+NicheCompass (**N**iche **I**dentification based on **C**ellular grap**H** **E**mbeddings of **COM**munication **P**rograms **A**ligned across **S**patial **S**amples) is a package for end-to-end analysis of spatial multi-omics data, including spatial atlas building, niche identification & characterization, cell-cell communication inference and spatial reference mapping. It is built on top of [PyG](https://pytorch-geometric.readthedocs.io/en/latest/) and [AnnData](https://anndata.readthedocs.io/en/latest/).
+
+## Resources
+- An installation guide, tutorials and API documentation is available in the [documentation](https://nichecompass.readthedocs.io/).
+- Please use [issues](https://github.com/Lotfollahi-lab/nichecompass/issues) to submit bug reports.
+- If you would like to contribute, check out the [contributing guide](https://nichecompass.readthedocs.io/en/latest/contributing.html).
+- If you find NicheCompass useful for your research, please consider citing the NicheCompass manuscript.
+
+## Reference
+```
+@article{Birk2025,
+  author    = {Birk, S. and Bonafonte-Pard{\`a}s, I. and Feriz, A. M. and et al.},
+  title     = {Quantitative characterization of cell niches in spatially resolved omics data},
+  journal   = {Nature Genetics},
+  year      = {2025},
+  doi       = {10.1038/s41588-025-02120-6},
+  url       = {https://doi.org/10.1038/s41588-025-02120-6}
+}
+```