How to plot in R with echarts4r

Hi. I’m Sharon Machlis at IDG Communications, here with Episode 56 of Do More With R: Plot in R with echarts4r.

ggplot2 is still my go-to for static plots. But I’m always on the lookout for new ways to make interactive graphs, tables, and maps. echarts4r is one of my new favorite packages: It’s intuitive, powerful, and flexible. And, as an editor, I appreciate well-thought-out documentation.

The package is an R wrapper for the echarts JavaScript library. Javascript echarts is now an official Apache Software Foundation project, it graduated from incubator status in December. That helps me feel confident I can rely on the JavaScript code underlying the R package.

So let’s take a look at echarts4r. Package author John Coene explains the basics in this getting started page. First thing to know: Every function in the package starts with e_.

You begin a visualization by creating an echarts object with the e_charts() function. That has a data frame as the first argument and the x-axis column as the second argument. John uses a pipe format in his examples, so I’ll follow his style: data frame name and pipe on the first line, e_charts() with the x-axis column on the second, and the type of chart – in his example, a line chart – with the y-axis series column on the third line of code. Let’s take a closer look at how this works.

For data, I downloaded and wrangled some housing price info by US city from Zillow. If you want to follow along, details are in this video’s related article. houses_wide has columns for month (I’m just looking at December for each year starting in 2007) for 9 cities.

Let’s start with the basics.

In this code, first I load the echarts4r and dplyr packages. Note I’m using the development version of echarts4r, which I installed from GitHub, to access the latest version of echarts.

My first step is to create an echarts object with my data frame, in this case houses_wide. If you’re familiar with ggplot, this first step is similar: It creates an object, but there’s no data in the visualization yet. You can see the x axis but no y axis or data. But look carefully at the x axis. I didn’t have to worry about the text labels on top of each other. echarts automatically displays only some of the x-axis values if there’s not enough room for all of them. Let me show this in RStudio.

Next, I’ll add the type of chart I want. For a line chart, that’s the e_line() function. That needs at least one argument, the column with the values. The argument is serie, that’s s-e-r-i-e, as in singular of series.

There are a lot of other chart types you can choose, including bar, area, scatter plots, boxplots, histograms, tree maps, even word clouds and pie charts and a LOT more. Even more than I’ve listed here, you can see the full list on the package Web site or in the help files.

Each of these functions take column names without quotation marks as arguments. That’s similar to how ggplot works. But most functions listed here have versions that take quoted column names. That lets you use variable names as arguments. John calls those “escape-hatch” functions, and they have an underscore at the end of the function name, like you see here. The “regular” e_line() function takes an unquoted column name. The “escape hatch” with the underscore takes the quoted column name. Here, I created variables for my x and y columns, and then used e_chart_() and e_line_() to use those variables. This makes it very simple to create functions out of your chart code!

Next, I’ll go back to my line chart and add a second city with another e_line() function. There are no tooltips displaying by default I can add those with the e_tooltips() function. Notice that commas are added to the tooltip values by default, which is nice.

But the tooltip here could be even more useful if I could see both values at the same time. I can do that with the tooltip argument trigger = axis.

I can turn this into a grouped bar chart just by swapping in e_bar() for e_line()

Did you notice how the numbers on the y axis have commas by default? Very handy not to have to add that in manually every time.

You’ll probably want to customize the colors for your graphs at some point. There are 13 built-in themes, which you can see on the echarts4r website.

I’ll change themes, but first let me save the graph I have now so far in a variable called p so I don’t run out of screen space.

I can add the bee-inspired theme to my p e_chart with e_theme(“bee-inspired”).

You can also create your own theme, or modify an existing one. And there’s an online tool to help! Let’s say I like most of the colors here but not the background. I can go into the Basic Config and change the background color to ivory. I can also change one of the colors I might not like. Now I need the resulting json file. Now I can use the e_theme_custom() function to add my theme to my graph.

OK now I think that ivory background is terrible on this graph. I can change to another theme; or I can simply customize it with the e_color() function and background argument. But because a theme is just a json file, it’s pretty human-readable. So it should be fairly easily to tweak it yourself and create a theme with everything you want.

You don’t need use a theme to customize your graph. You can set line colors with the e_color() function. The first argument for the e_color() function is a vector of colors for your lines, bars, points, whatever. Here I first create a vector of 3 colors – you see I can use color names or hex values. Then I just add that vector to e_color() as the first argument. I’m saving this new graph as variable p to make it easy to swap in new colors.

I don’t see RColorBrewer palettes built into echarts4r the way they are in ggplot, but it’s very easy to add them yourself. Here I loaded the RColorBrewer library and then created a vector of colors with the brewer.pal() function. I want 3 colors using the Dark2 palette (one of my favorites). Now those are my_colors in the graph.

By the way, this same format lets you use the R paletteer package to access a LOAD of R palettes from a lot of different palette packages. I can decide I want the first, second, and fifth colors from that Color_Blind palette for my 3-line graph.

I can store those as a vector in my_colors. If you’re not familiar with the paletteer package, the function paletteer_d() accesses any of the available discreet color palettes. Here I want Color_Blind from ggthemes, and I chose colors 1, 2, and 5 for my vector.

If there are a lot of series, you probably don’t want to type out each one by name. And, you don’t have to. echarts4r handles tidy data frames in long format elegantly, too. In this next group of examples, I’ll use a data frame in long format with condo price info. Columns are City, Month, Value, and HomeType.

Check this out: I used dplyr’s group_by() function on the data before running e_charts() on it. echarts4r understands that! Now if I tell echarts to use Month for the x axis and Value for the y axis, it knows to plot each group as a separate series! I’m saving this graph to a variable called myplot.

That legend at the top of the graph isn’t very helpful, though. If I want to find Tampa, I can mouse over; but it’s kind of hard to see with the other lines right near it. But never fear: You can customize the legend, too! (Of course)

Notice the 2 lines of code I added to myplot: e_grid() and e_legend(). That e_grid(right = ‘15%’) says that I want my main graph visualization to have 15% padding on the right side. The e_legend() function says to make the legend vertical instead of horizontal, add a 5 pixel padding on the right, and add a 15% padding on the top.

That helps, but if I want to only see Tampa, I need to click off every other legend item. Some interactive dataviz tools let you double click an item to just show that one. Echarts handles this a little differently: You can add buttons to “invert” the selection process, so you only see the items you click.

To do this, I added a selector argument to the e_legend() function. I saw those buttons in a sample echart JavaScript chart that used selector, but it’s not built-in functionality in echarts4r. John only hard-coded some of the functionality in the wrapper; but we can use all of it -- with the right syntax.

A quick detour for a little “how this works under the hood”. Here’s an example John has on the echarts4r site. You can see the original echarts JavaScript documentation at the top: tooltip.axisPointer.type. tooltip is an available echarts4r function, e_tooltip(), so we can use that in R. axisPointer is a tooltip option, but it’s not part of the R package. One of axisPointer’s options is type, which can have a value of line, shadow, none, or cross.

Now we need to translate that JavaScript into R. We can do that by using axisPointer as an argument of tooltip(). Makes sense. Here’s the important part: For the value of axisPointer, we create a list, with the list content type = ‘cross’.

If you know how this works, you have all the power and flexibility of the entire echarts JavaScript library, not only the functions and arguments John coded into the package.

Quick review: Here’s what the JavaScript documentation looks like and here’s how we should translate it into R for echarts4r.

To create two selector buttons, this is the JavaScript syntax. Here’s the R syntax: Each key-value pair gets its own list within the selector list. Everything’s a list, sometimes nested. That’s it!

OK let’s turn to something easier: a title for our chart. Echarts4r has an e_title() function that can take arguments text for the title text, subtext for the subtitle text, and also link and sublink if you want to add a clickable URL to either the title or subtitle.

If I want to change the alignment of the headline and subheadline, the argument is left. left can take a number for how much padding you want between the left edge and the start of text, but it also can take center or right for alignment as you see here. left = ‘center’ isn’t very intuitive for new users, but it does make some sense. Here’s what left = 10% looks like.

Next up: Sometimes you want to color by group. For these next demos, I’ll use a data set with columns for the city and month, value for condos, value for single-family homes, and “Region” which I just made up for purposes of coloring by group. Here’s a scatter plot to see if single-family and condo prices move in tandem. If I use dplyr’s group_by() on the data before creating a scatter plot, the plot is colored by region. I’m also able to set my dot size with symbol_size. I’ve added something else to my plot: a few “toolbox features”. You can see them at the top right of the graph. Here I’ve got zoom, reset, view the underlying data, and save the plot as an image. I’ll need to run this on RStudio so you can see how they work.

Echarts4r also has some statistical functions. Here I’m adding a linear regression line with e_lm(). There are a couple of other statistical functions, including error bars.

Now, I’d like to close this tour of echarts4r with some animations over time! For these demos, I’m going to use data from the US CDC on vaccinations by state: doses administered compared to vaccine doses received, to see which states are doing the best job of getting vaccines they have into people’s arms quickly. This data has columns for State, TotalDistributed (that’s how many the state received), TotalAdministered, ReportDate, Used (which is administered divided by distributed), PctUsed (Used as a percentage), and a column for what color I want each state to be. The bars will all be the same color except for the state I want to highlight, in this case Massachusetts, if I choose to do that.

Here’s code for an animated timeline. If I group my data by date, add timeline = TRUE to e_charts() and autoPlay = TRUE to the timeline options function, I get an autoplaying timeline! timeline = TRUE is a very easy way to animate data by time in a bar graph!

In the rest of this code, I set the bars to be all one color, using itemStyle and a list with color equals the color I want. The rest of the code is more styling: Turn the legend off, add labels for the bars with e_labels(), add a title with a font size of 24, and leave a 100-pixel space between the top of the graph grid and the top of the entire visualization.
> Here’s a look at the full chart, since the code cut off the bottom on the slide.

Animating a line chart is as easy as adding the e_animation() function. Charts are animated by default, but you can make the duration longer to create a more noticeable effect. I need to refresh the slide so you can see the animation when the page loads.

This is one of the coolest chart types. It’s available in echarts version 5. When I recorded this, you needed the GitHub version of echart4r to use version 5 features. This is a GIF, because my racing bars don’t render in my slide. But let me copy and paste the code and run it in RStudio so you can see that it works. I’ll be going over the code after.

Here’s the start of the racing bars. It’s a basic bar chart with timeline = TRUE, everything should look familiar. I start with my data frame, then use dplyr’s group_by() to group the data by date – you have to group by date for timelines and racing bars.

Then I create an e_charts object with State as my x axis with timeline = TRUE, and add e_bar() to make a bar chart using the PctUsed column for my values. The only new thing I’ve added is realtimeSort = TRUE.

The highlighted code within e_bar() is just setting a black border around my bars – not necessary, but I know some people like to do that. I also turn off the legend, since it’s not helpful here.

The next lines of highlighted code flip the graph from vertical to horizontal bars. E_y_axis inverse = TRUE sorts the bars from highest to lowest. This next group of highlighted code adds a value label to the bars at the inside right position. All the formatter = code lines are using JavaScript to make a custom format for how the labels appear – in this case I’m adding a percent sign. That’s optional. The format syntax is useful to know, though, because you can use the same syntax to customize tooltips. params.value[0] is the x-axis value and params.value[1] is the y-axis value. You concatenate values and strings together in JavaScript with the plus sign.

e_add() is where I map the colors in my data’s color column to the bars, using “itemStyle”. This is very different from ggplot and may take a little getting used to if you’re a tidyverse user. Finally, I add my title and subtitle, including a clickable URL for the subtitle, and I add some padding around the graph grid and the headline so they all don’t run into each other. And there you have it!

That’s it for this episode, thanks for watching! I hope you’ve enjoyed this introductory tour of echarts4r.

For more R tips – including a link to the article associated with this video – head to bit.ly/domorewithR, all lower case except for the R. Hope to see you next time! Stay healthy and safe everyone.