VIVS

VIVS (Variational Inference for Variable Selection) is a Python package to identify molecular dependencies in omics data. Please refer to the preprint and to the project repository here for more details.

Installation

To install the package, on Python >= 3.9, you can do the following:

1. install jax with GPU support (see here for instructions)
2. install the package using pip:

pip install vivs

Alternatively, you can clone the repository and install the package in editable mode:

pip install -e .

Basic usage

Data format

To use VIVS in your project, import the data of intest in a scanpy AnnData object. Right now, VIVS only supports assays where $X$ corresponds to gene expression counts. In particular, make sure than the anndata contains raw counts and not normalized data.

The response(s) $Y$ of interest are expected to be stored in the obsm attribute of the anndata object, either as an array or as a dataframe.

VIVS may not scale to many thousands of genes. In such a case, it is recommended to filter the genes before running VIVS, which can be done in the following way:

from vivs import select_genes

adata = select_genes(adata, n_top_genes=2000)

Model fitting and inference

VI-VS can be initialized and trained as follows:

from vivs import VIVS

model = VIVS(
    adata,
    feature_obsm_key="my_obsm_key",
    xy_linear=False,
    xy_model_kwargs={"n_hidden": 8}
)
model.train_all()

Once the model is trained, feature significance can be computed as follows:

res = model.get_hier_importance(n_clusters_list=[100, 200])

Here, n_clusters_list is a list of the number of clusters to consider for the hierarchical clustering of the features.

These results can be visualized using plot_hier_importance:

model.plot_hier_importance(res, theme_kwargs=dict(figure_size=(15, 2))