Create an R Markdown template from a form

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");
#> <!-- and conducted by the Center for Open Science. More            -->
#> <!-- information is available at                                   -->
#> <!-- https://www.cos.io/initiatives/prereg, and other templates    -->
#> <!-- are available at: https://osf.io/zab38/                       -->
#> 
#> 
#> <!-- Study Information ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
#> 
#> ```{r preregr-study_information-item_1-iLOS01, echo=FALSE, results='hide'}
#> 
#> ###-------------------------------------------------------------------
#> ### Title
#> ###-------------------------------------------------------------------
#> 
#> ### Provide the working title of your study. It may be the same title
#> ### that you submit for publication of your final manuscript, but it
#> ### is not a requirement.
#> ### 
#> ### **Example**: Effect of sugar on brownie tastiness.
#> ### 
#> ### **More info**: The title should be a specific and informative
#> ### description of a project. Vague titles such as 'Fruit fly
#> ### preregistration plan' are not appropriate.
#> 
#> preregrObject <-
#>   preregr::prereg_specify(
#>     preregrObject,
#>     item_1 = "Unspecified"
#> );
#> 
#> ```
#> 
#> ```{r preregr-study_information-item_2-wbtK3Q, echo=FALSE, results='hide'}
#> 
#> ###-------------------------------------------------------------------
#> ### Authors
#> ###-------------------------------------------------------------------
#> 
#> preregrObject <-
#>   preregr::prereg_specify(
#>     preregrObject,
#>     item_2 = "Unspecified"
#> );

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");
#>   headingLevel = 2
#> );
#> ```
#> 
#> 
#> <!-- Here, the form specification is included. ~~~~~~~~~~~~~~~~~~~~-->
#> <!-- This chunk is executed earlier on though. ~~~~~~~~~~~~~~~~~~~~-->
#> 
#> ```{r preregr-formSpecification-xomP2M, echo=FALSE, eval=FALSE}
#> 
#> preregrFormSpec <- 
#>   structure(list(instructions = structure(list(heading = "Introduction", 
#>       description = "Preregistration is the act of submitting a study plan, ideally also with analytical plan, to a registry prior to conducting the work. Preregistration increases the discoverability of research even if it does not get published further. Adding specific analysis plans can clarify the distinction between planned, confirmatory tests and unplanned, exploratory research.\n\nThis preprint contains a template for the “OSF Prereg” form available from the OSF Registry. An earlier version was originally developed for the Preregistration Challenge, an education campaign designed to initiate preregistration as a habit prior to data collection in basic research, funded by the Laura and John Arnold Foundation (now Arnold Ventures) and conducted by the Center for Open Science. More information is available at https://www.cos.io/initiatives/prereg, and other templates are available at: https://osf.io/zab38/"), row.names = c(NA, 
#>   -1L), class = "data.frame"), metadata = structure(list(field = c("title", 
#>   "author", "date", "comments", "version"), content = c("OSF Prereg", 
#>   "Sara Bowman, Alexander C. DeHaven, Tim Errington ,Tom E Hardwicke, David Thomas Mellor, Brian A. Nosek & Courtney K. Soderberg",

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:

```{r including-the-child, child = "C:/Path/To/Child-document.Rmd"}
```

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):

```{r, preregistration-export}
preregr::prereg_spec_to_pdf(
  preregrObject,
  file = here::here("prereg", "registration-1---preregistration.pdf"),
  author = rmarkdown::metadata$author
);
```

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