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.

Load the library

<link href="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@73.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@73.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.min.js"></script>

The markup and the spec

Nodes carry id, name, group; edges carry id1, id2, value. colorNodeBy colours by community and networkLayoutType: "forceDirected" runs the physics.

<canvas id="network" width="650" height="500"></canvas>
<script>
  var groups = ["Alpha", "Beta", "Gamma"], nodes = [], byGroup = {}, k = 0;
  groups.forEach(function (g) {
    byGroup[g] = [];
    for (var i = 0; i < 7; i++) {
      var nid = "n" + k; nodes.push({ id: nid, name: g + (i + 1), group: g });
      byGroup[g].push(nid); k++;
    }
  });

  var edges = [];
  groups.forEach(function (g) {                         // dense within a community
    var m = byGroup[g];
    for (var i = 0; i < m.length; i++)
      for (var j = i + 1; j < m.length; j++)
        if (Math.random() < 0.5)
          edges.push({ id1: m[i], id2: m[j], value: 1 + Math.floor(Math.random() * 5) });
  });
  for (var e = 0; e < 6; e++) {                         // a few cross-community links
    var pair = groups.slice().sort(function () { return Math.random() - 0.5; }).slice(0, 2);
    var a = byGroup[pair[0]], b = byGroup[pair[1]];
    edges.push({ id1: a[Math.floor(Math.random() * a.length)],
                 id2: b[Math.floor(Math.random() * b.length)], value: 1 });
  }

  var config = {
    graphType: "Network",
    networkLayoutType: "forceDirected",
    colorNodeBy: "group",
    nodeSize: 25,
    showAnimation: true,
    title: "A small community network"
  };

  new CanvasXpress("network", { nodes: nodes, edges: edges }, config);
</script>

Live result

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 JSON spec that renders the same from R, Python, or a web page.

Next

• Sankey / alluvial diagrams in JavaScript
• Gallery: https://canvasxpress.org/examples.html
• Source & npm: https://github.com/neuhausi/canvasXpress

Load the library

<link href="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@73.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@73.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.min.js"></script>

The markup and the spec

Four tracks that share one coordinate axis: gene models (box, multi-exon, connected), coverage across three tissues (bar), an expression heatmap (heatmap), and variant markers (triangle).

<canvas id="genome" width="760" height="520"></canvas>
<script>
  // Gene models: each gene is a set of exon [start, end] intervals, drawn connected.
  var genes = [];
  for (var j = 0; j < 4; j++) {
    var start = 40 + j * 120, nex = 2 + Math.floor(Math.random() * 3), exons = [];
    for (var k = 0; k < nex; k++) exons.push([start + k * 30, start + k * 30 + 18]);
    genes.push({ id: "GENE" + (j + 1), dir: j % 2 === 0 ? "right" : "left",
                 fill: "rgb(70,130,220)", outline: "rgb(0,0,0)", data: exons });
  }

  // Coverage and expression: one entry per binned position, three tissues each.
  var coverage = [], express = [], rnd = function (a, b) { return a + Math.floor(Math.random() * (b - a + 1)); };
  for (var i = 0; i < 22; i++) {
    var o = 50 + i * 22;
    coverage.push({ id: "p" + i, offset: o, data: [rnd(8, 45), rnd(8, 45), rnd(8, 45)] });
    express.push({ id: "p" + i, offset: o,
                   data: [Math.round(Math.random() * 4 - 2), Math.round(Math.random() * 4 - 2),
                          Math.round(Math.random() * 4 - 2)] });
  }

  // Variants: point markers at genomic positions.
  var snps = [];
  for (var s = 0; s < 9; s++)
    snps.push({ id: "rs" + (1000 + s), offset: rnd(45, 520), fill: "rgb(200,40,40)", outline: "rgb(0,0,0)" });

  var data = { tracks: [
    { name: "Genes (exon models)", type: "box", connect: true, data: genes },
    { name: "Coverage — Heart / Liver / Kidney", type: "bar", height: 120,
      fill: "rgb(80,80,200)", outline: "rgb(60,60,60)", data: coverage },
    { name: "Expression (z-score)", type: "heatmap", height: 90, data: express },
    { name: "SNPs", type: "triangle", data: snps }
  ]};

  var config = { graphType: "Genome", background: "rgb(245,245,245)", featureStaggered: true,
                 title: "Multi-track genome browser: genes, coverage, expression and variants" };

  new CanvasXpress("genome", data, config);
</script>

Live result

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 JSON spec that renders the same from R, Python, or a web page.

Next

• Interactive network graphs in JavaScript
• Gallery: https://canvasxpress.org/examples.html
• Source & npm: https://github.com/neuhausi/canvasXpress

Load the library and the data

The 96-sample QC table is published next to this post as a small JS object, qc-data.js — QC_DATA is a sample-centric CanvasXpress data object (each sample is a point; z holds its lane/batch/library).

<link href="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@73.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@73.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.min.js"></script>
<script src="qc-data.js"></script>

The panels

The overview heatmap transposes the data to metrics × samples and z-scores each metric. The four triage panels read QC_DATA directly and all share broadcastGroup: "qc" — select points in one and the same samples re-mark in the rest.

<canvas id="qcHeat" width="820" height="420"></canvas>
<canvas id="qcMap" width="640" height="360"></canvas>
<canvas id="qcContam" width="640" height="360"></canvas>
<canvas id="qcQ30" width="640" height="360"></canvas>
<canvas id="qcReads" width="820" height="300"></canvas>
<script>
  var metrics = QC_DATA.y.smps, samples = QC_DATA.y.vars, rows = QC_DATA.y.data;

  // Overview: transpose to metrics x samples and z-score each metric.
  var hmData = metrics.map(function (_, c) {
    var col = rows.map(function (r) { return r[c]; });
    var mean = col.reduce(function (a, b) { return a + b; }, 0) / col.length;
    var sd = Math.sqrt(col.reduce(function (a, b) { return a + (b - mean) * (b - mean); }, 0) / col.length) || 1;
    return col.map(function (v) { return Math.round((v - mean) / sd * 100) / 100; });
  });
  new CanvasXpress("qcHeat",
    { y: { vars: metrics, smps: samples, data: hmData },
      x: { Batch: QC_DATA.z.Batch, Library: QC_DATA.z.Library } },
    { graphType: "Heatmap", samplesClustered: true, variablesClustered: true,
      colorSpectrum: ["navy", "white", "firebrick3"],
      title: "QC metrics (z-scored) — 96 samples clustered" });

  // Linked triage panels (same QC_DATA, shared broadcast group).
  function panel(id, cfg) {
    new CanvasXpress(id, QC_DATA, Object.assign({ broadcast: true, broadcastGroup: "qc" }, cfg));
  }
  panel("qcMap", { graphType: "Scatter2D", xAxis: ["pct_duplication"], yAxis: ["pct_mapped"],
    colorBy: "Batch", sizeBy: "total_reads", title: "Mapping rate vs duplication — select bottom-right" });
  panel("qcContam", { graphType: "Scatter2D", xAxis: ["pct_mapped"], yAxis: ["contamination_freemix"],
    colorBy: "Batch", title: "Contamination (freemix) vs mapping rate" });
  panel("qcQ30", { graphType: "Scatter2D", xAxis: ["gc_content"], yAxis: ["pct_q30"],
    colorBy: "Library", title: "Q30 vs GC content, coloured by library" });
  panel("qcReads", { graphType: "Bar", graphOrientation: "vertical", xAxis: ["total_reads"],
    colorBy: "Batch", title: "Total reads per sample (flag the short ones)" });
</script>

Live result

Drag a selection box across the bad cluster in the mapping-vs-duplication panel — the other panels restrict to the same samples so you can read their contamination, library and depth.

The cross-filter is one shared broadcastGroup — no framework, no event wiring. Each panel stays a portable data + config spec.

Why “reproducible”

The same specs reproduce the dashboard from R, Python, or a web page, against the same QC table.

Next

• Interactive network graphs in JavaScript
• Gallery: https://canvasxpress.org/examples.html
• Source & npm: https://github.com/neuhausi/canvasXpress

Install

pip install canvasxpress

The data shape

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

import random
random.seed(1)

groups = ["Alpha", "Beta", "Gamma"]
nodes, by_group = [], {g: [] for g in groups}
k = 0
for g in groups:
    for i in range(7):
        nid = f"n{k}"; nodes.append({"id": nid, "name": f"{g}{i+1}", "group": g})
        by_group[g].append(nid); k += 1

edges = []
for g in groups:                                   # dense within a community
    m = by_group[g]
    for i in range(len(m)):
        for j in range(i + 1, len(m)):
            if random.random() < 0.5:
                edges.append({"id1": m[i], "id2": m[j], "value": random.randint(1, 5)})
for _ in range(6):                                 # a few cross-community links
    g1, g2 = random.sample(groups, 2)
    edges.append({"id1": random.choice(by_group[g1]), "id2": random.choice(by_group[g2]), "value": 1})

The plot

from canvasxpress.canvas import CanvasXpress
from canvasxpress.render.jupyter import CXNoteBook
from IPython.display import display

data = {"nodes": nodes, "edges": edges}
config = {
    "graphType": "Network",
    "networkLayoutType": "forceDirected",
    "colorNodeBy": "group",
    "nodeSize": 25,
    "showAnimation": True,
    "title": "A small community network",
}

cx = CanvasXpress(render_to="network", data=data, config=config, width=650, height=500)
for part in CXNoteBook(cx).render():
    display(part)

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 JSON spec that renders the identical network from R or JavaScript, and can be validated and re-rendered later.

Next

• Sankey / alluvial diagrams in Python
• Gallery: https://canvasxpress.org/examples.html
• Package: https://pypi.org/project/canvasxpress/

Install

pip install 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.)

import csv, statistics as st

rows = list(csv.DictReader(open("ngs-qc.csv")))
metrics = ["total_reads", "pct_mapped", "pct_duplication", "pct_q30",
           "gc_content", "insert_size", "contamination_freemix"]

samples = [r["sample"] for r in rows]
annot   = {"Lane": [r["lane"] for r in rows], "Batch": [r["batch"] for r in rows],
           "Library": [r["library"] for r in rows]}
raw = {m: [float(r[m]) for r in rows] for m in metrics}
print(len(samples), "samples,", len(metrics), "metrics")

96 samples, 7 metrics

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. Here the matrix is metrics × samples.

from canvasxpress.canvas import CanvasXpress
from canvasxpress.render.jupyter import CXNoteBook
from IPython.display import display

z = {m: [(v - st.mean(raw[m])) / (st.pstdev(raw[m]) or 1) for v in raw[m]] for m in metrics}
hm = {"y": {"vars": metrics, "smps": samples, "data": [[round(x, 2) for x in z[m]] for m in metrics]},
      "x": {"Batch": annot["Batch"], "Library": annot["Library"]}}

cx = CanvasXpress(render_to="qcHeat", data=hm, width=820, height=420, config={
    "graphType": "Heatmap", "samplesClustered": True, "variablesClustered": True,
    "colorSpectrum": ["navy", "white", "firebrick3"],
    "title": "QC metrics (z-scored) — 96 samples clustered"})
for part in CXNoteBook(cx).render():
    display(part)

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 and its lane/batch/library live in the per-sample annotation z. Select points in any panel and the same samples re-mark everywhere.

# Sample-centric: vars = samples (points), smps = metrics (axes), z = per-sample annotations.
data = {"y": {"vars": samples, "smps": metrics, "data": [[raw[m][i] for m in metrics] for i in range(len(samples))]},
        "z": annot}

def panel(cfg, cid, w=640, h=360):
    cfg = {**cfg, "broadcast": True, "broadcastGroup": "qc"}
    cx = CanvasXpress(render_to=cid, data=data, config=cfg, width=w, height=h)
    for part in CXNoteBook(cx).render():
        display(part)

panel({"graphType": "Scatter2D", "xAxis": ["pct_duplication"], "yAxis": ["pct_mapped"],
       "colorBy": "Batch", "sizeBy": "total_reads",
       "title": "Mapping rate vs duplication — select the bottom-right"}, "qcMap")

panel({"graphType": "Scatter2D", "xAxis": ["pct_mapped"], "yAxis": ["contamination_freemix"],
       "colorBy": "Batch", "title": "Contamination (freemix) vs mapping rate"}, "qcContam")

panel({"graphType": "Scatter2D", "xAxis": ["gc_content"], "yAxis": ["pct_q30"],
       "colorBy": "Library", "title": "Q30 vs GC content, coloured by library"}, "qcQ30")

panel({"graphType": "Bar", "graphOrientation": "vertical", "xAxis": ["total_reads"],
       "colorBy": "Batch", "title": "Total reads per sample (flag the short ones)"}, "qcReads", w=820, h=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 R or JavaScript, against the same ngs-qc.csv.

Next

• Interactive network graphs in Python
• Gallery: https://canvasxpress.org/examples.html
• Package: https://pypi.org/project/canvasxpress/

Install

pip install 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).

import random
random.seed(3)

# Gene models: each gene is a set of exon [start, end] intervals, drawn connected.
genes = []
for j in range(4):
    start = 40 + j * 120
    exons = [[start + k * 30, start + k * 30 + 18] for k in range(random.randint(2, 4))]
    genes.append({"id": f"GENE{j+1}", "dir": "right" if j % 2 == 0 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 + i * 22 for i in range(22)]
coverage = [{"id": f"p{i}", "offset": o,
             "data": [random.randint(8, 45), random.randint(8, 45), random.randint(8, 45)]}
            for i, o in enumerate(offsets)]
express  = [{"id": f"p{i}", "offset": o,
             "data": [round(random.gauss(0, 1), 2) for _ in range(3)]}
            for i, o in enumerate(offsets)]

# Variants: point markers at genomic positions.
snps = [{"id": f"rs{1000+k}", "offset": random.randint(45, 520),
         "fill": "rgb(200,40,40)", "outline": "rgb(0,0,0)"} for k in range(9)]

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

The plot

from canvasxpress.canvas import CanvasXpress
from canvasxpress.render.jupyter import CXNoteBook
from IPython.display import display

config = {
    "graphType": "Genome",
    "background": "rgb(245,245,245)",
    "featureStaggered": True,
    "title": "Multi-track genome browser: genes, coverage, expression and variants",
}

cx = CanvasXpress(render_to="genome", data=data, config=config, width=760, height=520)
for part in CXNoteBook(cx).render():
    display(part)

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 JSON spec that renders the identical browser view from R or JavaScript, and can be validated and re-rendered later.

Next

• Interactive network graphs in Python
• Gallery: https://canvasxpress.org/examples.html
• Package: https://pypi.org/project/canvasxpress/

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

Load the library

<link href="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@73.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@73.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.min.js"></script>

The markup and the spec

The base matrix is data; same-shaped data2 (copy number) and data3 (mutation) are the overlays, each cell a string like "Amplification", "Missense", or "".

<canvas id="onco" width="820" height="440"></canvas>
<script>
  var genes = ["TP53","KRAS","PIK3CA","PTEN","EGFR","BRAF","APC","RB1","NF1","MYC","CDKN2A","ARID1A"],
      samples = [], CNA = ["Amplification","Deletion"], MUT = ["Missense","Nonsense","Truncating"];
  for (var i = 0; i < 28; i++) samples.push("T" + (i + 1 < 10 ? "0" : "") + (i + 1));
  function pick(a) { return a[Math.floor(Math.random() * a.length)]; }

  var base = [], cna = [], mut = [];
  genes.forEach(function (g, gi) {
    var rate = Math.max(0.05, 0.5 * (1 - gi / genes.length)), b = [], c = [], m = [];
    samples.forEach(function () {
      b.push(Math.round((Math.random() * 4 - 2) * 100) / 100);
      c.push(Math.random() < rate * 0.5 ? pick(CNA) : "");
      m.push(Math.random() < rate ? pick(MUT) : "");
    });
    base.push(b); cna.push(c); mut.push(m);
  });

  var data = { y: { vars: genes, smps: samples, data: base, data2: cna, data3: mut } };
  var config = { graphType: "Heatmap", oncoprintCNA: "data2", oncoprintMUT: "data3",
                 overlaysThickness: 100, xAxis: samples,
                 title: "Mutation landscape: 12 genes across 28 tumours" };

  new CanvasXpress("onco", data, config);
</script>

Live result

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 JSON spec that renders the same from R, Python, or a web page.

Next

• A clustered heatmap in JavaScript
• Gallery: https://canvasxpress.org/examples.html
• Source & npm: https://github.com/neuhausi/canvasXpress

Install

pip install 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.

import random
random.seed(5)

genes = ["TP53", "KRAS", "PIK3CA", "PTEN", "EGFR", "BRAF",
         "APC", "RB1", "NF1", "MYC", "CDKN2A", "ARID1A"]
samples = [f"T{i+1:02d}" for i in range(28)]
mutrate = {g: max(0.05, 0.5 * (1 - i / len(genes))) for i, g in enumerate(genes)}

CNA = ["Amplification", "Deletion"]; MUT = ["Missense", "Nonsense", "Truncating"]
base, cna, mut = [], [], []
for g in genes:
    base.append([round(random.gauss(0, 1), 2) for _ in samples])
    cna.append([random.choice(CNA) if random.random() < mutrate[g] * 0.5 else "" for _ in samples])
    mut.append([random.choice(MUT) if random.random() < mutrate[g] else "" for _ in samples])

subtype = [random.choice(["Basal", "Luminal", "HER2"]) for _ in samples]
pathway = [("TSG", "Oncogene")[i % 2] for i in range(len(genes))]

The plot

The overlays go in the y object alongside the base data; oncoprintCNA / oncoprintMUT name them, and xAxis lists the samples.

from canvasxpress.canvas import CanvasXpress
from canvasxpress.render.jupyter import CXNoteBook
from IPython.display import display

data = {"y": {"vars": genes, "smps": samples, "data": base, "data2": cna, "data3": mut},
        "x": {"Subtype": subtype}, "z": {"Pathway": pathway}}
config = {"graphType": "Heatmap", "oncoprintCNA": "data2", "oncoprintMUT": "data3",
          "overlaysThickness": 100, "xAxis": samples,
          "title": "Mutation landscape: 12 genes across 28 tumours"}

cx = CanvasXpress(render_to="onco", data=data, config=config, width=820, height=440)
for part in CXNoteBook(cx).render():
    display(part)

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 JSON spec that renders the identical oncoprint from R or JavaScript, and can be validated and re-rendered later.

Next

• A clustered heatmap in Python
• Gallery: https://canvasxpress.org/examples.html
• Package: https://pypi.org/project/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

Load the library

<link href="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@73.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@73.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.min.js"></script>

The markup and the spec

Rows are the tracks you draw, columns are the positions around the ring; Region segments the ring, and circularConnections is a list of [colour, from, to] ribbons.

<canvas id="circ" width="560" height="560"></canvas>
<script>
  var segments = [], tracks = ["Expression", "Methylation", "CopyNumber", "Density"],
      cols = ["rgb(220,40,40)", "rgb(40,120,220)", "rgb(40,160,60)", "rgb(240,150,20)"];
  for (var i = 0; i < 80; i++) segments.push("s" + (i + 1));
  function pick(a) { return a[Math.floor(Math.random() * a.length)]; }

  var data_m = tracks.map(function () {
    return segments.map(function () { return Math.round((Math.random() * 4 - 2) * 100) / 100; });
  });
  var region = segments.map(function (_, i) { return "chr" + (Math.floor(i / 20) + 1); });
  var conns = [];
  for (var c = 0; c < 18; c++) conns.push([pick(cols), pick(segments), pick(segments)]);

  var data = { y: { vars: tracks, smps: segments, data: data_m }, x: { Region: region } };
  var config = {
    graphType: "Circular",
    circularConnections: conns,
    circularTrackGraphType: ["bar", "heatmap", "line", "dot"],
    circularTrackGraphWeight: [30, 20, 25, 25],
    circularTrackName: [1, 2, 3, 4],
    segregateSamplesBy: ["Region"],
    title: "Circos-style multi-track plot with connections"
  };

  new CanvasXpress("circ", data, config);
</script>

Live result

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 JSON spec that renders the same from R, Python, or a web page.

Next

• Genome browser tracks in JavaScript
• Gallery: https://canvasxpress.org/examples.html
• Source & npm: https://github.com/neuhausi/canvasXpress

Install

pip install 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.

import random
random.seed(8)

segments = [f"s{i+1}" for i in range(80)]
tracks   = ["Expression", "Methylation", "CopyNumber", "Density"]
data_m   = [[round(random.gauss(0, 1), 2) for _ in segments] for _ in tracks]

region = [f"chr{i//20 + 1}" for i in range(80)]
cols   = ["rgb(220,40,40)", "rgb(40,120,220)", "rgb(40,160,60)", "rgb(240,150,20)"]
conns  = [[random.choice(cols), random.choice(segments), random.choice(segments)] for _ in range(18)]

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.

from canvasxpress.canvas import CanvasXpress
from canvasxpress.render.jupyter import CXNoteBook
from IPython.display import display

data = {"y": {"vars": tracks, "smps": segments, "data": data_m}, "x": {"Region": region}}
config = {
    "graphType": "Circular",
    "circularConnections": conns,
    "circularTrackGraphType": ["bar", "heatmap", "line", "dot"],
    "circularTrackGraphWeight": [30, 20, 25, 25],
    "circularTrackName": [1, 2, 3, 4],
    "segregateSamplesBy": ["Region"],
    "title": "Circos-style multi-track plot with connections",
}

cx = CanvasXpress(render_to="circ", data=data, config=config, width=560, height=560)
for part in CXNoteBook(cx).render():
    display(part)

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 JSON spec that renders the identical circular plot from R or JavaScript, and can be validated and re-rendered later.

Next

• Genome browser tracks in Python
• Gallery: https://canvasxpress.org/examples.html
• Package: https://pypi.org/project/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 regions 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 (per capita, per 100k); reserve raw counts for a proportional-symbol map, where a sized bubble carries the count honestly.

Load the library

<link href="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@71.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@71.3.0/inst/htmlwidgets/lib/canvasXpress/canvasXpress.min.js"></script>

The markup and the spec

The columns (smps) are the regions — they match the map by name — and the single row (vars) is the variable you colour by: CO₂ emissions per country for 2018. We fetch a prepared table and a small annotation table (continent, ISO code), parse the tab-separated text, and hand the matrix to CanvasXpress. The two choices that make this map work are in the colour scale: a seven-stop viridis colorSpectrum, and colorSpectrumBreaksMethod: "quantile", which puts an equal number of countries in every colour class — on skewed data that guarantee is what keeps all seven colours on the map.

<canvas id="co2quant" width="760" height="520"></canvas>
<script>
  var DATA = "https://www.canvasxpress.org/data/r/cX-CO2-dat.txt";
  var SMP  = "https://www.canvasxpress.org/data/r/cX-CO2-smp.txt";

  // split a tab-separated file into a list of cell-arrays (one per row)
  function rows(text) {
    return text.trim().split("\n").map(function (line) { return line.split("\t"); });
  }

  Promise.all([fetch(DATA).then(function (r) { return r.text(); }),
               fetch(SMP ).then(function (r) { return r.text(); })])
    .then(function (texts) {
      var d = rows(texts[0]);                      // [header, ["CO2", v1, v2, ...]]
      var countries = d[0].slice(1);               // header, minus the empty corner cell
      var values    = d[1].slice(1).map(Number);   // the CO2 values

      var s = rows(texts[1]);                       // header + one row per country
      var col = {};                                 // header name -> column index
      s[0].forEach(function (name, i) { col[name] = i; });
      var byCountry = {};
      s.slice(1).forEach(function (r) { byCountry[r[0]] = r; });
      var continent = countries.map(function (c) { return byCountry[c][col["Continent"] + 1]; });

      var data = {
        y: { vars: ["CO2"], smps: countries, data: [values] },
        x: { Continent: continent }
      };
      var config = {
        graphType: "Map",
        colorBy: "CO2",
        topoJSON: "https://www.canvasxpress.org/data/maps/WORLD.json",
        mapId: "co2Quantile",
        colorSpectrum: ["#440154", "#443983", "#31688e", "#21918c",
                        "#35b779", "#90d743", "#fde725"],
        colorSpectrumBreaksMethod: "quantile",
        mapColor: "#d9dde3",
        mapOutlineColor: "#ffffff",
        legendPosition: "bottom",
        title: "CO2 emissions per country (2018)",
        subtitle: "Seven quantile classes: each colour holds about 28 of 198 countries"
      };
      new CanvasXpress("co2quant", data, config);
    });
</script>

Live result

Every band of the ramp is doing work: the darkest purples are the smallest emitters, the yellows the largest, and the legend’s break values tell you the class edges are data-driven, not evenly spaced. Hover any country for its name, continent and value.

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. See for yourself — same data, default scale:

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 the scale’s grammar, not decoration:

• 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. Use a three-colour colorSpectrum and pin the midpoint:

  colorBy: "Change",
  colorSpectrum: ["#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” the data does not have. Viridis and the ColorBrewer ramps are colour-blind-safe and perceptually ordered; a rainbow ramp is neither. Keep the same scale across small multiples so maps stay comparable.

Beyond the world map

• Other boundaries. Point topoJSON at any shape file — US states, a country’s provinces, counties, custom districts. The join key is just the shape name.
• Projection. mapProjection: "albers" (equal-area) or "mercator". Equal-area projections matter for choropleths: Mercator inflates high latitudes and exaggerates their visual weight.
• Categorical maps. Point colorBy at a categorical field for a qualitative choropleth with a discrete legend.
• Polish. legendNumberFormat formats the ticks, legendInside floats the legend over ocean, showMapLabels draws region names (best on few-region maps), mapColor sets the no-data fill so missing reads as missing, and decorations drops labelled markers on cities.

The whole figure — data, boundaries, classing rule and palette — is one portable spec you can re-render from R or Python.

Next

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

Install

pip install canvasxpress pandas

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 regions 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 (smps) are the regions — they match the map by name — and each row (vars) is a variable you can colour by. Here it’s CO₂ emissions per country for 2018. We load a prepared table; swap it for your own (any country → value table works).

import pandas as pd

dat = pd.read_csv(
    "https://www.canvasxpress.org/data/r/cX-CO2-dat.txt",
    sep="\t", index_col=0,
)
smp = pd.read_csv(
    "https://www.canvasxpress.org/data/r/cX-CO2-smp.txt",
    sep="\t", index_col=0,
).reindex(dat.columns)        # align annotation to the country order

print(dat.shape)              # (1, N): one row (CO2) x N countries
dat.iloc[:, :4]

(1, 198)

The map: quantile classes on a viridis ramp

y carries the matrix (vars = the variable, smps = the countries, data = the values); the optional x block adds per-country annotations (continent, ISO code) for richer tooltips. The two choices that make this map work are in the colour scale: a seven-stop viridis colorSpectrum, and colorSpectrumBreaksMethod = "quantile", which puts an equal number of countries in every colour class. On skewed data that guarantee is what keeps all seven colours on the map.

from canvasxpress.canvas import CanvasXpress
from canvasxpress.render.jupyter import CXNoteBook
from IPython.display import display

data = {
    "y": {
        "vars": list(dat.index),            # ["CO2"]
        "smps": list(dat.columns),          # country names
        "data": dat.values.tolist(),        # [[values]]
    },
    "x": {
        "Continent": smp["Continent"].tolist(),
        "Code":      smp["Code"].tolist(),
    },
}

config = {
    "graphType": "Map",
    "colorBy":   "CO2",
    "topoJSON":  "https://www.canvasxpress.org/data/maps/WORLD.json",
    "mapId":     "co2Quantile",
    "colorSpectrum": ["#440154", "#443983", "#31688e", "#21918c",
                      "#35b779", "#90d743", "#fde725"],
    "colorSpectrumBreaksMethod": "quantile",
    "mapColor":        "#d9dde3",
    "mapOutlineColor": "#ffffff",
    "legendPosition":  "bottom",
    "title":    "CO2 emissions per country (2018)",
    "subtitle": "Seven quantile classes: each colour holds about 28 of 198 countries",
}

cx = CanvasXpress(render_to="co2quant", data=data, config=config, width=760, height=520)
for part in CXNoteBook(cx).render():
    display(part)

Every band of the ramp is doing work: the darkest purples are the smallest emitters, the yellows the largest, and the legend’s break values tell you the class edges are data-driven, not evenly spaced. Hover any country for its name, continent and value.

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:

linear = {
    "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",
}

cx = CanvasXpress(render_to="co2lin", data=data, config=linear, width=700, height=480)
for part in CXNoteBook(cx).render():
    display(part)

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 the scale’s grammar, not decoration:

• 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 a three-colour colorSpectrum and pin the midpoint with colorSpectrumZeroValue:

  "colorBy": "Change",
  "colorSpectrum": ["#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” 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 units and provenance.
• "legendNumberFormat": {"style": "decimal", "decimals": 1, "suffix": "%"} — format legend ticks.
• mapColor / mapOutlineColor — the fill for no-data regions (a neutral grey) and the shape borders, so missing data reads as missing rather than as a value.
• "showMapLabels": True — draw region names (best on few-region maps; clutters a 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 country’s provinces, counties, custom districts. The join key is just the shape name.
• Projection. "mapProjection": "albers" (equal-area) or "mercator". Equal-area projections matter for choropleths: Mercator inflates high latitudes and exaggerates their visual weight.
• Categorical maps. Point colorBy at a categorical column 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 — is one portable spec you can store, validate and re-render from R or JavaScript.

Next

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

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

Load the library

<link href="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@69.6.1/inst/htmlwidgets/lib/canvasXpress/canvasXpress.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/gh/neuhausi/canvasXpress@69.6.1/inst/htmlwidgets/lib/canvasXpress/canvasXpress.min.js"></script>

The markup and the spec

Each row is one path through the stages; the value (Freq) is the single variable, and the stages are sample annotations (x). sankeyAxes lists the stages in order.

<canvas id="sankey" width="700" height="500"></canvas>
<script>
  var cohorts = ["Cohort A", "Cohort B"],
      treats  = ["Drug 1", "Drug 2", "Placebo"],
      outcomes = ["Response", "Stable", "Progression"];

  var Cohort = [], Treatment = [], Outcome = [], Freq = [];
  cohorts.forEach(function (co) {
    treats.forEach(function (tr) {
      outcomes.forEach(function (ou) {
        var base = ou === "Response" ? 40 : ou === "Stable" ? 25 : 15;
        if (tr === "Placebo" && ou === "Response") base = 12;   // placebo responds less
        Cohort.push(co); Treatment.push(tr); Outcome.push(ou);
        Freq.push(base + Math.floor(Math.random() * 16));
      });
    });
  });

  var ids = Freq.map(function (_, i) { return "r" + (i + 1); });

  var data = {
    y: { vars: ["Freq"], smps: ids, data: [Freq] },
    x: { Cohort: Cohort, Treatment: Treatment, Outcome: Outcome }
  };

  var config = {
    graphType: "Sankey",
    sankeyAxes: ["Cohort", "Treatment", "Outcome"],
    xAxis: ["Freq"],
    colorBy: "Outcome",
    sankeyType: "proportional",
    graphOrientation: "horizontal",
    title: "Patient flow: cohort to treatment to outcome"
  };

  new CanvasXpress("sankey", data, config);
</script>

Live result

Hover any stream to see the count; the widths are proportional to the frequency. sankeyType can also be "aligned" (classic alluvial) or "equal".

Why “reproducible”

The data+config is the figure — one portable JSON spec that renders the same from R, Python, or a web page.

Next

• Interactive volcano plots in JavaScript
• Gallery: https://canvasxpress.org/examples.html
• Source & npm: https://github.com/neuhausi/canvasXpress