Metadata-Version: 2.4
Name: m3-sc
Version: 0.3.0
Summary: Multimodal, multi-batch, condition-aware single-cell model with donor-level disease prediction
Project-URL: Homepage, https://github.com/PYangLab/M3
Project-URL: Documentation, https://pyanglab.github.io/M3/
Project-URL: Repository, https://github.com/PYangLab/M3
Author: CSB Yang Laboratory
License: MIT
License-File: LICENSE
Keywords: CITE-seq,batch-integration,deep-learning,multiomics,patient-prediction,single-cell,variational-autoencoder
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Requires-Dist: anndata
Requires-Dist: captum
Requires-Dist: h5py
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scanpy
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# M3

**M3** is a deep generative framework for **condition-aware integration**,
**patient-level inference**, and **multi-resolution interpretation** of multimodal
single-cell omics data across many biological conditions and samples.

From one shared, condition-aware representation, M3 delivers six downstream tasks:
factorised dimension reduction, condition-aware batch correction, mosaic
integration + imputation, patient-level condition inference, patient/sample
generation, and multi-resolution attribution.

📖 **Documentation & tutorials:** https://pyanglab.github.io/M3/

## Install

### Python

```bash
pip install m3-sc      # imported as `import m3`
```

PyTorch comes along automatically. If you need a build matched to a specific CUDA
version, install it first and pip will keep it:

```bash
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install m3-sc
```

For the development version: `pip install "git+https://github.com/PYangLab/M3.git"`.

### R

```r
install.packages("remotes")
remotes::install_github("PYangLab/M3", subdir = "m3-r")
```

The R package provisions its own Python engine through
[basilisk](https://bioconductor.org/packages/basilisk/) on first use — no manual
Python / PyTorch setup, and R and Python produce identical results.

## Quickstart (Python)

```python
import m3

data  = m3.datasets.liu_demo()                                  # built-in demo
model = m3.M3(data, condition_keys=["cond_group"],
              celltype_key="mergedcelltype").train()
emb   = model.embedding(part="bio")                             # integrated embedding
```

## Repository layout

| Path | What |
|---|---|
| `src/m3/` | the `m3-sc` Python package (PyTorch engine vendored under `_engine/`) |
| `m3-r/` | the R package — `library(m3)`, basilisk-wrapped, same engine |
| `website/` | documentation site (MkDocs Material); `mkdocs serve -f website/mkdocs.yml` |
| `.github/workflows/deploy.yml` | builds + publishes the docs to GitHub Pages |
| `tests/` | Python test suite |

## License

See [LICENSE](LICENSE).
