Package 'CanvasXpressBio'

Paired boxplot with per-subject connections using CanvasXpress

Description

Draws a grouped boxplot of one measurement across conditions, overlaying the individual points and drawing a line between the repeated measurements of each subject. The measurement is one feature (row) of a [SummarizedExperiment::SummarizedExperiment] assay, and the grouping, faceting, connecting and colouring are taken from its 'colData'.

Usage

cxboxplot(
  object,
  feature,
  group,
  segregate = NULL,
  connect = NULL,
  color = NULL,
  points = c("all", "sina", "jitter", "none"),
  assay = 1L,
  ...
)

Arguments

object	A 'SummarizedExperiment'.
feature	The assay feature (row name) whose values are plotted.
group	'colData' column that defines the box groups along the x-axis (for example a time point).
segregate	Optional 'colData' column that splits the plot into panels (for example a cohort).
connect	Optional 'colData' column identifying the subject, so repeated measurements are joined by a line.
color	Optional 'colData' column used to colour the points and connecting lines.
points	How the individual observations are drawn over the boxes: '"all"' (the default) places every point, '"sina"' packs them into a beeswarm that stays legible with many points, '"jitter"' spreads them randomly, and '"none"' draws boxes only. The beeswarm and jitter layouts scale to hundreds or thousands of points without overplotting.
assay	Assay to read, given as a name or index. Defaults to the first.
...	Additional CanvasXpress configuration passed to [canvasXpress::canvasXpress()].

Value

A 'canvasXpress' htmlwidget.

Examples

se <- SummarizedExperiment::SummarizedExperiment(
    assays  = list(expr = matrix(rnorm(8), nrow = 1,
                   dimnames = list("IL6", paste0("s", 1:8)))),
    colData = data.frame(
        Subject   = rep(paste0("P", 1:4), each = 2),
        Condition = rep(c("Baseline", "Week 12"), 4),
        row.names = paste0("s", 1:8)))
cxboxplot(se, feature = "IL6", group = "Condition", connect = "Subject")

---

Visualize a Bioconductor object with CanvasXpress

Description

Renders a Bioconductor data object as an interactive CanvasXpress chart. The assay matrix becomes the chart data, with 'colData' supplied as sample (column) annotations and 'rowData' as variable (row) annotations, so the annotations are available for interactive grouping, coloring and sorting.

Usage

cxplot(object, ...)

## S4 method for signature 'SummarizedExperiment'
cxplot(
  object,
  assay = 1L,
  graphType = "Heatmap",
  n = NULL,
  overlays = NULL,
  var_overlays = NULL,
  cluster = FALSE,
  ...
)

Arguments

object	A Bioconductor data object. Currently a [SummarizedExperiment::SummarizedExperiment] or any class extending it (e.g. 'SingleCellExperiment', 'DESeqDataSet').
...	Additional CanvasXpress configuration passed through to [canvasXpress::canvasXpress()] (for example 'title' or 'colorScheme').
assay	Assay to plot, given as a name or an index. Defaults to the first assay.
graphType	CanvasXpress graph type. Defaults to '"Heatmap"'.
n	Optional integer. When supplied, only the 'n' most variable features (rows) are kept before plotting — a common convenience for large genomics matrices. Defaults to 'NULL', which keeps all features.
overlays	Sample ('colData') annotations to draw as overlay tracks beside the heatmap. 'TRUE' shows every 'colData' column; a character vector names specific ones; 'NULL' (the default) shows none.
var_overlays	Feature ('rowData') annotations to draw as overlay tracks, accepting the same values as 'overlays'.
cluster	Logical; when 'TRUE' both samples and features are hierarchically clustered (adding dendrograms). Defaults to 'FALSE'.

Value

A 'canvasXpress' htmlwidget.

Examples

se <- SummarizedExperiment::SummarizedExperiment(
    assays  = list(counts = matrix(rnorm(20), nrow = 5,
                   dimnames = list(paste0("g", 1:5), paste0("s", 1:4)))),
    colData = data.frame(group = rep(c("A", "B"), 2),
                         row.names = paste0("s", 1:4)))
cxplot(se, title = "Example heatmap")

---

Kaplan-Meier survival plot with CanvasXpress

Description

Draws an interactive Kaplan-Meier survival curve from per-subject survival data, optionally stratified into groups. Survival columns are read from the 'colData' of a [SummarizedExperiment::SummarizedExperiment] (so the same object that feeds [cxplot()] can produce the survival plot) or from a plain data frame.

Usage

cxsurvival(
  object,
  time = "time",
  status = "status",
  group = NULL,
  tooltip = NULL,
  ...
)

Arguments

object	A 'SummarizedExperiment' (its 'colData' is used) or a data-frame-like table with one row per subject.
time, status	Column names holding the follow-up time and the event status ('1'/'TRUE' = event, '0'/'FALSE' = censored).
group	Optional column name used to stratify and colour the curves (for example a treatment arm or cohort). 'NULL' draws a single curve.
tooltip	Optional character vector of extra 'colData' column names to carry with each subject, so hovering a step or a censored observation shows that subject's metadata (for example age, sex or disease stage). 'NULL' (the default) carries only the grouping column.
...	Additional CanvasXpress configuration passed to [canvasXpress::canvasXpress()].

Value

A 'canvasXpress' htmlwidget.

Examples

cd <- data.frame(
    time   = c(5, 12, 18, 24, 7, 15, 22, 30),
    status = c(1, 1, 0, 1, 1, 0, 1, 0),
    arm    = rep(c("A", "B"), each = 4))
cxsurvival(cd, time = "time", status = "status", group = "arm")

---

Volcano plot of differential-expression results with CanvasXpress

Description

Draws an interactive volcano plot (log fold change against $-\log_{10}$ p-value) from a table of differential-expression results. The input is coerced with [as.data.frame()], so a 'DESeqResults' object, a 'limma::topTable()' data frame, or any comparable table works.

Usage

cxvolcano(
  x,
  logfc = "log2FoldChange",
  pval = "padj",
  label = TRUE,
  label_genes = NULL,
  label_fc = 1,
  label_p = 2,
  ...
)

Arguments

x	A data-frame-like table of results.
logfc, pval	Column names holding the log fold change and the (adjusted) p-value. The defaults suit 'DESeq2' output.
label	Logical; when 'TRUE' (the default) genes are labelled with their row names. Set to 'FALSE' to draw an unlabelled volcano.
label_genes	Optional character vector of gene (row) names to label. When supplied, only these genes are labelled — useful for calling out a named set on a dense plot. When 'NULL' (the default) every significant gene is labelled instead.
label_fc, label_p	Thresholds that decide which genes are labelled: a gene is labelled when its absolute log fold change exceeds 'label_fc' and its $-\log_{10}$ p-value exceeds 'label_p'. Defaults of '1' and '2' label points outside a two-fold change and below p $\approx$ 0.01.
...	Additional CanvasXpress configuration passed to [canvasXpress::canvasXpress()].

Value

A 'canvasXpress' htmlwidget.

Examples

res <- data.frame(
    log2FoldChange = rnorm(100),
    padj           = runif(100),
    row.names      = paste0("gene", 1:100))
cxvolcano(res, title = "Volcano")

---

Build a dense single-feature SummarizedExperiment for a beeswarm demo

Description

Returns a 'SummarizedExperiment' with one feature measured across several groups and many observations per group, so a boxplot with a sina / beeswarm overlay ([cxboxplot()] with 'points = "sina"') can be shown to stay legible at scale rather than collapsing into an overplotted mass.

Usage

makeBeeswarmDemo(n_per_group = 500)

Arguments

n_per_group

Integer; observations in each group. Defaults to '500'.

Value

A [SummarizedExperiment::SummarizedExperiment] with a single '"Expression"' feature and a 'Group' column in its 'colData'.

Examples

bse <- makeBeeswarmDemo(n_per_group = 100)
cxboxplot(bse, feature = "Expression", group = "Group", points = "sina")

---

Build the demonstration SummarizedExperiment used in the vignette

Description

Assembles a small, self-contained 'SummarizedExperiment' so the vignette can show every figure from one object with a single function call instead of an inline data-construction block. The study follows 24 patients in two cohorts, each measured at baseline and at week 12 over a panel of twelve marker genes. 'colData' records the cohort, time point, subject, a follow-up time with an event indicator, and the direction of each subject's biomarker change; 'rowData' records whether each gene is an up- or down-regulated marker.

Usage

makeDemoSE()

Details

The derived analyses that the other figures need are attached to the object's [S4Vectors::metadata()] so the vignette needs no further wrangling: 'deResults' is a differential-expression table (the twelve markers among a synthetic genome-wide background) for [cxvolcano()], and 'albPaired' holds the per-cohort paired t-test p-values for the 'ALB' marker shown by [cxboxplot()]. The random draws are seeded reproducibly with [withr::with_seed()], so the object is identical on every call.

Value

A [SummarizedExperiment::SummarizedExperiment] with 'deResults' and 'albPaired' in its 'metadata()'.

Examples

se <- makeDemoSE()
se
S4Vectors::metadata(se)$albPaired

---