PerturbVI

Perturbvi is a scalable approach to infer regulatory modules through informative latent component model in the single-cell Perturb-seq data.

Install

uv pip install perturbvi

Quick start

From AnnData (recommended)

Prepare the file with transformed expression in adata.X and the binary perturbation matrix in adata.obsm["G"], then load and fit:

from perturbvi import fit_screen, load_screen, residualize_screen

data = load_screen(
    "screen.h5ad",
    x_key=None,  # None (Default) = adata.X
    g_key="G",  # "G" (Default) = adata.obsm["G"]
    control=None,
)

data = load_screen(
    "screen.h5ad",
    x_key="transformed",  # adata.layers["transformed"]
    g_key="G",  # "G" (Default) = adata.obsm["G"]
    control=None,
)

data = load_screen(
    "screen.h5ad",
    x_key="counts",  # adata.layers["counts"]
    g_key="perturbations",  # adata.obsm["perturbations"]
    control="Nontargeting",  # drop the reference column
)

data = residualize_screen(data)  # optional; only if you loaded covariates

fit = fit_screen(data, z_dim=12, l_dim=400, tau=50)

Same workflow from the CLI:

perturbvi fit screen.h5ad \
  --output results \
  --z-dim 12 --l-dim 400 --tau 50

Omit --control when G is baseline-free; add --control Nontargeting when G keeps its reference column.

perturbvi analyze results

Already have X and G? (arrays or CSV)

PerturbData keeps expression, perturbations, and covariates aligned:

from perturbvi import PerturbData, fit_screen, residualize_screen

# control= drops the reference column; omit it when G is baseline-free
data = PerturbData(
    X=expression,
    G=G,
    covariates=covariates,
    control="Nontargeting",
)

data = residualize_screen(data)  # optional

fit = fit_screen(data, z_dim=12, l_dim=400, tau=50)

X and G are both required, and their rows must refer to the same cells in the same order. Read CSV/TSV files with pandas first, then pass the resulting DataFrames so gene and perturbation names stay aligned.

fit_screen() always centers each gene across cells. If your expression is not already scaled, pass standardize=True to also divide each gene by its standard deviation, giving every gene unit variance.

control= names a reference column in G to drop (for example "Nontargeting"). Omit it when G is already baseline-free.

See the Workflow for complete input and analysis guidance and the Input structure page for where each piece of a screen lives in an AnnData file. The Cookbook for real Datlinger, Norman, and Adamson screens.

Documentation

• Workflow: constructing X and G, names, covariates, fitting, saving, and analysis.
• Input structure: AnnData layout for X, G, and covariates.
• Cookbook: real LUHMES, Datlinger, Adamson, Norman, and A375 10x examples.
• API: Python functions, CLI options, result tables, and saved files.

Support

Please report bugs or feature requests in the issue tracker. 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:

• SuShiE: a Bayesian fine-mapping framework for molecular QTL data across multiple ancestries.
• jaxQTL: scalable, count-based large-scale eQTL mapping.
• MA-FOCUS: a Bayesian fine-mapping framework using TWAS statistics across multiple ancestries to identify causal genes for complex traits.
• SuSiE-PCA: scalable Bayesian variable selection for sparse principal component analysis.
• twas_sim: simulation of TWAS statistics.
• traceax: stochastic trace estimation for linear operators.
• FactorGo: scalable variational factor analysis for learning pleiotropic factors from GWAS summary statistics.
• HAMSTA: estimation of heritability explained by local ancestry data from admixture mapping summary statistics.

PerturbVI is distributed under the terms of the MIT license.