echartr

The goal of echartr is to provide an R interface to Echarts that is as close to the original JavaScript API as possible.

Creating a chart

The function for creating a new chart is echartr(), which takes an option argument. This argument is a list of lists that defines the chart’s configuration.

For example, we can replicate this basic line chart like so:

echartr(option = list(
  xAxis = list(type = "category", data = c("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")),
  yAxis = list(type = "value"),
  series = list(type = "line", data = c(150, 230, 224, 218, 135, 147, 260))
))

Working with data frames

Since most data being visualised in R come from a data frame, echartr provides helper functions for building the option object from data frames. These functions are prefixed with ec_.

Building the same chart using ec_line() looks like:

data <- tibble::tibble(
  day = c("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"),
  value = c(150, 230, 224, 218, 135, 147, 260)
)

echartr(option = list(
  xAxis = list(type = "category"),
  yAxis = list(type = "value"),
  series = ec_line(data, day, value)
))

All ec_ functions take a data frame as the first argument. ec_line expects a y argument and optionally an x argument, which can be any expression that can be evaluated from the data frame columns and local environment.

For example, we can transform the y-values within the ec_line arguments:

inverse <- function(x) {
  1 / x
}

echartr(option = list(
  xAxis = list(type = "category"),
  yAxis = list(type = "value"),
  series = ec_line(data, day, inverse(value))
))

Series properties

Other series properties can be provided as named arguments to the ec_ functions. For example, specifying a lineStyle:

echartr(option = list(
  xAxis = list(type = "category"),
  yAxis = list(type = "value"),
  series = ec_line(data, day, value, lineStyle = list(width = 5, type = "solid"))
))

These can also refer to the data frame columns - any series property taking multiple values will result in multiple series. Consider the case where we want to plot 2 different weeks:

data2 <- data |>
  dplyr::mutate(week = "Week 1") |>
  dplyr::bind_rows(
    tibble::tibble(
      day = c("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"),
      value = c(180, 200, 252, 177, 200, 212, 276),
      week = "Week 2"
    )
  )

echartr(option = list(
  xAxis = list(type = "category"),
  yAxis = list(type = "value"),
  legend = list(show = TRUE),
  series = ec_line(data2, day, value, name = week)
))

This works even for deeply nested properties:

echartr(option = list(
  xAxis = list(type = "category"),
  yAxis = list(type = "value"),
  legend = list(show = TRUE),
  series = ec_line(
    data2, day, value, 
    name = week, 
    label = list(
      show = (week == "Week 1") # Show label for Week 1 only
    )
  )
))

Debugging in Javascript

echartr is designed based on the belief that using the Echarts Javascript API is the most straightforward way to build and understand Echarts.

That’s why it’s always easy to see the javascript equivalent of your R code - printing the output of any of the ec_ functions will show you the equivalent javascript.

ec_line(data2, y = value, name = week)
#> Warning in build_spec(df, ...): No data dimensions specified
#> [[1]]
#> [[1]]$type
#> [1] "line"
#> 
#> [[1]]$y
#> [1] 150
#> 
#> [[1]]$name
#> [1] "Week 1"
#> 
#> [[1]]$data
#> [[1]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[2]]
#> [[2]]$type
#> [1] "line"
#> 
#> [[2]]$y
#> [1] 230
#> 
#> [[2]]$name
#> [1] "Week 1"
#> 
#> [[2]]$data
#> [[2]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[3]]
#> [[3]]$type
#> [1] "line"
#> 
#> [[3]]$y
#> [1] 224
#> 
#> [[3]]$name
#> [1] "Week 1"
#> 
#> [[3]]$data
#> [[3]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[4]]
#> [[4]]$type
#> [1] "line"
#> 
#> [[4]]$y
#> [1] 218
#> 
#> [[4]]$name
#> [1] "Week 1"
#> 
#> [[4]]$data
#> [[4]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[5]]
#> [[5]]$type
#> [1] "line"
#> 
#> [[5]]$y
#> [1] 135
#> 
#> [[5]]$name
#> [1] "Week 1"
#> 
#> [[5]]$data
#> [[5]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[6]]
#> [[6]]$type
#> [1] "line"
#> 
#> [[6]]$y
#> [1] 147
#> 
#> [[6]]$name
#> [1] "Week 1"
#> 
#> [[6]]$data
#> [[6]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[7]]
#> [[7]]$type
#> [1] "line"
#> 
#> [[7]]$y
#> [1] 260
#> 
#> [[7]]$name
#> [1] "Week 1"
#> 
#> [[7]]$data
#> [[7]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[8]]
#> [[8]]$type
#> [1] "line"
#> 
#> [[8]]$y
#> [1] 180
#> 
#> [[8]]$name
#> [1] "Week 2"
#> 
#> [[8]]$data
#> [[8]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[9]]
#> [[9]]$type
#> [1] "line"
#> 
#> [[9]]$y
#> [1] 200
#> 
#> [[9]]$name
#> [1] "Week 2"
#> 
#> [[9]]$data
#> [[9]]$data[[1]]
#> list()
#> 
#> [[9]]$data[[2]]
#> list()
#> 
#> 
#> 
#> [[10]]
#> [[10]]$type
#> [1] "line"
#> 
#> [[10]]$y
#> [1] 252
#> 
#> [[10]]$name
#> [1] "Week 2"
#> 
#> [[10]]$data
#> [[10]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[11]]
#> [[11]]$type
#> [1] "line"
#> 
#> [[11]]$y
#> [1] 177
#> 
#> [[11]]$name
#> [1] "Week 2"
#> 
#> [[11]]$data
#> [[11]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[12]]
#> [[12]]$type
#> [1] "line"
#> 
#> [[12]]$y
#> [1] 212
#> 
#> [[12]]$name
#> [1] "Week 2"
#> 
#> [[12]]$data
#> [[12]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[13]]
#> [[13]]$type
#> [1] "line"
#> 
#> [[13]]$y
#> [1] 276
#> 
#> [[13]]$name
#> [1] "Week 2"
#> 
#> [[13]]$data
#> [[13]]$data[[1]]
#> list()
#> 
#> 
#> 
#> attr(,"class")
#> [1] "ec_object"

For an option list-tree, using new_option as the outermost list will do the same:

new_option(
  xAxis = list(type = "category", data = unique(data$day)),
  yAxis = list(type = "value"),
  series = ec_line(data, y = value)
)
#> Warning in build_spec(df, ...): No data dimensions specified
#> $xAxis
#> $xAxis$type
#> [1] "category"
#> 
#> $xAxis$data
#> [1] "Mon" "Tue" "Wed" "Thu" "Fri" "Sat" "Sun"
#> 
#> 
#> $yAxis
#> $yAxis$type
#> [1] "value"
#> 
#> 
#> $series
#> [[1]]
#> [[1]]$type
#> [1] "line"
#> 
#> [[1]]$y
#> [1] 150
#> 
#> [[1]]$data
#> [[1]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[2]]
#> [[2]]$type
#> [1] "line"
#> 
#> [[2]]$y
#> [1] 230
#> 
#> [[2]]$data
#> [[2]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[3]]
#> [[3]]$type
#> [1] "line"
#> 
#> [[3]]$y
#> [1] 224
#> 
#> [[3]]$data
#> [[3]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[4]]
#> [[4]]$type
#> [1] "line"
#> 
#> [[4]]$y
#> [1] 218
#> 
#> [[4]]$data
#> [[4]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[5]]
#> [[5]]$type
#> [1] "line"
#> 
#> [[5]]$y
#> [1] 135
#> 
#> [[5]]$data
#> [[5]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[6]]
#> [[6]]$type
#> [1] "line"
#> 
#> [[6]]$y
#> [1] 147
#> 
#> [[6]]$data
#> [[6]]$data[[1]]
#> list()
#> 
#> 
#> 
#> [[7]]
#> [[7]]$type
#> [1] "line"
#> 
#> [[7]]$y
#> [1] 260
#> 
#> [[7]]$data
#> [[7]]$data[[1]]
#> list()
#> 
#> 
#> 
#> attr(,"class")
#> [1] "ec_object"
#> 
#> attr(,"class")
#> [1] "ec_option" "ec_object"

These can be written straight to the clipboard with ec_clip for easy pasting into the Echarts online editor:

ec_clip(ec_line(data2, y = value, name = week))

Next steps

This guide has shown you how to create a basic chart using echartr - to get the most out of echartr, check out the guides on events and actions and shiny bindings