Metadata-Version: 2.4
Name: scmidas
Version: 0.2.0
Summary: A torch-based integration method for single-cell multi-omic data.
Author-email: labomics <omicshub@outlook.com>
License: MIT
Project-URL: Homepage, https://github.com/labomics/midas
Project-URL: Documentation, https://scmidas.readthedocs.io/
Project-URL: Source, https://github.com/labomics/midas
Project-URL: Changelog, https://scmidas.readthedocs.io/en/latest/release.html
Project-URL: Issues, https://github.com/labomics/midas/issues
Keywords: single-cell,multi-omics,integration,pytorch,scanpy,anndata,mudata
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch<2.11,>=2.5
Requires-Dist: torchvision<0.26,>=0.20
Requires-Dist: torchaudio<2.11,>=2.5
Requires-Dist: lightning<2.7,>=2.4
Requires-Dist: numpy<3,>=1.23
Requires-Dist: scipy<2,>=1.9
Requires-Dist: pandas<3,>=1.5
Requires-Dist: scikit-learn<2,>=1.2
Requires-Dist: matplotlib<4,>=3.7
Requires-Dist: anndata<0.13,>=0.10
Requires-Dist: mudata<0.4,>=0.3
Requires-Dist: scanpy<2,>=1.10
Requires-Dist: tqdm<5,>=4.64
Requires-Dist: requests<3,>=2.28
Requires-Dist: toml<1,>=0.10
Requires-Dist: natsort<9,>=8
Provides-Extra: notebook
Requires-Dist: ipykernel<7,>=6; extra == "notebook"
Provides-Extra: dev
Requires-Dist: pytest<9,>=7; extra == "dev"
Requires-Dist: pytest-cov<6,>=4; extra == "dev"
Requires-Dist: ruff<1,>=0.5; extra == "dev"
Requires-Dist: mypy<2,>=1.7; extra == "dev"
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: twine<6,>=5; extra == "dev"
Requires-Dist: pip-tools<8,>=7; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx<9,>=7; extra == "docs"
Requires-Dist: sphinx-book-theme<2,>=1.1; extra == "docs"
Requires-Dist: sphinx-copybutton<1,>=0.5; extra == "docs"
Requires-Dist: sphinx-markdown-tables<1,>=0.0.17; extra == "docs"
Requires-Dist: recommonmark<1,>=0.7; extra == "docs"
Requires-Dist: nbsphinx<1,>=0.9; extra == "docs"
Dynamic: license-file

# MIDAS

<div align="center">
  <img src="docs/source/_static/img/midas_logo_vertical.png" alt="MIDAS Logo" width="900px">
</div>

<p align="center">
  MIDAS turns raw mosaic single-cell multimodal data into <strong>imputed</strong>, <strong>batch-corrected matrices</strong> and <strong>disentangled latent representations</strong>.
</p>

<p align="center">
  <a href="https://github.com/labomics/midas/actions/workflows/test.yml"><img src="https://github.com/labomics/midas/actions/workflows/test.yml/badge.svg" alt="CI Status"></a>
  <a href="https://pypi.org/project/scmidas/"><img src="https://img.shields.io/pypi/v/scmidas" alt="PyPI version"></a>
  <a href="https://scmidas.readthedocs.io/en/latest/"><img src="https://img.shields.io/readthedocs/scmidas" alt="Documentation Status"></a>
  <a href="https://github.com/labomics/midas/blob/main/LICENSE"><img src="https://img.shields.io/github/license/labomics/midas?v=1" alt="License"></a>
  <a href="https://colab.research.google.com/github/labomics/midas/blob/main/examples/quickstart.ipynb"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"></a>
  <a href="https://github.com/labomics/midas/stargazers"><img src="https://img.shields.io/github/stars/labomics/midas?style=social" alt="GitHub Stars"></a>
</p>

**Documentation:** [scmidas.readthedocs.io](https://scmidas.readthedocs.io/en/latest/)

## Key features

*   **Mosaic integration** — handle datasets where different batches measure different modality combinations (e.g. some batches have RNA + ATAC, others only RNA).
*   **Multi-modal support** — RNA, ADT, ATAC out of the box; configurable for additional modalities.
*   **Imputation** — fill in missing modalities with model-derived values.
*   **Batch correction** — remove technical variation across batches.
*   **Knowledge transfer** — fine-tune a pre-trained reference model on a query dataset.
*   **Multi-GPU training** — built on PyTorch Lightning, with DDP support for mosaic data.
*   **TensorBoard integration** — live training loss and UMAP visualisations.

## Installation

```bash
conda create -n scmidas python=3.12
conda activate scmidas
pip install scmidas
```

## Quick start

A bundled 1600-cell PBMC RNA+ADT mosaic dataset lets you go from `pip install` to a UMAP in about a minute on a single GPU — no extra downloads, no config files. Click the [Colab badge](https://colab.research.google.com/github/labomics/midas/blob/main/examples/quickstart.ipynb) to run it without installing anything, or copy the snippet:

```python
import scmidas

mdata = scmidas.datasets.quickstart()      # bundled toy MuData
model = scmidas.integrate(mdata)           # ~1 min on a mid-range GPU
out   = model.predict(joint_latent=True)   # latent embeddings per batch
```

This produces lineage-separated clusters that mix freely across batches:

<div align="center">
  <img src="docs/source/_static/img/quickstart_umap.png" alt="quickstart UMAP" width="850px">
</div>

> ⚠️ **`scmidas.integrate()` defaults are tuned for the bundled toy dataset.** For your own data, override `max_epochs` (1000-2000 is typical) and consider letting `batch_size` default back to 256, e.g. `scmidas.integrate(my_mdata, max_epochs=2000, batch_size=256)`. See the [full demos](https://scmidas.readthedocs.io/en/latest/) for end-to-end pipelines on real-sized data, including imputation, batch correction, and cross-modality translation.

## Reproducibility

Code and data to reproduce the results in the paper live on the [`reproducibility`](https://github.com/labomics/midas/tree/reproducibility) branch.

## Citation

If you use MIDAS in your research, please cite:

```bibtex
@article{he2024mosaic,
  title   = {Mosaic integration and knowledge transfer of single-cell multimodal data with {MIDAS}},
  author  = {He, Zhen and Hu, Shuofeng and Chen, Yaowen and An, Sijing
             and Zhou, Jiahao and Liu, Runyan and Shi, Junfeng and Wang, Jing
             and Dong, Guohua and Shi, Jinhui and Zhao, Jiaxin and Ou-Yang, Le
             and Zhu, Yuan and Bo, Xiaochen and Ying, Xiaomin},
  journal = {Nature Biotechnology},
  volume  = {42},
  number  = {10},
  pages   = {1594--1605},
  year    = {2024},
  doi     = {10.1038/s41587-023-02040-y},
  publisher = {Nature Publishing Group}
}
```

## Contributing

Bug reports and feature requests: please open a [GitHub issue](https://github.com/labomics/midas/issues). For code contributions, branch from `main`, make sure `pytest tests/` passes, and open a pull request — for non-trivial changes, an issue first to discuss the design is appreciated.

## License

[MIT](https://github.com/labomics/midas/blob/main/LICENSE).
