PyViscel

Interactive visualization and analysis of single-cell transcriptomics data — Python port of the VisCello R/Bioconductor package.

No R runtime required. Native AnnData/h5ad format throughout.

---

Installation

Option A — pip from GitHub (recommended)

pip install git+https://github.com/Gartner-Lab/pyviscel.git

To upgrade to the latest version later:

pip install --upgrade git+https://github.com/Gartner-Lab/pyviscel.git

Option B — conda environment (recommended for new machines)

Some dependencies (leidenalg, igraph, umap-learn) can be tricky to build from source. Using conda avoids compiler issues:

conda create -n pyviscel python=3.12
conda activate pyviscel
conda install -c conda-forge leidenalg python-igraph umap-learn
pip install git+https://github.com/Gartner-Lab/pyviscel.git

Option C — development install (for contributors)

git clone https://github.com/Gartner-Lab/pyviscel.git
cd pyviscel
pip install -e ".[dev]"

Runtime dependencies (auto-installed): anndata, dash, dash-bootstrap-components, plotly, pandas, numpy, scipy, scikit-learn, umap-learn, openTSNE, leidenalg, igraph, statsmodels, gseapy, matplotlib, seaborn.

---

Quick Start

Step 1 — Get your data into h5ad

Option A — Convert from an existing VisCello R object:

# In R — requires the original VisCello R package
library(VisCello)
cc <- readRDS("my_cello.rds")
viscello_to_h5ad(cc, "my_data.h5ad")

Option B — Build an AnnData directly in Python:

from pyviscel import validate_adata, save_adata
validate_adata(adata)          # checks required slots
save_adata(adata, "my_data.h5ad")

Step 2 — Explore programmatically

from pyviscel import load_adata, list_cellos, list_projections

adata = load_adata("my_data.h5ad")
print(list_cellos(adata))                       # ['All Cells', 'T cells', ...]
print(list_projections(adata, "All Cells"))     # ['UMAP_2D', 'UMAP_3D', ...]

Step 3 — Launch the interactive web app

from pyviscel import run_app
run_app("my_data.h5ad", host="127.0.0.1", port=8050)

Or from the terminal:

pyviscel my_data.h5ad
pyviscel my_data.h5ad --host 0.0.0.0 --port 8050   # accessible on local network
pyviscel my_data.h5ad --no-validate                 # skip schema check for external h5ad files

Then open http://127.0.0.1:8050 in your browser.

---

Web App Features

Explorer Tab

Control	Description
Cello dropdown	Select a named cell subset
Projection dropdown	Select a 2-D or 3-D embedding (PCA, t-SNE, UMAP)
Color By dropdown	Color cells by metadata column, Manual_Selection, or gene expression
Point size / Alpha	Adjust marker size and transparency
Legend	Toggle full / abbreviated / no legend

Cell Annotation (manual selection)

2-D projections:

1. Switch the main scatter to lasso/box tool (toolbar icon)
2. Draw a selection on the plot — the status bar shows the cell count
3. Click Confirm — the selection is saved as Group 1, Group 2, etc. in a new Manual_Selection column
4. Repeat for more groups
5. Select Manual_Selection in Color By to see all groups

3-D projections:

1. Rotate the 3-D scatter to any viewing angle
2. Click Snapshot Current View — a 2-D projection of that camera angle appears below
3. Draw a lasso on the 2-D projection — the cell count updates
4. Click Confirm — same Group 1/2/3 workflow as 2-D
5. Click Clear to reset the projection panel

Differential Expression Tab

Compares a selected group of cells against a background using:

• Chi-square — fast, good for detecting marker genes
• Mann-Whitney U — non-parametric, robust
• sSeq — negative-binomial model (closest to edgeR/DESeq2 behaviour)

The DE panel shows:

• Group 1 DEGs — genes upregulated in the selected group (log2FC > 0)
• Group 2 DEGs — genes upregulated in the background group (log2FC < 0, displayed as positive fold-change)
• A scatter plot coloured by group membership on the selected projection
• A gene expression scatter for any gene you search in the DE results
• A heatmap of the top significant genes

Results are sortable and downloadable as CSV.

Enrichment Tab

GO/KEGG over-representation analysis (ORA) via the Enrichr API (gseapy).

• Select the organism matching your data (human, mouse, rat, fly, zebrafish, yeast, worm)
• Select the gene set type: Biological Process (BP), Molecular Function (MF), Cellular Component (CC), KEGG, or All
• Click Run Enrichment — results appear in per-group tabs, sortable and downloadable as Excel
• Error and diagnostic messages appear below the button (gene count submitted, organism used)

---

Modules

Module	Description
pyviscel.io	Load/save .h5ad, validate schema, list cellos and projections
pyviscel.cello_class	Cello and CelloCollection — named cell subsets with projections
pyviscel.dim_reduction	PCA, t-SNE, UMAP (stored in adata.obsm)
pyviscel.clustering	k-NN graph construction, Leiden / Louvain / density clustering
pyviscel.differential_expression	Chi-square, Mann-Whitney U, sSeq NB DE tests
pyviscel.enrichment	GO/KEGG over-representation analysis via gseapy (Enrichr or offline)
pyviscel.plotting	Plotly scatter plots, expression plots, feature violin/box plots
pyviscel.heatmap	Annotated gene expression heatmap (log → z-score → cluster)
pyviscel.ui_components	Reusable Dash/DBC layout components
pyviscel.app	Full Dash application with Explorer, Annotation, and DE tabs
pyviscel.convert	Utilities for converting R VisCello objects to AnnData

---

Development

pip install -e ".[dev]"
pytest tests/ -q          # 390 tests

Tests cover all analysis modules and the Dash app layout/callbacks.

---

Known Limitations / Upcoming Work

• 3-D camera-angle selection: snapshot projection works; minor visual edge cases remain (being fixed)
• dash_table.DataTable deprecation warning from Dash — no functional impact; migration to dash-ag-grid planned
• Enrichr enrichment uses the built-in Enrichr background, not a custom gene universe (Enrichr API limitation); use compute_go_offline() directly for custom-background ORA