class: center, middle, inverse, title-slide # Reproducible wRiting with R Markdown ## ♻️ 📃 🌟 ### Ed Berry, Senior Data Scientist (they/them) ### Sky Betting & Gaming --- # Overview * What is R Markdown? * Writing with R Markdown * Output formats * Tips and tricks --- # What is R Markdown? * Created and maintained by Yihui Xie, Software Engineer, R Studio > [*"a productive notebook interface to weave together narrative text and code to produce elegantly formatted output"*](https://rmarkdown.rstudio.com/index.html) <img src="figures/rmarkdown.png" width="287" style="display: block; margin: auto;" /> --- # Why use R Markdown? * Interactive notebooks combining code and narrative text * Simple syntax * Wide range of output formats + With endless customisation * It's just a fancy text file + Version control + Reproducible --- # Writing with R Markdown R Markdown documents are made up of three components <img src="figures/example_document_annotated.png" width="100%" style="display: block; margin: auto;" /> --- # YAML Header ```yaml --- title: "Example" subtitle: 'R Markdown file' author: "Ed" date: "29/11/2019" output: html_document --- ``` --- # YAML Header ```yaml --- title: "Reproducible wRiting with R Markdown" subtitle: "♻️ 📃 🌟" author: "Ed, Senior Data Scientist" institute: "Sky Betting & Gaming" output: xaringan::moon_reader: lib_dir: libs css: ["default", "my-theme.css", "my-theme-fonts.css"] nature: highlightStyle: github highlightLines: true countIncrementalSlides: false --- ``` --- # Markdown .pull-left[ ```markdown # Example Heading Here we can write our text, making use of **bold** or *italics* We can have + bullet + points and 1. numbered 2. lists > blockquotes [links](link.com) even $LaTeX$. ``` ] .pull-right[ <img src="figures/markdown_output.png" width="140%" style="display: block; margin: auto;" /> ] --- # Code blocks/chunks ````markdown ```{r} ggplot(mtcars) + aes(wt, mpg, color = factor(cyl)) + geom_point() + labs(color = 'cyl') + theme_minimal() + theme(legend.position = c(0.85, 0.75)) ``` ```` <img src="reproducible-writing-with-rmarkdown_files/figure-html/unnamed-chunk-4-1.png" width="40%" style="display: block; margin: auto;" /> --- # Code blocks/chunks ````markdown ```{r echo=F, out.width='40%', fig.height=3, fig.width=3.5} ggplot(mtcars) + aes(wt, mpg, color = factor(cyl)) + geom_point() + labs(color = 'cyl') + theme_minimal() + theme(legend.position = c(0.85, 0.75)) ``` ```` <img src="reproducible-writing-with-rmarkdown_files/figure-html/unnamed-chunk-5-1.png" width="40%" style="display: block; margin: auto;" /> --- # Code blocks/chunks Can also include code in-line .pull-left[ * `` The mean was `r mean(x)` `` ] .pull-right[ * The mean was 5 ] --- layout: false class: inverse, middle, center # Output formats --- layout: true --- # Documents * [`html_document`](https://bookdown.org/yihui/rmarkdown/html-document.html) .small[*[the `text` is a link to the documentation]*] <img src="figures/html_document.png" width="50%" style="display: block; margin: auto;" /> --- # Documents * [`pdf_document`](https://bookdown.org/yihui/rmarkdown/pdf-document.html) * [`word_document`](https://bookdown.org/yihui/rmarkdown/word-document.html) * [`pagedown`](https://github.com/rstudio/pagedown) .pull-left[ ```yaml --- title: "Example" subtitle: 'R Markdown file' author: "Ed" date: "29/11/2019" output: pdf_document --- ``` ] .pull-right[ <img src="figures/pdf_document.png" width="75%" style="display: block; margin: auto;" /> ] --- # Slides HTML slides * [`xaringan`](https://bookdown.org/yihui/rmarkdown/xaringan.html) (like these) * [`ioslides_presentation`](https://bookdown.org/yihui/rmarkdown/ioslides-presentation.html) * [`slidy_presentation`](https://bookdown.org/yihui/rmarkdown/slidy-presentation.html) * [`revealjs::revealjs_presentation`](https://bookdown.org/yihui/rmarkdown/revealjs.html) PDF slides * [`beamer_presentation`](https://bookdown.org/yihui/rmarkdown/beamer-presentation.html) Powerpoint * [`powerpoint_presentation`](https://bookdown.org/yihui/rmarkdown/powerpoint-presentation.html) --- # Books * [`bookdown::gitbook`](https://bookdown.org/yihui/bookdown/html.html#gitbook-style) * [`bookdown::epub_book`](https://bookdown.org/yihui/bookdown/e-books.html) * [`bookdown::pdf_book`](https://bookdown.org/yihui/bookdown/latexpdf.html) * [`pagedown`](https://github.com/rstudio/pagedown) <img src="figures/thesis_blogpost.png" width="75%" style="display: block; margin: auto;" /> --- # Websites / blogs * [`blogdown`](https://bookdown.org/yihui/blogdown/) <img src="figures/blogdown.png" width="75%" style="display: block; margin: auto;" /> --- # Dashboards * [`flexdashboard`](https://rmarkdown.rstudio.com/flexdashboard/) <img src="figures/flexdashboard.png" width="75%" style="display: block; margin: auto;" /> --- # Academic papers * [`rticles`](https://github.com/rstudio/rticles) + Templates for a range of publishers such as Royal Society Open Science, PeerJ, Springer, & Sage * [`papaja`](https://crsh.github.io/papaja_man/introduction.html#getting-started) + APA formatted articles --- # CVs * [`pagedown::html_resume`](https://github.com/rstudio/pagedown) * [`vitae`](https://ropensci.org/blog/2019/01/10/vitae/) <img src="figures/vitae.png" width="80%" style="display: block; margin: auto;" /> --- layout: false class: inverse, middle, center # Tips & tricks --- layout: true --- # Templates `File > New File > R Markdown...` <img src="figures/templates.png" width="60%" style="display: block; margin: auto;" /> --- # Parameters ```yaml --- title: "Example" output: html_document params: date: '2019-11-28' --- ``` ````markdown ```{r} con <- '<code for some DB connection>' sql_query <- glue::glue_sql(" SELECT * FROM database.table WHERE dt = {params$date} ", .con = con) ``` ```` * `render("my-report.Rmd", params = list(date = "2019-11-29"))` --- # LaTeX To create PDF outputs you need LaTeX installed (except for `pagedown`) * [`tinytex`](https://yihui.org/tinytex/) is a lightweight TeX distribution from Yihui Xie * You can create custom LaTeX themes for your [PDF documents](https://bookdown.org/yihui/rmarkdown/pdf-document.html) --- # Misc tips and tricks * A number of packages provide in-built themes for HTML output, such as [`rmarkdown`](https://www.datadreaming.org/post/r-markdown-theme-gallery/) and [`xaringan`](https://github.com/yihui/xaringan/wiki/Themes) + *These can be customised with small amounts of CSS* * Sometimes you'll want to create a PDF of a HTML document (e.g. these slides) + `pagedown::chrome_print()` --- # Misc tips and tricks * R Studio has a built-in Markdown Quick Reference + `Help > Markdown Quick Reference` * R Studio has a spell-checker <img src="figures/spellcheck.png" width="60%" style="display: block; margin: auto;" /> --- # Misc tips and tricks Put each sentence of Markdown on a separate line .small[(Thanks to [Oliva Guest](https://oliviaguest.com) for this one)] ```markdown # Example Heading Here's our first setence on a line. Then a second on another line. This will make comparing files using version control a lot easier. ``` --- class: middle .big[.center[*"The most challenging thing in the world is not to learn fancy technologies, but control your own wild heart."*]] .big[.center[[**Yihui Xie**](https://bookdown.org/yihui/bookdown/faq.html)]] --- # Thanks * R Users Leeds Organising Committee * NHS Digital * The authors and contributers of all these wonderful R packages --- layout: false class: inverse, middle, center # Resources --- layout: true --- # Blog posts [Get Started Guide](https://rmarkdown.rstudio.com/lesson-1.html) * .small[*Nice tutorial straight from R Studio.*] [Writing your thesis with bookdown](https://www.eddjberry.com/post/writing-your-thesis-with-bookdown/) * .small[*Shameless self-promotion. This post is a bit out-of-date now, but is hopefully of some use.*] --- # Books [R4DS: Chp. 27 R Markdown ](https://r4ds.had.co.nz/r-markdown.html) [R Markdown: The Definitive Guide](https://bookdown.org/yihui/rmarkdown/) * .small[*This book is very comprehensive meaning it may feel a little overwhelming at first. R Studio's Get Started Guide or the R4DS chapters may be a better starting point.*] [bookdown: Authoring Books and Technical Documents with R Markdown](https://bookdown.org/yihui/bookdown/) * .small[*Everything you need to know about writing books with R Markdown.*] [blogdown: Creating Websites with R Markdown](https://bookdown.org/yihui/blogdown/) * .small[*The go-to place if you want to create a website using `blogdown`.*] --- # Package documentation [R Markdown Cheatsheet](https://rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf) [R Markdown Reference Guide](https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf) * .small[*The Reference Guide is great for laying out all the chunk options.*] * .small[*These can be accessed from R Studio: `Help > Cheatsheets`.*] [Learn R Markdown](https://cran.r-project.org/web/packages/rmarkdown/vignettes/rmarkdown.html) --- # Other cool stuff [`xaringanthemer`](https://pkg.garrickadenbuie.com/xaringanthemer/articles/xaringanthemer.html) * .small[A package to create custom `xaringan` themes.] [R Markdown Gallery](https://rmarkdown.rstudio.com/gallery.html) * .small[Loads of inspiration for the amazing things you can do with R and R Markdown.]