Package {canvasXpress}


Version: 1.74.3
Title: Visualization Package for CanvasXpress in R
Description: Enables creation of visualizations using the CanvasXpress framework in R. CanvasXpress is a standalone JavaScript library for reproducible research with complete tracking of data and end-user modifications stored in a single PNG image that can be played back. See https://www.canvasxpress.org for more information.
Type: Package
License: GPL-3
Encoding: UTF-8
Language: en-US
URL: https://github.com/neuhausi/canvasXpress
BugReports: https://github.com/neuhausi/canvasXpress/issues
Depends: R (≥ 3.6)
Imports: htmlwidgets (≥ 1.0), htmltools, httr, jsonlite, stats, utils
RoxygenNote: 7.3.3
Suggests: repr, scales, ggalluvial, shiny (≥ 1.1.0), canvasXpress.data, dplyr, DT, glue, grid, knitr, png, readr, rlang, rmarkdown, stringr, testthat, tibble, tidyr, limma, ggplot2, survminer, S7, patchwork, GGally, ggpubr, ggpattern, ggh4x
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2026-11-18 20:55:19 UTC; conniebrett
Author: Isaac Neuhaus [aut], Connie Brett [aut, cre]
Maintainer: Connie Brett <connie@aggregate-genius.com>
Repository: CRAN
Date/Publication: 2026-11-19 01:00:02 UTC

CanvasXpress Visualization Package

Description

A package to assist in creating visualizations in CanvasXpress in R.

Details

CanvasXpress is a standalone JavaScript library for reproducible research with complete tracking of data and end-user modifications stored in a single PNG image that can be played back for an extensive set of visualizations.

More Information

https://www.canvasxpress.org

browseVignettes(package = "canvasXpress")

Author(s)

Maintainer: Connie Brett connie@aggregate-genius.com

Authors:

See Also

Useful links:


HTML Widget Creation

Description

Custom HTML widget creation function based on widget YAML and JavaScript for use in any html-compatible context

Usage

canvasXpress(
  data = NULL,
  smpAnnot = NULL,
  varAnnot = NULL,
  graphType = "Scatter2D",
  events = NULL,
  afterRender = NULL,
  pretty = FALSE,
  digits = 4,
  width = 600,
  height = 400,
  destroy = FALSE,
  validate = FALSE,
  ...
)

Arguments

data

data.frame-, matrix-, list- , or ggplot- classed object

smpAnnot

additional data that applies to samples (columns)

varAnnot

additional data that applies to variables (rows)

graphType

type of graph to be plotted - default = "Scatter2D"

events

user-defined events (e.g. mousemove, mouseout, click and dblclick)

afterRender

event triggered after rendering

pretty

print tagged code (JSON/HTML) nicely - default = FALSE

digits

display digits - default = 4

width

plot width (valid CSS units) - default = 600px

height

plot height (valid CSS units) - default = 400px

destroy

used to indicate removal of a plot - default = FALSE

validate

if TRUE, check the config parameters against the CanvasXpress parameter catalog and warn on unknown parameters or invalid enumerated values (see cxValidateConfig) - default = FALSE

...

additional parameters passed to canvasXpress

Value

htmlwidgets object

Piping Support

Piping is supported (both the magrittr ' canvasXpress object into data parameter. Any new parameters will be added to the original configuration of the object, any parameters with data that existed before will be replaced, and any parameters set to null will be removed. It is important to note that primary data changes are not allowed in this construct - which means that anything specified by using the data, varAnnot, or smpAnnot parameters cannot be changed from the original values.


HTML Widget Creation using JSON input

Description

Custom HTML widget creation function based on widget YAML and JavaScript for use in any html-compatible context using raw JSON input. Validation of data and configuration is deferred completely to the canvasXpress JavaScript library.

Usage

canvasXpress.json(
  json,
  pretty = FALSE,
  digits = 4,
  width = 600,
  height = 400,
  destroy = FALSE
)

Arguments

json

JSON string or object

pretty

print tagged code (JSON/HTML) nicely - default = FALSE

digits

display digits - default = 4

width

plot width (valid CSS units) - default = 600px

height

plot height (valid CSS units) - default = 400px

destroy

used to indicate removal of a plot - default = FALSE

Details

For the formatting of the JSON input object see

**Note:** this function is intended for use by advanced users who are experimenting with or need to utilize the json-formatted input to canvasXpress and are comfortable debugging chart issues in a browser (JavaScript) context instead of in R.

Value

htmlwidgets object

More Information

https://www.canvasxpress.org

Examples


my_json <- '{ "data": {"y": { "vars": ["Performance"],
                              "smps": ["January"],
                              "data": [[85]] }},
              "config": { "graphType": "Meter",
                          "meterType": "gauge" }}'

canvasXpress.json(my_json)


Shiny UI function

Description

Output creation function for canvasXpressOutput in Shiny applications and interactive Rmd documents

Usage

canvasXpressOutput(outputId, width = "100%", height = "400px")

Arguments

outputId

shiny unique ID

width

width of the element - default = 100%

height

height of the element - default = 400px

Value

Output function that enables the use of the widget in applications

See Also

renderCanvasXpress

cxShinyExample


CanvasXpress configuration parameter catalog

Description

Returns a data.frame describing every CanvasXpress config parameter - its name, type, default value, allowed values (for enumerated parameters) and a one-line description. The catalog is generated from the CanvasXpress config schema (the same source as the JavaScript .d.ts and Python CXConfig types) and shipped with the package under inst/config/config-params.json.

Usage

cxConfigParams()

Details

Because canvasXpress accepts config parameters through ..., R cannot autocomplete them; this catalog is the R equivalent of those typed surfaces - a searchable, documented reference you can query programmatically and validate against with cxValidateConfig.

Value

A data.frame with columns parameter, type, default, options (a list-column of allowed values, or NULL) and description. The result is memoised for the session.

See Also

cxValidateConfig, canvasXpress

Examples

## Not run: 
params <- cxConfigParams()
# look up one parameter
params[params$parameter == "graphType", ]
# every parameter whose description mentions "legend"
params[grepl("legend", params$description, ignore.case = TRUE), "parameter"]

## End(Not run)


Stand-Alone HTML Page Creation

Description

This function creates and returns a stand-alone HTML page containing the given canvasXpress object. Width and height can be inferred from the canvasXpress object (default) or overridden for the page output.

Usage

cxHtmlPage(chartObject, width = NULL, height = NULL)

Arguments

chartObject

a canvasXpress plot object

width

plot width override for the HTML page (valid CSS units) - default = NULL

height

plot height override for the HTML page (valid CSS units) - default = NULL

Value

a character string containing a self-contained html page

Examples

## Not run: 
my_chart <- canvasXpress(data      = data.frame(Sample1 = c(33, 48),
                                                Sample2 = c(44, 59),
                                                Sample3 = c(55, 6)),
                         graphType = "Bar",
                         title     = "Example Bar Chart",
                         width     = "600px")

# create a page using the chart dimensions on my_chart
html_page <- cxHtmlPage(my_chart)

# or change the chart width/height for this page:
html_page <- cxHtmlPage(my_chart, width = "100%", height = "70vh")

# save page for viewing/sharing
writeLines(html_page, tempfile(fileext = ".html"))

## End(Not run)


Create Shiny Example Application

Description

This function runs one of the available shiny example applications. To see the list of available example applications run the function with no inputs

Usage

cxShinyExample(example = NULL)

Arguments

example

character name of a valid example application.

Value

Launches a running shiny example application

See Also

canvasXpressOutput

renderCanvasXpress


Validate a CanvasXpress configuration against the parameter catalog

Description

Checks a named config list against cxConfigParams and reports parameters that are not recognised and enumerated parameters set to a value outside their allowed options. This mirrors the compile-time checking the JavaScript .d.ts and Python CXConfig types give consumers, for R code where config flows through ... and is otherwise unchecked.

Usage

cxValidateConfig(config, strict = FALSE)

Arguments

config

A named list of CanvasXpress config parameters (the same name = value pairs you would pass to canvasXpress via ...).

strict

Logical; if TRUE, raise an error when any issue is found instead of warning. Default FALSE.

Details

Recognised-but-unlisted parameters (obfuscation aliases, or a parameter newer than the installed catalog) are reported as unknown; that is a hint, not proof of an error - canvasXpress still accepts any parameter.

Value

Invisibly, a list with elements unknown (character vector of unrecognised parameter names) and bad_options (a named list mapping each offending enumerated parameter to the invalid value supplied). A config with no issues returns two empty elements and emits no message.

See Also

cxConfigParams, canvasXpress

Examples

## Not run: 
cxValidateConfig(list(graphType = "Bar", colorScheme = "Tableau"))   # clean
cxValidateConfig(list(graphType = "NotAType", wat = 1))              # warns

## End(Not run)


Calibration (reliability) curve

Description

Builds a canvasXpress calibration curve from a data frame of binary truth and predicted probabilities. Probabilities are grouped into equal-width bins; each non-empty bin is plotted at (mean predicted probability, observed frequency), with the perfect-calibration diagonal and the expected calibration error (ECE) in the title.

Usage

cx_calibration(
  data,
  truth,
  prob,
  positive = NULL,
  bins = 10,
  title = NULL,
  ...
)

Arguments

data

a data frame of classifier results

truth

column of observed binary class labels (bare or quoted name)

prob

column of predicted positive-class probabilities in [0,1]

positive

the label treated as the positive class (default: inferred)

bins

number of probability bins (default 10)

title

chart title (default: "Calibration (ECE = ...)")

...

further canvasXpress config options

Value

a canvasXpress htmlwidget


Confusion matrix for a classifier

Description

Builds a canvasXpress confusion-matrix heatmap from a data frame holding observed and predicted labels, counting every (actual, predicted) pair over the sorted union of labels. Counts are colour-encoded and printed in each cell.

Usage

cx_confusion(data, truth, pred, labels = NULL, title = NULL, ...)

Arguments

data

a data frame of classifier results

truth

column of observed class labels (bare or quoted name)

pred

column of predicted class labels (bare or quoted name)

labels

optional ordered vector of class labels

title

chart title (default: "Confusion matrix")

...

further canvasXpress config options

Value

a canvasXpress htmlwidget

Examples

## Not run: 
df <- data.frame(truth = c("a","a","b","b"), pred = c("a","b","b","b"))
cx_confusion(df, truth, pred)

## End(Not run)

Feature importance bar chart

Description

Builds a horizontal canvasXpress bar chart of feature importances from a data frame, sorted by descending importance (optionally capped at 'top').

Usage

cx_importance(data, feature, importance, top = NULL, title = NULL, ...)

Arguments

data

a data frame of feature importances

feature

column of feature names (bare or quoted name)

importance

column of importance values (bare or quoted name)

top

optional number of top features to keep

title

chart title (default: "Feature importance")

...

further canvasXpress config options

Value

a canvasXpress htmlwidget


Learning curve

Description

Builds a canvasXpress learning curve from a data frame of training-set sizes and the matching training and validation scores, drawn as two lines over the size axis.

Usage

cx_learning_curve(data, size, train, val, title = NULL, ...)

Arguments

data

a data frame with size, train and validation columns

size

column of training-set sizes (bare or quoted name)

train

column of training scores (bare or quoted name)

val

column of validation scores (bare or quoted name)

title

chart title (default: "Learning curve")

...

further canvasXpress config options

Value

a canvasXpress htmlwidget


Precision-recall curve for a binary classifier

Description

Builds a canvasXpress precision-recall curve from a data frame holding binary truth and continuous scores, computing precision/recall at each threshold and the average precision (AP) and drawing the no-skill baseline.

Usage

cx_pr(data, truth, score, positive = NULL, title = NULL, ...)

Arguments

data

a data frame of classifier results

truth

column of observed binary class labels (bare or quoted name)

score

column of decision scores / positive-class probabilities

positive

the label treated as the positive class (default: inferred)

title

chart title (default: "Precision-Recall (AP = ...)")

...

further canvasXpress config options

Value

a canvasXpress htmlwidget


ROC curve for a binary classifier

Description

Builds a canvasXpress ROC curve from a data frame holding binary truth and continuous scores, computing the TPR/FPR sweep and the trapezoidal AUC and drawing the chance diagonal as a reference line.

Usage

cx_roc(data, truth, score, positive = NULL, title = NULL, ...)

Arguments

data

a data frame of classifier results

truth

column of observed binary class labels (bare or quoted name)

score

column of decision scores / positive-class probabilities

positive

the label treated as the positive class (default: inferred)

title

chart title (default: "ROC curve (AUC = ...)")

...

further canvasXpress config options

Value

a canvasXpress htmlwidget

Examples

## Not run: 
df <- data.frame(truth = c(0,0,1,1), score = c(0.1,0.4,0.35,0.8))
cx_roc(df, truth, score)

## End(Not run)

SHAP summary (beeswarm)

Description

Builds a canvasXpress SHAP summary beeswarm from a SHAP-value matrix and the matching feature-value matrix. Every (sample, feature) becomes a jittered point grouped on the feature axis, positioned by its SHAP value and coloured by the underlying feature value. Features are ordered by descending mean absolute SHAP.

Usage

cx_shap(shap, values, features = NULL, top = NULL, title = NULL, ...)

Arguments

shap

a samples x features matrix or data frame of SHAP values

values

a samples x features matrix or data frame of feature values (for colour)

features

optional feature names (default: column names of 'shap')

top

optional number of top features to keep

title

chart title (default: "SHAP summary")

...

further canvasXpress config options

Value

a canvasXpress htmlwidget


Converts a ggplot object to a list that can be used by CanvasXpress.

Description

Converts a ggplot object to a list that can be used by CanvasXpress.

Usage

ggplot.as.list(o, ...)

Arguments

o

the ggplot object

...

additional parameters to the function


Reconstruct approximate ggplot2 source code from a ggplot object.

Description

Walks a ggplot object and returns code that renders an equivalent plot. This is BEST-EFFORT: functions passed to stats (e.g. fun = mean) round-trip only by name, custom themes collapse to a note (a complete theme carries every element, so the original theme_*()/element_*() calls cannot be recovered), and the data pipeline that built o$data is unrecoverable.

Usage

ggplot.decompiled(o, data_name = "dat")

Arguments

o

a ggplot object.

data_name

the symbol used for the data argument in the emitted ggplot(...) call (default "dat").

Details

The result is also attached to the output of ggplot.as.list as the decompiled field.

Value

A single character string containing the reconstructed code, with one ggplot layer/scale/label per line. Use cat() or writeLines() to print it. Returns NA_character_ for non-ggplot input.

Examples

## Not run: 
  p <- ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) + ggplot2::geom_point()
  cat(ggplot.decompiled(p, "mtcars"))

## End(Not run)


Shiny Render function

Description

Render function for canvasXpressOutput in Shiny applications and interactive Rmd documents

Usage

renderCanvasXpress(expr, env = parent.frame(), quoted = FALSE)

Arguments

expr

expression used to render the canvasXpressOutput

env

environment to use - default = parent.frame()

quoted

whether the expression is quoted - default = FALSE

Value

Render function that enables the use of the widget in applications

Destroy

When there exists a need to visually remove a plot from a Shiny application when it is not being immediately replaced with a new plot use the destroy option as in:

renderCanvasXpress({canvasXpress(destroy = TRUE)})

See Also

canvasXpressOutput

cxShinyExample