Getting Started with c3plot • c3plot

Introduction

R is renowned for its graphical capabilities, and base R’s ‘graphics’ package makes it easy and quick to create clean, useful plots. However, plots created with base graphics are static images and therefore lack interactive features such as tooltips or zooming.

The c3plot package implements various plotting functions with similar names, arguments and behavior to their counterparts in base graphics, except the plots they create are interactive HTML widgets rendered using the C3.js charting library. This makes it easy to generate interactive versions of common plots without the cognitive overhead of using/learning a plotting package with completely different arguments and syntax. This vignette will help you get started creating interactive visualizations with c3plot.

The first step is to install the package:

# install.packages("devtools")
devtools::install_github("arkraieski/c3plot")

Basic Scatter Plots

The c3plot() function works much like base R’s plot() function. To create a scatter plot, we simply have to provide two vectors (often from the same data.frame) for the arguments x and y. There are many optional arguments that can be specified, but we’ll get to that later in this document.

First, let’s create a basic scatter plot using base R as a refresher:

library(c3plot)
mtcars <- mtcars # R's Motor Trend Cars Dataset

plot(x = mtcars$hp, y = mtcars$qsec)

Now with c3plot():

c3plot(x = mtcars$hp, y = mtcars$qsec)

You can use the mouse wheel to zoom in on this chart, and the points have tooltips. Importantly, neither this nor the base R plot earlier have much in the way of chartjunk.

Title and Axis Labels

Just like with plot(), we can specify a plot title and x and y axis labels using the arguments main, xlab, and ylab, respectively:

c3plot(x = mtcars$hp, y = mtcars$qsec,
       main = "1/4 Mile Time vs. Horsepower",
       xlab = "HP",
       ylab = "Seconds")

Line plots

Like the base plot() function, c3plot() can also create line plots by setting the type argument to “l” (default is “p” for points). You can also show both points and lines by setting it to “b”.

x <- 1:10
y <- x*x

c3plot(x, y, type = "l", zoom = FALSE)

Color

For c3plot() colors for the points can be specified using the col argument. Colors can be given as strings containing a hex value or strings with names of R built-in colors. You can run grDevices::colors() to see all valid color names.

To color all points the same color, provide a single value for col:

c3plot(x = mtcars$hp, y = mtcars$qsec, col = "red")

Points can also be colored by groups in the data. There are two ways of doing this:

Pass a factor the same length as x to the col.group argument and leave col NULL. Points will be grouped by col.group, and then each group will be assigned a color by C3.js using its default palette.
Pass a factor to col.group and vector of colors to use for each group to col.

First, let’s color a scatter plot by a factor but let C3.js pick the colors:

# convert mtcars$cyl to a factor
mtcars$cyl <- as.factor(paste(mtcars$cyl, "cylinders"))

c3plot(mtcars$hp, mtcars$mpg, col.group = mtcars$cyl, legend.title = "cyl")

Now, coloring manually from R:

c3plot(mtcars$hp, mtcars$mpg, col.group = mtcars$cyl, 
       col = c("red2", "yellow3", "purple"),
       legend.title = "cyl")

Pie charts

Sometimes, your boss might want you to make a pie chart.

c3plot also provides a c3pie() function that works like the base R pie function, albeit with a simplified set of arguments. x is a vector of non-negative numerical quantities. Names for the pie slices can be given as a character vector to the labels argument. If x is a named vector, the names will be used to label the pie slices (labels defaults to names(x)).

Here’s an example adapted from the help file for pie():

pie.sales <- c(0.12, 0.3, 0.26, 0.16, 0.04, 0.12)
names(pie.sales) <- c("Blueberry", "Cherry",
    "Apple", "Boston Cream", "Other", "Vanilla Cream")
c3pie(pie.sales)

S3 methods

Like base’s plot(), c3plot() is a generic function with S3 methods for various classes of base R objects. While c3plot() doesn’t have as many methods, this nonetheless provides some useful shortcuts for making some common plots. To see all available methods, run:

methods(c3plot)
#> [1] c3plot.default*  c3plot.density*  c3plot.factor*   c3plot.function*
#> [5] c3plot.lm*      
#> see '?methods' for accessing help and source code

So far, we’ve been working with the default method. Each method has help available. For example, you would run ?c3plot.density to view the help file for c3plot.density().

Let’s create a density plot with the Old Faithful geyser data using c3plot.density(). First, create a “density” object:

d <- density(faithful$eruptions, bw = "sj")
class(d)
#> [1] "density"
d
#> 
#> Call:
#>  density.default(x = faithful$eruptions, bw = "sj")
#> 
#> Data: faithful$eruptions (272 obs.); Bandwidth 'bw' = 0.14
#> 
#>        x               y            
#>  Min.   :1.180   Min.   :0.0001834  
#>  1st Qu.:2.265   1st Qu.:0.0422638  
#>  Median :3.350   Median :0.1709243  
#>  Mean   :3.350   Mean   :0.2301726  
#>  3rd Qu.:4.435   3rd Qu.:0.4134348  
#>  Max.   :5.520   Max.   :0.5945634

Since c3plot() has a method for “density” objects, we can plot this object simply by passing it to the x argument (this method doesn’t need y):

c3plot(d)

Compare to the base R version:

plot(d)

The plots are very similar aside from some visual differences and obviously the interactivity of the c3plot version. c3plot() methods are designed to replicate the functionality of their Base R counterparts.

c3plot.function() lets us do cool stuff like this:

c3plot(qnorm) # default range c(0, 1)

and this (note use of scientific notation on y-axis):

c3plot(sin, -pi,  3*pi, col = "orange2", sci.y = TRUE)

Bar charts

This package also provides a c3barplot() function modeled after barplot() from base graphics. Pass a numeric vector describing the heights of the bars to the heights argument. You can also provide a vector of names for the bars to the argument narmes.arg (otherwise the x-axis will be numbered sequentially). Here’s a simple, silly example:

c3barplot(heights = c(100, 30), names.arg = c("Red Sox", "Yankees"), ylab = "% Awesome",
          main = "Awesomeness of Baseball Teams")

You can also use the “shortcut” provided by the c3plot.factor() method to make a bar chart of factor level counts. Simply pass a factor to the x argument:

# cyl column of mtcars was already converted into a factor earlier in this vignette
c3plot(mtcars$cyl, col = "#FF2800", main = "Cars by Number of Cylinders in mtcars")

Conclusion

By now you should be more than ready to start using c3plot on your own data. Consult the help pages for details about arguments and methods. While c3plot doesn’t offer quite the same level of customization as base graphics, it’s a simple, interactive alternative for many common base plots.