第3讲 rmarkdown 与 Quarto

class: center, middle, inverse, title-slide

.title[
# 量化金融与金融编程
]
.subtitle[
## L03 <code>rmarkdown</code> 与 Quarto
]
.author[
### <br>曾永艺
]
.institute[
### 厦门大学管理学院
]
.date[
### <br>2023-10-07
]

---

class: inverse, center, middle, hide_logo
background-image: url(imgs/logo-rmarkdown.png), url(imgs/logo-quarto.png)
background-size: 4em, 5.5em
background-position: 15% 50%, 85% 50%

<div>
<style type="text/css">.xaringan-extra-logo {
width: 50px;
height: 50px;
z-index: 0;
background-image: url(imgs/logo-sm.png);
background-size: contain;
background-repeat: no-repeat;
position: absolute;
top:0.5em;right:0.5em;
}
</style>
<script>(function () {
  let tries = 0
  function addLogo () {
    if (typeof slideshow === 'undefined') {
      tries += 1
      if (tries < 10) {
        setTimeout(addLogo, 100)
      }
    } else {
      document.querySelectorAll('.remark-slide-content:not(.title-slide):not(.inverse):not(.hide_logo)')
        .forEach(function (slide) {
          const logo = document.createElement('a')
          logo.classList = 'xaringan-extra-logo'
          logo.href = 'https://qfwr2022.netlify.app'
          slide.appendChild(logo)
        })
    }
  }
  document.addEventListener('DOMContentLoaded', addLogo)
})()</script>
</div>

# 1. `rmarkdown` 与 Quarto

---
class: center, middle

.font250.bold[Your data has a story.]

.font200.red.bold[_Yes!_]

<br>.font250.bold[Tell it with R markdown / Quarto.]

.font200[🤔  .red.bold[_Why?_ & _How?_]]

---
layout: true
background-image: url(imgs/logo-rmarkdown.png)
background-size: 2em
background-position: 51% 5%

### [{{R Markdown}}](https://rmarkdown.rstudio.com/)  -> `rmarkdown` <sup>.font70[2.25]</sup>

---

> .font110.bold[_Dynamic Documents for R_]

.font110[

- R Markdown 为数据科学提供了一种统一的写作框架，可以集成代码、输出结果和文本说明

- R Markdown 文档是可复现的（_reproducible_）

- R Markdown 主体使用 Markdown 撰写，并利用 [{{Pandoc}}](https://pandoc.org/) 将 `knitr` 后的 <svg aria-hidden="true" role="img" viewBox="0 0 640 512" style="height:1em;width:1.25em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M593.8 59.1H46.2C20.7 59.1 0 79.8 0 105.2v301.5c0 25.5 20.7 46.2 46.2 46.2h547.7c25.5 0 46.2-20.7 46.1-46.1V105.2c0-25.4-20.7-46.1-46.2-46.1zM338.5 360.6H277v-120l-61.5 76.9-61.5-76.9v120H92.3V151.4h61.5l61.5 76.9 61.5-76.9h61.5v209.2zm135.3 3.1L381.5 256H443V151.4h61.5V256H566z"/></svg> 文档转换为目标输出格式并进行样式渲染，支持包括 html、PDF、Word、幻灯片、仪表盘图表、shiny 应用、期刊论文、书籍、网站等静态或动态的展示

]

---
layout: true
background-image: url(imgs/logo-quarto2.png)
background-size: 7.5em
background-position: 8.5% 5%

### [{{&emsp;&emsp;&emsp;&emsp;&emsp;&nbsp;<sup>.font70[1.3.433]</sup>}}](https://quarto.org/)

---

> .font110.bold[_Open source tools for scientific and technical publishing_]

.font50[<br>]

.font120.bold[

- Author using [Jupyter](https://jupyter.org/) notebooks or with plain text markdown in your favorite editor.

- Create dynamic content with Python, R, Julia, and Observable.

- Publish reproducible, production quality articles, presentations, websites, blogs, and books in HTML, PDF, MS Word, ePub, and more.

- Write using [Pandoc](https://pandoc.org/) markdown, including equations, citations, crossrefs, figure panels, callouts, advanced layout, and more.

- Share knowledge and insights organization-wide by publishing to Posit Connect, Confluence, or other publishing systems.

]

---

> .font110.bold[_Open source tools for scientific and technical publishing_]

---
layout: false
class: inverse, center, middle, hide_logo
background-image: url(imgs/logo-rmarkdown.png), url(imgs/logo-quarto.png)
background-size: 4em, 5.5em
background-position: 20% 38%, 19% 62%

# 2. 动态文档构成

---
layout: true

### >> YAML 文件头

---

.font110[
- YAML 文件头处于两个 `---` 之间
- [YAML](https://yaml.org/)：_YAML Ain't Markup Language_，易于读写的层次化数据
- 利用 YAML 文件头提供 metadata 并控制文档渲染和样式等方面的参数
]

.pull-left.font100[
```yaml
---
title: "Penguins, meet Quarto!"
subtitle: 企鹅遇上Quarto！💘
author: "曾永艺"
date: today
format: 
  html:
    toc: true
    code-fold: true
editor: visual
---
```

- [{{一文看懂 YAML}}](https://zhuanlan.zhihu.com/p/145173920)

- [{{Quarto HTML Options}}](https://quarto.org/docs/reference/formats/html.html)

- **RStudio**'s [{{YAML Intelligence}}](https://quarto.org/docs/tools/rstudio.html#yaml-intelligence)

]

.pull-right.code80[
```yaml
---
title: "量化金融与金融编程"
subtitle: "L03 `rmarkdown` 与 Quarto"
author: "<br>曾永艺"
institute: "厦门大学管理学院"
date: "<br>2023-10-07"
output:
  xaringan::moon_reader:
    css: [libs/zen-styles-v2.3-rev.css]
    lib_dir: libs
    chakra: libs/remark-latest.min.js
    nature:
      ratio: '16:9'
      highlightLines: true
      countIncrementalSlides: false
---
```
`?xaringan::moon_reader`
]

---
layout: true

### >> Markdown 文本

---

.font110[
- 用 [**{{扩展的 Markdown 语法}}**](https://qfwr2023.netlify.app/readings/markdown-basics.html)  <svg aria-hidden="true" role="img" viewBox="0 0 640 512" style="height:1em;width:1.25em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M593.8 59.1H46.2C20.7 59.1 0 79.8 0 105.2v301.5c0 25.5 20.7 46.2 46.2 46.2h547.7c25.5 0 46.2-20.7 46.1-46.1V105.2c0-25.4-20.7-46.1-46.2-46.1zM338.5 360.6H277v-120l-61.5 76.9-61.5-76.9v120H92.3V151.4h61.5l61.5 76.9 61.5-76.9h61.5v209.2zm135.3 3.1L381.5 256H443V151.4h61.5V256H566z"/></svg>来撰写说明性文本（<svg aria-hidden="true" role="img" viewBox="0 0 640 512" style="height:1em;width:1.25em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M593.8 59.1H46.2C20.7 59.1 0 79.8 0 105.2v301.5c0 25.5 20.7 46.2 46.2 46.2h547.7c25.5 0 46.2-20.7 46.1-46.1V105.2c0-25.4-20.7-46.1-46.2-46.1zM338.5 360.6H277v-120l-61.5 76.9-61.5-76.9v120H92.3V151.4h61.5l61.5 76.9 61.5-76.9h61.5v209.2zm135.3 3.1L381.5 256H443V151.4h61.5V256H566z"/></svg>是用来格式化纯文本文件的轻量级语法，其设计哲学就是使得文本既容易写又容易读）。
]

- .font110[.red.bold[[{{rstudio-visual-markdown-editing}}](https://rstudio.github.io/visual-markdown-editing/)] 🤩]

---
layout: true

### >> 代码块

---

.font100[
1. 插入代码块：使用快捷键 .kbd[Ctrl+Alt+I]（也可使用编辑器工具栏上的 Insert 按钮 或者 手工输入代码段标记符```` ```{r} ```` 和```` ``` ````）
2. 设置代码块标签名和[{{代码块选项}}](https://quarto.org/docs/reference/cells/cells-knitr.html)（也可在通过 `knitr::opts_chunk$set()` 或者 YAML 文件头设置全局选项——当同个选项多处设置时，局部设置优先），善用RStudio**智能补全**功能
3. 编写 <svg aria-hidden="true" role="img" viewBox="0 0 581 512" style="height:1em;width:1.13em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M581 226.6C581 119.1 450.9 32 290.5 32S0 119.1 0 226.6C0 322.4 103.3 402 239.4 418.1V480h99.1v-61.5c24.3-2.7 47.6-7.4 69.4-13.9L448 480h112l-67.4-113.7c54.5-35.4 88.4-84.9 88.4-139.7zm-466.8 14.5c0-73.5 98.9-133 220.8-133s211.9 40.7 211.9 133c0 50.1-26.5 85-70.3 106.4-2.4-1.6-4.7-2.9-6.4-3.7-10.2-5.2-27.8-10.5-27.8-10.5s86.6-6.4 86.6-92.7-90.6-87.9-90.6-87.9h-199V361c-74.1-21.5-125.2-67.1-125.2-119.9zm225.1 38.3v-55.6c57.8 0 87.8-6.8 87.8 27.3 0 36.5-38.2 28.3-87.8 28.3zm-.9 72.5H365c10.8 0 18.9 11.7 24 19.2-16.1 1.9-33 2.8-50.6 2.9v-22.1z"/></svg> 代码
4. 运行代码：使用快捷键 .kbd[Ctrl+Shift+Enter] | .kbd[Ctrl+Enter] 或者 点击.green[▶]按钮
]

.font100[
- 行内代码

```r
  这份数据中包含了`r nrow(diamonds)`颗钻石的信息。其中只有`r nrow(diamonds) - nrow(smaller)`颗
钻石大于2.5克拉。其余钻石的分布如下图所示。
```
]

---
layout: false
class: inverse, center, middle, hide_logo
background-image: url(imgs/logo-quarto.png)
background-size: 5.5em
background-position: 10% 50%

# 3. Quarto 工作流与随堂练习

---
layout: true

### >> 工作流

---

.pull-left.font100[

1. 创建（通用的）项目文件夹

2. 打开新的 .qmd 文档：`File > New File > Quarto Document ...`

- **Document** | Presentation | Interactive
    
    - 修改 Title 和 Author，设置输出格式为 **Html**、Engine 为 **Knitr** 等

3. **存盘 ↔ 根据需要编辑修改模板文档**

4. `Render` .qmd 文档，生成目标输出文档

5. 在 RStudio 窗口中预览结果

6. 在 Background Jobs 窗口中检查文档创建过程记录

7. 使用和 .qmd 文档一并存储的目标输出文档

8. 将报告发布到网络服务器（可选步骤）
]

.pull-right[
<br>

]

---
layout: false
class: hide_logo
background-image: url(docs/imgs/penguins.png)
background-size: 40%
background-position: 90% 90%

## 🙋‍♂️ Your Turn!

<br>

.font150[

1. 安装 `palmerpenguins` 包

2. 下载模板与文件

+ 从 [{{课程网站}}](https://qfwr2023.netlify.app/slides/lec-03/docs/_hello.qmd) 或 QQ 课程群共享文件下载 `_hello.qmd`.red[（并重命名为 `hello.qmd`）]

+ 从 [{{课程网站}}](https://qfwr2023.netlify.app/slides/lec-03/docs/imgs/penguins.png) 或 QQ 课程群<br>共享文件下载 `penguins.png`

3. 循序渐进完成以下步骤 ......

]

---
layout: false
class: hide_logo

## 🙋‍♂️ Your Turn >> 🕐

.font120[

1. 在 RStudio IDE 中完成：

1) 新建（通用）项目 L03_class，查看项目文件夹的内容

2) 将下载的 `hello.qmd` 放入 L03_class 根目录

3) 在 L03_class 根目录下新建文件夹 imgs，将下载的 `penguins.png` 放入其中

2. 在 RStudio 中打开 `hello.qmd` 文档，并完成如下操作：
    
    ![](imgs/class-render.png)

3. **和队友（或身边的同学）一起找出 qmd 文档的三类构成要素，并讨论各个构成要素和 Render 生成的 HTML文档是如何一一对应的。**

]

---
layout: false
class: hide_logo

## 🙋‍♂️ Your Turn >> 🕑

.font120[
感觉渲染生成的 HTML文档中存在几个明显的问题啊 😢！<br>
请同学们探索下相应的解决方法（修订后记得 .kbd[Ctrl + S] 存盘 -> <br>
文档会自动重新 Render）：
]

.font120[1\. 渲染文档中免费赠送的 `AUTHOR` 和 `PUBLISHED` 能否改为中文？]

> 可以！提示：语言？language？-> [{{Quarto 官网}}](https://quarto.org/) 全局搜索之（[{{备用链接}}](https://mystifying-jepsen-fa4396.netlify.app/)）。

.font120[2\. 日期变了（本来是`October 08, 2023`），但能否改为更简洁的 `2023-10-08`？]

.font120[3\. 已设置 `toc: true`，但怎么就看不到目录呢？难道需要设置 `toc-location`？]

.font120[4\. 代码块 `load-packages` 输出大量提示信息，怎么关了它？两行 `library(*)` 有无必要显示？怎么关了它？]

.font120[5\. 代码块 `plot-penguins` 有 _Warning_，怎么关了它？]

.font120[6\. 代码块 `plot-penguins` 占用的空间有点大，我已知道通过设置代码块选项 `echo: false` 可关闭代码显示，但~~万一老板/读者一时兴起又想检视代码呢？！]

---
layout: false
class: hide_logo

## 🙋‍♂️ Your Turn >> 🕒

.font120[
这下好多啦，但还是得再东调调，西补补——可千万别辜负我们<br>
厦大人“止于至善”的校训 😁：
]

.font120[1\. 代码块 `plot-penguins` 输出的图表并未居中对齐，看起来不太舒服。改了！]

.font120[2\. 代码块 `plot-penguins` 输出的图表竟然没有标题，不满足学术规范。加上！]

.font120[3\. 嗯~~ 成功自动生成了图表标题，但怎么就没有自动生成“图#:”的标识呢？]

> 提示：试着将代码块标签修改为 `fig-penguins` 试试？

.font120[4\. 顺带将前一段落中的“下图”修改为交叉引用啦——手动输入？还是？]

> 提示：不想再用 [{{Quarto官网}}](https://quarto.org/) 全局搜索？那就切换为 **Visual** 编辑方式，找看看应该是 Insert 什么呢？

.font120[5\. 图表标题怎么没有居中对齐呢？]

> 提示：[浏览器->选中图表标题->右键->检查->尝试修改Elements的style ->]增加CSS

---
layout: false
class: hide_logo

## 🙋‍♂️ Your Turn >> 🕓

.font120[
最后的最后，假如还有时间的话~~：
]

.font120[1\. 目前 paper 只有两段，怎么也得有三段！给加上“## 结论”吧，随便写点什么都行——譬如“总之，个人认为南极企鹅碰上 Quarto 标示着一场令人期待的梦幻数据科学探险之旅的开始！🌈”]

.font120[2\. 可尝试着设置 HTML文档的 [主题（theme）](https://quarto.org/docs/output-formats/html-themes.html)——轻松一个参数就能带给你焕然一新的感觉。]

.font120[3\. 可尝试给 `format:` 增加一个文档输出类型选项：`docx: default`，然后展开 **Render** 按键右侧的下箭头 -> **Render MS Word**，看看结果如何。]

.font120[4\. 还想尝试将文档输出为 PDF 格式？中文文档，那还是别太为难 Quarto 和 Pandoc （以及折腾你自己啦）——个人感觉将生成的 HTML 文档在浏览器中打开然后打印为 PDF 格式可能是最直接且最美观的方式啦。]

.font120[5\. 同学们还应该进一步了解下[代码块的 `knitr` 选项](https://quarto.org/docs/reference/cells/cells-knitr.html)、 [LaTex公式](https://quarto.org/docs/output-formats/html-basics.html#latex-equations)、[标签页](https://quarto.org/docs/output-formats/html-basics.html#tabsets)、[页面布局](https://quarto.org/docs/authoring/article-layout.html)……以及不同的输出格式，如[幻灯片](https://quarto.org/docs/presentations/)、[网站](https://quarto.org/docs/websites/)、[图书](https://quarto.org/docs/books/)……等等。]

---
layout: false
class: inverse, center, middle, hide_logo
background-image: url(imgs/logo-xaringan.png)
background-size: 5.5em
background-position: 76% 50%

# 4. `prettydoc`、`tufte` 和 &emsp;&emsp;&emsp; ...

---
layout: false

### >> [{{`prettydoc`<sup>.font60[0.4.1]</sup>}}](https://prettydoc.statr.me)

---
layout: false

### >> [{{`tufte`<sup>.font60[0.13]</sup>}}](https://rstudio.github.io/tufte/)

---
layout: true

### >> [{{`xaringan`<sup>.font60[0.28]</sup>}}](https://github.com/yihui/xaringan)

---

> .font110[Creating HTML5 presentations with `remark.js` through `R Markdown`.]

.left-column[
<img src="imgs/xaringan_01.png" width="92%" style="display: block; margin: auto 0 auto auto;" />
]

.right-column[
<iframe src="https://slides.yihui.org/xaringan/zh-CN.html" width="100%" height="460px" data-external="1"></iframe>
]

---
layout: false
background-image: url(imgs/logo-xaringanthemer.png)
background-size: 5%
background-position: 41% 4%

### >> [{{`xaringanthemer`<sup>.font60[0.4.2]</sup>}}](https://pkg.garrickadenbuie.com/xaringanthemer) &emsp;&emsp;和 [{{`xaringanExtra`<sup>.font60[0.7.0]</sup>}}](https://pkg.garrickadenbuie.com/xaringanExtra)

.pull-left.code60[

```r
# install.packages("xaringanthemer")
```

```yaml
---
output:
  xaringan::moon_reader:
*    css: xaringan-themer.css
---
```

````r
```{r xaringan-themer, include=FALSE, warning=FALSE}
library(xaringanthemer)
style_duo_accent(
  primary_color = "#1381B0", secondary_color = "#FF961C",
  inverse_header_color = "#FFFFFF",
  header_font_google = google_font("Josefin Sans"),
  text_font_google   = google_font("Montserrat", "300", "300i"),
  code_font_google   = google_font("Fira Mono")
)
```
````
]

.pull-right.font75[

.font110[
> `xaringanExtra`: .can-edit.red.key-xaringanExtra[A playground of enhancements and extensions for `xaringan`]
]

- Add an overview of your presentation with **tile view** 🗺
- Make your slides **editable** 📝
- Share your slides in style with **share again** 📼
- Broadcast your slides in real time to viewers with **broadcast** 📡
- Scribble on your slides during your presentation with **scribble** 👩‍🎨
- Announce slide changes with a subtle **tone** 🔊
- Animate slide transitions with **animate.css** 📽
- Add tabbed panels to slides with **panelset** 🗂
- Add a logo to all of your slides with **logo** 💌
- Add a search box to search through your slides with **search** 🔍
- Use the **Tachyons** CSS utility toolkit 🏗
- Add a live video feed of your **webcam** 🤳
- Add one-click code copying with **clipboard** 📋
- Always play gifs from the start with **freezeframe** ⏸️
- **Fit** your slides to fill the browser window 📐
- Add extra CSS **styles** 😎
]

---
layout: false
class: inverse, center, middle, animated, lightSpeedIn, slideOutLeft

# 参考资料与课后作业

---
class: animated, slideInRight

.font120.bold[
相信同学们现在对 `rmarkdown` 和 Quarto 有了初步的认识，下面列出一些学习资料，同学们可进一步学习精进 🏆
]

.pull-left.font120[

- 📖 **教材**<br>
[{{_R for Data Science, 2e_}}](https://r4ds.hadley.nz/) 一书关于 Quarto 的第29章和第30章<br>
（大致对应中文翻译版[《R数据科学》](https://www.ituring.com.cn/book/2113)的第20、22和23章）

<br>
- 🏡 **官网**<br>
[**{{Quarto}}**](https://quarto.org/) / 
[**{{R Markdown}}**](https://rmarkdown.rstudio.com/)

<br>
- 📝 **速查**<br>
[**{{Quarto}}**](https://qfwr2023.netlify.app/slides/lec-03/docs/quarto-cheatsheet.pdf) / 
[**{{R Markdown}}**](https://qfwr2023.netlify.app/slides/lec-03/docs/rmarkdown-cheatsheet.pdf)

]

.pull-right.font120[

.right[
<img src="imgs/rmarkdown-book.jpg" width="45%" /><img src="imgs/rmarkdown-cookbook.png" width="45%" />
]

- [{{_R Markdown: The Definitive Guide_}}](https://bookdown.org/yihui/rmarkdown/)  
- [{{_R Markdown Cookbook_}}](https://bookdown.org/yihui/rmarkdown-cookbook/)

]

---

### >> 课后作业

.font150[
自由组队，两人一组，共同完成课后作业：
]

.font130[
🕐 从 L02 课件中挑出 3 ~ 4 个你们感兴趣的数据可视化代码段，就其制作两种类型的展示文档：
]
  
  1. .font120[[{{`Quarto|HTML`}}](https://quarto.org/docs/output-formats/html-basics.html) 或 [{{`prettydoc`}}](https://prettydoc.statr.me/themes.html) -> 📂 *L03_HW/docs/*]
  
  2. .font120[[{{`Quarto|Revealjs`}}](https://quarto.org/docs/presentations/revealjs/) 或 [{{`xaringan`}}](https://slides.yihui.org/xaringan/zh-CN.html) -> 📂 *L03_HW/slides/*]

.font130[
🕑 记得**多尝试各种选项设置**，同时在文档内**加上相应的说明性文字**（如解释代码或输出图形，其余内容可自由发挥，丰俭由人啦 😁）
]

.font130[
🕒 作业共同署名（`author: 姓名 + 姓名`）
]

.font130[
🕓 确认两份文档运行无误后将文件夹📂 *L03_HW* **打包为 .zip 格式压缩文档**，由其中**一位**同学于2023年10月15日22:00前将压缩包提交至 [{{坚果云链接}}](https://send2me.cn/KFJc2IN9/Q8Kvv8EApjAO-Q)
]

---
layout: false
class: center, middle, hide_logo, animated, zoomInDown
background-image: url(imgs/logo-xaringan.png)
background-size: 12%
background-position: 50% 40%

<br><br><br><br><br><br><br>
<hr color='#f00' size='2px' width='80%'>
<br>
.Large.red[_**本网页版讲义的制作由 R 包 [{{`xaringan`}}](https://github.com/yihui/xaringan) 赋能！**_]