Getting Started with qrmdtmpl

Source: vignettes/qrmdreport_getting_started.Rmd

Disclaimer

The way how to use the package qrmdtmpl to produce project reports based on a given template is described.

Package Installation

The first step is to install the package qrmdtmpl.

# if (!is.element("remotes", installed.packages())) install.packages("remotes")
remotes::install_github(repo = 'fbzwsqualitasag/qrmdtmpl')

New Report Using RStudio

After the installation, a new report based on the template in qrmdtmpl can be created using File -> New File -> RMarkdown -> From Template -> Qualitas AG Project Report.

From R Console

A new report can also be generated from the R Console using the command

rmarkdown::draft(file = 'report1', package = 'qrmdtmpl', template = 'qprojectreport', create_dir = TRUE)

This creates a new RMarkdown file called report1.Rmd in a new subdirectory called report1. This can then be edited and knit to a pdf-document.

Wrapper Functions

The following wrapper functions are available in this package ‘qrmdtmpl’

# slides
qrmdtmpl::draft_qbeamerslides(ps_path = '20210216_test_slides_no_rmd')
qrmdtmpl::draft_qbeamerslides(ps_path = '20210216_test_slides_with_rmd.Rmd')

# empty doc
qrmdtmpl::draft_qemptydoc(ps_path = '20210216_test_empty_no_rmd')
qrmdtmpl::draft_qemptydoc(ps_path = '20210216_test_empty_with_rmd.Rmd')

# generic doc
qrmdtmpl::draft_qgenericdoc(ps_path = '20210216_test_generic_no_rmd')
qrmdtmpl::draft_qgenericdoc(ps_path = '20210216_test_generic_with_rmd.Rmd')

# report
qrmdtmpl::draft_qprojectreport(ps_path = '20210216_test_report_no_rmd')
qrmdtmpl::draft_qprojectreport(ps_path = '20210216_test_report_with_rmd.Rmd')

Placeholders in Templates

A number of placeholders were introduced into the document templates. These placeholders can be replaced by specific values when creating a new document. Placeholders are mainly used in the yaml header of the documents. The place holders are surrounded by a starting tag (<ph>) and an end tag (</ph>). The placeholders include

  • title of the document (<ph>title</ph>)
  • author of the document (<ph>author</ph>)
  • date of creation (<ph>date</ph>)
  • output format (<ph>output_format</ph>)

The values to be inserted at the position of the placeholders can be specified by the argument pl_repl_value which expects a list with the names that correpsond to the placeholder names between the start and end tags. A possible call to create a project report might then look as follows

qrmdtmpl::draft_quagprojectreport(ps_path = "example_quagprojectreport",
                                  pl_repl_value = list(title = "Example Project Report",
                                                       author = "Peter von Rohr",
                                                       date   = "2021-08-27",
                                                       output_format = "pdf_document"))

Generate Example Reports

To demonstrate the use of different templates, example documents can be generated. The following statement creates a German example report with the Qualitas AG Logo and with the document structure that seams to be common for this type of reports.

tmprepdir <- tempdir()
create_example_qprojektreport(ps_path = tmprepdir)
unlink(tmprepdir, recursive = TRUE, force = TRUE)

The above example allows to inspect a more detailed RMarkdown sourcefile that shows how tables and diagrams are created and referenced. All the captions related to tables and diagrams are shown in German. This is possible because of the latex-package babel which is included in the document header included in the yaml-header section.