mschart2 R package

mschart2 is an experimental add-on build on top of the original mschart package. It is not a replacement for, nor is it affiliated with, the original project. All of the heavy lifting was done by David Gohel and the contributors at ArData — this fork simply tries to build a few extra features on top of their excellent work. We are enormously grateful for what they have created and shared with the community. See Acknowledgements below.

mschart2 is a drop-in successor to the mschart package. It provides a framework for easily creating charts for ‘Microsoft PowerPoint’ presentations, ‘Microsoft Word’ documents and ‘Microsoft Excel’ workbooks. It has to be used with package officer that will produce the charts in new or existing PowerPoint, Word or Excel files. With ‘Microsoft Charts’, the data is integrated into the document and linked to the chart. The result can be edited, annotated and resized. If the data is updated in the document, the chart is also updated.

mschart2 keeps the full mschart API and adds native chart features that were previously unavailable, including trendlines, error bars, multi-level (nested) category axes, reference lines, richer titles and footers, a one-call font control, leader lines and per-point data labels.

See vignette("mschart2") for a full guided tour of the new features.

Chart types

Classical charts (Office 2007+): ms_barchart(), ms_linechart(), ms_areachart(), ms_scatterchart(), ms_piechart(), ms_bubblechart(), ms_radarchart(), ms_stockchart().

chartEx charts (Office 2016+): ms_boxplotchart(), ms_funnelchart(), ms_histogramchart(), ms_paretochart(), ms_sunburstchart(), ms_treemapchart(), ms_waterfallchart().

Classical charts can be combined on the same plot area with ms_chart_combine().

New native features in mschart2

mschart2 adds several chart elements that the original package could not produce. Each is a small helper applied to an existing chart object:

library(officer)

# Trendline (regression / fit line) on a scatter or line series
scatter <- ms_scatterchart(data = mtcars, x = "wt", y = "mpg")
scatter <- chart_trendline(scatter, type = "linear", display_r_squared = TRUE)

# Error bars (fixed value, percentage, std dev / error, or custom vectors)
bars <- ms_barchart(
  data = data.frame(cat = c("A", "B", "C"), val = c(4, 7, 5)),
  x = "cat", y = "val"
)
bars <- chart_error_bars(bars, type = "stdDev", value = 1)

# Multi-level (nested) category axis, e.g. Quarter grouped under Year
nested <- data.frame(
  year    = rep(c("2023", "2024"), each = 4),
  quarter = rep(c("Q1", "Q2", "Q3", "Q4"), 2),
  sales   = c(10, 12, 9, 14, 11, 13, 12, 16)
)
nc <- ms_barchart(data = nested, x = "quarter", y = "sales")
nc <- chart_multilevel_axis(nc, levels = c("year", "quarter"))

# Reference / target line at a constant value
bars <- chart_reference_line(bars, value = 6, label = "Target", colour = "red")

# Rich title with subtitle + alignment, and a footer / source note
bars <- chart_title(bars, title = "Revenue", subtitle = "by category",
                    align = "left")
bars <- chart_footer(bars, text = "Source: internal data")

# Restyle every text element (title, axes, labels, legend, footer) at once
bars <- chart_font(bars, family = "Calibri")

# Leader lines and per-point data-label control
pie <- ms_piechart(data = data.frame(g = c("A", "B"), v = c(3, 7)),
                   x = "g", y = "v")
pie <- chart_labels_leaders(pie, show = TRUE)
bars <- chart_labels_at(bars, index = 1,
                        text = officer::fp_text(bold = TRUE, color = "red"))

# Number-format helpers for axes and labels (no raw Excel codes needed)
bars <- chart_ax_y(bars, num_fmt = fmt_thousands())

Every one renders as a genuine, editable Microsoft Office chart element, so they remain live when the underlying data is refreshed in the document.

Capability matrix

Feature	Function	New in mschart2
Trendline / fit line	chart_trendline()	Yes
Error bars	chart_error_bars()	Yes
Multi-level category axis	chart_multilevel_axis()	Yes
Reference / target line	chart_reference_line()	Yes
Rich title + subtitle + alignment	chart_title()	Yes
Footer / source note	chart_footer()	Yes
One-call font for all text	chart_font()	Yes
Data-label leader lines	chart_labels_leaders()	Yes
Per-point data labels	chart_labels_at()	Yes
Number-format helpers	fmt_number(), fmt_percent(), …	Yes
Box plot, histogram, pareto	ms_boxplotchart(), ms_histogramchart(), ms_paretochart()	Yes
Treemap, sunburst, funnel, waterfall	ms_treemapchart(), ms_sunburstchart(), ms_funnelchart(), ms_waterfallchart()	Yes

Example

This is a basic example which shows you how to create a bar chart.

library(mschart2)

sales <- data.frame(
  quarter = rep(c("Q1", "Q2", "Q3", "Q4"), each = 2),
  revenue = c(12, 9, 15, 11, 18, 14, 21, 17),
  region  = rep(c("EU", "US"), times = 4)
)

bars <- ms_barchart(
  data = sales, x = "quarter", y = "revenue", group = "region"
)

Then use package officer to send the object as a chart.

library(officer)
doc <- read_pptx()
doc <- add_slide(doc, layout = "Title and Content", master = "Office Theme")
doc <- ph_with(doc, value = bars, location = ph_location_fullsize())

print(doc, target = "example.pptx")

The same chart object can be dropped into an Excel sheet with officer::sheet_add_drawing(). By default the chart’s underlying data is written next to the chart automatically.

You can also write the data first with officer::sheet_write_data() and ask the chart to reuse it by passing write_data = FALSE. This is useful when the data should appear at a specific position, or when several charts share the same dataset:

wb <- read_xlsx()
wb <- add_sheet(wb, label = "sales")

# 1. Write the data on the sheet at the desired position.
wb <- sheet_write_data(wb, sheet = "sales", value = bars$data_series,
                       start_col = 1, start_row = 1)

# 2. Add the chart and tell it to reference the data already in place.
wb <- sheet_add_drawing(wb, sheet = "sales", value = bars,
                        write_data = FALSE,
                        start_col = 1, start_row = 1,
                        left = 5, top = 0.5, width = 6, height = 4)

print(wb, target = "example.xlsx")

Use print(your_chart, preview = TRUE) to open the chart in PowerPoint while iterating.

Installation

You can install the development version from GitHub:

devtools::install_github("martinctc/mschart2")

Contributing to the package

Bug reports

When you file a bug report, please spend some time making it easy for me to follow and reproduce. The more time you spend on making the bug report coherent, the more time I can dedicate to investigating the bug as opposed to the bug report.

Acknowledgements

mschart2 exists only because of the original mschart package created by David Gohel and the contributors at ArData, together with the wider officeverse ecosystem (officer and friends). Their work is what makes native, editable Microsoft Office charts from R possible at all.

This project is an experimental, community add-on that stands entirely on the shoulders of that work. We are deeply grateful for the years of effort, generosity and open-source stewardship the original authors have put in, and our only aim here is to build a few additional features on top of what they have so kindly shared. All original authorship, contributors and the MIT license are retained. If you find mschart2 useful, please consider starring and supporting the original project first.