A small change with a big surface

A PR on teal.widgets adds a render path for interactive htmlwidgets. If plot_r() returns an htmlwidget — canvasXpress, plotly, anything with a Shiny binding — plot_with_settings renders it through the widget’s own binding, keeping the familiar card chrome. Height, width, and full-screen work as before, and download produces a self-contained HTML file you can email or archive.

It is strictly opt-in. Every existing static-plot caller behaves exactly as it did; the interactive path triggers only when a module author chooses to return a widget.

library(shiny)
library(canvasXpress)
library(teal.widgets)

pg <- as.data.frame(na.omit(palmerpenguins::penguins))

ui <- bslib::page_fluid(plot_with_settings_ui("p"))

server <- function(input, output, session) {
  plot_with_settings_srv(
    "p",
    plot_r = reactive(canvasXpress(
      data = pg, graphType = "Scatter2D",
      xAxis = list("flipper_length_mm"), yAxis = list("body_mass_g"),
      colorBy = "species"
    ))
  )
}
shinyApp(ui, server)

The chart that lands in the card is a real canvasXpress widget — the same one you can render on its own here. Hover a point, click to select, use the toolbar to export:

library(canvasXpress)

pg <- as.data.frame(na.omit(palmerpenguins::penguins))

canvasXpress(
  data      = pg,
  graphType = "Scatter2D",
  xAxis     = list("flipper_length_mm"),
  yAxis     = list("body_mass_g"),
  colorBy   = "species",
  title     = "Palmer penguins — flipper length vs body mass"
)

Inside plot_with_settings, that interactivity sits in the usual card, with the resize and download controls you already use:

Describe the chart instead of configuring it

Because the render path is generic, you inherit whatever the widget can do. canvasXpress, for instance, can build a chart from a plain-English prompt — no graphType, no axes:

plot_with_settings_srv(
  "p",
  plot_r = reactive(canvasXpress(
    data   = pg,
    prompt = "Create a scatter plot of bill_depth_mm vs body_mass_g and color by species"
  ))
)

Try it live

There’s a running demo — three canvasXpress plots inside plot_with_settings cards:

canvasxpress.shinyapps.io/teal-canvasxpress-demo

or install the PR build and run it yourself:

pak::pak("pharmaverse/teal.widgets#371")

Why it matters

Interactive dashboards usually mean leaving the tools you trust for a BI platform, and losing reproducibility in the trade. This keeps both: the module model and reproducible, code-defined figures of teal, plus the interactivity and portability of an htmlwidget. The figure is still code — it just moves now.

The discussion that started it is teal#1757; the PR is teal.widgets#371. Feedback from teal users is welcome, especially on how you’d want widget support wired into the module API.

The data shape

canvasXpress builds a network from two tables: nodes (id, name, group) and edges (id1, id2, value). Swap this simulated three-community graph for your own.

library(canvasXpress)

set.seed(1)
grp   <- rep(c("Alpha", "Beta", "Gamma"), each = 7)
ids   <- paste0("n", seq_along(grp))
nodes <- data.frame(id = ids, name = paste0(grp, ave(grp, grp, FUN = seq_along)),
                    group = grp, stringsAsFactors = FALSE)

# Dense within a community, sparse between communities — the structure a layout reveals.
e1 <- c(); e2 <- c(); ev <- c()
for (g in unique(grp)) {
  m <- ids[grp == g]
  for (i in seq_along(m)) for (j in seq_along(m))
    if (i < j && runif(1) < 0.5) { e1 <- c(e1, m[i]); e2 <- c(e2, m[j]); ev <- c(ev, sample(1:5, 1)) }
}
for (k in 1:6) {                                     # a few cross-community links
  pair <- sample(unique(grp), 2)
  e1 <- c(e1, sample(ids[grp == pair[1]], 1)); e2 <- c(e2, sample(ids[grp == pair[2]], 1)); ev <- c(ev, 1)
}
edges <- data.frame(id1 = e1, id2 = e2, value = ev, stringsAsFactors = FALSE)

The plot

Pass the two tables as nodeData and edgeData; colorNodeBy colours by the community, and networkLayoutType = "forceDirected" runs the physics simulation.

canvasXpress(
  nodeData          = nodes,
  edgeData          = edges,
  graphType         = "Network",
  networkLayoutType = "forceDirected",
  colorNodeBy       = "group",
  nodeSize          = 25,
  showAnimation     = TRUE,
  title             = "A small community network",
  width             = 650,
  height            = 500
)

Drag any node and the layout settles around it; hover to read the label. The three communities separate on their own because within-group edges outnumber the cross-group ones.

Why “reproducible”

The nodes, edges and config are the figure — one portable specification. The same spec renders the identical network from Python or JavaScript, and can be validated and re-rendered later.

Next

• Sankey / alluvial diagrams in R
• Gallery: https://canvasxpress.org/examples.html
• Package: https://github.com/neuhausi/canvasXpress

The QC table

96 samples with mapping rate, duplication, Q30, GC, insert size and contamination (VerifyBamID freemix), plus lane / batch / library annotations. (Download: ngs-qc.csv.)

library(canvasXpress)

qc <- read.csv("ngs-qc.csv", stringsAsFactors = FALSE)
metrics <- c("total_reads", "pct_mapped", "pct_duplication", "pct_q30",
             "gc_content", "insert_size", "contamination_freemix")

m        <- as.matrix(qc[, metrics]); rownames(m) <- qc$sample
annot    <- data.frame(Lane = qc$lane, Batch = qc$batch, Library = qc$library,
                      row.names = qc$sample)
head(qc[, c("sample", "batch", "library", "pct_mapped", "pct_duplication",
            "contamination_freemix")], 4)

  sample batch  library pct_mapped pct_duplication contamination_freemix
1   S001  RunA    PolyA      93.85           11.90                0.0165
2   S002  RunC RiboZero      86.82           13.41                0.0015
3   S003  RunA RiboZero      99.47            7.88                0.0205
4   S004  RunC    PolyA      97.33           13.95                0.0283

Overview — a clustered QC heatmap

Z-score each metric and cluster: outlier samples and any batch/library structure jump out at a glance. This is the “is anything wrong, and where” view.

canvasXpress(
  data = t(scale(m)), smpAnnot = annot,
  graphType = "Heatmap", samplesClustered = TRUE, variablesClustered = TRUE,
  colorSpectrum = list("navy", "white", "firebrick3"),
  title = "QC metrics (z-scored) — 96 samples clustered",
  width = 820, height = 420
)

The linked triage dashboard

Four panels over the same samples, all sharing broadcastGroup = "qc". The sample is the unit, so each sample is a point (varAnnot carries its lane/batch/library). Select points in any panel — drag a box in a scatter, click a bar — and the same samples re-mark everywhere.

qc_panel <- function(cfg, ...) {
  do.call(canvasXpress, c(list(data = m, varAnnot = annot,
                               broadcast = TRUE, broadcastGroup = "qc"), cfg, list(...)))
}

qc_panel(list(graphType = "Scatter2D", xAxis = list("pct_duplication"),
              yAxis = list("pct_mapped"), colorBy = "Batch", sizeBy = "total_reads",
              title = "Mapping rate vs duplication — select the bottom-right"),
         width = 640, height = 360)

qc_panel(list(graphType = "Scatter2D", xAxis = list("pct_mapped"),
              yAxis = list("contamination_freemix"), colorBy = "Batch",
              title = "Contamination (freemix) vs mapping rate"),
         width = 640, height = 360)

qc_panel(list(graphType = "Scatter2D", xAxis = list("gc_content"),
              yAxis = list("pct_q30"), colorBy = "Library",
              title = "Q30 vs GC content, coloured by library"),
         width = 640, height = 360)

qc_panel(list(graphType = "Bar", graphOrientation = "vertical",
              xAxis = list("total_reads"), colorBy = "Batch",
              title = "Total reads per sample (flag the short ones)"),
         width = 820, height = 300)

Why “reproducible”

Each panel is a portable data + config spec; the cross-filter is just a shared broadcastGroup. The same specs reproduce the dashboard from Python or JavaScript, against the same ngs-qc.csv.

Next

• Interactive network graphs in R
• Gallery: https://canvasxpress.org/examples.html
• Package: https://github.com/neuhausi/canvasXpress

The data shape

A Genome figure is a list of tracks that share one coordinate axis — each with a type. Real browser views stack several: here we build four — gene models (box, multi-exon, connected), coverage across three tissues (bar), an expression heatmap (heatmap), and variant markers (triangle).

library(canvasXpress)

set.seed(3)

# Gene models: each gene is a set of exon [start, end] intervals, drawn connected.
genes <- lapply(0:3, function(j) {
  start <- 40 + j * 120
  exons <- lapply(0:(sample(2:4, 1) - 1), function(k) list(start + k * 30, start + k * 30 + 18))
  list(id = paste0("GENE", j + 1), dir = if (j %% 2 == 0) "right" else "left",
       fill = "rgb(70,130,220)", outline = "rgb(0,0,0)", data = exons)
})

# Coverage and expression: one entry per binned position, three tissues each.
offsets  <- 50 + (0:21) * 22
coverage <- lapply(seq_along(offsets), function(i)
  list(id = paste0("p", i), offset = offsets[i],
       data = list(sample(8:45, 1), sample(8:45, 1), sample(8:45, 1))))
express  <- lapply(seq_along(offsets), function(i)
  list(id = paste0("p", i), offset = offsets[i],
       data = list(round(rnorm(1), 2), round(rnorm(1), 2), round(rnorm(1), 2))))

# Variants: point markers at genomic positions.
snps <- lapply(0:8, function(k)
  list(id = paste0("rs", 1000 + k), offset = sample(45:520, 1),
       fill = "rgb(200,40,40)", outline = "rgb(0,0,0)"))

genome <- list(tracks = list(
  list(name = "Genes (exon models)", type = "box", connect = TRUE, data = genes),
  list(name = "Coverage — Heart / Liver / Kidney", type = "bar", height = 120,
       fill = "rgb(80,80,200)", outline = "rgb(60,60,60)", data = coverage),
  list(name = "Expression (z-score)", type = "heatmap", height = 90, data = express),
  list(name = "SNPs", type = "triangle", data = snps)
))

The plot

The Genome graph type is passed through to the engine as-is; featureStaggered spreads crowded features so labels stay legible.

canvasXpress(
  data            = genome,
  graphType       = "Genome",
  background       = "rgb(245,245,245)",
  featureStaggered = TRUE,
  title            = "Multi-track genome browser: genes, coverage, expression and variants",
  width            = 760,
  height           = 520
)

The Genome graphType is an advanced chart, data is passed as-is to the JS library

Scroll/drag to pan and zoom into a region; every track stays locked to the shared coordinate axis, so the gene models, coverage, expression and variants line up position-for-position. Swap each track for your own pileup, annotation and VCF-derived data.

Why “reproducible”

The tracks and config are the figure — one portable spec that renders the identical browser view from Python or JavaScript, and can be validated and re-rendered later.

Next

• Interactive network graphs in R
• Gallery: https://canvasxpress.org/examples.html
• Package: https://github.com/neuhausi/canvasXpress

The data shape

An oncoprint is a Heatmap with overlay matrices: a base matrix (y, here expression) plus same-shaped layers for copy-number (data2) and mutation (data3). Each overlay cell is a string like "Amplification", "Missense", or "" for none.

library(canvasXpress)

set.seed(5)
genes   <- c("TP53", "KRAS", "PIK3CA", "PTEN", "EGFR", "BRAF",
             "APC", "RB1", "NF1", "MYC", "CDKN2A", "ARID1A")
samples <- sprintf("T%02d", 1:28)
mutrate <- setNames(pmax(0.05, 0.5 * (1 - (seq_along(genes) - 1) / length(genes))), genes)

base <- matrix(round(rnorm(length(genes) * length(samples)), 2),
               nrow = length(genes), dimnames = list(genes, samples))

CNA <- c("Amplification", "Deletion"); MUT <- c("Missense", "Nonsense", "Truncating")
cna <- mut <- matrix("", length(genes), length(samples), dimnames = list(genes, samples))
for (g in genes) for (s in samples) {
  if (runif(1) < mutrate[g])       mut[g, s] <- sample(MUT, 1)
  if (runif(1) < mutrate[g] * 0.5) cna[g, s] <- sample(CNA, 1)
}

smpAnnot <- data.frame(Subtype = sample(c("Basal", "Luminal", "HER2"), length(samples), replace = TRUE),
                      row.names = samples)
varAnnot <- data.frame(Pathway = rep(c("TSG", "Oncogene"), length.out = length(genes)),
                      row.names = genes)

The plot

Pass the overlays in a named data list and point oncoprintCNA / oncoprintMUT at them. xAxis lists the samples.

canvasXpress(
  data          = list(y = base, data2 = cna, data3 = mut),
  smpAnnot      = smpAnnot, varAnnot = varAnnot,
  graphType     = "Heatmap",
  oncoprintCNA  = "data2", oncoprintMUT = "data3",
  overlaysThickness = 100,
  xAxis         = as.list(samples),
  title         = "Mutation landscape: 12 genes across 28 tumours",
  width         = 820, height = 440
)

canvasXpress sorts the waterfall for you and shows the alteration frequency per row. Hover a cell to read the exact alteration; swap the overlays for your own MAF / CNA calls.

Why “reproducible”

The base matrix, the overlays and the config are the figure — one portable spec. The same spec renders the identical oncoprint from Python or JavaScript, and can be validated and re-rendered later.

Next

• A clustered heatmap in R
• Gallery: https://canvasxpress.org/examples.html
• Package: https://github.com/neuhausi/canvasXpress

The data shape

The matrix is tracks × segments (rows are the tracks you draw, columns are the positions around the ring). A sample annotation segments the ring (here into chromosomes), and circularConnections is a list of [colour, from, to] ribbons.

library(canvasXpress)

set.seed(8)
segments <- paste0("s", 1:80)
tracks   <- c("Expression", "Methylation", "CopyNumber", "Density")
y <- matrix(round(rnorm(length(tracks) * length(segments)), 2),
            nrow = length(tracks), dimnames = list(tracks, segments))

smpAnnot <- data.frame(Region = rep(paste0("chr", 1:4), each = 20), row.names = segments)

cols  <- c("rgb(220,40,40)", "rgb(40,120,220)", "rgb(40,160,60)", "rgb(240,150,20)")
conns <- lapply(1:18, function(i)
  list(sample(cols, 1), sample(segments, 1), sample(segments, 1)))

The plot

circularTrackGraphType picks a renderer per track (bar, heatmap, line, dot), circularTrackGraphWeight sets each track’s radial thickness, and segregateSamplesBy splits the ring by the annotation.

canvasXpress(
  data      = y, smpAnnot = smpAnnot,
  graphType = "Circular",
  circularConnections     = conns,
  circularTrackGraphType  = list("bar", "heatmap", "line", "dot"),
  circularTrackGraphWeight = list(30, 20, 25, 25),
  circularTrackName        = list(1, 2, 3, 4),
  segregateSamplesBy       = list("Region"),
  title     = "Circos-style multi-track plot with connections",
  width     = 560, height = 560
)

Each ring is one track; the inner ribbons are the connections. Hover a segment to read its values; swap the matrix and ribbons for your own genomic tracks and interactions.

Why “reproducible”

The matrix, the connections and the config are the figure — one portable spec. The same spec renders the identical circular plot from Python or JavaScript, and can be validated and re-rendered later.

Next

• Genome browser tracks in R
• Gallery: https://canvasxpress.org/examples.html
• Package: https://github.com/neuhausi/canvasXpress

First, the trap: colour encodes a rate, not a count

A choropleth fills an area, and area is a size channel your eye cannot help reading. Shade countries by a raw count — total cases, total emissions, total sales — and big, populous regions light up simply because they are big and populous. You have drawn a population map with extra steps.

The fix is almost always to map a rate or density: cases per 100k, emissions per capita, sales per store. Reserve raw counts for a proportional-symbol map (a sized bubble at each centroid), where the size channel carries the count honestly. Decide which question you are answering before you pick the geometry — this one choice prevents most misleading maps.

One value per region

A choropleth needs exactly one measurement per shape. In canvasXpress the columns are the regions (they match the map by name) and the row is the variable you colour by — here CO₂ emissions per country for 2018. Load a prepared table; swap it for your own (any country → value table works).

library(canvasXpress)

y <- read.table(
  "https://www.canvasxpress.org/data/r/cX-CO2-dat.txt",
  header = TRUE, sep = "\t", quote = "", row.names = 1,
  check.names = FALSE, stringsAsFactors = FALSE
)

dim(y)              # 1 row (CO2) x N countries

[1]   1 198

y[, 1:4]

    Afghanistan  Albania  Algeria Andorra
CO2    10.45267 5.402999 164.3093 0.46421

The single row is the variable (CO2); each column name is a country that must match a shape in the map. An optional sample annotation table (rows = countries) rides along for richer tooltips and legends — here the continent and ISO code.

x <- read.table(
  "https://www.canvasxpress.org/data/r/cX-CO2-smp.txt",
  header = TRUE, sep = "\t", quote = "", row.names = 1,
  check.names = FALSE, stringsAsFactors = FALSE
)
head(x)

            Code     Continent     Country
Afghanistan  AFG          Asia Afghanistan
Albania      ALB        Europe     Albania
Algeria      DZA        Africa     Algeria
Andorra      AND        Europe     Andorra
Angola       AGO        Africa      Angola
Anguilla     AIA North America    Anguilla

The map: quantile classes computed in R, painted by the map

graphType = "Map" with a topoJSON of world boundaries draws the shapes and joins the countries by name — no manual merge, no projection math. The statistics stay in R, where they belong: we cut the values into seven quantile classes with quantile() + cut(), so each class holds an equal number of countries (~28 of 198), then colour by that classed annotation with a viridis palette. On skewed data that equal-count guarantee is what keeps all seven colours on the map.

vals   <- as.numeric(y[1, ])
breaks <- unique(quantile(vals, probs = seq(0, 1, length.out = 8)))
cls    <- cut(vals, breaks = breaks, include.lowest = TRUE)
x$Emissions <- sprintf(
  "Q%d: %s", as.integer(cls),
  gsub(",", " - ", gsub("[][()]", "", levels(cls)))[as.integer(cls)]
)
table(x$Emissions)   # ~28 countries per class

Q1: 0.00765 - 0.564    Q2: 0.564 - 2.69      Q3: 2.69 - 7.8      Q4: 7.8 - 22.4 
                 29                  28                  28                  28 
      Q5: 22.4 - 46        Q6: 46 - 208  Q7: 208 - 9.96e+03 
                 28                  28                  29 

canvasXpress(
  data      = y,
  smpAnnot  = x,
  graphType = "Map",
  colorBy   = "Emissions",
  topoJSON  = "https://www.canvasxpress.org/data/maps/WORLD.json",
  mapId     = "co2Quantile",
  colors = list("#440154", "#443983", "#31688e", "#21918c",
                "#35b779", "#90d743", "#fde725", "#d9dde3"),
  mapColor        = "#d9dde3",
  mapOutlineColor = "#ffffff",
  legendPosition  = "bottom",
  legendColumns   = 4,
  title    = "CO2 emissions per country (2018)",
  subtitle = "Seven quantile classes computed in R: each colour holds about 28 of 198 countries",
  width  = 760,
  height = 560
)

Every band of the ramp is doing work: the darkest purples are the smallest emitters, the yellows the largest, and the legend states each class’s actual value range — the edges are data-driven, not evenly spaced. The eighth colour, a neutral grey, catches map regions with no data so missing reads as missing. Hover any country for its name, continent, class and value.

If you prefer to keep the classing inside the engine, current CanvasXpress builds accept colorSpectrum (the ramp) plus colorSpectrumBreaksMethod = "quantile" and do the same cut at render time — the R route above works everywhere and keeps the breaks inspectable in your session.

Why not just a plain linear ramp?

Because the data is heavy-tailed — a few countries emit thousands of megatonnes while most emit almost nothing. On a linear scale, 195 of these 198 countries fall into the bottom fifth of the range, so a continuous ramp paints nearly the whole world one pale tone and spends its colour on two or three outliers:

canvasXpress(
  data      = y,
  smpAnnot  = x,
  graphType = "Map",
  colorBy   = "CO2",
  topoJSON  = "https://www.canvasxpress.org/data/maps/WORLD.json",
  mapId     = "co2Linear",
  legendPosition = "left",
  theme = "solarized",
  title    = "The same data on a plain linear ramp",
  subtitle = "195 of 198 countries sit in the bottom fifth of the scale - the map goes flat",
  width  = 700,
  height = 480
)

This is the single most common choropleth failure. The cure is classing:

• colorSpectrumBreaksMethod = "quantile" — equal counts per class. Every colour is used, by construction. The right default for skewed data and for “which regions rank high/low” questions.
• colorSpectrumBreaksMethod = "jenks" — natural breaks that minimise within-class variance. Best when the data has genuine clusters with gaps between them; on smoothly heavy-tailed data like this it piles almost everything into the bottom class, so check the legend before you trust it.
• Three to seven classes is the usable range — beyond that, readers cannot match colours to the legend.

Choose the palette on purpose

The palette is not decoration — it is the scale’s grammar:

• Sequential (dark → light of ordered hues, like viridis above) for a quantity that only goes up: counts, rates, concentrations.

• Diverging (two hues meeting at a neutral midpoint) when values are meaningful above and below a reference: change vs. last year, difference from a target, a signed index. Give canvasXpress a three-colour colorSpectrum and pin the midpoint with colorSpectrumZeroValue:

  colorBy = "Change",
  colorSpectrum = list("#2166ac", "#f7f7f7", "#b2182b"),  # blue - neutral - red
  colorSpectrumZeroValue = 0                               # value mapped to the middle colour

  Never use a diverging palette for a purely positive quantity — the neutral midpoint invents a “normal” that the data does not have.

Viridis and the ColorBrewer ramps are colour-blind-safe and perceptually ordered; a rainbow ramp is neither, so readers cannot tell which end means “more”. Keep the same scale across small multiples so maps stay comparable.

Polish: legend, labels and base styling

• subtitle / source — caption the units and provenance.
• legendNumberFormat = list(style = "decimal", decimals = 1, suffix = "%") — format the legend ticks as percentages, currency, etc.
• mapColor / mapOutlineColor — the fill for regions with no data (a neutral grey) and the border between shapes, so missing data reads as missing rather than as a value.
• showMapLabels = TRUE — draw region names (best on maps with few regions, e.g. a single country’s provinces; it clutters a 190-country world map).
• legendInside = TRUE — float the legend over empty ocean to reclaim width.

Beyond the world map

• Other boundaries. Point topoJSON at any shape file — US states, a single country’s regions, counties, custom districts. The join key is just the shape name.
• Projection. mapProjection = "albers" (equal-area, good for the US) or "mercator". Equal-area projections matter for choropleths: Mercator inflates high latitudes, exaggerating those regions’ visual weight.
• Categorical maps. Point colorBy at a categorical column (an election winner, a priority tier) for a qualitative choropleth with a discrete legend.
• Markers. Add decorations to drop labelled points on cities or call out specific regions.

The whole figure — data, boundaries, classing rule and palette — travels together as one spec, so a reviewer can reproduce it exactly and a colleague can re-render it from Python or JavaScript.

Next

• Choropleth maps in Python
• Choropleth maps in JavaScript
• Clustered heatmaps in R
• Gallery: https://canvasxpress.org/examples.html

The data shape

canvasXpress builds a Sankey from a tidy table where each row is one path through the stages, plus a frequency/weight. Swap this simulated clinical flow for your own counts.

library(canvasXpress)

set.seed(1)
cohort <- c(); treat <- c(); outcome <- c(); freq <- c()
for (co in c("Cohort A", "Cohort B"))
 for (tr in c("Drug 1", "Drug 2", "Placebo"))
  for (ou in c("Response", "Stable", "Progression")) {
    base <- if (ou == "Response") 40 else if (ou == "Stable") 25 else 15
    if (tr == "Placebo" && ou == "Response") base <- 12          # placebo responds less
    cohort  <- c(cohort, co); treat <- c(treat, tr); outcome <- c(outcome, ou)
    freq    <- c(freq, base + sample(0:15, 1))
  }

The value (Freq) is the single measured variable; the stage columns are sample annotations. In canvasXpress terms: one variable × N path-rows, with the categorical stages as smpAnnot.

ids <- paste0("r", seq_along(freq))
y <- data.frame(matrix(freq, nrow = 1, dimnames = list("Freq", ids)), check.names = FALSE)
smpAnnot <- data.frame(Cohort = cohort, Treatment = treat, Outcome = outcome,
                       row.names = ids, check.names = FALSE)

The plot

graphType = "Sankey" with sankeyAxes listing the stages in order, xAxis naming the value, and colorBy coloring the streams.

canvasXpress(
  data     = y,
  smpAnnot = smpAnnot,
  graphType = "Sankey",
  sankeyAxes = list("Cohort", "Treatment", "Outcome"),
  xAxis      = list("Freq"),
  colorBy    = "Outcome",
  sankeyType = "proportional",
  graphOrientation = "horizontal",
  title = "Patient flow: cohort → treatment → outcome",
  width  = 700,
  height = 500
)

Hover any stream to see the count; the widths are proportional to the frequency, so you can read the flow at a glance — e.g. how much of each cohort ends in Response vs Progression, and how Placebo differs. sankeyType can also be "aligned" (classic alluvial) or "equal".

Why “reproducible”

The data+config is the figure — one portable JSON spec. The same spec renders the identical Sankey from Python or JavaScript, and can be validated and re-rendered later.

Next

• Interactive volcano plots in R
• Gallery: https://canvasxpress.org/examples.html
• Package: https://github.com/neuhausi/canvasXpress

The data

A measurement across a few dose groups and two conditions. Swap in your own long-format table.

library(canvasXpress)

set.seed(1)
doses <- c("Low", "Medium", "High"); conds <- c("Control", "Treated")
value <- c(); Dose <- c(); Condition <- c()
for (d in doses) for (co in conds) {
  mu <- if (d == "Low") 6 else if (d == "Medium") 8 else 10
  if (co == "Treated") mu <- mu + 1.5
  value <- c(value, round(rnorm(40, mu, 1.2), 2))
  Dose <- c(Dose, rep(d, 40)); Condition <- c(Condition, rep(co, 40))
}

In canvasXpress terms a violin is a Boxplot graph with the violin turned on: one measured variable × N observations, with the grouping columns as smpAnnot.

ids <- paste0("o", seq_along(value))
y <- data.frame(matrix(value, nrow = 1, dimnames = list("value", ids)), check.names = FALSE)
smpAnnot <- data.frame(Dose = Dose, Condition = Condition, row.names = ids, check.names = FALSE)

A full violin per group

showViolinBoxplot = TRUE draws the violin (with a small boxplot inside); violinScale = "area" makes equal-area violins.

canvasXpress(
  data = y, smpAnnot = smpAnnot, graphType = "Boxplot",
  showViolinBoxplot = TRUE, violinScale = "area",
  groupingFactors = list("Dose"), xAxis = list("value"),
  smpTitle = "Dose", title = "Distribution of value by dose",
  width = 650, height = 500
)

A split (half) violin comparing two conditions

Group by both factors, colour by the condition, and set violinSide = "split" — the two conditions share each dose position, one on each half. This reads far better than two full violins side by side.

canvasXpress(
  data = y, smpAnnot = smpAnnot, graphType = "Boxplot",
  showViolinBoxplot = TRUE, violinScale = "area",
  groupingFactors = list("Dose", "Condition"), colorBy = "Condition",
  violinSide = "split", violinTrim = FALSE, xAxis = list("value"),
  smpTitle = "Dose", title = "Control vs Treated — split violin by dose",
  width = 650, height = 500
)

Hover to read the density and summary stats. violinSide can also be "lt" or "rb" for a one-sided half violin (handy for a raincloud when paired with violinPointsSide).

Why “reproducible”

The data+config is the figure — one portable JSON spec that renders the identical violins from Python or JavaScript, and can be validated and re-rendered later.

Next

• Interactive volcano plots in R
• Paired before/after boxplots in R
• Gallery: https://canvasxpress.org/examples.html

Install

install.packages(c("canvasXpress", "ggpubr"))

A paired dataset

Long format, two rows per subject — one per timepoint. Swap in your own repeated-measures table.

library(ggplot2)
library(ggpubr)

set.seed(7)
n  <- 25
df <- data.frame(
  id    = rep(paste0("P", seq_len(n)), 2),
  time  = rep(c("Baseline", "Week 12"), each = n),
  value = c(rnorm(n, 8, 1.2),                       # baseline
            rnorm(n, 8, 1.2) + rnorm(n, -1.2, 0.8)) # follow-up (a drop)
)

Build it with ggpaired, then wrap it

ggpaired draws the two boxes and the per-subject connecting lines; stat_compare_means adds a paired test. Then hand the whole thing to canvasXpress():

library(canvasXpress)

g <- ggpaired(
  df, x = "time", y = "value", id = "id",
  color = "time", line.color = "gray", line.size = 0.3
) +
  stat_compare_means(paired = TRUE, method = "t.test")

canvasXpress(g)

Each grey line is one subject moving from Baseline to Week 12, the boxes summarize each timepoint, and the paired t-test labels the comparison. It’s interactive — hover a line to follow a subject — and the figure is one portable spec you can reproduce from R, Python or JavaScript.

Why paired, not two independent boxes

A side-by-side boxplot hides who changed. The connecting lines make within-subject change visible: a treatment can lower the group median while a handful of subjects still rise — exactly the pattern you want to catch before drawing conclusions.

Next

• Use ggplot2 & ggpubr plots directly with canvasXpress
• Interactive volcano plots in R
• Gallery: https://canvasxpress.org/examples.html

Install

install.packages(c("canvasXpress", "ggpubr"))

Wrap a plot you already have

Here’s an ordinary ggpubr boxplot with pairwise comparisons (geom_pwc) — the significance brackets that show a test between each pair of groups. Build it exactly as you normally would:

library(ggplot2)
library(ggpubr)

g <- ggboxplot(iris, x = "Species", y = "Sepal.Width", fill = "Species") +
  geom_pwc(method = "t_test", label = "p.format")

Now make it interactive — one call, the same object:

library(canvasXpress)

canvasXpress(g)

That’s the whole idea: no re-specification. canvasXpress reads the ggplot object — its data, aesthetics, layers, scales and the geom_pwc brackets — and renders it. Hover the points, drag to zoom, or open the toolbar to filter and re-style, and the result serializes to one portable spec you can store and reproduce from R, Python or JavaScript.

What transfers

• Geoms and layers — points, boxes, lines, and stats like geom_pwc / stat_compare_means.
• Aesthetic mappings — x, y, fill, color, grouping.
• Scales, labels and facets from the ggplot object.

When to reach for the native API instead

Wrapping a ggplot is ideal for reusing plots you already have. When you’re building a figure fresh — or want fine control over CanvasXpress-specific features (clustering, dendrograms, interactive annotations) — call canvasXpress() on your data directly with a graphType. See the other posts for that style.

Next

• Paired before/after boxplots in R
• Interactive volcano plots in R
• Gallery: https://canvasxpress.org/examples.html

An expression matrix with sample metadata

Swap this simulated block for your own matrix (genes in rows, samples in columns) and a table of per-sample annotations — the output of any normalization/DE pipeline works.

library(canvasXpress)

set.seed(1)
ng    <- 40                       # genes (rows)
ns    <- 30                       # samples (columns)
genes <- paste0("Gene", seq_len(ng))
samps <- paste0("S", seq_len(ns))
cond  <- rep(c("Tumor", "Normal"), each = ns / 2)

# Two gene blocks, up in one condition each
m <- matrix(rnorm(ng * ns), ng, ns, dimnames = list(genes, samps))
m[ 1:20, cond == "Tumor"]  <- m[ 1:20, cond == "Tumor"]  + 2
m[21:40, cond == "Normal"] <- m[21:40, cond == "Normal"] + 2

canvasXpress takes the matrix as data and a sample annotation table (rows = samples) that becomes an annotation track over the columns.

smpAnnot <- data.frame(Condition = cond, row.names = samps, check.names = FALSE)

The plot

samplesClustered and variablesClustered turn on hierarchical clustering (with dendrograms) on columns and rows; colorSpectrum sets the diverging palette.

canvasXpress(
  data     = as.data.frame(m),
  smpAnnot = smpAnnot,
  graphType = "Heatmap",
  samplesClustered  = TRUE,
  variablesClustered = TRUE,
  colorSpectrum = list("navy", "white", "firebrick3"),
  showSmpDendrogram = TRUE,
  showVarDendrogram = TRUE,
  title = "Clustered expression heatmap",
  width  = 650,
  height = 550
)

The rows and columns are reordered by similarity, the dendrograms show the clustering, and the samples separate cleanly by condition. Hover a cell for its gene, sample and value; the whole figure is one portable spec you can store, validate and re-render.

Scaling up

The same call handles much larger matrices — hundreds of genes by dozens to hundreds of samples — clustering and rendering the full matrix interactively in the browser, not a static image. Point size and labels adapt automatically.

Next

• Interactive volcano plots in R
• Kaplan–Meier survival curves in R
• Gallery: https://canvasxpress.org/examples.html

A survival table

Swap this simulated block for your own data: you need, per subject, a follow-up time, a censoring indicator (1 = censored, 0 = event), and the grouping variable.

library(canvasXpress)

set.seed(1)
n    <- 200
arm  <- sample(c("Treatment", "Control"), n, replace = TRUE)
base <- ifelse(arm == "Treatment", 60, 40)      # treatment survives longer
time <- round(rexp(n, rate = 1 / base), 1)
cens <- rbinom(n, 1, 0.3)                        # 1 = censored, 0 = event
subj <- paste0("Subj", seq_len(n))

canvasXpress reads two columns for a Kaplan–Meier plot — the time and its matching censor flag — plus a per-subject annotation carrying the group.

y <- data.frame(
  "Time"        = time,
  "Time-Censor" = cens,
  row.names     = subj,
  check.names   = FALSE
)

varAnnot <- data.frame(Arm = arm, row.names = subj, check.names = FALSE)

The plot

The key is graphType = "KaplanMeier" and passing both columns to xAxis (time first, then the censor column). colorBy stratifies the curves.

canvasXpress(
  data     = y,
  varAnnot = varAnnot,
  graphType = "KaplanMeier",
  xAxis    = list("Time", "Time-Censor"),
  colorBy  = "Arm",
  title    = "Overall survival by treatment arm",
  xAxisTitle = "Time (weeks)",
  yAxisTitle = "Probability of survival",
  invertCensored = TRUE,     # draw censoring ticks
  showKMConfidenceIntervals = FALSE,
  width  = 650,
  height = 500
)

Hover any step for the time and survival probability; the tick marks are censored subjects. Because canvasXpress derives the survival curve from the raw table, you never precompute the steps — and the same spec re-renders the identical curve from Python or JavaScript.

A common gotcha

The survival transform only fires with graphType = "KaplanMeier". If you use a bare "Scatter2D" you’ll get a raw scatter of the censor values instead — survival probability is computed by the engine, it is not a column in your data.

Next

• Interactive volcano plots in R
• Gallery: https://canvasxpress.org/examples.html
• Package & issues: https://github.com/neuhausi/canvasXpress

Install

install.packages("canvasXpress")

A differential-expression table

For a self-contained example we simulate 1,000 genes. Swap this block for your own results table (e.g. the output of limma::topTable() or DESeq2::results()) — you need a log fold change and a significance value per gene.

library(canvasXpress)

set.seed(1)
n     <- 1000
genes <- paste0("Gene", seq_len(n))

# Simulate a realistic volcano: most genes have no real effect, a minority are
# differentially expressed. Significance follows effect size / standard error, which
# is what gives a volcano its shape.
de     <- runif(n) < 0.12                                   # ~12% truly changed
sgn    <- sample(c(-1, 1), n, replace = TRUE)
effect <- ifelse(de, sgn * (0.8 + 0.9 * runif(n)), 0)       # true log2FC
se     <- 0.22 + 0.5 * runif(n)                             # per-gene standard error
logFC  <- round(effect + rnorm(n, 0, se), 3)               # observed log2FC
pval   <- 2 * pnorm(-abs(logFC / se))                       # z-test p-value
negLogP <- round(pmin(-log10(pval), 16), 3)

# Classify each gene by effect size + significance
group <- ifelse(logFC >  1 & negLogP > 1.3, "Increased",
         ifelse(logFC < -1 & negLogP > 1.3, "Decreased", "NoChange"))

canvasXpress expects a numeric matrix/data frame of values (genes in rows) plus an optional variable annotation table carrying per-gene attributes — here the regulation call and the fold change we’ll use for point size.

y <- data.frame(
  "logFC"     = logFC,
  "-log-pVal" = negLogP,
  row.names   = genes,
  check.names = FALSE
)

varAnnot <- data.frame(
  Group = group,
  FC    = round(2^abs(logFC), 2),
  row.names   = genes,
  check.names = FALSE
)

The plot

canvasXpress(
  data     = y,
  varAnnot = varAnnot,
  graphType = "Scatter2D",
  xAxis    = list("logFC"),
  yAxis    = list("-log-pVal"),
  colorBy  = "Group",
  colorKey = list(Group = list(
    Increased = "rgba(197,27,38,0.75)",
    Decreased = "rgba(33,102,172,0.75)",
    NoChange  = "rgba(150,150,150,0.35)"
  )),
  sizeBy   = "FC",
  sizes    = c(3, 6, 9, 12, 15),
  title    = "Publication-ready volcano plot",
  xAxisTitle = "log2 fold change",
  yAxisTitle = "-log10 p-value",
  showDecorations = TRUE,
  decorations = list(line = list(
    list(color = "rgba(120,120,120,0.8)", width = 1, x =  1),
    list(color = "rgba(120,120,120,0.8)", width = 1, x = -1),
    list(color = "rgba(120,120,120,0.8)", width = 1, y = 1.301)
  )),
  width  = 650,
  height = 500
)

The chart is interactive: hover a point for its gene and values, drag to zoom, or use the toolbar to filter by regulation group. The dashed guides mark the ±1 log2FC and the p = 0.05 cutoffs.

Why “reproducible”

Everything above serializes to one JSON specification — the data and the config. That spec is portable: the identical figure renders from the Python (canvasxpress) and JavaScript packages, and it can be validated against a published schema and re-rendered later, so a figure in a paper can be regenerated and audited rather than just looked at.

Where to go next

• Gallery of examples: https://canvasxpress.org/examples.html
• From your object (survival tables, expression matrices, single-cell): https://canvasxpress.org/migrate.html
• Package & issues: https://github.com/neuhausi/canvasXpress