In GerkeLab/grkmisc: A package of miscellaneously helpful functions

options(htmltools.dir.version = FALSE)

class: left bottom hide-count

.talk-meta[ .talk-title[

Talk Title Here

]

.talk-author[ Your Name ]

.talk-date[ r strftime(Sys.time(), "%B %d, %Y") ] ]

```{css echo=FALSE} .talk-logo { width: 200px; height: 200px; position: absolute; top: 25%; left: 12%; } .talk-meta { font-family: Overpass; position: absolute; text-align: left; bottom: 10px; left: 25px; } .talk-author { color: #444; font-weight: bold; font-size: 1.5em; line-height: 1em; } .talk-date { color: #666; font-size: 1.25em; line-height: 0; }

---
class: center, middle

# xaringan

### /ʃæ.'riŋ.ɡæn/

---
class: inverse, center, middle

# Get Started

---

# Hello World

Install the **xaringan** package from [Github](https://github.com/yihui/xaringan):

```r
devtools::install_github("yihui/xaringan")

--

You are recommended to use the RStudio IDE, but you do not have to.

• Create a new R Markdown document from the menu File -> New File -> R Markdown -> From Template -> Ninja Presentation;<sup>1</sup>

--

• Click the Knit button to compile it;

--

• or use the RStudio Addin<sup>2</sup> "Infinite Moon Reader" to live preview the slides (every time you update and save the Rmd document, the slides will be automatically reloaded in RStudio Viewer.

.footnote[ [1] 中文用户请看这份教程

[2] See #2 if you do not see the template or addin in RStudio. ]

---

background-image: url(r xaringan:::karl) background-position: 50% 50% class: center, bottom, inverse

You only live once!

---

Hello Ninja

As a presentation ninja, you certainly should not be satisfied by the "Hello World" example. You need to understand more about two things:

1. The remark.js library;

2. The xaringan package;

Basically xaringan injected the chakra of R Markdown (minus Pandoc) into remark.js. The slides are rendered by remark.js in the web browser, and the Markdown source needed by remark.js is generated from R Markdown (knitr).

---

remark.js

You can see an introduction of remark.js from its homepage. You should read the remark.js Wiki at least once to know how to

• create a new slide (Markdown syntax<sup>*</sup> and slide properties);

• format a slide (e.g. text alignment);

• configure the slideshow;

• and use the presentation (keyboard shortcuts).

It is important to be familiar with remark.js before you can understand the options in xaringan.

.footnote[[*] It is different with Pandoc's Markdown! It is limited but should be enough for presentation purposes. Come on... You do not need a slide for the Table of Contents! Well, the Markdown support in remark.js may be improved in the future.]

---

background-image: url(r xaringan:::karl) background-size: cover class: center, bottom, inverse

I was so happy to have discovered remark.js!

---

class: inverse, middle, center

Using xaringan

---

xaringan

Provides an R Markdown output format xaringan::moon_reader as a wrapper for remark.js, and you can use it in the YAML metadata, e.g.

---
title: "A Cool Presentation"
output:
  xaringan::moon_reader
    yolo: true
    nature:
      autoplay: 30000
---

See the help page ?xaringan::moon_reader for all possible options that you can use.

---

remark.js vs xaringan

Some differences between using remark.js (left) and using xaringan (right):

.pull-left[ 1. Start with a boilerplate HTML file;

1. Plain Markdown;

2. Write JavaScript to autoplay slides;

3. Manually configure MathJax;

4. Highlight code with *;

5. Edit Markdown source and refresh browser to see updated slides; ]

.pull-right[ 1. Start with an R Markdown document;

1. R Markdown (can embed R/other code chunks);

2. Provide an option autoplay;

3. MathJax just works;<sup>*</sup>

4. Highlight code with {{}};

5. The RStudio addin "Infinite Moon Reader" automatically refreshes slides on changes; ]

.footnote[[*] Not really. See next page.]

---

Math Expressions

You can write LaTeX math expressions inside a pair of dollar signs, e.g. $\alpha+\beta$ renders $\alpha+\beta$. You can use the display style with double dollar signs:

$$\bar{X}=\frac{1}{n}\sum_{i=1}^nX_i$$

$$\bar{X}=\frac{1}{n}\sum_{i=1}^nX_i$$

Limitations:

1. The source code of a LaTeX math expression must be in one line, unless it is inside a pair of double dollar signs, in which case the starting $$ must appear in the very beginning of a line, followed immediately by a non-space character, and the ending $$ must be at the end of a line, led by a non-space character;

2. There should not be spaces after the opening $ or before the closing $.

3. Math does not work on the title slide (see #61 for a workaround).

---

R Code

# a boring regression
fit = lm(dist ~ 1 + speed, data = cars)
coef(summary(fit))
dojutsu = c('地爆天星', '天照', '加具土命', '神威', '須佐能乎', '無限月読')
grep('天', dojutsu, value = TRUE)

---

R Plots

par(mar = c(4, 4, 1, .1))
plot(cars, pch = 19, col = 'darkgray', las = 1)
abline(fit, lwd = 2)

---

Tables

If you want to generate a table, make sure it is in the HTML format (instead of Markdown or other formats), e.g.,

knitr::kable(head(iris), format = 'html')

---

HTML Widgets

I have not thoroughly tested HTML widgets against xaringan. Some may work well, and some may not. It is a little tricky.

Similarly, the Shiny mode (runtime: shiny) does not work. I might get these issues fixed in the future, but these are not of high priority to me. I never turn my presentation into a Shiny app. When I need to demonstrate more complicated examples, I just launch them separately. It is convenient to share slides with other people when they are plain HTML/JS applications.

See the next page for two HTML widgets.

---

library(leaflet)
leaflet() %>% addTiles() %>% setView(-93.65, 42.0285, zoom = 17)

---

DT::datatable(
  head(iris, 10),
  fillContainer = FALSE, options = list(pageLength = 8)
)

---

Some Tips

• When you use the "Infinite Moon Reader" addin in RStudio, your R session will be blocked by default. You can click the red button on the right of the console to stop serving the slides, or use the daemonized mode so that it does not block your R session. To do the latter, you can set the option

  r options(servr.daemon = TRUE)

  in your current R session, or in ~/.Rprofile so that it is applied to all future R sessions. I do the latter by myself.

  To know more about the web server, see the servr package.

--

• Do not forget to try the yolo option of xaringan::moon_reader.

  yaml output: xaringan::moon_reader: yolo: true

---

Some Tips

• Slides can be automatically played if you set the autoplay option under nature, e.g. go to the next slide every 30 seconds in a lightning talk:

  yaml output: xaringan::moon_reader: nature: autoplay: 30000

--

• A countdown timer can be added to every page of the slides using the countdown option under nature, e.g. if you want to spend one minute on every page when you give the talk, you can set:

  yaml output: xaringan::moon_reader: nature: countdown: 60000

  Then you will see a timer counting down from 01:00, to 00:59, 00:58, ... When the time is out, the timer will continue but the time turns red.

---

Some Tips

• There are several ways to build incremental slides. See this presentation for examples.

• The option highlightLines: true of nature will highlight code lines that start with *, or are wrapped in {{ }}, or have trailing comments #<<;

  yaml output: xaringan::moon_reader: nature: highlightLines: true

  See examples on the next page.

---

Some Tips

.pull-left[ An example using a leading *:

```r
if (TRUE) {
** message("Very important!")
}
```

Output:

if (TRUE) {
* message("Very important!")
}

This is invalid R code, so it is a plain fenced code block that is not executed. ]

.pull-right[ An example using {{}}:

`r ''````r
if (TRUE) {
*{{ message("Very important!") }}
}
```

Output:

if (TRUE) {
{{ message("Very important!") }}
}

It is valid R code so you can run it. Note that {{}} can wrap an R expression of multiple lines. ]

---

Some Tips

An example of using the trailing comment #<< to highlight lines:

`r ''````r
library(ggplot2)
ggplot(mtcars) + 
  aes(mpg, disp) + 
  geom_point() +   #<<
  geom_smooth()    #<<
```

Output:

library(ggplot2)
ggplot(mtcars) + 
  aes(mpg, disp) + 
  geom_point() +   #<<
  geom_smooth()    #<<

---

Some Tips

• To make slides work offline, you need to download a copy of remark.js in advance, because xaringan uses the online version by default (see the help page ?xaringan::moon_reader).

• You can use xaringan::summon_remark() to download the latest or a specified version of remark.js. By default, it is downloaded to libs/remark-latest.min.js.

• Then change the chakra option in YAML to point to this file, e.g.

  yaml output: xaringan::moon_reader: chakra: libs/remark-latest.min.js

• If you used Google fonts in slides (the default theme uses Yanone Kaffeesatz, Droid Serif, and Source Code Pro), they won't work offline unless you download or install them locally. The Heroku app google-webfonts-helper can help you download fonts and generate the necessary CSS.

---

Macros

• remark.js allows users to define custom macros (JS functions) that can be applied to Markdown text using the syntax ![:macroName arg1, arg2, ...] or ![:macroName arg1, arg2, ...](this). For example, before remark.js initializes the slides, you can define a macro named scale:

  js remark.macros.scale = function (percentage) { var url = this; return '<img src="' + url + '" style="width: ' + percentage + '" />'; };

  Then the Markdown text

  markdown ![:scale 50%](image.jpg)

  will be translated to

  html <img src="image.jpg" style="width: 50%" />

---

Macros (continued)

• To insert macros in xaringan slides, you can use the option beforeInit under the option nature, e.g.,

  yaml output: xaringan::moon_reader: nature: beforeInit: "macros.js"

  You save your remark.js macros in the file macros.js.

• The beforeInit option can be used to insert arbitrary JS code before remark.create(). Inserting macros is just one of its possible applications.

---

CSS

Among all options in xaringan::moon_reader, the most challenging but perhaps also the most rewarding one is css, because it allows you to customize the appearance of your slides using any CSS rules or hacks you know.

You can see the default CSS file here. You can completely replace it with your own CSS files, or define new rules to override the default. See the help page ?xaringan::moon_reader for more information.

---

CSS

For example, suppose you want to change the font for code from the default "Source Code Pro" to "Ubuntu Mono". You can create a CSS file named, say, ubuntu-mono.css:

@import url(https://fonts.googleapis.com/css?family=Ubuntu+Mono:400,700,400italic);

.remark-code, .remark-inline-code { font-family: 'Ubuntu Mono'; }

Then set the css option in the YAML metadata:

output:
  xaringan::moon_reader:
    css: ["default", "ubuntu-mono.css"]

Here I assume ubuntu-mono.css is under the same directory as your Rmd.

See yihui/xaringan#83 for an example of using the Fira Code font, which supports ligatures in program code.

---

Themes

Don't want to learn CSS? Okay, you can use some user-contributed themes. A theme typically consists of two CSS files foo.css and foo-fonts.css, where foo is the theme name. Below are some existing themes:

names(xaringan:::list_css())

To use a theme, you can specify the css option as an array of CSS filenames (without the .css extensions), e.g.,

output:
  xaringan::moon_reader:
    css: [default, metropolis, metropolis-fonts]

If you want to contribute a theme to xaringan, please read this blog post.

---

class: inverse, middle, center background-image: url(https://upload.wikimedia.org/wikipedia/commons/3/39/Naruto_Shiki_Fujin.svg) background-size: contain

Naruto

---

background-image: url(https://upload.wikimedia.org/wikipedia/commons/b/be/Sharingan_triple.svg) background-size: 100px background-position: 90% 8%

Sharingan

The R package name xaringan was derived<sup>1</sup> from Sharingan, a dōjutsu in the Japanese anime Naruto with two abilities:

• the "Eye of Insight"

• the "Eye of Hypnotism"

I think a presentation is basically a way to communicate insights to the audience, and a great presentation may even "hypnotize" the audience.<sup>2,3</sup>

.footnote[ [1] In Chinese, the pronounciation of X is Sh /ʃ/ (as in shrimp). Now you should have a better idea of how to pronounce my last name Xie.

[2] By comparison, bad presentations only put the audience to sleep.

[3] Personally I find that setting background images for slides is a killer feature of remark.js. It is an effective way to bring visual impact into your presentations. ]

---

Naruto terminology

The xaringan package borrowed a few terms from Naruto, such as

• Sharingan (写輪眼; the package name)

• The moon reader (月読; an attractive R Markdown output format)

• Chakra (查克拉; the path to the remark.js library, which is the power to drive the presentation)

• Nature transformation (性質変化; transform the chakra by setting different options)

• The infinite moon reader (無限月読; start a local web server to continuously serve your slides)

• The summoning technique (download remark.js from the web)

You can click the links to know more about them if you want. The jutsu "Moon Reader" may seem a little evil, but that does not mean your slides are evil.

---

class: center

Hand seals (印)

Press h or ? to see the possible ninjutsu you can use in remark.js.

---

class: center, middle

Thanks!

Slides created via the R package xaringan.

The chakra comes from remark.js, knitr, and R Markdown.

GerkeLab/grkmisc documentation built on Feb. 23, 2020, 6:50 a.m.