---
title: "Charting Data Frames"
author: "Joshua Kunst"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Charting Data Frames}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, warning = FALSE, message = FALSE, echo = FALSE}
library(highcharter)
library(dplyr)
options(highcharter.theme = hc_theme_smpl(), highcharter.debug = TRUE)
```

## Introduction

We chart data. Data can come in different ways: numeric or character vectors,
as time series objects, etc. but the most common object with data is a data 
frame. So, why can chart this type of object in __highcharter__?

Highcharter have two main functions to create a chart from data and another
to add data to an existing `highchart` object.

1. `hchart`: A generic function which take an object (like vector, time series,
data frames, likert object, etc) and return a `highchart` object (chart)
2. `hc_add_series`: A generic function which add data to a existing
`highchart` object depending the type (class) of the data.

There are a last function will be useful to chart data from data frame. The 
functions is `hcaes` which will define the aesthetic mappings. This 3 functions
are inspired in __ggplot2__ package. So:

- `hchart` works like ggplot2's `qplot`.
- `hc_add_series` works like ggplot2's `geom_`s.
- `hcaes` works like ggplot2's `aes`.

The main differences with ggplot2 are here we need the data and the aesthetics
explicit in every highchart functions. 

## Examples

Lets see examples to be more clear.

```{r}
data("mpg", package = "ggplot2")
head(mpg)
```

```{r}
hchart(mpg, "point", hcaes(x = displ, y = cty))
```

The previous code is same as:

```{r}
highchart() %>% 
  hc_add_series(mpg, "point", hcaes(x = displ, y = cty))
```

With highcharter you can have other type of charts.

```{r}
data("diamonds", package = "ggplot2")
dfdiam <- diamonds %>% 
  group_by(cut, clarity) %>%
  summarize(price = median(price))

head(dfdiam)

hchart(dfdiam, "heatmap", hcaes(x = cut, y = clarity, value = price)) 
```

```{r}
data(economics_long, package = "ggplot2")

economics_long2 <- filter(economics_long,
                          variable %in% c("pop", "uempmed", "unemploy"))

head(economics_long2)

hchart(economics_long2, "line", hcaes(x = date, y = value01, group = variable))
```


You can even chart a treemaps:
```{r}
data(mpg, package = "ggplot2")

mpgman <- mpg %>% 
  group_by(manufacturer) %>% 
  summarise(n = n(),
            unique = length(unique(model))) %>% 
  arrange(-n, -unique)

head(mpgman)

hchart(mpgman, "treemap", hcaes(x = manufacturer, value = n, color = unique))
```


## Extra parameters

You can add other parameters to add options to the data series:

```{r}
mpgman2 <- count(mpg, manufacturer, year)

head(mpgman2)

hchart(mpgman2, "bar", hcaes(x = manufacturer, y = n, group = year),
       color = c("#FCA50A", "#FCFFA4"),
       name = c("Year 1999", "Year 2008"))
```

## A more advanced examples

Using the `broom` package is really great due the you 
can work with tidy data:

```{r, message=FALSE}
library(dplyr)
library(broom)

```
```{r}
data(diamonds, package = "ggplot2")

set.seed(123)
data <- diamonds %>% 
  filter(carat > 0.75, carat < 3) %>% 
  sample_n(500)

modlss <- loess(price ~ carat, data = data)
fit <- arrange(augment(modlss), carat)

head(fit)
```

Now we try to be specific in what parameter we use.

```{r}
highchart() %>% 
  hc_add_series(
    data,
    type = "scatter",
    hcaes(x = carat, y = price, size = depth, group = cut),
    maxSize = 5 # max size for bubbles
    ) %>%
  hc_add_series(
    fit,
    type = "spline",
    hcaes(x = carat, y = .fitted),
    name = "Fit",
    id = "fit", # this is for link the arearange series to this one and have one legend
    lineWidth = 1 
    ) %>% 
  hc_add_series(
    fit,
    type = "arearange",
    hcaes(x = carat, low = .fitted - 3*.se.fit, high = .fitted + 3*.se.fit),
    linkedTo = "fit", # here we link the legends in one.
    color = hex_to_rgba("gray", 0.2),  # put a semi transparent color
    zIndex = -3 # this is for put the series in a back so the points are showed first
    )
```
