Chapter 10 Charts with mschart

Package mschart lets R users to create Microsoft Office charts from data, and then add title, legends, and annotations to the chart object.

The graph produced is a Microsoft graph, which means that it can be edited in your Microsoft software and that the underlying data are available.

The package will not allow you to make the same charts as with ggplot2. It allows only a subset of the charts possible with ‘Office Chart’. The package is often used to industrialize graphs that are then consumed and annotated by non-R users.

10.1 How to create a chart

Names of high level functions are all prefixed with ms_. The following charts are the only available from all possible MS charts:

  • barcharts: ms_barchart()
  • line charts: ms_linechart()
  • scatter plots: ms_scatterchart()
  • area charts: ms_areachart()

They all are producing a chart that can be quickly previewed with command:

print(the_chart, preview = TRUE)

After the creation of the object, it can be customized

  • by using options specific to the chart (with chart_settings()),
  • by changing the options related to the axes (with chart_ax_x() and chart_ax_y()),
  • by changing the options related to the labels (with chart_data_labels()),
  • by changing the colors, line widths, … with functions
    • chart_labels_text()
    • chart_data_fill()
    • chart_data_line_style()
    • chart_data_line_width()
    • chart_data_size()
    • chart_data_smooth()
    • chart_data_stroke()
    • chart_data_symbol()
  • by changing the general theme with function chart_theme(),
  • by changing the title labels with function chart_labels().

10.2 Quick start

10.2.1 Call an high level function

We need to call an high level function (one of those starting with ms_). These functions accept the following arguments:

  • data: the data.frame containing the data to be plotted.
  • x, y, the names of x and y columns.
  • eventually group: a column name that contains the groups that will separate the data into distinct series.
  • eventually labels: a column name that will be used as labels associated with the graphic elements. If more than a value, the first value is used for custom labels, the other columns will be written in the underlying ‘Microsoft Excel’ file so that users can manually choose these labels.
my_barchart <- ms_barchart(data = browser_data, 
  x = "browser", y = "value", group = "serie")

10.2.2 Write charts in Microsoft documents

Let’s have a look at the result by sending it to a new PowerPoint presentation:

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = my_barchart, location = ph_location_fullsize())
print(doc, target = "reports/barchart_01_stacked_powerpoint.pptx")

Note you can quickly preview the chart in a PowerPoint file by calling:

print(my_barchart, preview = "pptx")

Or in a new Word document:

doc <- read_docx()
doc <- body_add_chart(doc, chart = my_barchart, style = "Normal")
print(doc, target = "reports/barchart_01_stacked_word.docx")

10.3 Customise charts

Charts are generated with default values. Options are available to change charts properties.

  • Global chart settings can be specified with generic function chart_settings(). Each type of chart has its own set of parameters.

The following code stacks the bars for each group.

my_barchart <- chart_settings( my_barchart, grouping = "stacked", gap_width = 50, overlap = 100 )
  • Axis properties are available with functions chart_ax_x() and chart_ax_y():
my_barchart <- chart_ax_x(my_barchart, cross_between = 'between', 
  major_tick_mark = "in", minor_tick_mark = "none")
my_barchart <- chart_ax_y(my_barchart, num_fmt = "0.00", rotation = -90)
  • Titles (main title, axis labels) can be set with function chart_labels():
my_barchart <- chart_labels(my_barchart, title = "A main title", 
  xlab = "x axis title", ylab = "y axis title")
  • Series visual settings can be customized with functions chart_data_fill(), chart_data_stroke(), chart_data_size(), chart_data_symbol(),
    chart_data_line_width(), chart_data_line_style() and chart_labels_text():
my_barchart <- chart_data_fill(my_barchart,
  values = c(serie1 = "#003C63", serie2 = "#ED1F24", serie3 = "#F2AA00") )
my_barchart <- chart_data_stroke(my_barchart, values = "transparent" )
doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = my_barchart, location = ph_location_fullsize())
print(doc, target = "reports/barchart_02_custom_powerpoint.pptx")

  • Global visual settings (e.g. groups fill and stroke colours) can be customised with functions set_theme().

10.4 Chart settings

Chart settings are general options relative to the graphic layout, such as grouping options (stacked, clustered, etc.) or scatter plot style (markers only, lines and markers, etc.).

Chart settings can be changed with function chart_settings(), a generic function, each type of chart has its own method. I encourage you to open the documentation of the function which details the appropriate parameters for each type of graph.

The following examples are illustrating usage of chart_settings with two different chart types:

my_bc_01 <- ms_barchart(
    data = browser_data, x = "browser", y = "value", group = "serie") %>% 
  chart_settings( dir = "vertical", grouping = "stacked", overlap = 100 )

my_bc_02 <- ms_barchart(
    data = browser_data, x = "browser", y = "value", group = "serie") %>% 
  chart_settings( dir = "vertical", grouping = "clustered", 
                  gap_width = 400, overlap = -100 )

my_sc_01 <- ms_scatterchart(
  data = mtcars, x = "disp", y = "drat") %>% 
  chart_settings(scatterstyle = "marker")

my_sc_02 <- ms_scatterchart(
  data = mtcars, x = "disp", y = "drat") %>% 
  chart_settings(scatterstyle = "lineMarker")
layout <- "Title and Content"
master <- "Office Theme"
read_pptx() %>% 
  add_slide(layout, master) %>% 
  ph_with(my_bc_01, location = ph_location_fullsize()) %>% 
  add_slide(layout, master) %>% 
  ph_with(my_bc_02, location = ph_location_fullsize()) %>% 
  add_slide(layout, master) %>% 
  ph_with(my_sc_01, location = ph_location_fullsize()) %>% 
  add_slide(layout, master) %>% 
  ph_with(my_sc_02, location = ph_location_fullsize()) %>% 
  print(target = "reports/chart_settings_01.pptx")

As bar charts can be complex to configure, helper function barchart_options() is provided.

10.5 Theme

A theme is a set of parameters (i.e. colors, fonts) that can be applied to a chart. As for ggplot objects, a theme is controling the appearance of non-data components of the plot.

Let’s first create a chart:

my_bc <- ms_barchart(
  data = browser_data, x = "browser", y = "value", group = "serie") %>% 
  as_bar_stack( ) %>% 
  chart_labels(title = "Title example", xlab = "x label", ylab = "y label")

… and add that chart in a PowerPoint file with officer:

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = my_bc, location = ph_location_fullsize())
print(doc, target = "reports/theme_00.pptx")

mschart is providing an interface to themes with function set_theme(). This function is using an object produced by mschart_theme(). The following are the supported arguments of the function:

  • axis_text
  • axis_text_x
  • axis_text_y
  • axis_ticks
  • axis_ticks_x
  • axis_ticks_y
  • axis_title
  • axis_title_x
  • axis_title_y
  • date_fmt
  • double_fmt
  • grid_major_line
  • grid_major_line_x
  • grid_major_line_y
  • grid_minor_line
  • grid_minor_line_x
  • grid_minor_line_y
  • integer_fmt
  • legend_position
  • legend_text
  • main_title
  • str_fmt
  • title_rot
  • title_x_rot
  • title_y_rot
mytheme <- mschart_theme(
  axis_title = fp_text(color = "#0D6797", font.size = 20, italic = TRUE),
  main_title = fp_text(color = "#0D6797", font.size = 24, bold = TRUE),
  grid_major_line = fp_border(color = "#AA9961", style = "dashed"),
  axis_ticks = fp_border(color = "#AA9961") 
  )
my_bc <- set_theme(my_bc, mytheme)
doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = my_bc, location = ph_location_fullsize())
print(doc, target = "reports/theme_01.pptx")

Some elements are inheriting properties from other theme elements. For example, axis_title_x and axis_title_y inherit from axis_title and are all expecting a fp_text; grid_major_line_x and grid_major_line_y inherit from grid_major_line and are all expecting a fp_border.

An helper function is provided to allow modifications of elements of the chart theme:

my_bc <- chart_theme( x = my_bc, 
  axis_title_x = fp_text(color = "red", font.size = 11),
  main_title = fp_text(color = "red", font.size = 15),
  legend_position = "t" )
doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = my_bc, location = ph_location_fullsize())
print(doc, target = "reports/theme_02.pptx")

10.6 Bar charts

Bar charts illustrate comparisons among individual items. In a bar chart, the categories are typically organized along the vertical axis, and the values along the horizontal axis.

10.6.1 grouped bars

my_barchart_01 <- ms_barchart(
  data = browser_data, x = "browser",
  y = "value", group = "serie"
)
doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = my_barchart_01, location = ph_location_fullsize())
print(doc, target = "reports/gallery_bar_01.pptx")

10.6.2 vertical stacked bars

as_bar_stack() is an helper function.

my_barchart_02 <- as_bar_stack(my_barchart_01)

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = my_barchart_02, location = ph_location_fullsize())
print(doc, target = "reports/gallery_bar_02.pptx")

10.6.3 horizontal stacked bars

  • Values
my_barchart_03 <- as_bar_stack(my_barchart_01, dir = "horizontal")

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = my_barchart_03, location = ph_location_fullsize())
print(doc, target = "reports/gallery_bar_03.pptx")

  • Percent
my_barchart_04 <- as_bar_stack(my_barchart_01, dir = "horizontal", 
  percent = TRUE)

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = my_barchart_04, location = ph_location_fullsize())
print(doc, target = "reports/gallery_bar_04.pptx")

10.7 Line charts

In a line chart, category data is on x axis, and value data is on the y axis. Line charts can show continuous data over time on an evenly scaled axis.

data <- data.frame(
  supp = factor(rep(c("OJ", "VC"), each = 3), levels = c("OJ", "VC")),
  dose = factor(rep(c("low", "medium", "high"), 2), levels = c("low", "medium", "high")),
  length = c(13.23, 22.7, 26.06, 7.98, 16.77, 26.14), 
  stringsAsFactors = FALSE)

lc_01 <- ms_linechart(data = data, x = "dose", y = "length", group = "supp")

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = lc_01, location = ph_location_fullsize())
print(doc, target = "reports/gallery_line_01.pptx")

10.7.1 With dates

Auto detection of dates is not yet implemented, sorry. You will need to specify the num_fmt argument.

lc_02 <- ms_linechart(data = browser_ts, x = "date",
                      y = "freq", group = "browser")
lc_02 <- chart_ax_x(lc_02, num_fmt = "m/d/yy")

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = lc_02, location = ph_location_fullsize())
print(doc, target = "reports/gallery_line_02.pptx")

10.7.2 Smoothed lines

It’s easy to smooth a line (or all lines) by using chart_data_smooth().

linec <- ms_linechart(data = iris, x = "Sepal.Length", y = "Sepal.Width", 
  group = "Species")
#> Warning in ms_linechart(data = iris, x = "Sepal.Length", y = "Sepal.Width", :
#> using continuous data in the x-axis is not an expected representation, the next
#> versions will prevent this.
linec_smooth <- chart_data_smooth(linec, 
  values = c(virginica = 1, versicolor = 0, setosa = 0) )

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = linec_smooth, location = ph_location_fullsize())
print(doc, target = "reports/gallery_line_04.pptx")

10.8 Area chats

Area charts can be used to plot change over time and draw attention to the total value across a trend. By showing the sum of the plotted values, an area chart also shows the relationship of parts to a whole.

ac_01 <- ms_areachart(data = data, x = "dose", 
  y = "length", group = "supp")

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = ac_01, location = ph_location_fullsize())
print(doc, target = "reports/gallery_area_01.pptx")

If using an x axis with date values, you will have to set a format with parameter num_fmt (with “m/d/yy” for example) in a call to chart_ax_x.

ac_02 <- ms_areachart(data = browser_ts, x = "date",
  y = "freq", group = "browser")
ac_02 <- chart_settings(ac_02, grouping = "percentStacked")
ac_02 <- chart_ax_x(ac_02, cross_between = "midCat", num_fmt = "m/d/yy")

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = ac_02, location = ph_location_fullsize())
print(doc, target = "reports/gallery_area_02.pptx")

10.9 Scatter plots

A scatter chart has two value axes: a horizontal (x) and a vertical (y) value axis. It combines x and y values into single data points and shows them in irregular intervals, or clusters. Scatter charts are typically used for showing and comparing numeric values.

sc_01 <- ms_scatterchart(data = mtcars, x = "disp", y = "drat", group = "gear")
sc_01 <- chart_settings(sc_01, scatterstyle = "marker")

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = sc_01, location = ph_location_fullsize())
print(doc, target = "reports/gallery_scatter_01.pptx")

Scatter plots can be customized. For example, it is possible to join the dots of only one category:

dat <- expand.grid(type = c("N", "S", "V", "X", "Y"),
            y = 1:20)
dat$value = rnorm(n = nrow(dat), mean = 50, sd = 4)

sc_02 <- ms_scatterchart(data = dat, x = "value", y = "y", group = "type")
sc_02 <- chart_settings(sc_02, style = "lineMarker")
sc_02 <- chart_data_line_style(sc_02,
  values = c("X" = "solid", "Y" = "none", "V" = "none", "N" = "none", "S" = "none") )

doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = sc_02, location = ph_location_fullsize())
print(doc, target = "reports/gallery_scatter_02.pptx")

10.10 Custom labels

You can use custom data labels in a chart by specifying a data label column.

The data.frame below contains a column named label. It is made of some text and unicodes for emoji (thanks to package emojifont). See this table for a complete list: https://apps.timwhitlock.info/emoji/tables/unicode

dat_no_group <- data.frame(
  stringsAsFactors = FALSE,
  cut = c("Fair", "Good", "Very Good", "Premium", "Ideal"),
  carat = c(1, 0.82, 0.71, 0.86, 0.54),
  n = c(1610L, 4906L, 12082L, 13791L, 21551L),
  label = c("\U0001f603", "\U0001f525", "", "Hello \U0001f47d", "\U0001f44e"),
  group = c("OK", "KO", "KO", "KO", "KO")
)
dat_no_group

We can use that column as label column when calling ms_barchart and other high level functions :

chrt <- ms_barchart(
  data = dat_no_group, group = "group",
  x = "cut", labels = "label", y = "n"
)
chrt <- chart_settings(chrt,
  vary_colors = TRUE,
  grouping = "standard",
  overlap = 90, gap_width = 150
)
chrt <- chart_data_labels(chrt, position = "outEnd")

chrt <- chart_data_fill(chrt, values = c(KO = "#0088CC", OK = "red"))
chrt <- chart_data_stroke(chrt, "transparent")

chrt <- chart_labels_text(chrt, fp_text(font.size = 20))
doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = chrt, location = ph_location_fullsize())
print(doc, target = "reports/chrt_with_label_01.pptx")

This feature should be used sparingly. For example, adding a label on each point of a scatter plot can result in an overloaded and unreadable graph.

As demonstrated in the previous example, when you need to change the font, color, size of labels, you can use function chart_labels_text() that accept an object returned by function officer::fp_text().