---
title: "c3 Basics"
output: 
  rmarkdown::html_vignette:
    fig_caption: yes
    self_contained: yes
    toc: no
vignette: >
  %\VignetteIndexEntry{Basic Use}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r setup, warning=FALSE, message=FALSE, echo=FALSE}

library(dplyr)

```

The `c3` package is a wrapper, or [htmlwidget](http://www.htmlwidgets.org/), for the [C3](http://c3js.org/) javascript charting library by [Masayuki Tanaka](https://github.com/masayuki0812). You will find this package useful if you are wanting to create a chart using [R](https://www.r-project.org/) and embedding it in a Rmarkdown document or Shiny App.  

The `C3` library is very versatile and includes a lot of options. Currently this package wraps most of the `C3` [options object](http://c3js.org/reference.html). Even with this current limitation a wide range of options are available. 



## Installation

You probably already guessed this bit.

```{r install, eval=FALSE}

install.packages('c3')

# OR

devtools::install_github("mrjoh3/c3")

```


## Usage

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` or `tibble` 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.

### The Basics

Where no options are supplied a simple line plot is produced by default. Where no x-axis is defined the plots are sequential. `Date` x-axis can be parsed with not additional setting if in the format `%Y-%m-%d` (ie '2014-01-01') 

```{r data, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

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)

```



### Piping

The package also imports the [magrittr](https://CRAN.R-project.org/package=magrittr) piping function (`%>%`) to simplify syntax.

```{r pipe, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

data %>% c3() 

```


## Other Line Plots

There are 5 different line plots available:

* line
* spline
* step
* area
* area-step


#### Spline

```{r spline, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

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



#### Step

```{r step, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

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

```



## Bar Plots

```{r bar, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

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.

```{r mixed, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

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. 

```{r y2, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

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


```{r scatter, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

mtcars %>%
  c3(x = 'mpg', 
     y = 'wt', 
     group = 'cyl') %>% 
  c3_scatter()
                
```




## Pie Charts

```{r pie, warning=FALSE, message=FALSE, fig.align='center', fig.width=4, fig.height=3}

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



## Donut Charts

```{r donut, warning=FALSE, message=FALSE, fig.align='center', fig.width=4, fig.height=3}

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



## Gauge Charts

```{r gauge, warning=FALSE, message=FALSE, fig.align='center', fig.width=6, fig.height=3}

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



## Grid Lines & Annotation

```{r grid, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

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  

```{r region, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

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



## Sub-chart



```{r subchart, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

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`.


```{r brewer, warning=FALSE, message=FALSE, fig.align='center', fig.width=4, fig.height=3}

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

```





```{r viridis, warning=FALSE, message=FALSE, fig.align='center', fig.width=4, fig.height=3}

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



## Point Size


```{r point, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

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](http://c3js.org/reference.html#data-onclick) and [examples](http://c3js.org/samples/chart_pie.html). The example below should be enough to get you started.

```{r onclick, eval=FALSE}

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](http://c3js.org/reference.html#tooltip-format-title). Or for more advanced usage see the `C3.js` [examples](http://c3js.org/samples/tooltip_format.html) page.

```{r tooltip, warning=FALSE, message=FALSE, fig.align='center', fig.width=8, fig.height=3}

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; }')))


```