Rmarkdown: Difference between revisions

From 太極
Jump to navigation Jump to search
 
Line 1,621: Line 1,621:
</pre>
</pre>


= postcards =
= postcards: personal/landing page =
[https://github.com/seankross/postcards postcards] - Create simple, beautiful personal websites and landing pages using only R Markdown.
[https://github.com/seankross/postcards postcards] - Create simple, beautiful personal websites and landing pages using only R Markdown.


Latest revision as of 20:19, 29 November 2024

Markdown language

According to wikipedia:

Markdown is a lightweight markup language, originally created by John Gruber with substantial contributions from Aaron Swartz, allowing people “to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML)”.

  • Markup is a general term for content formatting - such as HTML - but markdown is a library that generates HTML markup.

Editors

Why You Should Be Writing Everything in Markdown 2023/10/11.

Github markdown Readme.md

How to nest code within a list using Markdown

https://meta.stackexchange.com/questions/3792/how-to-nest-code-within-a-list-using-markdown

Continuous publication

Open collaborative writing with Manubot Himmelstein et al 2019

Syntax

Comment: https://stackoverflow.com/questions/4823468/comments-in-markdown. The html method does not work. I need to try use Shift+ CMD + c.

Table

Simple example 

| Column 1       | Column 2     | Column 3     |
| :------------- | :----------: | -----------: |
|  Cell Contents | More Stuff   | And Again    |
| You Can Also   | Put Pipes In | Like this \| |

Include code

Markdown Code Block: Including Code In .md Files

  • Inline code blocks: 
    Use `print("Hello, world!")` to print a message to the screen.
  • Fenced code blocks: 
    ```python
print("Hello, world!")
for i in range(10):
    print(i)
```
  • Indented code blocks 
    Here's some regular text. And now a code block:

    print("Hello, world!")
    if True:
        print('true!')

Literate programming

Rmarkdown

HTML5 slides examples

Software requirement

Slide #22 gives an instruction to create

  • regular html file by using RStudio -> Knit HTML button
  • HTML5 slides by using pandoc from command line.

Files:

  • Rcmd source: 009-slides.Rmd Note that IE 8 was not supported by github. For IE 9, be sure to turn off "Compatibility View".
  • markdown output: 009-slides.md
  • HTML output: 009-slides.html

We can create Rcmd source in Rstudio by File -> New -> R Markdown.

There are 4 ways to produce slides with pandoc

  • S5
  • DZSlides
  • Slidy
  • Slideous

Use the markdown file (md) and convert it with pandoc 

pandoc -s -S -i -t dzslides --mathjax html5_slides.md -o html5_slides.html

If we are comfortable with HTML and CSS code, open the html file (generated by pandoc) and modify the CSS style at will.

Tips

Debug

Debugging RMarkdown

YAML

  • ymlthis package - write YAML for R Markdown, bookdown, blogdown, and more.
  • R Markdown Crash Course YAML Headers

Some examples 

---
title: "My Title"
date: "`r format(Sys.time(), '%d %B, %Y')`"
output:
  pdf_document:
    toc: true
    number_sections: true
classoption: landscape    
---

---
title: "My Title"
date: "`r format(Sys.time(), '%d %B, %Y')`"
output: latex_document
---

Debug by keep tex

Rmarkdown Retain .tex file. We can use this technique to see what goes wrong in the middle step. 

output:
  pdf_document:
    keep_tex: true
---

HTML output

Useful YAML options for generating HTML reports in R

HTML Turn off title

Rmarkdown: Turn off title

HTML with dynamic table of contents

---
title: "My title"
output: 
  rmdformats::robobook: 
    highlight: tango
    number_sections: true
    lightbox: true
    gallery: true
    code_folding: hide
---

Inlcude latex packages

render(, params)

---
title: "Homework"
output:
  html_document:
    code_folding: hide
    toc: true
    toc_float: true
    theme: "flatly"
params:
  run: TRUE
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, eval = params$run)
```

```{r chunk1}
dim(iris)
```

We can use the following command to create an html file that does not evaluate the code for the whole document. 

rmarkdown::render("Homework.Rmd",
          params=list(run = FALSE), 
          output_file = "Homework.html")

Code folding

Center title in html output

How do I center my YAML heading in an R markdown html document? Use CSS styling.

Office (Word, Powerpoint) output

Examples

ComBatCorr, Preview HTML 

---
title: "..."
author: "..."
output:
  html_document:
    code_folding: hide
    toc: true
    toc_float: true
    theme: "flatly"
editor_options: 
  chunk_output_type: console
---

PDF output 

---
title: "..."
date: "`r format(Sys.time(), '%d %B, %Y')`"
output:
  pdf_document:
    toc: true
    toc_depth: 3
    number_sections: true
    fig_caption: true
urlcolor: blue
---

Chunk options

Some options:

  • echo=FALSE. whether to include R source code in the output file
  • message=FALSE. whether to preserve messages emitted by message() (similar to warning)
  • results = 'hide'. hide results; this option only applies to normal R output (not warnings, messages or errors) like print() or cat().
    • Note: if we spell the option incorrectly like result = 'hide' , the 'R markdown' window from running knitting will not show any warnings and the purpose of hiding the print result will not work either.
  • include. whether to include the chunk output in the final output document;
  • warning. whether to preserve warnings (produced by warning()) in the output like we run R code in a terminal (if FALSE, all warnings will be printed in the console instead of the output document). This seems to be useful. Too many warnings will make the computation time much longer (eg. 3 hours vs 30 minutes) no to say the output file will be very large.
  • error. whether to preserve errors (from stop()); If you want to show the errors without stopping R, you may use the chunk option error = TRUE. See Do not stop on error
  • comment. Remove Hashes in R Output from R Markdown and Knitr
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE, cache = TRUE, warning = FALSE, 
                      message = FALSE, verbose = FALSE)
```

Global options

Suppose I want to create a simple markdown only documentation without worrying about executing code, instead of adding eval = FALSE to each code chunks, I can insert the following between YAML header and the content. Even bash chunks will not be executed. 

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, eval = FALSE)
```

Include sections inside a chunk

```{r}
# Chunk section 1 ----
...
# Chunk section 2 ----
```

Ignore duplicate chunk labels

I got an error Calls: <Anonymous> ... process_file -> split_file -> lapply -> FUN -> parse_block Execution halted because of duplicate chunk labels.

See Chapter 14 Miscellaneous knitr Tricks

Include all the code from the Rmd

Use knitr::all_labels().

Conditional `echo` (or eval or include) in rmarkdown chunks

Control eval or output. Following is an example that the chunk will be run if a "linux" machine is detected (e.g. the linux machine is some quality such as a larger RAM). 

```{r label}
get_os <- function(){
  sysinf <- Sys.info()
  if (!is.null(sysinf)){
    os <- sysinf['sysname']
    if (os == 'Darwin')
      os <- "osx"
  } else { ## mystery machine
    os <- .Platform$OS.type
    if (grepl("^darwin", R.version$os))
      os <- "osx"
    if (grepl("linux-gnu", R.version$os))
      os <- "linux"
  }
  tolower(os)
}

doNextChunk <- get_os() == "linux"
```

```{r conditional, eval = doNextChunk}
"hello world!"
```

Conditional evaluation using params

See here

Conditional code for specific output formats

Breaking the page in LaTeX output for PDFs. Note that commands passed to LaTeX in this way need to be escaped with a double slash. 

`r if (knitr::is_latex_output()) '\\newpage'`

results = "asis"

Output text as raw Markdown content

"source" (run) all of the code chunks in a .qmd file

"source" (run) all of the code chunks in a .qmd file (like `source("analysis.qmd")`) inside another .qmd file? See 3.4 Convert R Markdown to R script 

```{r}
library(knitr)
temp_r_file <- tempfile(fileext = '.R')
purl("first-file.qmd", output = temp_r_file)
source(temp_r_file)
unlink(temp_r_file)
```

Multiple plots/tables in one chunk

twitter

Reuse code chunks, combine chunks

See R Markdown Tips and Tricks #3: Time-savers & Trouble-shooters

Comment chunks not working

Comment out some chunks/part of Rmd file. Use 'eval = FALSE' works.

inline code

https://rmarkdown.rstudio.com/lesson-4.html (`r x<-5 `)

Language support (engine)

Mix markdown with Latex

TinyTex for pdf output (works on Windows OS too)

https://github.com/yihui/tinytex and Debugging page for different solutions.

On NIH/biowulf, there is no 'pdflatex' program. So a pdf file cannot be generated.

I install tinytex. At the end, many latex executable files (pdflatex, bibtex, ...) are installed under ~/bin directory.

Step 1: 

> install.packages("tinytex")
trying URL 'https://yihui.name/gh/tinytex/tools/install-unx.sh'
Content type 'text/plain; charset=utf-8' length 616 bytes
...
tlmgr: package log updated: /spin1/home/linux/USERNAME/.TinyTeX/texmf-var/web2c/tlmgr.log
TinyTeX installed to /spin1/home/linux/USERNAME/.TinyTeX
You may have to restart your system after installing TinyTeX to make sure ~/bin appears in your PATH variable (https://github.com/yihui/tinytex/issues/16).

Step 2: I also need to run 

> tinytex::install_tinytex()
trying URL 'https://yihui.org/gh/tinytex/tools/install-unx.sh'
...
tlmgr: package log updated: /home/brb/.TinyTeX/texmf-var/web2c/tlmgr.log
TinyTeX installed to /home/brb/.TinyTeX
You may have to restart your system after installing TinyTeX to make sure ~/bin appears in your PATH variable (https://github.com/yihui/tinytex/issues/16).

So we don't need to manually install Miktex on Windows.

On my Ubuntu 20.04, ~/.profile already adds $HOME/bin and $HOME/.local/bin to $PATH.

After changing the .profile file, you have to logout from your account and login, then it will be sourced once automatically.

On my Linux Mint, I got an error tlmgr: unexpected return value from verify_chcksum: -5 ! Latex Error: File multirow.sty not found when I run rmarkdown::render(). Missing package. "Remote repository newer than local", How do I upgrade TinyTeX yearly after I had installed it in the previous year? I got a message like “tlmgr: Remote repository is newer than local (2017 < 2018)“. 

$ tlmgr --verify-repo=none install multirow
# tlmgr: Local TeX Live (2019) is older than remote repository (2020).
Cross release updates are only supported with 
  update-tlmgr-latest(.sh/.exe) --update
See https://tug.org/texlive/upgrade.html for details.

R> tinytex::reinstall_tinytex()
R> q()

$ tlmgr --verify-repo=none install multirow

Built-in examples from rmarkdown

# This is done on my ODroid xu4 running Ubuntu Mate 15.10 (Wily)
# I used sudo apt-get install pandoc in shell
# and install.packages("rmarkdown") in R 3.2.3

library(rmarkdown)
rmarkdown::render("~/R/armv7l-unknown-linux-gnueabihf-library/3.2/rmarkdown/rmarkdown/templates/html_vignette/skeleton/skeleton.Rmd")
# the output <skeleton.html> is located under the same dir as <skeleton.Rmd>

Note that the image files in the html are embedded Base64 images in the html file. See

Templates

Knit button

  • It calls rmarkdown::render()
  • It does not count as an interactive session. But if we call rmarkdown::render() in an R session, it counts as an interactive session.
  • R Markdown = knitr + Pandoc
  • rmarkdown::render() = knitr::knit() + a system() call to pandoc

Exit knitting early

Miscellaneous knitr Tricks

Pandoc's Markdown

pandoc will be installed automatically if we install tidyverse by using sudo apt install r-cran-tidyverse binary package.

Originally Pandoc is for html.

Extensions

  • YAML metadata
  • Latex Math
  • syntax highlight
  • embed raw HTML/Latex (raw HTML only works for HTML output and raw Latex only for Latex/pdf output)
  • tables
  • footnotes
  • citations

Types of output documents

  • Latex/pdf, HTML, Word
  • beamer, ioslides, Slidy, reval.js
  • Ebooks
  • ...

Some examples: 

pandoc test.md -o test.html
pandoc test.md -s --mathjax -o test.html
pandoc test.md -o test.docx
pandoc test.md -o test.pdf
pandoc test.md --latex-engine=xlelatex -o test.pdf
pandoc test.md -o test.epb

Check out ?rmarkdown::pandoc_convert()/

When you click the Knit button in RStudio, you will see the actual command that is executed.

pandoc included in RStudio

RStudio included pandoc already. On my Ubuntu 20.04 it is included in "/usr/lib/rstudio/bin/pandoc/" (Sys.getenv("RSTUDIO_PANDOC")). Note the path is not in the global environment PATH.

Check pandoc availability and version

pander and rapport packages

Examples/gallery

Some examples of creating papers (with references) based on knitr can be found on the Papers and reports section of the knitr website.

Read the docs Sphinx theme and journal article formats

http://blog.rstudio.org/2016/03/21/r-markdown-custom-formats/

  • rticles package
  • rmdformats package. For each format, it also takes the option from html_document such as code_folding (the default is 'none' so there is no way to control it on HTML).
    • downcute: how to turn off black color
    • robobook: looks pretty. TOC is on LHS & can be closed like bookdown theme.
    • material
    • readthedown
    • html_clean: the TOC is kind of small
    • html_docco
output: 
  rmdformats::robobook: 
    highlight: tango
    number_sections: true
    lightbox: true
    gallery: true
    code_folding: show

rmarkdown news, floating TOC

How to create TOC from HTML/pdf?

Some examples that have no TOC in vignettes

Is there any web app that can generate the TOC?

Useful tricks when including images

Space

Add horizontal space

Use &nbsp; See https://stackoverflow.com/a/36831500

Add vertical space

See here.

Figure

Avoid blank pages

Don't generate more than one plot in one chunk (learned by experience).

Reference a figure in latex

LaTeX examples: How to reference a figure or table

An rmarkdown example.

We can use this technique in rmarkdown. For example:

  • In text: reference by \ref{fig1}
  • In chunk:
```{r myLabel, fig.cap="My caption\\label{fig1}"}
```

Floating

See the solution Prevent figures from floating and the comment there

In general, we do not recommend that users force LaTeX to stop floating figures. This solution was included in this book by popular demand,2 but there could be some serious side-effects when LaTeX is unable to float figures.

Related to figures or tables floating, if we want to start in a new page, we can use \clearpage instead of \newpage; see Why is \newpage ignored sometimes ?

Figure caption

Figure size

Different ways to set figure size in RMarkdown

1. Define size in YAML header 

--- 
title: "My Document" 
output: html_document: 
fig_width: 6 
fig_height: 4 
---

2. Global chunk 

knitr::opts_chunk$set(fig.width=12, fig.height=8)

3. Chunk options 

{r fig1, fig.align = 'center', fig.height = 3, fig.width = 5}

{r fig3, fig.width = 5, fig.asp = .62}

{r fig4, out.width = '40%'}

4. use knitr::include_graphics(); see Tips and tricks for working with images and figures in R Markdown documents 

```{r  out.width = "50%"}
include_graphics(img1_path) 
```

5. Control the size of plots/images. It works. 

![A nice image.](foo/bar.png){width=50%}

Tables

Rmd --> md (by pandoc) --> tex --> pdf

The default output is a markdown table when kable() is used in an Rmd document. It is Pandoc that converts the markdown table to latex table.

Package Example Comment
knitr kable()
kableExtra kable() + piping. bsSimulscript.Rmd
xtable bsSimulTable.Rmd vignette is in Rnw.

NB. In one case, I have a short table (2 rows only) and the table cannot be put on the same page of a figure which takes up a whole page and a lot of space was wasted at the top and bottom of the page. However, after I change the way of creating the table from xtable to knitr::kable() & knitrExtra, the problem is gone.

How to Make Beautiful Tables in R: gt, kable + kableExtra, formattable, DT, reactable, flextable.

Table contest

knitr::kable

From scratch

Little useless-useful R functions – Transforming dataframe to markdown table

Caption and special character

When the caption (no matter we are using kable() or xtable()) contains special characters like an underscore character "_" (e.g. "HALLMARK_P53_PATHWAY"), the table cannot be rendered correctly (the pdf file will not be able to interpret \begin{table}[!h] and \caption{} ).

So a simple solution like gsub("_", "", genesetid) will solve this problem.

*kableExtra (images in tables)

https://cran.r-project.org/web/packages/kableExtra/index.html, Insert Images into Columns, Add an image to a table-like output in R

This example Using gt, gtExtras and openair to present air quality monitoring data can insert clickable expandable figures in tables. The example uses gt and gtExtras package.

Example: 

options(knitr.table.format = "latex", knitr.kable.NA = "")
kable(x, booktabs = T, digits=4, 
      caption = "deltaC from 10 splits\\label{tb1}") %>%
  kable_styling(font_size = 8, latex_options = c("striped", "hold_position"))

Alternate row color with knitr:kable in R Markdown 

knitr::kable(mtcars, "html") %>%
  kable_styling("striped")

kable kableExtra, Cells with hyperlinks

How to stop bookdown tables from floating to bottom of the page in pdf?

For HTML output, we can highlight elements in certain column using different colors. See this vignette from postpi.

gt and gtExtras

Include images in tables

Include plots in tables (without using gtExtras package)

gtsummary

xtable

The caption created by xtable() was under a table. Cf. The caption is above the table when we use kable().

The package assume the document type is html or pdf. Other types like doc does not work.

Example: 

print(xtable(x, digits = 4, 
             caption = "deltaC \\label{tb3}"), 
       comment = FALSE, 
       size="\\fontsize{7pt}{8pt}\\selectfont",
       floating = TRUE,
       latex.environments="center")

xtableList() can create a list of tables; see xtable List of Tables Gallery.

Below is an Rmarkdown example that would generate a pdf file with desired tables. Pay attention to various options here because the default options won't work. 

---
title: "xtable in rmarkdown"
date: "`r format(Sys.time(), '%d %B, %Y')`"
output: pdf_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE, message=FALSE)
```

```{r , results='asis'}
require(xtable)
data(mtcars)
mtcars <- mtcars[, 1:6]
mtcarsList <- split(mtcars, f = mtcars$cyl)
### Reduce the size of the list elements
mtcarsList[[1]] <- mtcarsList[[1]][1,]
mtcarsList[[2]] <- mtcarsList[[2]][1:2,]
mtcarsList[[3]] <- mtcarsList[[3]][1:3,]
attr(mtcarsList, "subheadings") <- paste0("Number of cylinders = ",
names(mtcarsList))
attr(mtcarsList, "message") <- c("Line 1 of Message",
                                 "Line 2 of Message")
xList <- xtableList(mtcarsList)
print.xtableList(xList, comment=FALSE)
```

The following example is to give alternative colors on rows. Note the option header-includes and tables in YAML section 

---
title: "testxtable"
header-includes:
   - \usepackage{colortbl}
output: pdf_document
tables: true
---

```{r cars, results='asis'}
library(xtable)
mydf <- data.frame(id = 1:10, var1 = rnorm(10), var2 = runif(10))
rws <- seq(1, (nrow(mydf)-1), by = 2)
col <- rep("\\rowcolor[gray]{0.95}", length(rws))
print(xtable(mydf), booktabs = TRUE,
      add.to.row = list(pos = as.list(rws), command = col))
```

Tips 

print(xt, size="\\fontsize{9pt}{10pt}\\selectfont") 
print(xtable(.., caption = " "), floating = TRUE)

Gmisc: create Table 1 used in medical articles

https://cran.r-project.org/web/packages/Gmisc/index.html

tableone

  • https://cran.r-project.org/web/packages/tableone/
  • Table 1 and the Characteristics of Study Population
    • The demo data can be downloaded
    • ?CreateTableOne
    • It can be verified that if the interested variable is continuous, we can use t.test(, var.equal = T)$p.value to obtain p-values. Or use the aov function: summary(aov(BMI ~ Gender, dt))[[1]][["Pr(>F)"]][1] .
    • If the interested variable is discrete, it seems it uses chi.square(var1, var2)$p.value to obtained p-values. It seems even the cells have small number of observations, it still use chisq-test. We can however obtain the Fisher's exact test p-values in the print() method.
    R> with(dt[1:15,], table(Smoking, Gender))
       Gender
Smoking Female Male
    No       5    6
    Yes      2    2

R> with(dt[1:15,], chisq.test(table(Education, Gender))$p.value)
[1] 0.6691241
Warning message:
In chisq.test(table(Education, Gender)) :
  Chi-squared approximation may be incorrect
R> with(dt[1:15,], fisher.test(table(Education, Gender))$p.value)
[1] 0.8135198

R> CreateTableOne(c("Smoking", "Education"), dt[1:15,], catVars, strata = c("Gender")) 
                   Stratified by Gender
                    Female    Male      p      test
  n                 7         8                    
  Smoking = Yes (%) 2 (28.6)  2 (25.0)   1.000     
  Education (%)                          0.669     
     High           2 (28.6)  4 (50.0)             
     Low            3 (42.9)  2 (25.0)             
     Medium         2 (28.6)  2 (25.0)  

R> print(CreateTableOne(c("Smoking", "Education"), dt[1:15,], catVars, strata = c("Gender")), 
         exact = c("Smoking", "Education")) 
                   Stratified by Gender
                    Female    Male      p      test 
  n                 7         8                     
  Smoking = Yes (%) 2 (28.6)  2 (25.0)   1.000 exact
  Education (%)                          0.814 exact
     High           2 (28.6)  4 (50.0)              
     Low            3 (42.9)  2 (25.0)              
     Medium         2 (28.6)  2 (25.0)  

# The print() result is a table so we can output it using write.table()
R> print(CreateTableOne(c("Smoking", "Education"), dt[1:15,], catVars, strata = c("Gender")), 
         exact = c("Smoking", "Education")) %>% dim()
# [1] 6 4
  • 简书

printr

https://cran.r-project.org/web/packages/printr/index.html

DT

https://cran.r-project.org/web/packages/DT/index.html

flextable

  • flextable. Create pretty tables for 'HTML', 'Microsoft Word' and 'Microsoft PowerPoint' documents. 
    library(flextable)
df <- data.frame(a=letters[1:3], b=rnorm(3), c=letters[4:6])
df <- flextable(df)
df <- add_header_row(ft, c("Merge Header", "Header 3"))
df <- align(ft, align = 'center', part = 'header')
df <- align(ft, j=1:3, align='center', part='body')
df <- set_caption(ft, caption = 'my table caption')
df <- add_footer_lines(df, values = c("blah 1", "blah 2"))
# Output to Word
library(officer)
doc <- read_docx()
doc <- body_add_flextable(doc, ft)
print(doc, target = "output.docx")
  • ebook with cheat sheet. Search "library" to find examples, especially the chapter Chapter 9 Transform objects into flextable 
    ---
title: "Untitled2"
output:
  word_document: default
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(flextable)
```

```{r echo=FALSE}
ft <- flextable(head(mtcars))
ft <- autofit(ft)
ft
```

A new chunk
```{r results='asis', echo = FALSE}
ft <- set_caption(ft, caption = "Table 1: New York Air Quality Measurements")
theme_zebra(ft) # ft <- theme_zebra(ft)
```

sparkTable

https://cran.r-project.org/web/packages/sparkTable/

sparkTable: Generating Graphical Tables for Websites and Documents with R. It depends on the Rglpk package which requires the glpk library. However, sparkTable is not maintained anymore.

skimr for useful and tidy summary statistics is new and provide a histogram next to each variable.

mmtable2

mmtable2 allows you to create and combine tables with a ggplot2/patchwork syntax.

tinytable

https://vincentarelbundock.github.io/tinytable/

How to align table and plot in rmarkdown html_document

https://stackoverflow.com/a/54359010

Math equations

RMarkdown Template that Manages Academic Affiliations

RMarkdown Template that Manages Academic Affiliations

Converting Rmarkdown to F1000Research LaTeX Format

BiocWorkflowTools package and paper

Convert markdown to HTML

Convert to a markdown document

md_document()

Internal links

If my section header is written as "## my section Header". Then I can link to it by using "[linked phrase](#my-section-header)".

Note here

  • Use one number sign (#) even it is a subsection
  • Use the hyphen sign to connect the space character
  • Use lower cases even the header contains capital letters

Another easier way to use the Heading identifiers as described in pandoc. In the header use "# section 1{#s1}" and in the toc or paragraph use '[my section name](#s1)".

Hyperlink color in pdf

Add below to the yaml for PDF documents. See R Markdown: The Definitive Guide. 

urlcolor: blue

Colored text

Blue text . See How to apply color in Markdown?.

icons for rmarkdown

https://ropensci.org/technotes/2018/05/15/icon/

Reproducible data analysis

html document

https://bookdown.org/yihui/rmarkdown/html-document.html

Search button and http server

It works on browser with a web server (including RStudio built-in). It does not work if we just open the index.html file directly in a web browser (e.g. browseURL("index.html") from R).

R built in Web server 

writeLines("<h1>Hi</H1>", "index.html")

library(servr)
servr::httd()

crosstalk - generating a plain HTML document with no need for a Shiny server

Rmarkdown taxonomy and the video by Thomas Mock

Interactive document: Shiny

See R Markdown Cheat Sheet.

When I follow the direction to add the code to the end of this Rmd file, I see

  • I can't run "Build" anymore. An error will come out: Error in numericInput("n", "How many cars?", 5) : could not find function "numericInput".
  • After I click "Run Document", the Rmd file will be displayed in either RStudio or a regular browser using R's built-in web server (http://127.0.0.1:YYYY/XXX.Rmd).

How to boost R Markdown interactivity with runtime Shiny and the article

Tooltip

tippy: Add Tooltips to 'R markdown' Documents or 'Shiny' Apps

Theme, CSS

Scrollable code/output

Download button/embed files

```{css echo = F}
.button_green {
  background-color: #4CAF50;
  font-size: 14px;
}
```

```{r}
library(downloadthis)

# Use the class parameter in download_this to apply your custom class
mtcars %>% download_this(
  output_name = "mtcars",
  output_extension = ".xlsx",
  button_label = "Download datasets as xlsx",
  button_type = "warning",  
  has_icon = TRUE,
  icon = "fa fa-save",
  class = "button_green" # Add your custom class here
)
```

library(download_this)

# Custom CSS for the button
button_css <- "
  background-color: #4CAF50;
  color: white;
  padding: 10px 20px;
  text-align: center;
  text-decoration: none;
  display: inline-block;
  font-size: 16px;
  margin: 4px 2px;
  cursor: pointer;
  border-radius: 4px;
"

# Create the download button
download_this(mtcars, style = button_css, 
              str_anvlopt = "Download Data", 
              output_name = "my_data.csv")

Dropdown menu

Automatic document production with R

https://itsalocke.com/improving-automatic-document-production-with-r/

Documents with logos, watermarks, and corporate styles

http://ellisp.github.io/blog/2017/09/09/rmarkdown

rticles and pinp for articles

Presentation

4 output format

font size

Presenter mode

  • ioslides presentation
    1. Follow this to add notes to your Rmd file.
    2. Add "?presentme=true" to the end of the URL of HTML file in your browser. This will popup another window/tab and this is the presenter will control and see all the notes. The original window/tab will be used by viewers. On my Chrome browser, I need to allow a popup from this location. Firefox is easy to allow popup. Safari browser is difficult.
    3. Use the "p" key to change the mode to Presenter mode. You will see the notes at the bottom of the screen. If the notes are very long, a slider will be shown on the RHS.
  • xaringan Presentations

PowerPoint slides

xaringan: presentation

.code-bg-gray .remark-code, .code-bg-gray .remark-code * {
 background-color:#e1e7e9!important;
}
In the YAML section, change to css: [default, metropolis, metropolis-fonts, custom.css]. In the code chunk, follow the instruction there by wrapping your code chunk with .code-bg-gray[ ]
  • You can use HTML elements directly in an R Markdown file. R Markdown allows you to mix Markdown, R code, and HTML code in the same document1. You can use HTML tags to format your text, create tables, insert images, and more. For example, if I want to highlight a certain line in a code block, we can use the span element with an inline CSS to set the background color. See 7.15 For hardcore HTML users (*) from R Markdown Cookbook.
<pre><code>
This is a code block
<span style="background-color:yellow">This line is highlighted</span>
</code></pre>
  • Change the font size of a table
<style>
# Slide with Table

table {
  font-size: 16px; /* Set the desired font size */
}
</style>

| Task                            | Docker Command              | 
|---------------------------------|-----------------------------|
| Build an image                  | `docker build`              |
| Run a container                 | `docker run`                |
| Pull an image from a registry   | `docker pull`               |

Create presentation file (beamer)

  1. Create Rmd file first in Rstudio by File -> R markdown. Select Presentation > choose pdf (beamer) as output format.
  2. Edit the template created by RStudio.
  3. Click 'Knit pdf' button (Ctrl+Shift+k) to create/display the pdf file.

An example of Rmd is 

---
title: "My Example"
author: You Know Me
date: Dec 32, 2014
output: beamer_presentation
---

## R Markdown

This is an R Markdown presentation. Markdown is a simple formatting syntax for authoring HTML, PDF, and MS Word documents. 
For more details on using R Markdown see <http://rmarkdown.rstudio.com>.

When you click the **Knit** button a document will be generated that includes both content as well as the output of any 
embedded R code chunks within the document.

## Slide with Bullets

- Bullet 1
- Bullet 2
- Bullet 3. Mean is $\frac{1}{n} \sum_{i=1}^n x_i$.
$$ 
\mu = \frac{1}{n} \sum_{i=1}^n x_i
$$

## New slide

![picture of BDGE](/home/brb/Pictures/BDGEFinished.png)

## Slide with R Code and Output

```{r}
summary(cars)
```

## Slide with Plot

```{r, echo=FALSE}
plot(cars)
```

Cache

  • https://yihui.org/knitr/demo/cache/
  • If my markdown file is called abc.Rmd, then two cache directories (abc_cache & abc_files) will be created by default. See rmarkdown’s site generator.
    • *_files: figures.
    • *_cache: *.RData, *.rdb, __packages.
    • When knitting failed due to my error, I will rm these two directories, fix my code and knit again.
  • Cache not work
  • Examples 
    > system.time(rmarkdown::render("~/Downloads/tmp.Rmd")) # first time
...
Output created: tmp.html
   user  system elapsed 
  3.123   0.108   5.426 
# It will create two directories: tmp_files, tmp_cache

> system.time(rmarkdown::render("~/Downloads/tmp.Rmd")) # Second time
...
Output created: tmp.html
   user  system elapsed 
  0.239   0.019   0.317

warning

If we enable cache, be careful on the consequence of just modifying one chunk code. In the following example, if we just modify chunk1 chunk, it will not modify the result from the chunk2 cache. 

```{r chunk1}
x <- 1
```

```{r chunk2, echo=FALSE}
print(x)
```

cache.extra option: dependence

  • rmarkdown cookbook > Chunk > Cache. Some examples
    • cache.extra = tools::md5sum('my-precious.csv')
    • cache.extra = getRversion()
    • cache.extra = Sys.Date()
    • cache.extra = Sys.info()[['sysname']]
  • We can use our own way to replace the cache design in knitr; see a simple example in the Cache subsection.
  • How to make code chunks depend on all previous chunks in knitr/rmarkdown?
  • Object used in cache.extra will be printed on screen. So if a complex object is used in cache.extra, it will take a long time to show the object (thus build the output). So it is smart to only use a simple part of a complex object in "cache.extra".
  • Even I use "eval=FALSE", the object in cache.extra is still printed out on screen (or depends on the order of the parameters?).
---
title: "myRmarkdown"
output: html_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, cache = TRUE)
```

```{r cars}
x <- 1:5
```

```{r pressure, echo=FALSE, cache.extra = x}
plot(x)
```

If we made a change on 'x', the 'pressure' chunk will be re-run when we knit the document.

Dependent on an R code

Use code = readLines('test.R') option in chunk; see How to make code chunks depend on all previous chunks in knitr/rmarkdown? and code chunk documentation.

interfere with RStudio

If I use RStudio to knit an Rmd file and the Rmd file has cache = TRUE, it will remember this option. For example, I also open another Rmd file and try to run rmarkdown::render("XXX.Rmd"), it will create XXX_cache folder even the new Rmd file has cache = FALSE. Solution: knit the new file in a terminal.

read knitr/Rmd cache

read knitr/Rmd cache in interactive session?. Use lazyLoad() function without specifying any extension. 

lazyLoad("unnamed-chunk-1_3c3ad57469a118cd9c584c8d941d2c09")

Note:

  1. lazyLoad("~/Path/unnamed-chunk-1_3c3ad57469a118cd9c584c8d941d2c09") will give an error cannot open 'xxx.rdb:' No such file or directory. It does not recognize the symbol "~/".
  2. It is better to use a chunk name without "-" (or some special characters like ".") in order to find the file using the chunk name. Then I can use grep("myChunkName_.+\\.rdb", ., value=T) %>% sub("\\..*$", "", .) to find the chunk's filename. Also when we use pipe to run lazyLoad(), it does not work unless we specify an argument; see Pipe in magrittr package is not working for function load().
list.files('myProject/fileName_cache/latex', full.names = T) %>% 
  grep("myChunkName_.+\\.rdb", ., value=T) %>% 
  sub("\\..*$", "", .) %>% lazyLoad(envir = globalenv())

lazyLoad2 <- function(filedir, name) {
  # Example:
  #   lazyLoad2("gse6532_cache/latex", "removeProg")
  # Warning:
  #   This assumes the 'name' does not contain any special characters
  if (missing(filedir)) {
    cat("Example:")
    cat("  lazyLoad2(\"project_cache/latex\", \"allF\") \n")
    return(invisible())
  }
  files <- grep(name, list.files(filedir, full.names = TRUE), value = TRUE)[1]
  file1 <- grep("\\.RData$", files, value = TRUE)
  lazyLoad(gsub("\\.RData$", "", file1 ), envir = globalenv())
}

_cache and _files folders

Files in these two folders do not work when I copy these two folders generated from macOS to Linux.

If I manually delete files under _files and re-render, it will give me an error that xxx.pdf cannot be found.

If I want to re-run a chunk without changing the Rmd file, we can just delete files (*.rdx, *.rdb, *.RData) related to a chunk in _cache/latex folder. There is no need to delete files in _files folder since files there will be re-generated too.

RStudio

RStudio is the best editor.

Markdown has two drawbacks: 1. it does not support TOC natively. 2. RStudio cannot show headers in the editor.

Therefore, use rmarkdown format instead of markdown.

Writing a R book and self-publishing it in Amazon

Create professional reports from R scripts, with custom styles

How to create professional reports from R scripts, with custom styles

reporter

reporter package

Publish R results

Scheduling R Markdown Reports via Email

http://www.analyticsforfun.com/2016/01/scheduling-r-markdown-reports-via-email.html

Scheduling Rmarkdown files on Windows

Scheduling Rmarkdown files on Windows - your foolproof guide

R notebook vs R markdown in RStudio

There is no coding difference. The difference is in the rendering. The file extension is the same.

R notebook

  • It adds html_notebook in the output option in the header.
  • You can then preview the rendering quickly without having to knit it (does not execute any of your R code chunks). If you manually 'Run' the chunks, the result will be shown up in preview.
  • It also refreshes the preview every time you save.
  • However in that preview you don't have the code output (no figures, no tables..)
  • You can mix several output options in your header so that you can keep the preview and keep your knit options for export
  • R Notebook is everything and above what R MarkDown is

Table creating packages

Graphics Output in LaTeX Format

Landscape output

https://stackoverflow.com/questions/25849814/rstudio-rmarkdown-both-portrait-and-landscape-layout-in-a-single-pdf

Break a long document and child option

Programmatically create new headings and outputs

Programmatically create new headings and outputs in Rmarkdown

Request an early exit

https://stackoverflow.com/a/33711413

Bibliographies

Docker

How to compile R Markdown documents using Docker

lazy load plots

lazyrmd package

Emoji

Citation

knitcitations. knitcitations is an R package designed to add dynamic citations to dynamic documents created with Yihui's knitr package.

Video

ari: The Automated R Instructor

Render an R script

Chapter 19 Render an R script from Happy Git and GitHub for the useR by Jenny Bryan.

Render the R script through one of these methods:

  • Click on the “notebook” icon in RStudio to “Compile Report”.
  • In RStudio, do File > Knit Document.
  • In R, do rmarkdown::render("YOURSCRIPT.R").

bookdown.org

The website is full of open-source books written with R markdown.

It is easy to download the book. Check the download icon on top (Toggle Sidebar, Search, Font settings, Edit, Download, Info).

To build the book, either use the "Build" button on the top right panel or use the command line 

bookdown::render_book("index.Rmd", "bookdown::gitbook")
bookdown::render_book("index.Rmd", "bookdown::pdf_book")

For example, to build the r4ds book (website), using 

# git clone https://github.com/hadley/r4ds.git
# Open the project in RStudio
# Using 'Build Book' button will give an error
#   Error in rmarkdown::render_site() : No site generator found
devtools::install_github("hadley/r4ds")
bookdown::render_book("index.Rmd", "bookdown::gitbook")

The generated folder _book is 25MB vs 51MB if we use webhttrack.

The bookdown website is easy to navigate using left/right arrow keys.

Figures in a bookdown are handled different from regular R markdown files. The full file path does not work. The "~/" or "../" symbol does not work. The symbolic link directories or files do not work. The only way it works is by creating a subdirectory under the bookdown index.Rmd file.

Also the way of including figures is different in R markdown and bookdown. In bookdown, we should follow this way. That is including knitr::include_graphics("images/myfile.png") in an R block. Recall that in R markdown file, we use ![](figures/myfile.png).

Alternatively we can use webhttrack to download the whole website/book without re-building the book in R.

TexLive

TexLive can be installed by 2 ways

  • sudo apt install texlive It includes tlmgr utility for package manager.
  • Official website

texlive-latex-extra

https://packages.debian.org/sid/texlive-latex-extra

For example, framed and titling packages are included.

tlmgr - TeX Live package manager

https://www.tug.org/texlive/tlmgr.html

Examples

  • Tidy Text Mining with R by Julia Silge and David Robinson (one of many books hosted on BOOKDOWN website).
  • Build 'R for Data Science by Garrett Grolemund, Hadley Wickham' 2019-0808
  • R Markdown: The Definitive Guide
    • Make sure we have done install.packages('tinytex'); tinytex::install_tinytex()
    • Change the font "Source Code Pro" to "Ubuntu" in index.Rmd and rmarkdown.Rmd (I am working on Ubuntu)
    • Change the font Palatino to Ubuntu in index.Rmd and rmarkdown.Rmd

YAML

Author with affiliation in bookdown: HTML and pdf

Publish on github

https://github.com/ThinkR-open/testdown

Create a website using R Markdown

R Markdown Websites, Files, R Markdown: The Definitive Guide -> rmarkdown’s site generator

  1. RStudio -> File -> New Project -> Simple R Markdown Website. This will create 3 files: _site.yml, index.Rmd and about.Rmd
  2. Click Build -> Build Website button or execute the R -q -e "rmarkdown::render_site()" function from within the directory containing your files to build _site, a directory of files ready to deploy as a standalone static website. In this simple example, it will generate index.html, about.html and a new directory site_libs. Note we are not supposed to manually edit any html files.

If we host these files on our server using Apache, we need to make sure the owner of the directory and files is www-data.

  • # move/copy the content in the folder _site to /var/www/mySite
  • cd /var/www/mySite # make sure the permission and owner of the directory are OK
  • sudo chown www-data:www-data *.html # any explanation
  • sudo chown -R www-data:www-data site_libs/ # this directory is generated by R
  • sudo nano /etc/apache2/sites-enabled/mySite.conf # see Apache
  • # sudo a2ensite mySite.conf
  • sudo service apache2 reload

Examples

pkgdown: create a website for your package

Blogdown

bs4cards: an R package for bootstrap 4 cards

bs4cards

Jekyll and Github

Deploying RMarkdown Online

portfoliodown

Introducing portfoliodown: The Data Science Portfolio Website Builder

distill

10 Make Websites to Share Results Online from the ebook R Without Statistics

flexdashboard

Pagedown

Convert an HTML to a PDF, PNG

Convert an HTML to a PDF, PNG, etc. The chrome_print function from {pagedown} can do this either for a local file (including an Rmd file that outputs HTML) or for a URL . 

library(pagedown)
chrome_print("example.html")
chrome_print("example.html", format="png")

postcards: personal/landing page

postcards - Create simple, beautiful personal websites and landing pages using only R Markdown.

Posterdown

posterdown: Use RMarkdown to generate PDF Conference Posters via HTML or LaTeX

rticles package

LaTeX Journal Article Templates for R Markdown

Latex tools

Mathpix Snip Take a screenshot of math and paste the LaTeX into your editor

Tutorials

https://latex-tutorial.com/tutorials/

Math

  • Use \textrm{} for normal text in math mode. For example, $n_\textrm{training} = n_\textrm{test} = 500$.

Quarto

Visual editor

Disable visual markdown editor on RStudio

Quarto dashboard

parsermd

https://rundel.github.io/parsermd/. The goal of parsermd is to extract the content of an R Markdown file to allow for programmatic interactions with the document’s contents (i.e. code chunks and markdown text).

Retrieved from "https://wiki.taichimd.us/index.php?title=Rmarkdown&oldid=40709"