Metadata-Version: 2.5
Name: perturbvi
Version: 0.3.0
Summary: Infer regulatory modules through informative latent component model in the single-cell Perturb-seq data
Project-URL: Documentation, https://mancusolab.github.io/perturbvi
Project-URL: Issues, https://github.com/mancusolab/perturbvi/issues
Project-URL: Source, https://github.com/mancusolab/perturbvi
Author-email: Abdullah Al-Nahid <alnahid@usc.edu>, Dong Yuan <dongyuan@usc.edu>, Nicholas Mancuso <nmancuso@usc.edu>
License-Expression: MIT
License-File: LICENSE.txt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.9
Requires-Dist: anndata
Requires-Dist: equinox
Requires-Dist: importlib-metadata; python_version < '3.8'
Requires-Dist: jax
Requires-Dist: jaxlib
Requires-Dist: jaxtyping
Requires-Dist: lineax
Requires-Dist: numpy
Requires-Dist: optax
Requires-Dist: optimistix
Requires-Dist: pandas
Requires-Dist: plum-dispatch
Requires-Dist: scipy
Provides-Extra: plotting
Requires-Dist: matplotlib>=3.7; extra == 'plotting'
Description-Content-Type: text/markdown

[![Documentation](https://img.shields.io/badge/Docs-Available-brightgreen)](https://mancusolab.github.io/perturbvi/)
[![PyPI](https://img.shields.io/pypi/v/perturbvi.svg)](https://pypi.org/project/perturbvi/)
[![GitHub](https://img.shields.io/github/stars/mancusolab/perturbvi?style=social)](https://github.com/mancusolab/perturbvi)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Project generated with Hatch](https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg)](https://github.com/pypa/hatch)

# PerturbVI

PerturbVI infers latent gene programs and their perturbation effects from
single-cell Perturb-seq data.

> [!NOTE]
> For the preprint, please see: <br/>
> *PerturbVI: A Scalable Latent Factor Model to Infer Genetic Regulatory Modules through CRISPR Perturbation Data*. <br/>
> [doi.org/10.0000/perturbvi](https://doi.org/10.0000/perturbvi) (placeholder DOI)

> [!IMPORTANT]
> To reproduce the analyses in the preprint: <br/>
> [zenodo.org/records/0000000](https://zenodo.org/records/0000000) (placeholder)

## Installation

```bash
uv pip install perturbvi
```

## Quick start

Prepare an H5AD file with transformed expression in `adata.X` and a binary,
named perturbation DataFrame in `adata.obsm["G"]`.

```python
from pathlib import Path
from perturbvi import fit_screen, load_screen, save_results

result_dir = Path("results/my_screen")
data = load_screen(
    "data/screen.h5ad",
)
fit = fit_screen(
    data,
    z_dim=12,
    l_dim=100,
)
save_results(
    fit,
    result_dir,
)
```

This saves the fitted model and labeled result CSVs in `result_dir`.
See the tutorials for plotting and enrichment.

## Tutorials

- [LUHMES Analysis with PerturbVI](https://mancusolab.github.io/perturbvi/luhmes/): fitting, factor and gene effects, and neuronal GO enrichment.
- Replogle Analysis with PerturbVI: fitting and interpretation (TBD).
- [Using PerturbVI with Your Data](https://mancusolab.github.io/perturbvi/workflow/): CSV and AnnData inputs, controls, covariates, and fitting.
- [API](https://mancusolab.github.io/perturbvi/api/): function arguments, result matrices, and CLI.

## Support

Please report bugs or feature requests in the
[issue tracker](https://github.com/mancusolab/perturbvi/issues). For questions
or comments, contact Abdullah Al Nahid (<alnahid@usc.edu>) or Nicholas Mancuso
(<nmancuso@usc.edu>).

## Other Software

Other software developed by the [Mancuso Lab](https://www.mancusolab.com/):

- [SuShiE](https://github.com/mancusolab/sushie): a Bayesian fine-mapping
  framework for molecular QTL data across multiple ancestries.
- [jaxQTL](https://github.com/mancusolab/jaxqtl): scalable, count-based
  large-scale eQTL mapping.
- [MA-FOCUS](https://github.com/mancusolab/ma-focus): a Bayesian fine-mapping
  framework using [TWAS](https://www.nature.com/articles/ng.3506) statistics
  across multiple ancestries to identify causal genes for complex traits.
- [SuSiE-PCA](https://github.com/mancusolab/susiepca): scalable Bayesian
  variable selection for sparse principal component analysis.
- [twas_sim](https://github.com/mancusolab/twas_sim): simulation of
  [TWAS](https://www.nature.com/articles/ng.3506) statistics.
- [traceax](https://github.com/mancusolab/traceax): stochastic trace
  estimation for linear operators.
- [FactorGo](https://github.com/mancusolab/factorgo): scalable variational
  factor analysis for learning pleiotropic factors from GWAS summary
  statistics.
- [HAMSTA](https://github.com/tszfungc/hamsta): estimation of heritability
  explained by local ancestry data from admixture mapping summary statistics.

---

PerturbVI is distributed under the terms of the
[MIT license](https://spdx.org/licenses/MIT.html).
