CanvasXpress R Interface

Getting Started

While R is a powerhouse for static data visualization, the modern data landscape demands interactivity. The canvasXpress R package is the bridge that connects R's analytical strength to the dynamic world of web-based charts. Developed as a core visualization component for bioinformatics and systems biology, CanvasXpress is designed to handle complex scientific datasets with a focus on creating fully reproducible and explorable visualizations.

This guide will walk you through the fundamentals of using the canvasXpress package to create interactive charts directly from your R data frames.

Installation

For the stable version, you can install the canvasXpress package directly from CRAN.

install.packages("canvasXpress")

Alternatively, to get the very latest features, you can install the development version from the official GitHub repository. You will need the devtools package first.

# install.packages("devtools") # Run this if you don't have devtools
devtools::install_github("neuhausi/canvasXpress")

Once installed, load the library to get started.

library(canvasXpress)

The Core Function: canvasXpress()

The primary function in the package is canvasXpress(). It's a versatile command that intelligently interprets your data and configuration to generate a chart. The most important parameter is data, which accepts a standard R data frame or matrix.

Live Example: Scatter Plot from iris data

The most direct way to create a chart is to pass an R data frame straight to the function. This is perfect for quick, exploratory analysis. Here, we'll use the built-in iris dataset and map columns to visual properties like the axes and colors.

The R Code

We pass the iris dataset and use parameters like xAxis, yAxis, and colorBy to map columns from the data frame to the visual properties of the chart. The result is a fully interactive scatter plot with a clickable legend and tooltips on hover.

# Use the built-in iris dataset
canvasXpress(
  data = iris,
  graphType = "Scatter2D",
  xAxis = list("Sepal.Length"),
  yAxis = list("Sepal.Width"),
  colorBy = "Species",
  title = "Iris Sepal Length vs. Width"
)

Enriching Plots with Metadata

For more complex visualizations, especially heatmaps and boxplots, you can provide additional metadata to group and annotate your data. This is done with the smpAnnot (sample annotations) and varAnnot (variable annotations) parameters.

Live Example: Grouped Boxplot

Here, we use the ToothGrowth dataset. We provide the main measurements in the data parameter and the grouping factors (doses and supp) as a separate data frame to smpAnnot. CanvasXpress uses this metadata to create the distinct groups on the x-axis.

The R Code

# Load the ToothGrowth dataset
data <- ToothGrowth

# Prepare the main data and the annotation data
main_data <- as.data.frame(t(data$len))
colnames(main_data) <- rownames(data)
sample_annotation <- data.frame(Dose = as.factor(data$dose), Supplement = data$supp)
rownames(sample_annotation) <- rownames(data)

# Create the boxplot, using smpAnnot to group the data
canvasXpress(
  data = main_data,
  smpAnnot = sample_annotation,
  graphType = 'Boxplot',
  groupingFactors = list('Dose', 'Supplement'),
  title = 'Tooth Growth by Supplement and Dose'
)

Integrating with Shiny Web Applications

The true power of canvasXpress in R is unlocked when you use it to build interactive web applications with Shiny. Shiny allows you to create a user interface with controls (like dropdowns and sliders) that can dynamically update your CanvasXpress charts in real time.

The integration is handled by two key functions:

• canvasXpressOutput(): This is used in your Shiny ui to create a placeholder for the chart.
• renderCanvasXpress(): This is used in your Shiny server function to build and render the chart.

A Basic Shiny App

Below is a complete example of a simple Shiny app. It displays a bar chart of the average horsepower for cars with different numbers of cylinders from the mtcars dataset. The chart in a real Shiny app would be fully interactive.

For a full implementation example, please refer to our blog post on this topic.

library(shiny)
library(canvasXpress)
library(dplyr)

# Prepare summary data
cars_data <- mtcars %>%
  group_by(cyl) %>%
  summarise(avg_hp = mean(hp)) %>%
  as.data.frame()

rownames(cars_data) <- paste(cars_data$cyl, "Cylinders")

# Define Shiny app
ui <- fluidPage(
    titlePanel("CanvasXpress in a Shiny App"),
    mainPanel(
      canvasXpressOutput("carPlot")
    )
)

server <- function(input, output) {
    output$carPlot <- renderCanvasXpress({
        canvasXpress(
            data = t(cars_data[, "avg_hp", drop = FALSE]),
            graphType = "Bar",
            title = "Average Horsepower by Number of Cylinders"
        )
    })
}

shinyApp(ui = ui, server = server)

Conclusion: A Powerful Tool for R Users

The canvasXpress R package provides a direct and powerful path from your data in R to sophisticated, interactive visualizations. Its ability to handle complex data and metadata makes it an invaluable tool for data exploration, especially in scientific research. By integrating seamlessly into the R environment and offering a simple yet flexible function, it empowers users to move beyond static plots and create engaging, insightful, and reproducible data experiences.