The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

WordR Package

Tomas Hovorka (tomashovorka@seznam.cz)

2023-01-03

WordR package enables creating MS Word files (.docx) from given MS Word template. It can evaluate inline R code, insert tables and plots. WordR package is technically a wrapper around a powerful package officer.

Motivation

R language has many ways for producing state-of-the-art reports. For example rmarkdown or Sweave packages are very effective in preparing reports in PDF format or R2wd for creating a MS Word report from scratch. However, such techniques has some drawbacks:

For nontechnical person it is very difficult to prepare the source (template) file.
It is not conveniently possible to further edit the resulting report (if rendered into e.g. PDF).
Formatting possibilities with rmarkdown or R2wd are limited and with Sweave complicated (LateX knowledge required).

On the other hand, WordR package, enables

preparation of the source file in MS Word, with all the bells and whistles it offers (and drawbacks!),
result is also editable MS Word document,
such document can be later saved as PDF from MS Word if needed.

To conclude, WordR package is useful, for example, when you need to

periodically prepare static report and/or
want non-technical people (who can use MS Word but not R) to be able to prepare majority of the template and/or
want the resulting report being editable, for example, for adding additional custom interpretation, based on the current results, without need to change the input template.

How to use the WordR package

All examples, and instructions given in this document applies to MS Word 2013. No major differences are expected to other versions (as of 2017).

Template preparation

First we need to create a template (.docx) file. Such file may contain any formatting MS Word allows. Apart from that, the template may contain two other things:

inline R code
bookmarks for inserting Tables or Plots

Examples can be found in the examples folder of the package.

Creating inline R code

This functionality enables including simple R expression(s) in the Word document, which is evaluated during file rendering. The result of the expression need to be a string of length one (or something coercible to character(1)). Line breaks cannot be inserted in this way. Because of used workflow, each R inline expression need to be a separate paragraph. However, MS Word offers a way how to do an inline paragraph. Steps for creating an inline expression:

Open MS Word, create a new file or open an existing one
locate the cursor on the place where you want to have the R expression
insert style separator by pressing Ctrl+Alt+Enter (it is preferable to have formatting symbols visible by clicking the “new line” sign button on Home>Paragraph panel in MS Word)
type `r expression`, where expression is R expression like 1+1.
insert style separator again
if you want the result to be in non-default format, insert cursor into the inline code area and select the desired format from Styles menu. (Do not select the r code as that would change the style for the text not the whole r inline code paragraph)

As a result you should see something like this: Inline Code

Example can be seen in file examples/templates/template1.docx.

Troubleshooting the inline code

How to insert corect (straight) quotes (' or "): MS Word is, by default (maybe depends on local settings), changing the quotes to ‘Smart quotes’. You can change it the MS Word settings under Proofing > AutoCorrect Options > Autoformat as you type... You can de-select Straight Quotes as Smart Quotes and that should revert the quotes to being straight. Or when typing, right after you type a quote, if Word turns it into a “smart quote,” immediately press Ctrl-Z.
The expression does not evaluate as expected: Just try to evaluate it in the environment where you are running the renderInlineCode function, and make sure its output is character of length one.
The output is not in desired style: insert cursor into the inline code paragraph and select the desired style from Styles menu in MS Word.

Inserting bookmarks for Plots or Tables

Example and more info about bookmarks in MS Word can be seen in file examples/templates/templateFT.docx

To render a table on a given place, just insert a bookmark with name t_XYZ where XYZ will be a name of a flextable (flextable::flextable) table.

To render a plot on a given place, just insert a bookmark with name p_XYZ where XYZ will be a name of plot function.

Template rendering

Functions for rendering the MS Word file are the main content of the WordR package. Typical rendering R script contains following steps:

calculation of the outputs - tables, plots and values for inline expressions
running renderInlineCode on the prepared template file
running body_add_flextables on the file resulting from previous step
running addPlots on the file resulting from previous step

Alternatively, from v0.3.3 renderAll function is available, which is a wrapper around those three rendering functions.

Examples can be seen in examples/examples.R.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.