Warning

This package is under active development and will definitely change. All attempts will be made to maintain the functionality and methods demonstrated in this document. Documentation is currently a work in progress.

Any suggestions, advice or requests are welcome. For any bugs (there will be bugs) please submit an issue.

Installation

You probably already guessed this bit. Choose CRAN or github install:

install.packages('c3')

devtools::install_github("mrjoh3/c3")

Usage

Please note that this package is under active development and may change at any time. The plots that currently work are line (and varieties), bar and scatter plots. Where possible the package tries to emulate the Grammer of Graphics used in Hadley Wickham’s ggplot2.

The c3 package is intended to be as simple and lightweight as possible. As a starting point the data input must be a data.frame with several options.

• If a data.frame without any options is passed all of the numeric columns will be plotted. This can be used in line and bar plots. Each column is a line or bar.
• For more complex plots only 3 columns are used, those defined as x, y and group. This requires a data.frame with a vertical structure.

library(c3)

data <- data.frame(a = abs(rnorm(20) * 10),
                  b = abs(rnorm(20) * 10),
                  date = seq(as.Date("2014-01-01"), by = "month", length.out = 20))

c3(data)

data %>% c3() 

Other Line Plots

There are 5 different line plots available:

• line
• spline
• step
• area
• area-step

data %>%
  c3() %>%
  c3_line('spline')

data %>%
  c3(x = 'date') %>%
  c3_line('area-step')

Bar Plots

data[1:10, ] %>%
  c3() %>%
  c3_bar(stacked = TRUE, 
         rotate = TRUE)

Mixed Geometry Plots

Mixed geometry currently only works with a horizontal data.frame where each numeric column is plotted.

data$c <- abs(rnorm(20) *10)
data$d <- abs(rnorm(20) *10)

data %>%
  c3() %>%
  c3_mixedGeom(type = 'bar', 
               stacked = c('b','d'),
               types = list(a='area',
                            c='spline')
               )

Secondary Y Axis

To use a secondary Y axis columns must first be matched to an axis and then the secondary axis made visible.

data %>% 
  select(date, a, b) %>%
  c3(x = 'date',
     axes = list(a = 'y',
                 b = 'y2')) %>% 
  c3_mixedGeom(types = list(a = 'line',
                            b = 'area')) %>% 
  y2Axis()

Scatter Plot

iris %>%
  c3(x = 'Sepal_Length', 
     y = 'Sepal_Width', 
     group = 'Species') %>% 
  c3_scatter()

Pie Charts

data.frame(sugar = 20,
           fat = 45,
           salt = 10) %>% 
  c3() %>% 
  c3_pie()

Donut Charts

data.frame(red = 82, green = 33, blue = 93) %>% 
  c3(colors = list(red = 'red',
                   green = 'green',
                   blue = 'blue')) %>% 
  c3_donut(title = '#d053ee')

Gauge Charts

data.frame(data = 80) %>% 
  c3() %>% 
  c3_gauge()

Grid Lines & Annotation

data %>%
  c3() %>%
  grid('y') %>%
  grid('x', 
       show = F, 
       lines = data.frame(value = c(3, 10), 
                          text= c('Line 1','Line 2')))

Region Highlighting

To highlight regions pass a single data.frame with columns axis, start, end and class. Multiple regions can be defined within the one data.frame for any axis (x, y, y2). Each row in the data.frame defines a separate region to be highlighted

data %>%
  c3() %>%
  region(data.frame(axis = 'x',
                    start = 5,
                    end = 6))

Sub-chart

data %>%
  c3(x = 'date') %>%
  subchart()

Color Palette

Plot color palettes can be changed to either RColorBrewer or viridis palettes using either RColorBrewer (S3 method) or c3_viridus.

data.frame(sugar = 20, 
           fat = 45, 
           salt = 10, 
           vegetables = 60) %>% 
  c3() %>% 
  c3_pie() %>%
  RColorBrewer()

data.frame(sugar = 20, 
           fat = 45, 
           salt = 10, 
           vegetables = 60) %>% 
  c3() %>% 
  c3_pie() %>%
  c3_viridis()

Point Size

data %>%
  c3(x = 'date') %>%
  point_options(r = 6, 
                expand.r = 2)

On Click

Onclick, onmouseover and onmouseout are all available via the c3 function. To use wrap a js function as a character string to htmlwidgets::JS(). Please see the C3.js documentation and examples. The example below should be enough to get you started.

data %>% 
    c3(onclick = htmlwidgets::JS('function(d, element){console.log(d)}'))

Tooltips

C3 tooltips are readily modified with the use of javascript functions. For further detail see the C3.js documentation. Or for more advanced usage see the C3.js examples page.

library(htmlwidgets)

data %>%
  c3() %>%
  tooltip(format = list(title = JS("function (x) { return 'Data ' + x; }"),
                        name = JS('function (name, ratio, id, index) { return name; }'),
                        value = JS('function (value, ratio, id, index) { return ratio; }')))