| name | ukbsci-plot |
| description | Publication-grade figure production for UK Biobank Research Analysis Platform (RAP) analyses built with UKBAnalytica. Wraps the package's built-in plotters — plot_forest (subgroup / regression forest), plot_calibration (clinical-model calibration), plot_regression_volcano (multi-exposure / multi-protein volcano), plot_heatmap, plot_stacked_bar, plot_violin, and plot_scatter for lightweight exploratory/manuscript panels, plus the family of survival, ML, SHAP, mediation, propensity, imputation, correlation, and enrichment plots from sibling skills — and adds a shared neutral theme (ukbsci_clinical / ukbsci_diverging / ukbsci_sequential palettes), a dual-format save helper, and a figure-contract checklist. Use this skill when the user asks for any manuscript figure derived from UKBAnalytica outputs: forest plots, volcano plots, KM curves, calibration plots, Love plots, SHAP summaries, multi-panel composites, or PDF / SVG high-resolution export. Triggers: UKB plotting, forest plot, volcano, calibration, manuscript figure, ggplot helper, ukbsci 画图, 论文级图, /ukbsci-plot. Hard rule: local agents must not read or inspect real UKB RAP participant-level data; generate scripts for RAP execution and interpret aggregate outputs only.
|
ukbsci-plot — Manuscript figure production for UKBAnalytica
0. RAP guardrails
Core rule: do not export UK Biobank participant-level raw data, direct
identifiers (eid, exact dates, raw RAP fields), or row-level source tables
that can be linked back to participants.
Strict local-agent boundary: this skill is for script generation,
workflow planning, package guidance, and interpretation of aggregate outputs.
The agent must not read, inspect, summarize, or process real UK Biobank RAP
participant-level data, including de-identified row-level tables, raw RAP
fields, exact dates, per-row predictions, row-level SHAP matrices, screenshots,
tracebacks, or logs containing row-level values. Generate scripts for the user
to run inside RAP; only aggregate results or rendered figures may be shared
back with the agent. See ../references/agent-privacy-boundary.md.
| Output | Sharing rule |
|---|
| Rendered PDF / SVG / PNG figure | Shareable if it does not expose identifiers, exact dates, raw RAP fields, row labels, or data previews. |
05-figs/data/Fig*.csv source CSV | Shareable only if aggregate (per-bin, per-strata, per-feature means/CIs). Never share a source CSV that contains raw per-participant values or identifiers. |
Coefficient / metric table from 04-results/*.csv | Shareable — aggregate only. |
| Per-participant raw values used to build a figure | Do not export. Keep intermediate data on RAP. |
| Individual-level interpretation figure (e.g. SHAP force plot) | Do not use a real participant row with the local agent. Generate synthetic or representative prototype-row figures inside RAP if needed. |
1. When to load
- Build the manuscript-ready forest plot of the main Cox / subgroup result.
- Produce calibration / DCA / ROC for a clinical model (paired with
ukbsci-ml).
- Volcano of a protein / metabolite / batch regression screen.
- Polished multi-panel figures combining outputs from multiple skills.
- Standardized save (
.pdf + .png + .svg) at 300 dpi.
2. When NOT to load
- The user wants a KM curve only →
ukbsci-survival::plot_km_curve (this
skill defers to it).
- The user wants Love / PS distribution →
ukbsci-propensity plots.
- The user wants mediation / MI / SHAP plots → use the originating skill's
plotter; this skill provides the shared theme and save helper.
3. Figure contract (always run first)
For any figure the user asks for, restate three things before plotting:
- Claim — the one-sentence conclusion the figure must support.
- Evidence panel(s) — which underlying CSV(s) from
04-results/ feed
the figure.
- Export contract — final size (mm), single-column / double-column,
font family, palette family.
A figure that cannot be re-rendered from 05-figs/data/Fig*.csv is not
acceptable.
4. Shared theme & palettes (define once, reuse everywhere)
UKBAnalytica does not ship custom themes. This skill defines the
following neutral helpers — copy verbatim into each plotting script:
library(ggplot2)
ukbsci_theme <- function(base_size = 7, base_family = "Arial") {
theme_classic(base_size = base_size, base_family = base_family) +
theme(
axis.line = element_line(linewidth = 0.35, colour = "black"),
axis.ticks = element_line(linewidth = 0.35, colour = "black"),
legend.title = element_text(size = base_size * 0.95),
legend.text = element_text(size = base_size * 0.85),
strip.text = element_text(size = base_size * 0.95, face = "bold"),
plot.title = element_text(size = base_size * 1.1, face = "bold"),
panel.grid = element_blank()
)
}
ukbsci_clinical <- c(
baseline = "#2F6FA3",
exposure = "#C74732",
control = "#7F7F7F",
accent = "#F2A93B",
highlight1 = "#3D8B66",
highlight2 = "#7A4E9B"
)
ukbsci_diverging <- c("#2166AC", "#67A9CF", "#D1E5F0",
"#F7F7F7",
"#FDDBC7", "#EF8A62", "#B2182B")
ukbsci_sequential <- c("#FFF7EC", "#FEE8C8", "#FDD49E",
"#FDBB84", "#FC8D59", "#EF6548",
"#D7301F", "#990000")
theme_set(ukbsci_theme())
These names are intentionally generic — they do not reference any
specific journal brand.
5. Standardized save helper
save_ukbsci_figure <- function(plot, name,
width_mm = 180, height_mm = 120,
dpi = 300,
outdir = "/mnt/project/<area>/05-figs") {
dir.create(outdir, showWarnings = FALSE, recursive = TRUE)
w <- width_mm / 25.4; h <- height_mm / 25.4
svglite::svglite(file.path(outdir, paste0(name, ".svg")), width = w, height = h)
print(plot); dev.off()
grDevices::cairo_pdf(file.path(outdir, paste0(name, ".pdf")),
width = w, height = h, family = "Arial")
print(plot); dev.off()
ragg::agg_png(file.path(outdir, paste0(name, ".png")),
width = w, height = h, units = "in", res = dpi)
print(plot); dev.off()
}
Manuscript single-column ≈ width_mm = 89; double-column ≈ 180. Use a
height that yields golden-ratio-ish aspect unless the figure dictates
otherwise.
6. UKBAnalytica plot families (where each one lives)
| Plot | Provided by | Notes |
|---|
| Forest (subgroup / batch reg) | UKBAnalytica::plot_forest | This skill — see §7 |
| Calibration | UKBAnalytica::plot_calibration | This skill — see §8 |
| Volcano | UKBAnalytica::plot_regression_volcano | This skill — see §9 |
| Heatmap | UKBAnalytica::plot_heatmap | Long-format matrix-style data |
| Stacked bar | UKBAnalytica::plot_stacked_bar | Categorical composition |
| Violin | UKBAnalytica::plot_violin | Grouped continuous distributions |
| Scatter | UKBAnalytica::plot_scatter | Exposure-response or feature-feature trends |
| KM survival | plot_km_curve | ukbsci-survival |
| Love / PS distribution | plot_balance, plot_ps_distribution | ukbsci-propensity |
| Mediation effects | plot_mediation, plot_mediation_forest | ukbsci-mediation |
| MI diagnostics | plot_mi_pooled, plot_mi_diagnostics | ukbsci-imputation |
| GO bar / lollipop | plot_go_ora_bar, plot_enrichment_lollipop | ukbsci-proteomics |
| Correlation heatmap | plot_correlation | this skill (re-export-friendly) |
| ML evaluation | plot_ml_roc, plot_ml_calibration, plot_ml_dca, … | ukbsci-ml |
| SHAP | plot_shap_summary, plot_shap_beeswarm, plot_shap_dependence, plot_shap_force | ukbsci-ml |
When mixing plots from sibling skills, apply the same theme via
theme_set(ukbsci_theme()) at the top of the orchestrating script and
override colors using the ukbsci_* palettes.
7. Forest plot — plot_forest()
plot_forest(results,
estimate_col = "estimate",
lower_col = "lower95",
upper_col = "upper95",
label_col = "subgroup",
pvalue_col = "pvalue",
p_interaction_col = "p_interaction",
null_value = 1,
log_scale = TRUE,
colors = NULL,
title = "Subgroup Analysis",
xlab = "Hazard Ratio (95% CI)",
show_n = TRUE,
show_events = TRUE)
Input: any data.frame with at least estimate, lower95, upper95, label.
Naturally consumes outputs of runmulti_cox / run_subgroup_analysis / run_multi_subgroup / runmulti_competing / pool_mi_models$pooled / tidy().
8. Calibration — plot_calibration()
plot_calibration(data, predicted, observed,
n_bins = 10,
smooth = TRUE,
conf_int = TRUE)
Input: per-prediction rows with predicted probabilities and binary
outcome. Note: this is participant-level so the data argument should
come from flow$final_test_predictions (which stays on RAP); the figure
itself summarises into n_bins bins, so the rendered output is aggregate.
9. Volcano — plot_regression_volcano()
plot_regression_volcano(data,
effect_col = NULL,
p_col = "pvalue",
adjusted_p_col = NULL,
label_col = NULL,
significance_cutoff = 0.05,
top_n_label_each = 5,
null_effect = 1,
x_lab = NULL,
y_lab = NULL,
x_limits = NULL,
y_limits = NULL,
point_size = 1.05,
label_size = 2,
colors = c(neutral = "#D8D8D8",
lower = "#2F6FA3",
higher = "#C74732"),
show_cutoff = TRUE)
Auto-detects effect_col (HR → OR → estimate) and label_col
(gene_symbol → protein_clean → variable). The output's
attr(., "plot_data") and attr(., "label_data") give the aggregate
underlying tables — write those to 05-figs/data/.
10. Lightweight plot helpers
Use these for compact exploratory or supplementary panels when the user has an
aggregate or de-identified plotting table.
plot_heatmap(cor_df, x = "trait", y = "protein", fill = "rho")
plot_stacked_bar(tab_df, x = "risk_group", fill = "case_status", position = "fill")
plot_violin(plot_df, x = "group", y = "marker", fill = "group")
plot_scatter(plot_df, x = "exposure", y = "outcome", color = "group")
Inputs must use column names as strings. Do not pass eid, exact dates, or
row-level raw RAP fields into local-agent-visible source CSVs.
11. Multi-panel composition
patchwork is the recommended layout engine:
library(patchwork)
top <- p_forest + p_volcano + plot_layout(widths = c(1, 1.2))
mid <- p_calib + p_dca + plot_layout(widths = c(1, 1))
fig <- top / mid +
plot_annotation(tag_levels = "a") &
ukbsci_theme()
save_ukbsci_figure(fig, "Fig01-composite",
width_mm = 180, height_mm = 200)
plot_annotation(tag_levels = "a") gives lowercase a, b, c, … panel
labels — common across observational epidemiology.
12. Common pitfalls
- Mixing
theme_classic() and theme_minimal() across panels of a
composite. Always end the orchestrating script with & ukbsci_theme() so
every patch inherits the same theme.
- Hard-coding hex colors per plot. Use the
ukbsci_* palettes and
keep colour semantics consistent across figures (baseline = blue, exposure
= red, accent = orange).
- Font availability.
cairo_pdf with family = "Arial" fails if Arial
is not installed on the RAP node. Fallback: use family = "sans" or
family = "DejaVu Sans", or register a project-installed font with
grDevices::loadfonts() before plotting.
3a. High-DPI PNG for dense figures. For complex multi-panel composites,
heatmaps, or SHAP beeswarm plots with many points, add a 600 dpi PNG
export alongside the standard 300 dpi one to improve readability in
supplementary figures. The save_ukbsci_figure() helper uses 300 dpi by
default; pass dpi = 600 for these cases.
plot_forest() reverses row order. Top row in the data frame
becomes the bottom of the figure (so the manuscript "primary" subgroup
appears at the top). Adjust order with dplyr::arrange() accordingly.- Volcano
effect_col auto-detection can pick the wrong column when
multiple effect-like columns exist. Pass effect_col explicitly for the
manuscript.
- Calibration n_bins = 10 can over-smooth in 100k+ cohorts. Increase
to 20 for large samples.
- Survival figures — generate via
ukbsci-survival; this skill
re-themes the result.
- Figure source CSVs: every figure script should write its source
data to
05-figs/data/Fig##-*.csv. Reviewers expect it; reproducibility
demands it.
13. Key functions
| Function | Returns |
|---|
plot_forest(...) | ggplot |
plot_calibration(data, predicted, observed, n_bins, smooth, conf_int) | ggplot |
plot_regression_volcano(...) | ggplot (with plot_data, label_data attrs) |
plot_heatmap(data, x, y, fill, label, show_values) | ggplot |
plot_stacked_bar(data, x, fill, weight, position) | ggplot |
plot_violin(data, x, y, fill, add_boxplot) | ggplot |
plot_scatter(data, x, y, color, add_smooth) | ggplot |
(helpers defined locally in this skill) ukbsci_theme(), ukbsci_clinical, ukbsci_diverging, ukbsci_sequential, save_ukbsci_figure() | utilities |
14. Related skills
| Skill | When |
|---|
ukbsci-regression | Source of forest / volcano inputs. |
ukbsci-survival | KM plots (uses its own plot_km_curve). |
ukbsci-ml | ROC / PR / calibration / DCA / SHAP plots. |
ukbsci-propensity | Love + PS distribution. |
ukbsci-mediation | Mediation forest. |
ukbsci-imputation | Pooled forest + FMI. |
ukbsci-proteomics | GO / KEGG figures. |
ukbsci-workflow | Phase 8 — assemble the final manuscript figure pack. |
15. References
