BadranSeq is an R package that produces publication-ready figures from Seurat objects without additional styling. Built on native ggplot2, it closes the gap between exploratory analysis and manuscript-quality visualisation that Seurat’s defaults leave open.
Seurat’s plotting functions are designed for exploration, not publication. Every project ends with the same boilerplate: computing and formatting PCA variance labels, adding cell borders, styling themes, building split-panel comparisons that preserve spatial context, and wiring up statistical annotations on violin plots. This work is repeated across every analysis, every manuscript, and every lab.
| Feature | Seurat | BadranSeq |
|---|---|---|
| PCA variance labels on axes | No | Automatic |
| Cell borders | No | On by default |
| Cluster labels | Off by default | On by default |
| Split-panel silhouettes | No — facets lose spatial context | Grey silhouette preserves context |
| Statistical violin plots | Not built-in | Kruskal–Wallis + pairwise via ggstatsplot |
| Viridis feature plots | No | Default |
| Interactive cell selection | Limited (CellSelector) |
Additive/subtractive brush selection |
| Publication theme | No | Consistent across all outputs |
| Automatic rasterisation | No | >50k cells auto-rasterised |
| Sankey / alluvial diagrams | No | Metadata relationship flows |
The figures below are generated with default settings — no theme adjustments, no manual annotations.
library(BadranSeq)
library(Seurat)
library(ggplot2)
library(patchwork)
data(pbmc3k)
p1 <- DimPlot(pbmc3k, reduction = "umap") + ggtitle("Seurat::DimPlot()")
p2 <- do_UmapPlot(pbmc3k) + ggtitle("BadranSeq::do_UmapPlot()")
p1 + p2
BadranSeq adds cell borders, boxed cluster labels, a vivid colour palette, and a clean theme — all with one function call.
p1 <- DimPlot(pbmc3k, reduction = "pca") + ggtitle("Seurat::DimPlot(reduction = 'pca')")
p2 <- do_PcaPlot(pbmc3k) + ggtitle("BadranSeq::do_PcaPlot()")
p1 + p2
Seurat’s PCA plot shows “PC_1” and “PC_2” with no indication of how much variance each component explains. BadranSeq computes and formats this automatically.
When comparing conditions, Seurat’s split.by facets each panel
independently — you cannot see where a subpopulation sits relative to
the full dataset. BadranSeq renders all cells as a grey silhouette in
every panel, overlaying only the current category in colour:
do_UmapPlot(pbmc3k, split.by = "condition")
do_StatsViolinPlot() wraps ggstatsplot::ggbetweenstats() with
Seurat-aware data extraction, automatic colour generation, and a
group.levels argument for comparing specific clusters:
do_StatsViolinPlot(pbmc3k, features = "CD3D",
group.by = "seurat_annotations",
group.levels = c("Naive CD4 T", "Memory CD4 T", "CD8 T"))
Set pairwise.display = "none" to keep the omnibus test subtitle
without bracket clutter.
do_SankeyPlot() visualises how categorical metadata variables relate
to each other — for example, how clusters map to cell type annotations:
do_SankeyPlot(pbmc3k, columns = c("seurat_clusters", "seurat_annotations"))
Each stratum is labelled; flows show how cells distribute across categories. Powered by ggalluvial.
Install the latest tagged release:
# pak (recommended)
pak::pkg_install("wolf5996/BadranSeq@v1.0.0")
# devtools
devtools::install_github("wolf5996/BadranSeq", ref = "v1.0.0")Install from the main branch for the latest changes (may include
unreleased features):
# pak
pak::pkg_install("wolf5996/BadranSeq")
# devtools
devtools::install_github("wolf5996/BadranSeq")| Function | Purpose |
|---|---|
do_UmapPlot() |
UMAP with borders, labels, silhouette split |
do_PcaPlot() |
PCA with automatic variance labels |
do_DimPlot() |
Unified entry point (routes to UMAP/PCA handler) |
do_FeaturePlot() |
Gene expression overlay with viridis scale |
do_StatsViolinPlot() |
Statistical violin via ggbetweenstats |
do_ViolinPlot() |
Descriptive violin (no statistics) |
do_SankeyPlot() |
Sankey/alluvial diagram for metadata relationships |
EnhancedElbowPlot() |
Variance-explained elbow plot with cutoff |
get_pca_variance() |
Extract PCA variance as a data.frame |
select_cells_interactive() |
Shiny brush selection of cells |
seurat_sleepwalk() |
Interactive embedding distance explorer |
fetch_cell_data() |
Tidy cell-level metadata/embedding extraction |
fetch_feature_data() |
Tidy long-format extraction from Seurat |
theme_badranseq() |
Publication theme for any ggplot |
generate_badranseq_colors() |
Vivid categorical colour palette |
Full documentation and worked examples: pkgdown site
Core (automatically installed): ggplot2, Seurat, colorspace, dplyr, tidyr, tibble, purrr, rlang, magrittr, SeuratObject, shiny, sleepwalk, stats.
Optional (install for extended features): patchwork (multi-panel layouts), ggrastr (rasterisation), ggstatsplot (statistical violin plots), ggalluvial (Sankey diagrams).
BadranSeq’s aesthetic design is inspired by SCpubr by Enrique Blanco Carmona. Key elements adapted from SCpubr include cell border rendering, colour palette generation, and the silhouette split approach. BadranSeq differs by providing a lighter-weight native ggplot2 implementation with additional features (PCA variance labels, statistical violin plots, interactive cell selection).
If you use BadranSeq in published work, please cite:
Elshenawy, B. (2025). BadranSeq: Publication-ready visualisation for single-cell RNA sequencing data in R. R package version 1.0.0. https://github.com/wolf5996/BadranSeq
MIT