Skip to contents

This R6 class allows to, given a template word document and a list of outputs, to add them at the given location in the text. It automates the time-consuming task of adding and formatting tables and figures to a word document. The two main inputs of the class are a template docx file, in this case a clinical trial report and a yaml file that will contain the names of the table/figures to be replaced and pointing to the new ones. The yml file, should have predefined structure and parameters to be set:

  • type. Indicates if it is a table (TBL) or a figure (FIG)

  • title. The title or caption of the table/figure in the template docx file

  • file. The name of the file (csv or image) to be used in the new version of the docx

  • widths. For tables only, a pre-defined column widths (useful for model parameter table, for example)

  • occurrence. Int. To be used when captions are duplicated for more than one figure/table. To set the order they appear in the word document.

An example of the yaml structure:


output_1:
  type: TBL
  title: "Caption of the output 1"
  file: output_1.csv
  widths: ~
  occurrence: ~
output_2:
  type: FIG
  title: "Caption of the output 2"
  file: output_2.png
  

Active bindings

template_docx_filename

Active binding for setting the path to the template docx

outputs_path

Active binding for setting the path to the folder with the outputs

doc_final_filename

Active binding for setting the path for the updated docx file

yml_filename

Active binding for setting the path to the yaml file

Methods


Method new()

Usage

ReplaceOutputs$new(
  template_docx_filename = NA_character_,
  outputs_path = NA_character_,
  doc_final_filename = NA_character_,
  yml_filename = NA_character_
)

Arguments

template_docx_filename

String. File name of the template docx to be modified. For example, "/path/to/file/filename.docx"

outputs_path

String. Path to the folder with the outputs (figures and tables-csvs) that will be added to the new version of the docx

doc_final_filename

String. File name of the updated version of the docx file. For example, "/path/to/file/filename_updated.docx"

yml_filename

String. File name of the yaml file that will guide the replacement of the outputs (tables and figures) in the updated docx. For example, "/path/to/file/filename.yml"

Examples

uo <- ReplaceOutputs$new(
   template_docx_filename = system.file("use_cases/02_automated_reporting",
                                        "Automated_Reporting_Example.docx",
                                        package="rdocx"),
   outputs_path = system.file("use_cases/02_automated_reporting/example_outputs",
                              package="rdocx"),
   doc_final_filename = "./test.docx",
   yml_filename = system.file("use_cases/02_automated_reporting",
                              "example_yml_1.yml",
                              package="rdocx")
 )


Method get_captions_to_yml()

Get captions to yaml Given a docx file, it scans the document to find the Figures and Tables captions and provides a yaml file with all the figures and tables found. It also scans the document for possible "Source:" which has to be after a placeholder figure/table. If source was found, it will be added to "file" param in the yaml file.

Usage

ReplaceOutputs$get_captions_to_yml(yml_caption_filename)

Arguments

yml_caption_filename

String. File name of the newly created yaml file that will contain the Figures and Tables of in the provided docx document. For example, "/path/to/file/filename.yml" It will follow the required format for the replacement of the outputs (tables and figures) to update docx.


output_1:
  type: TBL
  title: "Caption of the output 1"
  file: ~
  widths: ~
  occurrence: ~
output_2:
  type: FIG
  title: "Caption of the output 2"
  file: ~
  widths: ~
  occurrence: ~
  

Examples

uo <- ReplaceOutputs$new(
   template_docx_filename = system.file("use_cases/02_automated_reporting",
                                        "Automated_Reporting_Example.docx",
                                        package="rdocx"),
   outputs_path = system.file("use_cases/02_automated_reporting/example_outputs",
                              package="rdocx"),
   doc_final_filename = "./test.docx"
 )
uo$get_captions_to_yml(yml_caption_filename="./test_yml.yml")


Method update_all_outputs()

Update all outputs. It iterates through all the outputs in the yml file, and assigns them in the correct location in the updated docx. If no "file" param given (NA or NULL), it will skip the output.

Usage

ReplaceOutputs$update_all_outputs()

Examples

uo <- ReplaceOutputs$new(
   template_docx_filename = system.file("use_cases/02_automated_reporting",
                                        "Automated_Reporting_Example.docx",
                                        package="rdocx"),
   outputs_path = system.file("use_cases/02_automated_reporting/example_outputs",
                              package="rdocx"),
   doc_final_filename = "./test.docx",
   yml_filename = system.file("use_cases/02_automated_reporting",
                              "example_yml_1.yml",
                              package="rdocx")
 )
uo$update_all_outputs()


Method clone()

The objects of this class are cloneable with this method.

Usage

ReplaceOutputs$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples


## ------------------------------------------------
## Method `ReplaceOutputs$new`
## ------------------------------------------------

uo <- ReplaceOutputs$new(
   template_docx_filename = system.file("use_cases/02_automated_reporting",
                                        "Automated_Reporting_Example.docx",
                                        package="rdocx"),
   outputs_path = system.file("use_cases/02_automated_reporting/example_outputs",
                              package="rdocx"),
   doc_final_filename = "./test.docx",
   yml_filename = system.file("use_cases/02_automated_reporting",
                              "example_yml_1.yml",
                              package="rdocx")
 )


## ------------------------------------------------
## Method `ReplaceOutputs$get_captions_to_yml`
## ------------------------------------------------

uo <- ReplaceOutputs$new(
   template_docx_filename = system.file("use_cases/02_automated_reporting",
                                        "Automated_Reporting_Example.docx",
                                        package="rdocx"),
   outputs_path = system.file("use_cases/02_automated_reporting/example_outputs",
                              package="rdocx"),
   doc_final_filename = "./test.docx"
 )
uo$get_captions_to_yml(yml_caption_filename="./test_yml.yml")


## ------------------------------------------------
## Method `ReplaceOutputs$update_all_outputs`
## ------------------------------------------------

uo <- ReplaceOutputs$new(
   template_docx_filename = system.file("use_cases/02_automated_reporting",
                                        "Automated_Reporting_Example.docx",
                                        package="rdocx"),
   outputs_path = system.file("use_cases/02_automated_reporting/example_outputs",
                              package="rdocx"),
   doc_final_filename = "./test.docx",
   yml_filename = system.file("use_cases/02_automated_reporting",
                              "example_yml_1.yml",
                              package="rdocx")
 )
uo$update_all_outputs()
#> INFO  [15:20:46.836] Word template filename:  /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/Automated_Reporting_Example.docx
#> INFO  [15:20:46.867] Outputs path:  /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/example_outputs
#> INFO  [15:20:46.874] Yml filename:  /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/example_yml_1.yml
#> INFO  [15:20:46.875] Final doc filename:  ./test.docx
#> INFO  [15:20:46.876] Date and time: 2024-11-19 15:20:46.8759 UTC
#> INFO  [15:20:46.877] DaVinci user:  runner
#> INFO  [15:20:46.878] ****************************************************************
#> INFO  [15:20:46.919] Output: FIG Data Point Distribution in Sample Set A
#> INFO  [15:20:47.160] Figure updated with: /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/example_outputs/Figure_2_1_Data_Point_Distribution.png
#> INFO  [15:20:47.161] Output: FIG Comparative Analysis of Categories X and Y
#> INFO  [15:20:47.358] Figure updated with: /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/example_outputs/Figure_2_2_Comparative_Analysis.png
#> INFO  [15:20:47.359] Output: FIG Comparative Analysis of Categories X and Y
#> INFO  [15:20:47.559] Figure updated with: /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/example_outputs/Figure_2_3_Comparative_Analysis.png
#> INFO  [15:20:47.560] Output: FIG Trend Analysis Over Time (Yearly Data)
#> INFO  [15:20:47.755] Figure updated with: /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/example_outputs/Figure_2_4_Trend_Analysis.png
#> INFO  [15:20:47.756] Output: FIG Trend Analysis Over Time (Yearly Data)
#> INFO  [15:20:47.951] Figure updated with: /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/example_outputs/Figure_2_5_Trend_Analysis.png
#> INFO  [15:20:47.952] Output: FIG Trend Analysis Over Time (Monthly Data)
#> INFO  [15:20:48.146] Figure updated with: /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/example_outputs/Figure_3_1_Trend_Analysis.png
#> INFO  [15:20:48.147] Output: TBL Summary of Sample Statistics
#> INFO  [15:20:48.247] Table updated with: /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/example_outputs/Table_2_1_Sample_Statistics.csv
#> INFO  [15:20:48.248] Output: TBL Breakdown of Category X by Subcategory
#> INFO  [15:20:48.338] Table updated with: /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/example_outputs/Table_2_2_Breakdown_of_Category_X.csv
#> INFO  [15:20:48.339] Output: TBL Yearly Performance Metrics
#> INFO  [15:20:48.453] Table updated with: /home/runner/work/_temp/Library/rdocx/use_cases/02_automated_reporting/example_outputs/Table_3_1_Yearly_Performance_Metrics.csv
#> INFO  [15:20:48.612] Docx saved!! File located at: ./test.docx
#> INFO  [15:20:48.613] ****************************************************************
#> INFO  [15:20:48.614] Information about this R session
#> INFO  [15:20:48.615] [1] "/home/runner/work/_temp/Library" "/opt/R/4.4.2/lib/R/site-library"
#> INFO  [15:20:48.615] [3] "/opt/R/4.4.2/lib/R/library"
#> INFO  [15:20:48.616] ****************************************************************
#> INFO  [15:20:48.629] R version 4.4.2 (2024-10-31)
#> INFO  [15:20:48.629] Platform: x86_64-pc-linux-gnu
#> INFO  [15:20:48.629] Running under: Ubuntu 22.04.5 LTS
#> INFO  [15:20:48.629]
#> INFO  [15:20:48.629] Matrix products: default
#> INFO  [15:20:48.629] BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
#> INFO  [15:20:48.629] LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.20.so;  LAPACK version 3.10.0
#> INFO  [15:20:48.629]
#> INFO  [15:20:48.629] locale:
#> INFO  [15:20:48.629]  [1] LC_CTYPE=C.UTF-8       LC_NUMERIC=C           LC_TIME=C.UTF-8
#> INFO  [15:20:48.629]  [4] LC_COLLATE=C           LC_MONETARY=C.UTF-8    LC_MESSAGES=C.UTF-8
#> INFO  [15:20:48.629]  [7] LC_PAPER=C.UTF-8       LC_NAME=C              LC_ADDRESS=C
#> INFO  [15:20:48.629] [10] LC_TELEPHONE=C         LC_MEASUREMENT=C.UTF-8 LC_IDENTIFICATION=C
#> INFO  [15:20:48.629]
#> INFO  [15:20:48.629] time zone: UTC
#> INFO  [15:20:48.629] tzcode source: system (glibc)
#> INFO  [15:20:48.629]
#> INFO  [15:20:48.629] attached base packages:
#> INFO  [15:20:48.629] [1] stats     graphics  grDevices utils     datasets  methods   base
#> INFO  [15:20:48.629]
#> INFO  [15:20:48.629] other attached packages:
#> INFO  [15:20:48.629] [1] rdocx_1.0.0
#> INFO  [15:20:48.629]
#> INFO  [15:20:48.629] loaded via a namespace (and not attached):
#> INFO  [15:20:48.629]  [1] xfun_0.49               bslib_0.8.0             httr2_1.0.6
#> INFO  [15:20:48.629]  [4] vctrs_0.6.5             tools_4.4.2             generics_0.1.3
#> INFO  [15:20:48.629]  [7] curl_6.0.1              tibble_3.2.1            fansi_1.0.6
#> INFO  [15:20:48.629] [10] pkgconfig_2.0.3         data.table_1.16.2       checkmate_2.3.2
#> INFO  [15:20:48.629] [13] desc_1.4.3              uuid_1.2-1              lifecycle_1.0.4
#> INFO  [15:20:48.629] [16] flextable_0.9.7         compiler_4.4.2          stringr_1.5.1
#> INFO  [15:20:48.629] [19] textshaping_0.4.0       brio_1.1.5              fontawesome_0.5.3
#> INFO  [15:20:48.629] [22] fontquiver_0.2.1        fontLiberation_0.1.0    htmltools_0.5.8.1
#> INFO  [15:20:48.629] [25] sass_0.4.9              yaml_2.3.10             pillar_1.9.0
#> INFO  [15:20:48.629] [28] pkgdown_2.1.1           crayon_1.5.3            jquerylib_0.1.4
#> INFO  [15:20:48.629] [31] whisker_0.4.1           openssl_2.2.2           cachem_1.1.0
#> INFO  [15:20:48.629] [34] magick_2.8.5            fontBitstreamVera_0.1.1 tidyselect_1.2.1
#> INFO  [15:20:48.629] [37] zip_2.3.1               digest_0.6.37           stringi_1.8.4
#> INFO  [15:20:48.629] [40] dplyr_1.1.4             purrr_1.0.2             fastmap_1.2.0
#> INFO  [15:20:48.629] [43] grid_4.4.2              cli_3.6.3               magrittr_2.0.3
#> INFO  [15:20:48.629] [46] utf8_1.2.4              withr_3.0.2             gdtools_0.4.1
#> INFO  [15:20:48.629] [49] backports_1.5.0         rappdirs_0.3.3          rmarkdown_2.29
#> INFO  [15:20:48.629] [52] officer_0.6.7           jpeg_0.1-10             askpass_1.2.1
#> INFO  [15:20:48.629] [55] ragg_1.3.3              png_0.1-8               memoise_2.0.1
#> INFO  [15:20:48.629] [58] evaluate_1.0.1          knitr_1.49              testthat_3.2.1.1
#> INFO  [15:20:48.629] [61] rlang_1.1.4             downlit_0.4.4           Rcpp_1.0.13-1
#> INFO  [15:20:48.629] [64] glue_1.8.0              xml2_1.3.6              rstudioapi_0.17.1
#> INFO  [15:20:48.629] [67] jsonlite_1.8.9          lgr_0.4.4               R6_2.5.1
#> INFO  [15:20:48.629] [70] systemfonts_1.1.0       fs_1.6.5