ebciii/audgendb_rmd_template

R Markdown Template for use on the Audiological and Genetic Database (AudGenDB) Project, but which can be useful for other projects with minor changes.

audgendb_rmd_template's Issues

Use the rprojroot::find_rstudio_root_file()) function to set the directory in knitr

Currently the root directory is specified with the assumption that the .Rmd file is in the rmarkdown directory (or at lease a direct child directory of the project directory, using knitr::opts_knit$set(root.dir = "..") in the setup chunk). If instead the rprojroot::find_rstudio_root_file()) command is used to set the directory for when knitr generates the R Markdown report, the template will have more flexibility, because no matter where the .Rmd file is located knitr should use the project directory as the starting point.

Highlight Conclusions in a Blue Box

To enhance and separate the conclusions, enclose them in a blue box:

Under YAML header:

<style>
div.blue { background-color:#e6f0ff; border-radius: 5px; padding: 16px 20px 8px 20px;}
</style>

Enclose Conclusion paragraph (but not header or its duplicates header text in ToC):

<div class = "blue">
</div>

In LoadLibraries chunk, use source() to add functions instead of knitr::read_chunk()

Using knitr::read_chunk()in the LoadLibraries chunk includes functions at the top of the document that appear as long, distracting, code chunks, and often the common functions are repeated in many different RMarkdown reports. Instead, use source(), which will make the code available to the script, but not display it.

The downside to the requested approach is the functions aren't readily available a first time user wants to see it without hunting through the repo to find the included sources. To make the code easy to find in the document, the knitr::read_chunk() function can be moved to the SessionInfo block at the bottom of the document. This block was designed to include potentially informative, but typically distracting information in the report, and can be accessed using html details block to hide and expose the information with a click.

New verstions of knitr require that markdown headers spaced from # header syntax

After upgrading knitr and RStudio, I noticed that the header syntax now needs to be separated from the title text (e.g. ###Conclusion### needs to be ### Conclusion ###). Otherwise, the ### is output explicitly instead of the markdown generating the appropriate html header. Therefore, need to ensure that all header text is separated from the # header syntax in the template.

Use `code_folding: show` in YAML header, so domain experts can hide code blocks

The base format of RMarkdown shows both the markdown descriptions and the code encompassed in gray boxes; the latter may be distracting for domain experts. One solution is provide an option to toggle the code between showing and hiding using the code_folding: option as a parameter for the html_document: choice in the YAML header of the RMarkdown document. This is nicely demonstrated in RPubs document, "Mapping of median January rainfall readings from Irish weather stations" (In fact, I very much like the 'poster' look of this Rpublication for certain purposes).

The two options for the code_folding: choice are: show and hide, which specify the default choice. My preference would be to show the code as a default, and let the user choose to change to hide the code, if that is their preference. The option to hide can be added as a comment to the Setup chunk just below the YAML header, because there may be circumstances in which that is a better option.