Where to store different settings in Rmarkdown files

This may be of use to others but it’s partly for me as I keep forgetting these and searching around for the .Rmd files in which I used the one I want!

Chris Evans https://www.psyctc.org/R_blog/ (PSYCTC.org)https://www.psyctc.org/psyctc/
2021-02-28

Updated with information about ggplot defaults 19.iii.21

Rmarkdown is brilliant as a framework in which to create reports using R and it’s often useful to reset various defaults at the start of a file. Increasingly I work from Rmarkdown to html so some of this only applies there. I find there are three places I set things:

Setttings in the yaml header

This is well documented in many places and https://bookdown.org/yihui/rmarkdown/html-document.html is probably the canonical reference but searching will provide much other advice. I often use:

---
title: "A title here"
author: "Xxxx Yxxx"
date: "03/01/2021"

output:
  html_document:
    toc: true
    toc_float: true
    toc_depth: 4
    fig_height: 8
    fig_width: 11    
# bibliography: references.bib
---

I think the main things to say about that is that I don’t find that the floating table of contents (toc_float: true) always works, with long documents and complex blocks with graphics and text I find it sometimes mangles the toc so I am using it less than I used to. This can be a useful place to set the figure heading if they might be the same for all your code blocks with graphic output. I am not sure how many other code block header settings you could set here. I must experiment more: could save me a lot of typing. The only other thing there is the bibliography line, commented out. I still haven’t got into regular use of the citation and referencing capacities built into Rmarkdown. Must try harder!

Here is another

---
title: "ICCs from multilevel models analysed with lme4 or nlmer"
author: "CE"
date: "26/02/2021"
output:
  html_document:
    # css: "test.css"
    toc: TRUE
    toc_float: FALSE
    dpi: 200
    out.width: "100%"
    fig.height: 40
---

That shows that you can call an external css file (see next section), so far I haven’t found that I have enough css to make that worth doing. More important here, and I’m still working on this, I have found that you can use out.width: "100%" to make the html avail itself of more of your screen width which I find useful. The dpi: 200 and huge fig.height: 40 settings were me trying to optimise my graphic output for some complex plots.

yaml heading settings for distill

… in index.Rmd

This is all I have in my index.Rmd file. As yet I haven’t found any other options that can usefully be added here.

---
title: "An R SAFAQ by Chris Evans"
site: distill::distill_website
listing: posts
---

… in “posts”

This where most of the Distill extensions to routine Rmarkdown yaml header blocks go. Here’s an example.

---
title: "Making the CECPfuns package: my own usable package"
description: |
  This is very much work in progress so look for later posts about CECPfuns as well as this.
base_url: https://www.xxxx.org/psyctc/Rblog/  
preview: https://www.xxxx.org/pelerinage2016/wp-content/uploads/2020/07/P1160474.jpg
author:
  - name: Xxxx Yyyy
    url: https://www.xxxx.org/R_blog/
    affiliation: xxxx.org
    affiliation_url: https://www.xxxx.org/psyctc/
    orcid_id: xxxx-xxxx-xxxx-xxxx

date: 2021-02-10
output:
  distill::distill_article:
    toc: true
    toc_depth: 4
    hightlight_downlit: true
    self_contained: false
    code_folding: true
creative_commons: CC BY-SA
---

I think that’s mostly self-explanatory and I hope I’ve messed up my own data with sufficient “xxxx” insertions that it’s safe for people to copy and paste to create their own extension on the basic yaml that distill:create_post("post title") creates. The code_folding option means that blocks of code are “folded” away by default but have a “Show code” button so the reader can unfold the code and read it.

… in articles/pages

Here is one of my yaml headers:

---
title: "Welcome to these pages"
description: |
  Welcome to these pages which I hope will be useful to people using R to analyse data.
base_url: https://www.xxx.org/psyctc/Rblog/  
author:
  - name: Xxxx Yyyy
    url: https://www.xxx.org/R_blog/
    affiliation: Xxxx.org
    affiliation_url: https://www.xxx.org/psyctc/
    orcid_id: xxxx-xxxx-xxxx-xxxx
date: "2021-03-19"
output: 
  distill::distill_article:
    self_contained: false
creative_commons: CC BY-SA    
---

I think that’s all pretty self-explanatory. I am sure you can see what to if copying and pasting this!

Settings in css block

This is not my expert area but I have been using a block like this:

click to show css_chunk.txt

(Apologies for this way of putting the code in here: I gave up on trying to work out how to escape characters or otherwise override things being mangled in knitting that!)

That is using the principles behind css (cascading style sheet) to set some html defaults. The first two stanzas allow raw R text output (which comes out in the html “pre” format) to come up in a horizontally scrollable window which can be useful where you find you are spitting out wide output and the next stanza I think determines the formatting of raw code (not sure about that!).

The body stanza is a recent discovery of mine. The “body” section of html is everything except the header information, i.e. it’s what the human reading an html document sees. That allows my html output to use more of my nice big screen.

Settings in early/first R code block

When you create a new Rmd file in Rstudio it always has this first R code block.

click to show default_setup_chunk.txt

I often expand that to something like this:

click to show big_setup_chunk.txt

Setting ggplot defaults

I have my own preferences for some of the “theme” elements in ggplot and discovered that I can set these for a whole Rmarkdown files like this:

### set ggplot defaults
theme_set(theme_bw())
theme_update(plot.title = element_text(hjust = .5),
             plot.subtitle = element_text(hjust = .5))

You can also make that a named object:

### set ggplot defaults
theme_set(theme_bw())
theme_update(plot.title = element_text(hjust = .5),
             plot.subtitle = element_text(hjust = .5)) -> CEtheme

And, of course, if you wanted to, you could even save that to a tiny file:

### set ggplot defaults
theme_set(theme_bw())
theme_update(plot.title = element_text(hjust = .5),
             plot.subtitle = element_text(hjust = .5)) -> CEtheme
save(CEtheme, "CEtheme")

Do contact me if you have advice about setting Rmarkdown options and if have corrections to the above.

Reuse

Text and figures are licensed under Creative Commons Attribution CC BY-SA 4.0. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".

Citation

For attribution, please cite this work as

Evans (2021, Feb. 28). Chris (Evans) R SAFAQ: Where to store different settings in Rmarkdown files. Retrieved from https://www.psyctc.org/R_blog/posts/2021-02-28-where-to-store-different-settings-in-rmarkdown-files/

BibTeX citation

@misc{evans2021where,
  author = {Evans, Chris},
  title = {Chris (Evans) R SAFAQ: Where to store different settings in Rmarkdown files},
  url = {https://www.psyctc.org/R_blog/posts/2021-02-28-where-to-store-different-settings-in-rmarkdown-files/},
  year = {2021}
}