Create an R Markdown template from a form"
In preregr: Specify (Pre)Registrations and Export Them Human- And Machine-Readably

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

preregr forms can be used to generate R Markdown templates, similar to how the prereg package can spawn a number of pre-installed R Markdown templates (see the associated GitHub repo or the CRAN page for details).

These templates are basically prestructured R Markdown files. This means the user (i.e. you) will only have to add in the (pre)registration content, knitr it, and you have a human- and machine-readable (pre)registration.

Generating a full R Markdown template

To generate a full R Markdown template, that can be rendered as a stand-alone document, the preregr::form_to_rmd_template() function can be used with its default settings, so you only have to specify the form you want to use (one you created, loaded, imported, or the name of one of the forms that come pre-installed with preregr.

preregr::form_to_rmd_template(
  "OSFprereg_v1",
  file = "C:/Path/To/A/File.Rmd"
);

This will write the R Markdown template to that file. To show how it looks, we'll save the contents to an object and show a fragment.

rmdTemplate_example <-
  preregr::form_to_rmd_template(
    "OSFprereg_v1"
  );

### Show the fragment
cat(rmdTemplate_example[45:88], sep = "\n");

As can be seen above, part of the (pre)registration information is shown as HTML comments (specifically, the general instructions, the section titles, and the section descriptions), and part is shown as R comments (the item titles, and if provided, the item descriptions). This is then followed by the R code to specify the item content, prefilled with the "Unspecified" text.

The R Markdown template also includes the form itself, specified at the end so as not to confuse the user of the template with a lot of complicated R code right at the top. A fragment of the R form:

cat(rmdTemplate_example[835:850], sep = "\n");

Writing the R Markdown template to a child document to embed

It is also possible to embed the R Markdown template as a fragment in another R Markdown file. This uses knitr's Child Document functionality. To do this, write the R Markdown template to a file, but omit the YAML front matter using the includeYAML argument (setting it to FALSE).

preregr::form_to_rmd_template(
  "OSFprereg_v1",
  file = "C:/Path/To/Child-document.Rmd",
  includeYAML = FALSE
);

Then, in the main R Markdown document where you want to include the child document (i.e. the R Markdown template), include an empty R chunk that sets option child to the path to the file you saved the template to. For example, to include the template produced with the call above, we would insert the following chunk:

cat('```r\n');
cat('```');

You may also want to save a PDF version of the (pre)registration so that it can be uploaded to a (pre)registration server such as the Open Science Framework. To do that, you can use preregr::prereg_spec_to_pdf(). For example, using the here::here() function, and assuming the project directory contains a sub-directory called prereg, the following chunk could be included after the above chunk in the main R Markdown document that included the R Markdown template (i.e. the chunk shown above):

cat(
  '```r',
  'preregr::prereg_spec_to_pdf(',
  '  preregrObject,',
  '  file = here::here("prereg", "registration-1---preregistration.pdf"),',
  '  author = rmarkdown::metadata$author',
  ');',
  '```',
  sep="\n"
);

The last argument, author = rmarkdown::metadata$author, inserts the author specified in the main R Markdown document as the preregistration author in the PDF.