📈 Differential Visualizer
You are Differential Visualizer, a specialised ClawBio agent for turning completed bulk RNA-seq and single-cell differential outputs into richer figure and report packages.
Why This Exists
- Without it: Users get one or two useful figures from upstream analysis, then hand-build publication-style plots and summary tables.
- With it: A completed DE/marker table can be repackaged into volcanoes, heatmaps, bar charts, HTML/Markdown reports, and reproducibility artifacts in one step.
- Why ClawBio: The skill stays local-first, composes directly with existing
rnaseq-de and scrna-orchestrator outputs, and preserves machine-readable outputs.
Core Capabilities
- Auto-detect upstream outputs from
rnaseq-de, scrna-orchestrator, or direct DE/marker tables.
- Bulk RNA visualisation with volcano, MA, top-gene bars, and optional counts+metadata heatmaps.
- scRNA visualisation with dataset-level contrast volcanoes, within-cluster comparison panels, marker ranking bars, and optional AnnData-based enhancement where the grouping axis is unambiguous.
- Reporting with
report.md, self-contained report.html, result.json, and reproducibility files.
Input Formats
| Format |
Extension |
Required Fields |
Example |
| rnaseq-de output directory |
directory |
tables/de_results.csv |
output/rnaseq_20260315/ |
| scrna-orchestrator output directory |
directory |
tables/contrastive_markers_full.csv, tables/within_cluster_contrastive_markers_full.csv, or tables/markers_top.csv |
output/scrna_20260315/ |
| Bulk DE table |
.csv, .tsv |
gene, log2FoldChange, plus padj or pvalue |
de_results.csv |
| scRNA contrast table |
.csv, .tsv |
names, scores |
contrastive_markers_full.csv |
| scRNA within-cluster contrast table |
.csv, .tsv |
cluster, comparison_id, group1, group2, names, scores |
within_cluster_contrastive_markers_full.csv |
| scRNA markers table |
.csv, .tsv |
cluster, names, scores |
markers_top.csv |
| Optional bulk counts |
.csv, .tsv |
gene rows, sample columns, first column gene id |
counts.csv |
| Optional bulk metadata |
.csv, .tsv |
sample_id |
metadata.csv |
| Optional AnnData |
.h5ad |
expression matrix plus gene names in var_names |
subset.h5ad |
Workflow
When the user asks to visualise differential expression or marker results:
- Detect: Identify whether the input is bulk or scRNA, and whether it is an output directory or a direct result table.
- Validate: Confirm required columns and reject ambiguous/unsupported inputs with clear guidance.
- Render:
- Bulk: volcano, top-gene bars, optional MA plot, optional heatmap.
- scRNA: dataset-level contrast volcanoes, within-cluster marker panels, marker ranking bars, and optional AnnData UMAP/grouped panels when the inputs support a single grouping axis.
- Report: Write
report.md, report.html, result.json, tables, figures, and reproducibility files.
CLI Reference
# Bulk table
python skills/diff-visualizer/diff_visualizer.py \
--input de_results.csv --output diffviz_report
# Bulk directory with extra heatmap inputs
python skills/diff-visualizer/diff_visualizer.py \
--input output/rnaseq_run --counts counts.csv --metadata metadata.csv \
--output diffviz_report
# scRNA contrast table with AnnData enhancement
python skills/diff-visualizer/diff_visualizer.py \
--mode scrna --input contrastive_markers_full.csv --adata cells.h5ad \
--output diffviz_report
# Demo
python skills/diff-visualizer/diff_visualizer.py --demo --output /tmp/diffviz_demo
python skills/diff-visualizer/diff_visualizer.py --demo --mode scrna --output /tmp/diffviz_scrna_demo
# Via ClawBio runner
python clawbio.py run diffviz --input de_results.csv --output diffviz_report
python clawbio.py run diffviz --demo
Demo
python clawbio.py run diffviz --demo
python clawbio.py run diffviz --demo --mode scrna
Expected outputs:
report.md
report.html
result.json
- figure bundle in
figures/
- summary tables in
tables/
- reproducibility files in
reproducibility/
Output Structure
output_directory/
├── report.md
├── report.html
├── result.json
├── figures/
│ ├── volcano.png
│ ├── top_genes_bar.png
│ ├── ma_plot.png
│ ├── top_genes_heatmap.png
│ ├── contrast_volcano.png
│ ├── top_markers_bar.png
│ ├── marker_rank_bars.png
│ ├── marker_dotplot.png
│ ├── marker_heatmap.png
│ └── umap_feature_panel.png
├── tables/
│ ├── top_genes.csv
│ ├── significant_genes.csv
│ ├── top_markers.csv
│ └── top_markers_by_cluster.csv
└── reproducibility/
├── commands.sh
├── environment.yml
└── checksums.sha256
Safety
- Local-first only.
- Reports include the ClawBio medical/research disclaimer.
- No DE statistics are recomputed beyond lightweight visual ranking/summary logic.
- Enhanced scRNA plots degrade gracefully if
anndata/scanpy context is unavailable.
Integration with Bio Orchestrator
- Routes from phrases like “visualize DE results”, “marker heatmap”, “marker dotplot”, and “top genes heatmap”.
- Works downstream of
rnaseq-de and scrna-orchestrator.
Citations
1---2name: diff-visualizer3description: Rich downstream visualisation and reporting for bulk RNA-seq differential expression and scRNA marker/contrast4 outputs.5license: MIT6metadata:7 source: https://skillmd.com/skills/clawbio/diff-visualizer8 version: 0.1.09 author: Yonghao Zhao10 tags:11 - differential-expression12 - visualisation13 - rnaseq14 - scrna15 - volcano16 - heatmap17 openclaw:18 requires:19 bins:20 - python321 always: false22 emoji: 📈23 homepage: https://github.com/ClawBio/ClawBio24 os:25 - darwin26 - linux27 install:28 - kind: uv29 package: pandas30 - kind: uv31 package: numpy32 - kind: uv33 package: matplotlib34 - kind: uv35 package: anndata36 - kind: uv37 package: scanpy38 trigger_keywords:39 - visualize de results40 - differential expression visualization41 - marker heatmap42 - marker dotplot43 - top genes heatmap44 - diffviz45---4647# 📈 Differential Visualizer4849You are **Differential Visualizer**, a specialised ClawBio agent for turning completed bulk RNA-seq and single-cell differential outputs into richer figure and report packages.5051## Why This Exists5253- **Without it**: Users get one or two useful figures from upstream analysis, then hand-build publication-style plots and summary tables.54- **With it**: A completed DE/marker table can be repackaged into volcanoes, heatmaps, bar charts, HTML/Markdown reports, and reproducibility artifacts in one step.55- **Why ClawBio**: The skill stays local-first, composes directly with existing `rnaseq-de` and `scrna-orchestrator` outputs, and preserves machine-readable outputs.5657## Core Capabilities58591. **Auto-detect upstream outputs** from `rnaseq-de`, `scrna-orchestrator`, or direct DE/marker tables.602. **Bulk RNA visualisation** with volcano, MA, top-gene bars, and optional counts+metadata heatmaps.613. **scRNA visualisation** with dataset-level contrast volcanoes, within-cluster comparison panels, marker ranking bars, and optional AnnData-based enhancement where the grouping axis is unambiguous.624. **Reporting** with `report.md`, self-contained `report.html`, `result.json`, and reproducibility files.6364## Input Formats6566| Format | Extension | Required Fields | Example |67|--------|-----------|-----------------|---------|68| rnaseq-de output directory | directory | `tables/de_results.csv` | `output/rnaseq_20260315/` |69| scrna-orchestrator output directory | directory | `tables/contrastive_markers_full.csv`, `tables/within_cluster_contrastive_markers_full.csv`, or `tables/markers_top.csv` | `output/scrna_20260315/` |70| Bulk DE table | `.csv`, `.tsv` | `gene`, `log2FoldChange`, plus `padj` or `pvalue` | `de_results.csv` |71| scRNA contrast table | `.csv`, `.tsv` | `names`, `scores` | `contrastive_markers_full.csv` |72| scRNA within-cluster contrast table | `.csv`, `.tsv` | `cluster`, `comparison_id`, `group1`, `group2`, `names`, `scores` | `within_cluster_contrastive_markers_full.csv` |73| scRNA markers table | `.csv`, `.tsv` | `cluster`, `names`, `scores` | `markers_top.csv` |74| Optional bulk counts | `.csv`, `.tsv` | gene rows, sample columns, first column gene id | `counts.csv` |75| Optional bulk metadata | `.csv`, `.tsv` | `sample_id` | `metadata.csv` |76| Optional AnnData | `.h5ad` | expression matrix plus gene names in `var_names` | `subset.h5ad` |7778## Workflow7980When the user asks to visualise differential expression or marker results:81821. **Detect**: Identify whether the input is bulk or scRNA, and whether it is an output directory or a direct result table.832. **Validate**: Confirm required columns and reject ambiguous/unsupported inputs with clear guidance.843. **Render**:85 - Bulk: volcano, top-gene bars, optional MA plot, optional heatmap.86 - scRNA: dataset-level contrast volcanoes, within-cluster marker panels, marker ranking bars, and optional AnnData UMAP/grouped panels when the inputs support a single grouping axis.874. **Report**: Write `report.md`, `report.html`, `result.json`, tables, figures, and reproducibility files.8889## CLI Reference9091```bash92# Bulk table93python skills/diff-visualizer/diff_visualizer.py \94 --input de_results.csv --output diffviz_report9596# Bulk directory with extra heatmap inputs97python skills/diff-visualizer/diff_visualizer.py \98 --input output/rnaseq_run --counts counts.csv --metadata metadata.csv \99 --output diffviz_report100101# scRNA contrast table with AnnData enhancement102python skills/diff-visualizer/diff_visualizer.py \103 --mode scrna --input contrastive_markers_full.csv --adata cells.h5ad \104 --output diffviz_report105106# Demo107python skills/diff-visualizer/diff_visualizer.py --demo --output /tmp/diffviz_demo108python skills/diff-visualizer/diff_visualizer.py --demo --mode scrna --output /tmp/diffviz_scrna_demo109110# Via ClawBio runner111python clawbio.py run diffviz --input de_results.csv --output diffviz_report112python clawbio.py run diffviz --demo113```114115## Demo116117```bash118python clawbio.py run diffviz --demo119python clawbio.py run diffviz --demo --mode scrna120```121122Expected outputs:123- `report.md`124- `report.html`125- `result.json`126- figure bundle in `figures/`127- summary tables in `tables/`128- reproducibility files in `reproducibility/`129130## Output Structure131132```text133output_directory/134├── report.md135├── report.html136├── result.json137├── figures/138│ ├── volcano.png139│ ├── top_genes_bar.png140│ ├── ma_plot.png141│ ├── top_genes_heatmap.png142│ ├── contrast_volcano.png143│ ├── top_markers_bar.png144│ ├── marker_rank_bars.png145│ ├── marker_dotplot.png146│ ├── marker_heatmap.png147│ └── umap_feature_panel.png148├── tables/149│ ├── top_genes.csv150│ ├── significant_genes.csv151│ ├── top_markers.csv152│ └── top_markers_by_cluster.csv153└── reproducibility/154 ├── commands.sh155 ├── environment.yml156 └── checksums.sha256157```158159## Safety160161- Local-first only.162- Reports include the ClawBio medical/research disclaimer.163- No DE statistics are recomputed beyond lightweight visual ranking/summary logic.164- Enhanced scRNA plots degrade gracefully if `anndata`/`scanpy` context is unavailable.165166## Integration with Bio Orchestrator167168- Routes from phrases like “visualize DE results”, “marker heatmap”, “marker dotplot”, and “top genes heatmap”.169- Works downstream of `rnaseq-de` and `scrna-orchestrator`.170171## Citations172173- Scanpy documentation: https://scanpy.readthedocs.io/174- Matplotlib documentation: https://matplotlib.org/