Biomedical Visualization Analysis Skill

0. Mandatory startup behavior

On every fresh activation of this skill, do not analyze data and do not emit plotting code yet.

First ask only:

请选择执行后端：R / Python

Wait for the user's choice.

After the user chooses:

1. Lock the session to that backend.
2. Do not mix R and Python unless the requested method genuinely has no practical implementation in the selected backend.
3. If a fallback is necessary, explain the limitation before using another backend.
4. Infer the data type and analytical objective from the request. Ask one concise clarification only when the analysis cannot be determined safely.
5. Prefer mature, widely used packages from CRAN/Bioconductor for R and PyPI/scverse/scikit-learn ecosystems for Python.
6. If the required plot/method is not in this registry, search current official package documentation before choosing a package.
7. This skill excludes all geographic maps, choropleths, provincial maps, world maps, and spatial map plotting.

1. Core principle: a plot is not automatically an analysis

Many screenshots in the source gallery are visualization forms rather than statistical methods.

Always separate:

• analysis: the statistical or bioinformatics computation that produces the result;
• visualization: the graphical encoding of that result.

Examples:

• Volcano plot -> differential analysis first, volcano second.
• Forest plot -> regression/meta-analysis effect estimates first, forest plot second.
• Heatmap -> normalized/transformed matrix and optional clustering first, heatmap second.
• Violin/box/raincloud -> group distribution visualization; the inferential test is separate.
• Sankey/alluvial -> flow/composition visualization; it does not itself estimate an effect.
• Venn/UpSet -> set overlap calculation; no biological significance test is implied.
• ROC -> prediction discrimination analysis; it requires model scores or a biomarker.
• UMAP/t-SNE -> embedding visualization; it is not evidence of statistical separation by itself.

Never invent an "analysis" solely because a plot can be drawn.

2. Analysis-to-figure decision registry

A. Descriptive distributions and group comparisons

Use for:

• box plot, violin plot, half violin, bean plot, raincloud
• beeswarm, jitter, paired scatter, connected dot plot
• histogram, density, ridgeline
• bar chart, grouped bar, stacked bar, error-bar bar
• QQ plot
• line plot and summary trajectory

Statistical choices:

• Continuous two-group: t test or Welch test if assumptions are reasonable; otherwise Wilcoxon rank-sum.
• Paired two-group: paired t test or Wilcoxon signed-rank.

• =3 groups: ANOVA/Welch ANOVA or Kruskal-Wallis, followed by multiplicity-controlled post-hoc tests.

• Repeated measures/longitudinal: mixed-effects model or GEE when inference is needed.
• Categorical proportions: chi-square/Fisher exact; regression for adjusted comparisons.
• Error bars must state whether they represent SD, SE, CI, or another quantity.

R:

• analysis: stats, rstatix, lme4, geepack
• plotting: ggplot2, ggbeeswarm, ggridges, ggdist, patchwork

Python:

• analysis: scipy.stats, statsmodels
• plotting: matplotlib, seaborn; plotly only when interactivity is explicitly needed

B. Correlation, association, and regression

Use for:

• correlation matrix, corrplot, circular correlation plot
• correlation network
• Mantel correlation network
• scatter with regression line
• density scatter
• lollipop correlation summary
• dual-variable plots

Statistical choices:

• Pearson: approximately linear association without severe outliers.
• Spearman: monotonic association, ordinal data, or outlier-prone distributions.
• Partial correlation when predefined covariate adjustment is required.
• Regression when adjusted effect estimation is the objective.
• Correct multiple testing across large correlation matrices.

R:

• analysis: stats, Hmisc, ppcor, vegan
• plotting: corrplot, ggcorrplot, ggplot2, igraph, tidygraph, ggraph

Python:

• analysis: scipy.stats, statsmodels, pingouin
• plotting: seaborn, matplotlib, networkx

C. Dimension reduction and unsupervised structure

Use for:

• PCA, 3D PCA
• PCoA
• NMDS
• t-SNE
• UMAP
• hierarchical clustering tree
• cluster heatmap

Rules:

• Scale features when variables have incomparable units, unless the method/data type dictates otherwise.
• PCA is linear; t-SNE/UMAP are visualization-oriented nonlinear embeddings.
• Do not interpret visual separation as a formal hypothesis test.
• For microbiome beta-diversity, PCoA/NMDS is often more natural than PCA.

R:

• PCA: stats::prcomp, factoextra
• PCoA/NMDS: vegan, ape
• UMAP: uwot
• t-SNE: Rtsne
• clustering: stats, ComplexHeatmap

Python:

• PCA/t-SNE: scikit-learn
• UMAP: umap-learn
• PCoA: scikit-bio
• clustering: scipy.cluster, scikit-learn
• plotting: matplotlib, seaborn

D. Heatmaps and matrix visualization

Use for:

• standard heatmap
• clustered heatmap
• annotated heatmap
• triangular heatmap
• matrix dot heatmap
• gene expression heatmap
• clinical heatmap
• heatmap + bar / heatmap + annotation
• circular heatmap

Rules:

• State whether rows/columns are scaled.
• Use transformed data appropriate for the assay.
• Distinguish supervised heatmaps (features preselected by outcome) from unsupervised heatmaps.
• Do not treat clustering dendrograms as inferential evidence.

R:

• primary: ComplexHeatmap
• simple: pheatmap
• circular: circlize + ComplexHeatmap

Python:

• seaborn.heatmap, seaborn.clustermap
• scipy.cluster.hierarchy
• circular/sector layout: pycirclize

E. Differential expression / differential abundance

Use for:

• volcano plot
• labeled volcano
• dual volcano
• four-color volcano
• gradient volcano
• nine-quadrant plot
• ranked gene plot
• differential heatmap
• top-gene lollipop

Bulk RNA-seq:

• raw integer counts -> DESeq2/edgeR in R; PyDESeq2 in Python
• log-expression / microarray -> limma in R
• do not run DESeq2 on TPM/FPKM as if they were raw counts

R:

• analysis: DESeq2, edgeR, limma
• plotting: EnhancedVolcano, ggplot2, ComplexHeatmap, ggrepel

Python:

• analysis: pydeseq2; statsmodels for custom GLMs
• plotting: matplotlib, seaborn, adjustText

Required outputs:

• effect size, raw p-value, adjusted p-value/FDR
• threshold values explicitly reported
• labeled genes chosen by a reproducible rule, not manual cherry-picking

F. Functional enrichment: ORA, GO, KEGG, Reactome

Use for:

• enrichment dot/bubble plot
• GO BP/CC/MF grouped bar/dot plot
• GO/KEGG bar plot
• pathway bubble
• GO circle
• cnetplot
• emapplot
• enrichment network
• chord diagram connecting genes and pathways
• enrichment sankey/alluvial
• treemap/gradient enrichment summary

Analysis:

• ORA uses a selected gene list plus a defensible background universe.
• Report adjusted p-values/FDR.
• Keep BP/CC/MF logically separated when needed.
• Do not interpret pathway count alone as pathway importance.

R:

• analysis: clusterProfiler, ReactomePA, DOSE
• visualization: enrichplot, ggplot2, circlize, ggalluvial
• gene sets: msigdbr, AnnotationDbi, organism-specific annotation packages

Python:

• analysis/visualization: gseapy
• GO-specific workflows: goatools
• networks: networkx
• chord/circular: pycirclize
• alluvial/sankey: plotly

G. GSEA / GSVA / ssGSEA / pathway activity

Use for:

• GSEA running-enrichment curve
• GSEA labeled-gene plot
• GSEA ridge plot
• GSEA NES + FDR bar/dot
• GSEA network
• GSVA pathway heatmap
• gene-set variation heatmap

Analysis rules:

• GSEA requires a ranked statistic for preranked workflows.
• Avoid ranking only by p-value.
• Report NES, nominal p-value where relevant, and FDR.
• For GSVA/ssGSEA, make clear that scores are sample-level pathway activity estimates.

R:

• GSEA: clusterProfiler, fgsea
• visualization: enrichplot
• GSVA: GSVA
• gene sets: msigdbr

Python:

• gseapy for GSEA, prerank, ssGSEA, GSVA-style workflows
• plotting: gseapy, matplotlib, seaborn

H. Set intersection and overlap

Use for:

• 2-6 set Venn
• proportional Venn/Euler
• vertical Venn
• Venn + bar
• UpSet

Rules:

• 2-3 small sets: Venn/Euler is acceptable.

• 3 sets or many intersections: default to UpSet.

• Proportional-circle diagrams should not imply precise area unless the algorithm preserves it.

R:

• ComplexUpset
• eulerr
• ggVennDiagram

Python:

• upsetplot
• matplotlib-venn for 2-3 sets

I. Composition, flow, and hierarchy

Use for:

• pie/donut
• nested donut / two-layer donut
• waffle
• stacked bar
• alluvial/sankey
• flow diagram
• funnel
• treemap
• streamgraph
• bump/rank plot

Rules:

• Prefer bar charts over pie charts when exact comparison matters.
• Sankey/alluvial requires explicit source-target-stage counts.
• Funnel charts are descriptive unless paired with a defined funnel analysis.
• Treemap area encodes quantity; do not use it for signed effects without careful encoding.

R:

• ggplot2
• ggalluvial
• treemapify
• ggstream
• ggbump

Python:

• matplotlib
• plotly for sankey, treemap, funnel, stream-like interactive graphics
• seaborn for static grouped/stacked displays

J. Survival analysis and time-to-event prediction

Use for:

• Kaplan-Meier curve
• best-cutoff KM
• forest plot of hazard ratios
• risk-score triptych
• time-dependent ROC
• Cox/LASSO-Cox outputs

Analysis:

• KM + log-rank for unadjusted group survival.
• Cox model for adjusted hazard ratios; verify proportional hazards.
• Avoid choosing an outcome cutpoint on the same dataset without internal validation.
• Time-dependent ROC must use censoring-aware methods.

R:

• survival
• survminer
• timeROC
• glmnet
• rms
• forestploter or ggplot2

Python:

• lifelines
• scikit-survival
• scikit-learn for non-survival prediction components
• matplotlib

K. Prediction, feature selection, and clinical models

Use for:

• ROC/AUC
• random-forest feature importance
• XGBoost feature selection
• SVM-RFE
• LASSO path
• nomogram
• calibration curve
• risk-score panels
• feature-importance lollipop/bar

Rules:

• Split or resample before model tuning.
• Prevent leakage: preprocessing and feature selection must occur inside resampling folds.
• Report discrimination and calibration.
• Prefer nested CV or bootstrap optimism correction for small clinical datasets.
• Do not select a single "best model" from test-set performance after repeated peeking.

R:

• tidymodels
• glmnet
• ranger
• xgboost
• kernlab
• pROC
• rms

Python:

• scikit-learn
• xgboost
• lifelines / scikit-survival when outcome is survival
• statsmodels for classical regression
• matplotlib, seaborn

L. Forest plots and effect-estimate summaries

Use for:

• hazard-ratio forest plot
• odds-ratio forest plot
• subgroup forest plot
• meta-analysis forest plot

Rule:
A forest plot is a display. The analytical model can be logistic regression, Cox regression, Poisson regression, linear regression, meta-analysis, or another estimator.

R:

• regression: stats, survival, glm
• meta-analysis: metafor, meta
• plotting: forestploter, ggplot2, package-native forest functions

Python:

• regression: statsmodels, lifelines
• meta-analysis: statsmodels.stats.meta_analysis
• plotting: matplotlib

M. Single-cell RNA-seq

Use for:

• UMAP/t-SNE by cell type
• single-cell marker volcano
• cluster volcano
• marker dot/bubble plot
• marker heatmap
• cell-type composition plots
• ligand-receptor interaction heatmap/network

R:

• primary: Seurat
• differential/marker acceleration: presto
• heatmaps: ComplexHeatmap
• ligand-receptor: CellChat
• plotting helpers: ggplot2, patchwork

Python:

• primary: scanpy + anndata
• large/advanced latent models: scvi-tools when appropriate
• ligand-receptor ecosystem: squidpy, liana
• plotting: scanpy, matplotlib, seaborn

Critical inference rule:
When comparing biological conditions across donors, do not treat cells as independent biological replicates. Prefer donor-level pseudobulk or a model that accounts for donor/sample structure when making condition-level differential-expression claims.

N. Immune deconvolution

Use for:

• CIBERSORT-style immune infiltration bars/boxes
• immune-cell heatmaps
• immune-cell correlation plots

R:

• immunedeconv
• IOBR when a broader tumor-microenvironment workflow is justified
• visualization: ggplot2, ComplexHeatmap

Python:

• use algorithm-specific implementations when licensing/input permits
• visualization: pandas, matplotlib, seaborn

Always distinguish measured single-cell proportions from computationally deconvolved bulk estimates.

O. Genomic variants, SNPs, CNVs, and cancer mutation landscapes

Use for:

• Manhattan plot
• SNP chromosome distribution
• SNP density
• LD heatmap
• ideogram
• chromosome + bar
• MAF summary
• oncoplot
• lollipop mutation
• CNV gain/loss
• Circos genome view
• fusion-gene Circos

R:

• maftools
• GenomicRanges
• karyoploteR
• CMplot
• LDheatmap
• circlize
• Gviz
• trackViewer
• ComplexHeatmap

Python:

• pysam
• PyRanges
• scikit-allel
• CoMut
• pycirclize
• matplotlib

Preference:
For dense publication-grade genomic circular views, MAF/onco plots, and chromosome idiograms, R generally has the stronger mature plotting ecosystem. Respect the user's chosen backend unless a method is impractical.

P. ChIP-seq / ATAC-seq / peak annotation / motif

Use for:

• peak chromosome distribution
• peak annotation pie/donut
• motif logo
• HOMER motif scatter/result plot
• peak/gene annotation heatmap

R:

• ChIPseeker
• GenomicRanges
• DiffBind
• motifmatchr
• universalmotif
• ggseqlogo
• ComplexHeatmap

Python:

• pybedtools
• pysam
• logomaker
• pandas
• matplotlib

Do not call peak annotation differential accessibility unless an explicit differential-accessibility model was run.

Q. miRNA, circRNA, methylation, and regulatory networks

Use for:

• circRNA-miRNA circular link diagram
• miRNA-target network
• miRNA target-prediction display
• methylation-expression joint scatter
• gene up/down regulation bar
• receptor-ligand network

R:

• network: igraph, tidygraph, ggraph
• circular: circlize
• methylation: assay-appropriate Bioconductor packages + ggplot2
• expression integration: limma, DESeq2 as appropriate

Python:

• network: networkx
• circular: pycirclize
• statistics: statsmodels, scipy
• plotting: matplotlib, seaborn

Target-prediction scores are computational predictions and must not be presented as experimentally validated interactions.

R. Microbiome / ecological community analysis

Use for:

• species accumulation
• rarefaction
• UPGMA / phylogenetic-style clustering
• NMDS
• PCoA
• ternary composition plot
• taxonomic stacked bar
• community heatmap

R:

• phyloseq
• vegan
• ape
• ggtree
• microbiome
• ggplot2

Python:

• scikit-bio
• scipy
• pandas
• matplotlib, seaborn
• ete3 for tree rendering when needed

S. Longitudinal and time-series patterns

Use for:

• multi-line trajectories
• smooth line
• expression trend
• Mfuzz time-series clusters
• streamgraph
• bump/rank chart
• repeated-measures box/violin panels

R:

• inference: lme4, nlme, geepack
• expression clustering: Mfuzz
• visualization: ggplot2, ggstream, ggbump

Python:

• inference: statsmodels
• clustering: scikit-learn, scipy
• visualization: matplotlib, seaborn, plotly

T. Specialized display-only graphics

Includes:

• radar/spider
• polar bars
• stem/lollipop
• 3D scatter / 3D bars
• 2.5D bars
• flower/petal charts
• proportional circles
• pencil/butterfly bars
• calendar heatmaps
• bullet charts

These are primarily display forms. Use only when they improve interpretation. Default to simpler 2D plots if a specialized shape obscures uncertainty or effect magnitude.

R:

• ggplot2
• plotly only for necessary interactive 3D
• calendR for calendar displays when justified

Python:

• matplotlib
• plotly
• calplot for calendar heatmaps

3. Source-gallery alias mapping

The following screenshot labels map to the analytical families above.

• 富集气泡图 / GO_KEGG富集 / GO_Pathway弦图 / GO circle / cnet / emap / 富集桑基 / 富集背呈图 -> Functional enrichment
• GSEA基因集富集 / GSEA标记基因 / GSEA网络 / GSEA山峦图 / NES+FDR -> GSEA/GSVA
• 火山图 / 双火山 / 三颜色火山 / 四色火山 / 代谢火山 / 九象限 -> Differential analysis
• 聚类热图 / 临床热图 / 圆形热图 / 三角热图 / 左右双侧组合热图 -> Heatmap/clustering
• PCA / PCoA / NMDS / t-SNE / UMAP / 聚类树 -> Dimension reduction/clustering
• KM / 最佳cutoff生存 / timeROC / 风险评分三联图 / 森林图 -> Survival/prediction
• ROC / LASSO-Cox / XGBoost特征 / SVM-RFE / RF特征 / 列线图 -> Prediction/feature selection
• 相关系数图 / 相关矩阵 / Mantel网络 / 相关网络 / 两组相关性 -> Correlation/regression
• Venn / Euler / UpSet / Venn+bar -> Set overlap
• Sankey / alluvial / 堆叠柱 / 饼 / 甜甜圈 / waffle / funnel / treemap -> Composition/flow
• Manhattan / LD heatmap / SNP density / 染色体分布 / MAF / oncoplot / Circos / CNV -> Genomics/variants
• 单细胞UMAP/tSNE / marker火山 / cluster火山 / dotplot / marker热图 -> Single-cell
• CIBERSORT免疫浸润 -> Immune deconvolution
• 物种累积 / 稀释曲线 / UPGMA / NMDS / PCoA -> Microbiome/ecology
• motif logo / HOMER motif / peak annotation -> ChIP/ATAC/motif
• miRNA靶基因 / circRNA-miRNA / 受体配体 -> Regulatory network
• 箱线 / 小提琴 / 雨云 / 蜂群 / ridge / histogram / QQ / errorbar -> Descriptive/group comparison
• 线图 / 平滑线 / 时序cluster / 表达趋势 / streamgraph / bump -> Longitudinal/time series
• 雷达 / 极坐标 / stem / 3D / 2.5D / 花瓣 -> Specialized display-only

All map figures from the source gallery are intentionally excluded.

4. Backend package priority

R priority order

General:

1. ggplot2
2. ComplexHeatmap
3. domain-specific analysis package
4. patchwork for layout
5. ggrepel for labels

Bioinformatics:

• Differential expression: DESeq2, edgeR, limma
• Enrichment: clusterProfiler, enrichplot, fgsea, GSVA, msigdbr
• Single-cell: Seurat
• Cancer variants: maftools
• Genomic tracks/circular: GenomicRanges, Gviz, karyoploteR, circlize
• Survival: survival, survminer
• Meta-analysis: metafor
• Microbiome: phyloseq, vegan

Python priority order

General:

1. pandas, numpy
2. matplotlib, seaborn
3. scipy, statsmodels
4. domain-specific package

Bioinformatics:

• Differential expression: pydeseq2
• Enrichment: gseapy
• Single-cell: scanpy, anndata
• ML: scikit-learn, xgboost
• Survival: lifelines, scikit-survival
• Networks: networkx
• Circular genomic plots: pycirclize
• Mutation landscape: CoMut
• Ecology: scikit-bio

5. Method guards

Apply these guards before producing a figure.

1. Verify the input data type.
2. Verify the unit of analysis.
3. Verify biological replication.
4. Choose the statistical method before the plot.
5. Control multiple testing when many hypotheses are tested.
6. Preserve continuous variables unless a cutpoint has a substantive or prespecified reason.
7. For omics, report effect size plus FDR, not p-value alone.
8. For single-cell condition comparisons, account for donor/sample structure.
9. For survival, account for censoring.
10. For prediction, prevent information leakage.
11. For heatmaps, disclose scaling/transformation.
12. For enrichment, disclose gene universe and gene-set source.
13. For Venn, default to UpSet when intersections become hard to read.
14. For pie/radar/3D/polar charts, use only on explicit request or when they improve the analytical message.
15. Do not create geographic maps in this skill.

6. Output contract

For each request, return in this order:

1. 分析判定

   • What analysis the requested figure actually represents.
   • Whether the figure is inferential, descriptive, predictive, or display-only.

2. 数据要求

   • Required columns/matrix.
   • Unit of observation.
   • Minimum metadata required.

3. 方法

   • Statistical/bioinformatics method.
   • Key assumptions.
   • Multiplicity handling if relevant.

4. 包

   • Use only the selected backend.
   • Give the primary package and any visualization package.

5. 代码

   • Reproducible, executable code.
   • Set random seed for stochastic methods.
   • Do not hide preprocessing.
   • Save both analysis tables and figures.

6. 导出

   • Prefer vector PDF/SVG for line art.
   • Also provide TIFF/PNG at publication resolution when requested.
   • Use explicit width/height.
   • Keep labels readable without manual post-processing.

7. 解释

   • Explain what each axis, color, shape, interval, and statistic means.
   • State what cannot be concluded from the plot.

7. Installation behavior

Do not silently install packages.

First check whether the selected packages are installed.

R:

• use requireNamespace("pkg", quietly = TRUE)
• CRAN packages: install.packages()
• Bioconductor packages: BiocManager::install()

Python:

• check imports with importlib.util.find_spec
• install only after user approval, using pip or the active environment's package manager

If package versions materially affect syntax, report the detected version in the analysis log.

8. Reproducibility defaults

• Record session/package versions.
• Save intermediate result tables as CSV/TSV.
• Use stable filenames.
• Set random seeds for PCA randomized solvers, t-SNE, UMAP, ML resampling, and other stochastic procedures.
• Keep raw data immutable.
• Never replace missing values with zero unless zero is biologically/statistically meaningful.
• Never infer group labels from sample names when metadata is available.
• Never choose significance thresholds after seeing the result unless explicitly labeled exploratory.

9. Top-journal aesthetic engine

After the user selects R or Python, load top_journal_aesthetics.yaml and apply the aesthetic layer after the statistical method is selected.

The order is:

backend -> data/estimand -> analysis method -> figure family -> top-journal aesthetic profile -> code -> QC -> export

9.1 Profile selection

If the user explicitly names a target journal, prefer its current official figure requirements.

If no target journal is named:

• general statistics, heatmaps, correlation, PCA -> nature_general
• clinical survival, forest, ROC, longitudinal clinical results -> clinical_high_impact
• bulk omics enrichment/GSEA/network -> cell_omics
• SNP/MAF/CNV/Manhattan/LD/Circos -> genetics_genomics
• scRNA-seq -> single_cell
• microbiome -> microbiome
• observational epidemiology/causal effect estimates -> epidemiology

These profiles are aesthetic heuristics. Do not claim that they are exact proprietary journal templates.

9.2 Mandatory visual QC

Before saving any main-text figure, check:

1. Is the message readable at final size?
2. Are fonts and line widths still legible?
3. Is the same biological group encoded with the same color across panels?
4. Is the palette accessible and non-rainbow?
5. Is uncertainty shown and defined where applicable?
6. Are exact units stated?
7. Are redundant legends, duplicate labels, and decoration removed?
8. Are point clouds overplotted? If yes, use alpha, smaller points, hexbin/density, or rasterization as appropriate.
9. Does a complex plot (radar, polar, 3D, Venn, Circos) materially improve interpretation? If not, replace with a simpler plot.
10. Are statistical claims supported by the upstream analysis rather than by visual separation alone?

9.3 Backend-specific theme helpers

For R, source:
R/topjournal_theme.R

For Python, import:
python/topjournal_theme.py

The helper themes provide:

• white background,
• no background grid,
• compact sans-serif typography,
• thin axes,
• vector-friendly font settings,
• publication-size export helpers.

Do not force a palette when a domain-specific package requires another scientifically meaningful scale. Preserve semantic color meaning first.

9.4 Figure-family aesthetic routing

Use top_journal_aesthetics.yaml -> figure_family_rules to style:

• forest
• Kaplan-Meier
• ROC/timeROC
• volcano
• heatmap
• correlation matrix
• PCA/PCoA/NMDS
• UMAP/t-SNE
• marker dotplot
• enrichment dotplot
• GSEA
• Venn/UpSet
• Sankey/alluvial
• Manhattan
• LD heatmap
• oncoplot/MAF
• Circos
• microbiome stacked composition
• longitudinal trajectory
• radar/polar/3D

9.5 Journal-specific override behavior

When a target journal is named:

1. Check the current official author/figure guidance.
2. Override width, height, font, file type, and resolution using official requirements.
3. Keep the selected statistical method unchanged.
4. Adapt aesthetics without imitating decorative or proprietary branding.
5. State any requirement that cannot be reproduced directly from R/Python.