Some Lesser Known Features of knitr

class: center, middle, inverse, title-slide

# Some Lesser Known Features of knitr
### <a href="https://yihui.org">Yihui Xie</a>
### 2018/06/12 @ the RaukR Summer School (Visby, Sweden)

---

class: center

# About me

## https://yihui.org

.center[![Yihui](https://avatars1.githubusercontent.com/u/163582?s=200)]

---
class: center

[![the knitr book](https://db.yihui.org/imgur/yYw46aF.jpg)](https://amzn.com/1498716962)

Most of things I talk about today are covered in the knitr book, which is unfortunately [not free](https://amzn.com/1498716962). I plan to work on a free book that contains the best parts of the knitr book later this year.

---

# knitr is not only for R

- It contains many, many other language engines: https://bookdown.org/yihui/rmarkdown/language-engines.html

- For example, Shell/Bash scripts, SQL, Python, C, C++, Fortran, Stan, ...

- Demo of two engines: `python` and `asis`.

````markdown
    ```{python}
    x = 42
    print(x)
    ```
    ````

````markdown
    ```{asis, echo=identical(knitr:::pandoc_to(), 'html')}
    Here is _some text_ that you want to display only
    when the output format of R Markdown is **HTML**.
    
    You can write arbitrary Markdown content in this chunk.
    ```
    ````

---

# knitr is not only for Markdown, either

R Markdown may be the most popular document format (R Markdown = knitr + pandoc), but you could also use other authoring languages such as LaTeX, HTML, AsciiDoc, and reStructuredText.

Demo: `*.Rnw`, `*.Rhtml`

---

# knitr works on R scripts, too

- Most of time you may be using `knitr::knit()`, but sometimes you may want `knitr::spin()`.

- If you use RStudio, you can click the button "Compile Report" on the toolbar.

- Demo

---
class: center

![:image 90%, the force in knitr is very strong](gif/git-push-force.gif)

---

# The chunk option include=FALSE

Have you ever used these chunk options?

````markdown
```{r, echo=FALSE, results='hide'}
```
````

````markdown
```{r, echo=FALSE, results='hide', message=FALSE, warning=FALSE}
```
````

or even

````markdown
```{r, echo=FALSE, results='hide', message=FALSE, warning=FALSE, fig.show='hide'}
```
````

You probably only need a single chunk option `include=FALSE`: https://yihui.org/en/2017/11/knitr-include-false/.

---
class: center

![:image 90%, you get nothing](gif/you-get-nothing.gif)

---

# Live-preview HTML output documents

- Tired of clicking the Knit button to view your results?

- Just use `xaringan::inf_mr('your.Rmd')`.

- `install.packages('xaringan')`
  
  - You can also use the RStudio addin "Infinite Moon Reader".

- Demo

- For more info, see

- https://bookdown.org/yihui/rmarkdown/compile.html
  
  - https://bookdown.org/yihui/rmarkdown/xaringan-preview.html
  
  - https://yihui.org/en/2017/08/why-xaringan-remark-js/

---
class: center

![:image 300px, sit back and relax](gif/dog-motor.gif)

---

# knitr::knit_watch()

Watch an input file continuously, and knit it when it is updated, e.g.,

```r
library(knitr)
knit_watch('foo.Rnw', knitr::knit2pdf)

knit_watch('foo.Rmd', rmarkdown::render)
```

This function works for any documents with any output formats, but unlike `xaringan::inf_mr()`, it does not automatically refresh the output page.

---

# Caching

- The chunk option `cache=TRUE`

- Basic idea: if nothing has changed from the previous run, just load the results instead of executing the code chunk again.

````markdown
```{r cache=TRUE}
Sys.sleep(10)  # pretend this is a time-consuming code chunk
```
````

---
class: center

![:image 70%, caching can make your code fast](gif/get-into-the-car.gif)

---

# You can generate animations from R plots

- Additional software: FFmpeg (https://ffmpeg.org)

- Easy to install for macOS users (use Homebrew, and `brew install ffmpeg`)

- Demo

````markdown
    ```{r fig.show='animate', interval=.2, ffmpeg.format='gif'}
    library(animation)
    demo('Mandelbrot', package = 'animation', echo = FALSE)
    ```
    ````

It is strongly recommended to use `cache=TRUE` in this case, because the animation may take a minute or two to generate.
    
    The animation format is specified by the chunk option `ffmpeg.format`. It could be `gif`, `mp4`, `webm`, or any other formats that FFmpeg supports.

---
class: center

![:image 70%, enjoy your own animations](gif/pixar.gif)

---

# HTML widgets for non-HTML output

- What is HTML Widgets? http://www.htmlwidgets.org

- HTML widgets are for HTML output formats (of course!). What if we embed a widget in a PDF document? In this case, **knitr** will take a screenshot of the widget automatically if you have installed **webshot** and PhantomJS:

```r
    install.packages("webshot")
    webshot::install_phantomjs()
    ```

- Demo

````markdown
    ```{r}
    DT::datatable(iris)
    ```
    ````

- More info: https://bookdown.org/yihui/bookdown/html-widgets.html

---

# Reuse a code chunk

- If you want to reuse the code from a chunk, don't copy and paste.

- Three ways:

1. Use the same label, but leave the chunk empty. Useful when you want to run the same code twice with different chunk options.
    
    1. Use the `ref.label` option, and leave the chunk empty; `ref.label` can be a vector of chunk labels.
    
    1. Use the `<<chunk-label>>` syntax to embed one chunk in another.

- Demo

- More info: https://yihui.org/knitr/demo/reference/

---

# The Docco style

- Usage: `knitr::rocco('your.Rmd')`

- Examples:

- https://cran.rstudio.com/web/packages/knitr/vignettes/docco-classic.html
  
  - https://cran.rstudio.com/web/packages/highr/vignettes/highr-internals.html

---

# knitr::imgur_upload()

- Upload an image to imgur.com and return its URL.

- The **reprex** package uses this function to automatically embed plots in the output of reproducible examples.

- https://yihui.org/en/2017/09/knitr-imgur-upload/

---

# knitr::knit_expand()

```r
library(knitr)
knit_expand(text = "The value of pi is {{pi}}.")

knit_expand(
  text = "The value of a is {{a}}, so a + 1 is {{a+1}}.",
  a = rnorm(1)
)
```

More info: https://cran.rstudio.com/web/packages/knitr/vignettes/knit_expand.html

Also see the **glue** package.

---

# knitr::fig_chunk()

- When you draw a plot in a code chunk, but want to show it elsewhere (not in the code chunk), `knitr::fig_chunk()` gives you the path to the plot file.

````markdown
    ```{r cars-plot, fig.show='hide'}
    plot(cars)
    ```
    
    Bla bla...
    
    ![a figure moved here](`r knitr::fig_chunk('cars-plot', 'png')`)
    ````

- More info: https://yihui.org/en/2017/09/knitr-fig-chunk/

---

# knitr::write_bib()

```r
knitr::write_bib(c("knitr", "shiny"))
```

```{.bibtex}
@Manual{R-knitr,
  title = {knitr: A General-Purpose Package for Dynamic Report Generation in R},
  author = {Yihui Xie},
  note = {R package version 1.20.3},
  url = {https://yihui.org/knitr/},
  year = {2018},
}
@Manual{R-shiny,
  title = {shiny: Web Application Framework for R},
  author = {Winston Chang and Joe Cheng and JJ Allaire and Yihui Xie and Jonathan McPherson},
  year = {2018},
  note = {R package version 1.1.0},
  url = {https://CRAN.R-project.org/package=shiny},
}
```

---
class: center

![:image 90%, you get nothing](gif/happy-elmo.gif)

---

# Thanks!

- Slides: [bit.ly/2018-raukr](https://bit.ly/2018-raukr)

- Me

- Homepage https://yihui.org
    
    - Twitter [@xieyihui](https://twitter.com/xieyihui); Github [@yihui](https://github.com/yihui)

- Questions? Consider [Stack Overflow](https://yihui.org/en/2017/08/so-gh-email/), or RStudio Community (https://community.rstudio.com).