71-R分享01-Rmd新手入门指南

参见：https://www.math.pku.edu.cn/teachers/lidf/docs/Rbook/html/_Rbook/rmarkdown.html[1]

1. 什么是Rmd(R markdown)?

★借助于R的knitr和rmarkdown扩展包的帮助， 可以在Markdown格式的源文件中插入R代码， 使得R代码的结果能够自动插入到最后生成的研究报告中。”

我们可以将Rmd 理解为，可以在md 文档中运行R 代码，并能将R 代码的运行结果最终输入到输出报告中的文件。

输出格式可以是HTML、docx、pdf、beamer等。R Markdown的基础格式是markdown格式， 严格说来是Pandoc软件支持的增强版的markdown格式， 比如， 支持LaTex格式的数学公式， 支持各种编程语言语法彩色加亮显示，等等。

2. Rmd 的基本结构

一个Rmd 文件包含三个部分：

分别是：

• yaml 格式的开头部分
• 一般md 格式的正文部分
• R 代码部分

我的第一个Rmd

选择Rmd 创建：

选择默认的值即可，这里选择输出为html：

直接选择knit 标志：

还不错：

3. 详说三大结构

3.1 开头部分

我们可以将Rmd 的开头部分理解为其元数据。可以用来规定文章标题、作者、日期、输出格式、输出设置等属性。

比如当我们用Rstudio 创建默认的Rmd：

头文件是：

---
title: "test"
author: "ghost"
date: "3/27/2021"
output: html_document
---

输出之后是这个亚子的：

头部分格式为yaml：

- #减号表并列
# #井号表注释
| #竖线表整块数据

这里我们不必细究yaml 的具体语法，通常的开头部分都是包括title, author, date, output 这四个部分的。而通过下面的格式进行定义：

key: "value"

而每个key 下面，可以对应subkey，用tab 间隔：

output: 
  html_document:
    toc: True

我们可以自定义一下date 与output。

日期

这里先提一下Rmd 的行内代码特性，行内代码的结果插入到一个段落中间， 代码以r`开头，以```结尾， 如r sin(pi/2)``在结果中会显示为1。

我们可以利用Rmd 支持行内插入R代码的特性，利用函数Sys.time() 获得时间的返回值：

date: "`r Sys.time()`"

另外还可以结合format 函数：

> format(Sys.time(), '%d %B, %Y')
[1] "27 三月, 2021"

image.png

设置目录

我们可以在output 下，设定toc：

output: 
  html_document:
    toc: True
    toc_depth: 3

toc_depth 用来指定目录显示的标题级数，如3 表示只会显示到 ### 对应的标题。默认下，html_document 对应为3；pdf_document 对应为2。

如果你不喜欢在Rmd 文件中标记序号：

# a

## b
good!

## d
bad!

# c
hhhh!

还可以打开number_sections ，这样在输出结果中会自动标记序号：

---
title: "01-美化作图"
author: "Peng"
date: "`r Sys.time()`"
output: 
  html_document:
    toc: True
    number_sections: True
---

image.png

另外一个比较好用的是toc_float，其包括两个选项，collapsed 控制是否显示子标题；smooth_scroll 控制跳转动画，默认为T 分别表示不显示：

---
title: "01-美化作图"
author: "Peng"
date: "`r Sys.time()`"
output: 
  html_document:
    toc: True
    number_sections: True
    toc_float:
      collapsed: false
---

打开后，我们就可以在页面的右侧选择对应目录：

3.2 正文部分

正文部分遵循md 语法，如果你熟练的掌握了md 句法，可以跳过这一部分～

关于md 学习，可以参见：013. 用Markdown来写作[2]

先前提到过，Rmd 的行内代码特性，行内代码的结果插入到一个段落中间， 代码以r`开头，以```结尾， 如r sin(pi/2)``在结果中会显示为1。

比如：

# 正文
今天是几号啊？
今天是`r mday(now())` 号。

image.png

3.3 代码块部分

代码块部分使用{r} chunk code 的形式：

library(lubridate)
now()

name 用来定义该段code chunk 的名称。

关于输出的几个选项

另外，根据R 代码的几个特征：

• 是否运行
• 是否显示代码
• 是否显示输出结果
• 是否显示输出的图像结果
• 是否提示warning, message 或error

比如加载相关包的代码块，我们就可以使用：

library(lubridate)

这样可以在输出结果中不显示可能出现的一些警告。

其他选项

• highlight 选项

转化后的R代码块缺省显示为彩色加亮形式。用选项highlight=FALSE关闭彩色加亮功能。

• prompt和comment选项

默认下，输出的结果中的R 的代码开始是没有任何符号的；而R 代码的运行结果则是用井号保护的。

我们可以进行修改，用选项 prompt=TRUE将R 用大于号提示符开始；用选项comment=''将结果的保护符号替换成自定义内容，"" 则表示不用任何符号保护：

a <- 3
a

image.png

• tidy 选项

加选项tidy=TRUE 可以自动重新排列代码段， 使得代码段格式更符合规范。例如：

s <- 0
for(x in 1:5) {s <- s + x^x; print(s)}

运行结果：

• collapse 选项

通常代码块的代码，会根据其运行输出，拆分成多个文本块，如果我们不希望输出为：

可以设置collapse=TRUE，代码和结果都将在一个文本块中显示：

sin(pi/2)
## [1] 1
cos(pi/2)
## [1] 6.123234e-17

全局设定

我们先前对于代码块的设定，都是作用于局部，不同的代码块只遵循其局部自定义的内容：

如果我们希望代码块的设置在所有结果中生效，需要进行专门的声明，比如在代码块的开头进行声明：

knitr::opts_chunk$set(echo = TRUE)
knitr::opts_chunk$set(warning = F, message  = F)

这个setup 中配置的信息将会作用于全部的代码块了。

4. Rmd 文件的编译

RStudio 是一个集成的R软件环境， 可以用来编辑和执行R程序， 这个软件也可以用来编辑和编译R Markdown格式的文件， 使得R Markdown格式的文件变得容易使用。

使用RStudio 提供的knit 工具，我们可以将Rmd 文件转换成HTML格式、PDF格式（需要安装LaTeX编译软件）、MS Word格式。

如果不借助于RStudio 软件， 也可以用R软件、knitr包、rmarkdown包、pandoc软件来完成R Markdown源文件的编译。比如：

rmarkdown::render("myfile.Rmd", output_format = "html_document", encoding="UTF-8")
rmarkdown::render("myfile.Rmd", output_format = "word_document", encoding="UTF-8")

在李东风老师的书中，还总结了一些差别：

用RStudio的Knit图标一键编译与用rmarkdown::render()命令编译有重要差别：

• 用Knit图标编译，Rmd文件中的程序会在一个崭新的会话中执行， 当前会话中已经定义的函数、变量、导入的扩展包不会影响到编译结果；
• 用rmarkdown::render()编译， Rmd文件中的程序是在当前会话中执行的， 会带来一定的兼容性问题， 有可能在别人的环境下就不能正确执行或者会给出不同结果。但是，rmarkdown::render()可以通过程序调用， 比如，循环地从同一个Rmd生成一系列不同的报告。为了不让当前会话环境干扰结果， 可以人为地打开一个新会话。

4.1 编译的过程

编译Rmd文件， 一般是调用rmarkdown::render() 函数执行任务。编译的第一步， 会调用knitr包的knit()函数将代码段中的程序依次运行， 结果保存为一个临时.md文件中， 图形结果暂存在单独的图形文件中， 文字结果会直接保存在临时.md文件中。编译的第二步， 调用外部程序Pandoc将临时的.md文件转换为要求的Word、HTML等输出格式；如果要求的输出是pdf_document， 则会调用Pandoc先将临时的.md文件转换为一个中间的.tex文件， 然后利用tinytex包调用外部的TinyTex软件将.tex文件编译为PDF结果。

4.2 其他格式文件的转换

• 从HTML格式可以转换成PDF格式

打开浏览器进入选定的网页后，可以选择菜单“打印”， 选打印机为“另存为PDF”， 然后选“更多设置”， 将其中的“缩放”改为自定义， 比例改为“90%”， 就可以将HTML网页转换成PDF， 其中的数学公式、表格、图形都可以比较好地转换。注意，如果不缩小打印， 数学公式的编号以及较长的数学公式可能会被裁剪掉。

• 从Word文件转换成PDF格式

使用Word软件的“文件-导出”或者“文件-另存为”功能即可。

• 从PDF 转换为其他格式

可以使用adobe acrobat 软件，除了字体之外，还可以使用：

参考资料

[1]https://www.math.pku.edu.cn/teachers/lidf/docs/Rbook/html/_Rbook/rmarkdown.html: https://www.math.pku.edu.cn/teachers/lidf/docs/Rbook/html/_Rbook/rmarkdown.html

[2]013. 用Markdown来写作: https://www.yuque.com/go/doc/31592921?view=doc_embed