RMarkdown to Docx: Generic Report
generic_report.Rmd
# Install and load rdocx
library(rdocx)
#> Warning: replacing previous import 'dplyr::lag' by 'stats::lag' when loading
#> 'rdocx'
#> Warning: replacing previous import 'dplyr::filter' by 'stats::filter' when
#> loading 'rdocx'
# Load other required packages
library(flextable)
library(magrittr)Introduction
In this vignette we demonstrate using the rdocx package
for creating a Generic Report Document with the following workflow:
- The user populates the Rmarkdown template for their report.
- The user renders their report as a docx file that follows the style of the provided docx template.
- The user inspects the docx report and if changes are needed the user can re-generate the report by editing the Rmarkdown template and re-rendering the docx version.
1. Populating the Rmarkdown template
For illustrative purposes, a Generic Report Rmd template has been
created. In the rdocx package, the template is stored
here:
use_cases/01_generic_report/generic_report_template.Rmd
The template collects the key static elements that are common across all reports as well as examples of some dynamic elements.
If you are new to Rmarkdown then you may find this cheat sheet helpful.
Static elements
In the Rmarkdown template the following static elements are supported:
- Title Page
- Change log table
- Signatures table
- Activity table
Each of these elements are represented as classes in the
rdocx package. Below is an example of how these are
populated in the Rmarkdown template for the title page element. Each
attribute of the element has a unique entry that goes through a series
of checks once entered. For example, dates are checked to ensure they
are in dd-Mmm-yyyy format. If the package encounters an
unexpected entry the user is alerted through an error message.
# === Provide information for the title page ===
tp <- rdocx::TitlePage$new(
report_title= "Super cool document",
department = "Cool department",
study_title = "Compute super cool things",
study_number = "OWNDJQW9923",
status = "Draft",
version = "1",
date = "01-Feb-2024",
bus_class = "Confidential"
)
#> Loading required namespace: testthatCustom elements
Tables and Figures
A report can also contain dynamic elements such as tables and figures
from your analysis. These can be included by adding your R code that
generates these outputs directly to the Rmarkdown file. For example, the
following code will create a formatted table using the
flextable package.
# Generate example data
example_data <- data.frame(
column_1 = seq(12),
column_2 = rnorm(12, mean = 10, sd = 1),
column_3 = paste0(round(rbeta(12, 1, 1), 2)*100, "%")
)
# Make a table
example_data %>%
flextable::flextable() %>%
flextable::width(width = 2) %>%
# Make headers bold
flextable::bold(bold = TRUE, part = "header") %>%
# Use zebra theme for row colors
flextable::theme_zebra() %>%
# Define column names
flextable::set_header_labels(
column_1 = "Header 1",
column_2 = "Header 2",
column_3 = "Header 3"
) %>%
# Set borders
flextable::border_outer() %>%
flextable::border_inner_h() %>%
flextable::border_inner_v() %>%
# Add table captions
flextable::set_caption(
caption = "Table 1-2: This is an example table. Add caption text here.",
style = "Table Caption", autonum = "autonum"
)Header 1 |
Header 2 |
Header 3 |
|---|---|---|
1 |
8.599956 |
2% |
2 |
10.255317 |
95% |
3 |
7.562736 |
30% |
4 |
9.994429 |
97% |
5 |
10.621553 |
70% |
6 |
11.148412 |
52% |
7 |
8.178182 |
29% |
8 |
9.752675 |
82% |
9 |
9.755800 |
32% |
10 |
9.717295 |
36% |
11 |
9.446301 |
90% |
12 |
10.628982 |
23% |
2. Rendering your docx file
Now that the Rmarkdown template has been populated with your analysis you can begin the process of rendering your docx file. This process will use the Generic Report Template as the reference document; this document provides the title page structure and the layout style for rendering the docx file. Note that the path to the Generic Report Template is configured using the function .
If you’d like to get more information on the Generic Report Template version, please call the following function:
generic_report_template()
#> [1] "/home/runner/work/_temp/Library/rdocx/use_cases/00_word_templates/generic_report/Generic_Report_Template.docx"Let’s render!
# Template Rmarkdown file that include the details for your sample size report.
rmd_filename <- system.file(
"use_cases/01_generic_report/",
"generic_report_template.Rmd",
package = "rdocx"
)
# Specify the location where you would like your docx to be written.
# Here we use the same location as the Rmarkdown template.
output_path <- dirname(rmd_filename)
# Define the version (e.g., 0, 1, 12 which will be modified to follow version
# Numbering guidelines, e.g., _v00, _v01, v_12.) of your report that will be used
# to name your docx file
version <- 2
rdocx::rmd_render(
rmd_filename = rmd_filename,
output_path = output_path,
version = version
)
#> INFO [17:02:18.931] ======================== Generic Report Details ============================================================================
#> INFO [17:02:18.963] Document name: OWNDJQW9923_Compute_super_cool_things_Super_cool_document_v02.docx
#> INFO [17:02:18.970] Document location after rendering: /home/runner/work/_temp/Library/rdocx/use_cases/01_generic_report
#> INFO [17:02:18.972] Date and time: 2024-11-15 17:02:18.971469 UTC
#> INFO [17:02:18.973]
#> INFO [17:02:18.974] ======================== R session info ==========================================================================================
#> /home/runner/work/_temp/LibraryINFO [17:02:18.975]
#> /opt/R/4.4.2/lib/R/site-libraryINFO [17:02:18.977]
#> /opt/R/4.4.2/lib/R/libraryINFO [17:02:18.978]
#> INFO [17:02:18.979]
#> INFO [17:02:18.993] R version 4.4.2 (2024-10-31)
#> INFO [17:02:18.993] Platform: x86_64-pc-linux-gnu
#> INFO [17:02:18.993] Running under: Ubuntu 22.04.5 LTS
#> INFO [17:02:18.993]
#> INFO [17:02:18.993] Matrix products: default
#> INFO [17:02:18.993] BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
#> INFO [17:02:18.993] LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.20.so; LAPACK version 3.10.0
#> INFO [17:02:18.993]
#> INFO [17:02:18.993] locale:
#> INFO [17:02:18.993] [1] LC_CTYPE=C.UTF-8 LC_NUMERIC=C LC_TIME=C.UTF-8
#> INFO [17:02:18.993] [4] LC_COLLATE=C.UTF-8 LC_MONETARY=C.UTF-8 LC_MESSAGES=C.UTF-8
#> INFO [17:02:18.993] [7] LC_PAPER=C.UTF-8 LC_NAME=C LC_ADDRESS=C
#> INFO [17:02:18.993] [10] LC_TELEPHONE=C LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C
#> INFO [17:02:18.993]
#> INFO [17:02:18.993] time zone: UTC
#> INFO [17:02:18.993] tzcode source: system (glibc)
#> INFO [17:02:18.993]
#> INFO [17:02:18.993] attached base packages:
#> INFO [17:02:18.993] [1] stats graphics grDevices utils datasets methods base
#> INFO [17:02:18.993]
#> INFO [17:02:18.993] other attached packages:
#> INFO [17:02:18.993] [1] cowplot_1.1.3 ggplot2_3.5.1 lgr_0.4.4 R6_2.5.1
#> INFO [17:02:18.993] [5] kableExtra_1.4.0 dplyr_1.1.4 officer_0.6.7 magrittr_2.0.3
#> INFO [17:02:18.993] [9] flextable_0.9.7 rdocx_1.0.0
#> INFO [17:02:18.993]
#> INFO [17:02:18.993] loaded via a namespace (and not attached):
#> INFO [17:02:18.993] [1] gtable_0.3.6 xfun_0.49 bslib_0.8.0
#> INFO [17:02:18.993] [4] vctrs_0.6.5 tools_4.4.2 generics_0.1.3
#> INFO [17:02:18.993] [7] tibble_3.2.1 fansi_1.0.6 pkgconfig_2.0.3
#> INFO [17:02:18.993] [10] data.table_1.16.2 checkmate_2.3.2 RColorBrewer_1.1-3
#> INFO [17:02:18.993] [13] desc_1.4.3 uuid_1.2-1 lifecycle_1.0.4
#> INFO [17:02:18.993] [16] farver_2.1.2 compiler_4.4.2 stringr_1.5.1
#> INFO [17:02:18.993] [19] textshaping_0.4.0 brio_1.1.5 munsell_0.5.1
#> INFO [17:02:18.993] [22] fontquiver_0.2.1 fontLiberation_0.1.0 htmltools_0.5.8.1
#> INFO [17:02:18.993] [25] sass_0.4.9 yaml_2.3.10 pillar_1.9.0
#> INFO [17:02:18.993] [28] pkgdown_2.1.1 crayon_1.5.3 jquerylib_0.1.4
#> INFO [17:02:18.993] [31] openssl_2.2.2 cachem_1.1.0 magick_2.8.5
#> INFO [17:02:18.993] [34] fontBitstreamVera_0.1.1 tidyselect_1.2.1 zip_2.3.1
#> INFO [17:02:18.993] [37] digest_0.6.37 stringi_1.8.4 labeling_0.4.3
#> INFO [17:02:18.993] [40] fastmap_1.2.0 grid_4.4.2 colorspace_2.1-1
#> INFO [17:02:18.993] [43] cli_3.6.3 utf8_1.2.4 withr_3.0.2
#> INFO [17:02:18.993] [46] gdtools_0.4.1 scales_1.3.0 backports_1.5.0
#> INFO [17:02:18.993] [49] rmarkdown_2.29 jpeg_0.1-10 askpass_1.2.1
#> INFO [17:02:18.993] [52] ragg_1.3.3 png_0.1-8 evaluate_1.0.1
#> INFO [17:02:18.993] [55] knitr_1.49 testthat_3.2.1.1 viridisLite_0.4.2
#> INFO [17:02:18.993] [58] rlang_1.1.4 Rcpp_1.0.13-1 glue_1.8.0
#> INFO [17:02:18.993] [61] xml2_1.3.6 svglite_2.1.3 rstudioapi_0.17.1
#> INFO [17:02:18.993] [64] jsonlite_1.8.9 systemfonts_1.1.0 fs_1.6.5
#> INFO [17:02:18.995]
#> INFO [17:02:18.996] ====================================================================================================================================
#> INFO [17:02:18.998] Rendering completed.You should now have rendered your docx file in the location
output_path. Please review the rendering to ensure it is as
expected.
Logging your settings and session info
The rmd_render function also logs information to aid
reproducibility and traceability. The log file will be written to the
same location as the output_path. The log file will contain
the following information:
The template used
The name and location of your rendered docx file
The path from where your R libraries are loaded (i.e. the package bundle version)
The R session info provided by
sessionInfo()
👀 If you encounter an error please raise an issue for the {rdocx} package team.