An interactive computational workbench for single-cell and spatial transcriptomics.
BioWorkbench is a lightweight, open-source Streamlit application for exploring, analyzing, and visualizing single-cell and spatial omics datasets through an interactive interface.
It is built around the scverse ecosystem while keeping the underlying computational functions separate from the user interface. The goal is to make common exploratory analyses easier to perform, inspect, and reproduce without requiring users to repeatedly modify analysis scripts.
BioWorkbench was built for people who want to spend their time thinking about biology rather than operating the computational machinery.
🚧 BioWorkbench is currently in beta.
The current beta focuses on conventional single-cell RNA-seq, MERFISH, and Visium HD spatial transcriptomics. The project is actively evolving, and feedback from researchers using real datasets is welcome.
Scientists need better environments for exploring biological data, asking questions, and forming hypotheses. BioWorkbench aims to provide that environment: a place where researchers can quickly explore their data, investigate observations, and decide what is worth analyzing further
Single-cell and spatial transcriptomics analyses often involve a combination of notebooks, scripts, visualization tools, and modality-specific workflows.
BioWorkbench is intended to sit between a full computational pipeline and a purely visual data explorer:
AnnData (.h5ad)
│
▼
┌─────────────────┐
│ Quality Control │
│ & Filtering │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Normalization & │
│ HVG Selection │
└────────┬────────┘
│
▼
┌─────────────────┐
│ PCA │
└────────┬────────┘
│
▼
┌─────────────────┐
│ UMAP + Leiden │
│ Clustering │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Marker Genes & │
│ Cluster Analysis│
└────────┬────────┘
│
▼
┌─────────────────┐
│ CellTypist │
│ Annotation │
└────────┬────────┘
│
▼
Annotated AnnData
For spatial datasets, the workflow extends this representation with spatial quality control, coordinates, spatial domains, and tissue-level visualization.
The long-term goal is not to replace established analysis frameworks such as Scanpy, Squidpy, or Seurat. Instead, BioWorkbench aims to provide a lightweight interactive layer for exploration, visualization, annotation, and downstream analysis.
BioWorkbench currently provides a conventional Scanpy-based single-cell workflow including:
- AnnData (
.h5ad) input - Cell and gene filtering
- Quality-control metric calculation
- Mitochondrial gene filtering
- Scrublet-based doublet detection
- Highly variable gene selection
- Total-count normalization
- Log transformation
- PCA
- Nearest-neighbor graph construction
- UMAP
- Leiden clustering
- Marker-gene analysis
- Cluster-level summaries
- CellTypist-based cell-type annotation
- Custom annotation workflows
- Interactive visualization
- Processed AnnData export
Users can interactively adjust parameters including:
- Minimum genes per cell
- Minimum cells per gene
- Maximum mitochondrial percentage
- Expected doublet rate
- Number of highly variable genes
- Number of principal components
- Number of neighbors
- UMAP
min_dist - Leiden resolution
BioWorkbench currently includes spatial workflows for MERFISH and Visium HD datasets. The workflows share spatial visualization and domain-analysis capabilities while keeping modality-specific quality control separate.
The imaging-based MERFISH workflow incorporates modality-specific information that is not captured by conventional scRNA-seq QC. Current functionality includes:
- Cell-level spatial coordinates
- Transcript counts per cell
- Genes detected per cell
- Blank-transcript measurements
- Percentage of blank transcripts
- Cell morphology and segmentation-derived metadata
- Cell area and volume
- Spatial quality-control visualization
- Spatial filtering
- Spatial-domain identification
- Spatial visualization
- Cell-type annotation in tissue coordinates
- Gene-expression visualization in tissue space
- Module-score visualization in tissue space
MERFISH QC includes blank-transcript measurements and segmentation-derived cell metadata.
The Visium HD workflow supports spatial expression data represented as AnnData, including:
- Spatial-coordinate validation and tissue-coordinate visualization
- QC metrics and gene/cell filtering
- Mitochondrial filtering and Scrublet-based doublet detection
- PCA, UMAP, and Leiden clustering
- Spatial-domain identification
- Visualization of observation metadata and expression in tissue coordinates
Visium HD uses the standard gene-expression QC and doublet-detection path.
Spatial workflows use the AnnData representation:
adata.obsm["spatial"]
for two-dimensional spatial coordinates. The same analyzed observations can therefore be explored from two complementary perspectives:
UMAP Tissue
│ │
▼ ▼
transcriptional physical/spatial
organization organization
│ │
└──────────────┬──────────────┘
▼
biological context
This is particularly useful for asking whether transcriptional clusters, annotations, or gene-expression patterns correspond to spatial organization within the tissue.
A typical single-cell analysis can follow:
1. Load AnnData
↓
2. Inspect QC metrics
↓
3. Filter cells and genes
↓
4. Detect potential doublets
↓
5. Retain singlets
↓
6. Normalize expression
↓
7. Select highly variable genes
↓
8. Run PCA
↓
9. Construct neighborhood graph
↓
10. Run UMAP
↓
11. Run Leiden clustering
↓
12. Identify marker genes
↓
13. Annotate cell types
↓
14. Explore annotations and expression
↓
15. Export processed AnnData
For MERFISH and Visium HD, spatial QC and spatial analysis can be incorporated into the workflow. The available QC metrics and filtering steps depend on the selected technology.
BioWorkbench integrates CellTypist for model-based cell-type annotation.
Users can:
- Browse available CellTypist models
- Select a reference model
- Run automated annotation
- Apply majority voting
- Inspect prediction confidence
- Visualize predictions on UMAP
- Explore annotations in spatial coordinates for supported datasets
Annotation results are stored in adata.obs.
The current workflow records CellTypist outputs such as:
celltypist_predicted_labels
celltypist_majority_voting
celltypist_conf_score
BioWorkbench also supports custom annotation workflows using JSON input.
NB: BioWorkbench does not support deconvolution or automatic annotation of VisiumHD data. However, you can perform manual annotation.
BioWorkbench supports interactive visualization of categorical and continuous cell-level measurements.
UMAPs can be colored by variables stored in adata.obs, including:
- Cluster assignments
- Cell-type annotations
- QC metrics
- Gene expression
- Other cell-level metadata
For supported spatial datasets, measurements can be displayed using tissue coordinates.
Both categorical and continuous variables are supported, allowing users to visualize:
- Cell types
- Clusters
- QC metrics
- Gene expression
- Module scores
- Other cell-level metadata
The same biological variable can therefore be examined in both transcriptional and spatial contexts.
BioWorkbench can package selected analysis parameters and AnnData objects from the current Streamlit session.
Selected AnnData objects are included as standard:
.h5ad
files. Analysis results stored in each selected AnnData object are retained in that file.
The Download page creates a ZIP archive named bioworkbench.wkb containing a manifest, selected parameters in params.json, and selected AnnData files under adatas/. To import a bundle, open 01 - Cell and Gene Filtering, upload the .wkb file in the sidebar, and select Restore bundle.
Restoring a bundle replaces the current session's AnnData objects and parameters with the objects and parameters included in that bundle. Import completes only after the full archive has been validated and its AnnData files have loaded. Version-1 bundles exported by earlier BioWorkbench versions remain supported. A .wkb is an export bundle, not a complete snapshot of the Streamlit application or its transient interface state.
The export bundle can be used to:
- Save an intermediate analysis state
- Transfer an analysis between environments
- Preserve and restore multiple selected AnnData objects and associated parameters
The ZIP-based format is intentionally used rather than Python object serialization so that the session data remains inspectable and portable.
Note: For interoperability with other tools,
.h5adremains the preferred data-exchange format.
BioWorkbench uses AnnData as its primary data structure.
A typical dataset is represented as:
AnnData
├── X expression matrix
├── obs cell metadata
├── var gene metadata
├── obsm embeddings / spatial coordinates
├── uns unstructured analysis metadata
└── layers alternative expression matrices
At minimum, a conventional single-cell dataset should contain a gene-expression matrix in:
adata.Xalong with appropriate cell and gene metadata.
The MERFISH workflow expects cell-level spatial information and may use platform-specific measurements such as:
- Cell coordinates
- Segmentation measurements
- Cell morphology
- Blank-transcript counts
- Cell area
- Cell volume
Spatial coordinates are standardized internally through:
adata.obsm["spatial"]The MERFISH input must include center_x and center_y in adata.obs; blank-probe genes are identified by names beginning with Blank-. Spatial QC plots also use the cell volume metadata column.
The Visium HD workflow expects a spatially aware AnnData (.h5ad) object with a numeric expression matrix in adata.X and two-dimensional coordinates in adata.obsm["spatial"]. Coordinates must be finite and provided for each observation. BioWorkbench validates the data and exposes the coordinate columns for spatial plotting. Non-empty adata.uns["spatial"] metadata is not required by the current workflow.
Default analysis parameters are maintained in:
config/params.yaml
Configuration is organized by modality and, where appropriate, spatial technology.
Conceptually:
single_cell:
...
spatial:
MERFISH:
...
Visium HD:
...Configuration values provide defaults for the interactive workflows and can be adjusted through the application where supported.
BioWorkbench is currently in beta and is being tested with real single-cell and spatial transcriptomics datasets.
The current beta focuses on:
- Single-cell RNA-seq
- MERFISH spatial transcriptomics
- Visium HD spatial transcriptomics
- Quality control and filtering
- Dimensionality reduction and clustering
- Marker-gene analysis
- Cell-type annotation
- Gene and module-score visualization
- Spatial visualization
- Spatial-domain exploration
- Exporting selected parameters and AnnData objects
BioWorkbench is primarily intended for:
- Computational biologists
- Bioinformaticians
- Single-cell researchers
- Spatial transcriptomics researchers
- Researchers working with AnnData-based datasets
You do not need to be a BioWorkbench developer to participate.
If you regularly work with .h5ad datasets and single-cell or spatial omics data, your feedback is particularly valuable.
Beta testers are encouraged to use BioWorkbench with real datasets and report:
- Bugs or unexpected behavior
- Installation problems
- Environment/dependency issues
- Confusing workflows
- UI/UX problems
- Visualization issues
- Unexpected analysis results
- Performance problems
- Missing functionality
- Features that would make the workflow more useful
You do not need to determine whether something is technically a "bug" before reporting it.
If something is confusing, surprising, or difficult to use, that is useful feedback.
Please open a GitHub Issue and include, where possible:
- What you were trying to do
- What you expected to happen
- What actually happened
- Steps to reproduce the problem
- Operating system
- Installation method
- Dataset characteristics
- Relevant error messages
- Screenshots, where useful
Clone the repository:
git clone https://github.com/poloarol/BioWorkbench.git
cd BioWorkbenchCreate a virtual environment:
python -m venv .venvsource .venv/bin/activate.venv\Scripts\Activate.ps1Install the dependencies:
pip install -r requirements.txtStart the Streamlit application:
streamlit run app.py --server.maxUploadSize=500The application will be available at http://localhost:8501. The upload widget currently limits individual .h5ad uploads to 500 MB. When changing the Streamlit server upload limit, note that the widget also has its own limit.
Upload an .h5ad dataset through the application to begin the analysis workflow.
BioWorkbench includes a Dockerfile for running the application in a containerized environment.
Build the image:
docker build -t bioworkbench .Run the application (the container listens on port 8501):
docker run --rm -p 8501:8501 bioworkbenchThe image runs as an unprivileged user and includes a health check. Then open:
http://localhost:8501
Docker provides an alternative to installing the Python dependencies directly on the host system and is particularly useful for reproducible beta testing.
BioWorkbench uses pytest for automated testing of its computational and utility functions, plotting behavior, and Streamlit application startup.
Run the complete test suite:
python -m pytestRun a specific test file:
python -m pytest tests/<test_file>.pyRun a specific test:
python -m pytest tests/<test_file>.py -k "<test_name>"The test suite validates reusable analysis workflows, dataset preparation and export, plotting behavior, and Streamlit application startup, including checks that workflow pages handle missing prerequisites. Tests use small synthetic datasets rather than large biological samples.
When modifying computational functionality, corresponding tests should be added or updated where appropriate.
BioWorkbench/
│
├── app.py # Main Streamlit application
│
├── pages/
│ ├── 01_filtering.py # QC and filtering
│ ├── 02_clustering.py # PCA, UMAP, clustering, spatial domains
│ ├── 03_annotation.py # Cell-type annotation
│ ├── 04_visualization.py # Gene/module visualization
│ └── 05_download.py # Parameter and AnnData export
│
├── src/
│ ├── filtering.py # Filtering and doublet detection
│ ├── clustering.py # Clustering and spatial analysis
│ ├── plotting.py # Visualization functions
│ └── utils.py # Data loading and shared utilities
│
├── config/
│ └── params.yaml # Analysis configuration
│
├── tests/ # Automated tests
│
├── notebooks/ # Exploratory analysis and development
│
├── docs/
│ └── images/ # Documentation assets
│
├── beta # Beta-testing guidance
├── requirements.txt # Python dependencies
├── Dockerfile # Container configuration
├── CITATION.cff # Software citation metadata
├── LICENSE # GNU GPL-3.0-or-later
└── README.md
The application interface is separated from the reusable computational layer.
This allows the analysis functions to evolve independently of Streamlit and makes them potentially reusable in:
- Scripts
- Notebooks
- Pipelines
- Automated workflows
- Future interfaces
| Component | Technology |
|---|---|
| Language | Python |
| Application | Streamlit |
| Data structure | AnnData |
| Single-cell analysis | Scanpy |
| Cell-type annotation | CellTypist |
| Doublet detection | Scrublet |
| Data manipulation | Pandas |
| Visualization | Matplotlib, Plotly, Seaborn |
| Testing | pytest |
| Containerization | Docker |
BioWorkbench is being developed incrementally, with emphasis on making the existing workflows robust before expanding to additional technologies.
- AnnData input
- Single-cell QC
- Cell and gene filtering
- Mitochondrial filtering
- Scrublet doublet detection
- Highly variable gene selection
- PCA
- UMAP
- Leiden clustering
- Marker-gene analysis
- CellTypist annotation
- Custom annotation
- Processed AnnData export
- MERFISH input
- MERFISH-specific QC
- Visium HD AnnData input and spatial-coordinate validation
- Visium HD QC and filtering
- Visium HD clustering and spatial-domain identification
- Spatial coordinate visualization
- Spatial annotation visualization
- Spatial-domain identification
- Spatially variable gene analysis
- Transcript-level visualization
- ZIP-based export of selected parameters and AnnData objects
- Restore BioWorkbench
.wkbexport bundles - Automated tests
- Containerized execution
- Improved spatial-domain analysis
- Improved spatial QC visualization
- Expanded spatial data validation
- More robust annotation workflows
- Additional spatial visualization capabilities
- Improved reproducibility and configuration management
- Expanded documentation
- Continuous integration
- Visium HD deconvolution and Automatic Annotation
- Xenium
- CosMX
- Spatial marker analysis
- Cell-neighborhood analysis
- Cell-cell interaction analysis
- Spatially aware cell-type annotation
- Multiple annotation models
- Marker-based annotation
- Interactive annotation editing
- Annotation confidence and uncertainty visualization
- Context-aware gene and gene-set information retrieval
- AI-assisted biological interpretation
BioWorkbench allows researchers to explore datasets and adjust common analysis parameters without repeatedly modifying analysis scripts.
Analysis functions are separated from the Streamlit interface so that computational components can be reused independently of the user interface.
AnnData serves as the central representation for expression data, metadata, embeddings, spatial coordinates, and analysis results.
Different biological technologies have different data structures and quality-control considerations.
BioWorkbench therefore aims to share common computational components where appropriate while exposing modality-specific workflows where necessary.
Configuration, reusable analysis functions, automated tests, containerization, and portable session bundles are intended to make computational behavior easier to inspect, validate, and reproduce.
The longer-term goal is to extend BioWorkbench from a single-cell analysis application into a lightweight computational workbench for single-cell and spatial biology.
BioWorkbench
│
┌───────────────┴───────────────┐
│ │
Single-cell Spatial Biology
│ │
┌──────┴──────┐ ┌─────────┼─────────┐
│ │ │ │ │
scRNA-seq Other MERFISH Xenium Other
assays spatial
│ │
└───────────────┬───────────────┘
│
▼
Shared computational
components
│
┌─────────────┼─────────────┐
│ │ │
QC Visualization Annotation
│ │ │
└─────────────┼─────────────┘
│
▼
Biological insight
The objective is not to replace established single-cell and spatial analysis frameworks.
Instead, BioWorkbench aims to provide a practical interactive layer that helps researchers inspect data, explore patterns, test hypotheses, and prepare analyses for more specialized computational workflows.
If you use BioWorkbench in research, please cite the repository using the information provided in CITATION.cff.
BioWorkbench is free software released under the GNU General Public License v3.0 or later (GPL-3.0-or-later).
You are free to use, study, modify, and redistribute BioWorkbench under the terms of the GNU GPL.
See LICENSE for the complete license terms.
BioWorkbench is research software under active development.
It is intended to support exploratory and computational analysis and should not be considered a validated clinical diagnostic tool.
Analysis results should be independently reviewed and interpreted in the context of the underlying dataset, experimental design, and appropriate biological knowledge.