Diff Visualizer

Documents

diff-visualizer

Diff Visualizer is an Agent Skill for documents published in the ClawBio/ClawBio repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Rich downstream visualisation and reporting for bulk RNA-seq differential expression and scRNA marker/contrast outputs.

View on GitHub ↗

QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

Open your project in Codex.
Copy and paste the prompt below.
Review files and risks before approving any action.

Prompt to paste

Inspect the Agent Skill at https://github.com/ClawBio/ClawBio/blob/HEAD/skills/diff-visualizer/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/diff-visualizer, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

📈 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

Scanpy documentation: https://scanpy.readthedocs.io/
Matplotlib documentation: https://matplotlib.org/