# FADVI: Factor Disentanglement Variational Inference
FADVI is a deep learning method for single-cell RNA sequencing analysis that disentangles batch-related variation, label-related variation, and residual variation using adversarial training and cross-correlation penalties.
Read the [documentation](https://fadvi.readthedocs.io/en/latest/) for usage and demo.
## Features
- **Factor Disentanglement**: Separates batch effects, cell type effects, and residual variation in single-cell data
- **Integration with scvi-tools**: Built on top of the scvi-tools framework for scalable analysis
- **Batch Correction**: Removes unwanted batch effects while preserving biological signal
- **Cell Type Classification**: Performs supervised learning for cell type prediction
## Installation
### Install from PyPI
```bash
pip install fadvi
```
## Quick Start
```python
import scanpy as sc
import scvi
from fadvi import FADVI
# Load your single-cell data
adata = sc.read_h5ad("your_data.h5ad")
# Setup the model
FADVI.setup_anndata(
adata,
batch_key="batch",
labels_key="cell_type",
unlabeled_category="Unknown",
layer="counts"
)
# Create and train the model
model = FADVI(adata)
model.train(max_epochs=30)
# Get latent representations
latent_l = model.get_latent_representation(representation="label")
latent_b = model.get_latent_representation(representation="batch")
# Get label predictions
prediction_label = model.predict(prediction_mode="label")
```
## Model Architecture
FADVI uses a variational autoencoder architecture with three latent subspaces:
- **z_b**: Batch-related latent factors
- **z_l**: Label-related latent factors
- **z_r**: Residual latent factors
The model uses adversarial training to ensure proper disentanglement between these factor subspaces.
## Citation
Comming soon...
If you use FADVI in your research, please cite:
```bibtex
@article{fadvi2025,
title={FADVI: disentangled representation learning for robust integration of single-cell and spatial omics data},
author={Wendao Liu},
journal={bioRxiv},
year={2025}
}
```
Raw data
{
"_id": null,
"home_page": null,
"name": "fadvi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Wendao Liu <liuwd15@gmail.com>",
"keywords": "single-cell, genomics, variational-inference, deep-learning, batch-correction, disentanglement",
"author": null,
"author_email": "Wendao Liu <liuwd15@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/21/ae/cb2237cb3aadc452b2264298528913600c009d1d630de77a2e96bbd725a2/fadvi-0.1.0.post1.tar.gz",
"platform": null,
"description": "# FADVI: Factor Disentanglement Variational Inference\r\n\r\nFADVI is a deep learning method for single-cell RNA sequencing analysis that disentangles batch-related variation, label-related variation, and residual variation using adversarial training and cross-correlation penalties.\r\n\r\nRead the [documentation](https://fadvi.readthedocs.io/en/latest/) for usage and demo.\r\n\r\n## Features\r\n\r\n- **Factor Disentanglement**: Separates batch effects, cell type effects, and residual variation in single-cell data\r\n- **Integration with scvi-tools**: Built on top of the scvi-tools framework for scalable analysis\r\n- **Batch Correction**: Removes unwanted batch effects while preserving biological signal\r\n- **Cell Type Classification**: Performs supervised learning for cell type prediction\r\n\r\n## Installation\r\n\r\n### Install from PyPI\r\n\r\n```bash\r\npip install fadvi\r\n```\r\n\r\n\r\n## Quick Start\r\n\r\n```python\r\n\r\nimport scanpy as sc\r\nimport scvi\r\nfrom fadvi import FADVI\r\n\r\n# Load your single-cell data\r\nadata = sc.read_h5ad(\"your_data.h5ad\")\r\n\r\n# Setup the model\r\nFADVI.setup_anndata(\r\n adata,\r\n batch_key=\"batch\",\r\n labels_key=\"cell_type\",\r\n unlabeled_category=\"Unknown\",\r\n layer=\"counts\"\r\n)\r\n\r\n# Create and train the model\r\nmodel = FADVI(adata)\r\nmodel.train(max_epochs=30)\r\n\r\n# Get latent representations\r\nlatent_l = model.get_latent_representation(representation=\"label\")\r\nlatent_b = model.get_latent_representation(representation=\"batch\")\r\n\r\n# Get label predictions\r\nprediction_label = model.predict(prediction_mode=\"label\")\r\n\r\n```\r\n\r\n## Model Architecture\r\n\r\nFADVI uses a variational autoencoder architecture with three latent subspaces:\r\n\r\n- **z_b**: Batch-related latent factors\r\n- **z_l**: Label-related latent factors \r\n- **z_r**: Residual latent factors\r\n\r\nThe model uses adversarial training to ensure proper disentanglement between these factor subspaces.\r\n\r\n\r\n## Citation\r\n\r\nComming soon...\r\n\r\nIf you use FADVI in your research, please cite:\r\n\r\n```bibtex\r\n@article{fadvi2025,\r\n title={FADVI: disentangled representation learning for robust integration of single-cell and spatial omics data},\r\n author={Wendao Liu},\r\n journal={bioRxiv},\r\n year={2025}\r\n}\r\n```\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Factor Disentanglement Variational Inference for single-cell batch integration",
"version": "0.1.0.post1",
"project_urls": {
"Bug Tracker": "https://github.com/liuwd15/fadvi/issues",
"Documentation": "https://fadvi.readthedocs.io",
"Homepage": "https://github.com/liuwd15/fadvi",
"Repository": "https://github.com/liuwd15/fadvi"
},
"split_keywords": [
"single-cell",
" genomics",
" variational-inference",
" deep-learning",
" batch-correction",
" disentanglement"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bed4e0b0fe308b9a5ff350a1243eb068db11f53b579dbcf0bee16da5872444bd",
"md5": "bc8e7097b8b85b9e46a9a020f545a4ae",
"sha256": "83bbf665ccf2c66037b05f585fea2c99d37237308b392e6ef62960e72b1fea3f"
},
"downloads": -1,
"filename": "fadvi-0.1.0.post1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bc8e7097b8b85b9e46a9a020f545a4ae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16438,
"upload_time": "2025-09-12T21:32:55",
"upload_time_iso_8601": "2025-09-12T21:32:55.890329Z",
"url": "https://files.pythonhosted.org/packages/be/d4/e0b0fe308b9a5ff350a1243eb068db11f53b579dbcf0bee16da5872444bd/fadvi-0.1.0.post1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "21aecb2237cb3aadc452b2264298528913600c009d1d630de77a2e96bbd725a2",
"md5": "3a1c15461e88b91b41431c838766701a",
"sha256": "7462a01efc2e1a6740ff278bfc1c03936c7f88b03315118fecbaa4af713b0408"
},
"downloads": -1,
"filename": "fadvi-0.1.0.post1.tar.gz",
"has_sig": false,
"md5_digest": "3a1c15461e88b91b41431c838766701a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 4027322,
"upload_time": "2025-09-12T21:32:57",
"upload_time_iso_8601": "2025-09-12T21:32:57.409365Z",
"url": "https://files.pythonhosted.org/packages/21/ae/cb2237cb3aadc452b2264298528913600c009d1d630de77a2e96bbd725a2/fadvi-0.1.0.post1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 21:32:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "liuwd15",
"github_project": "fadvi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "scvi-tools",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "torch",
"specs": [
[
">=",
"1.12.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "scanpy",
"specs": [
[
">=",
"1.8.0"
]
]
},
{
"name": "anndata",
"specs": [
[
">=",
"0.8.0"
]
]
},
{
"name": "torchmetrics",
"specs": [
[
">=",
"0.10.0"
]
]
}
],
"lcname": "fadvi"
}
JSON
