02-components.Rmd

# bookdown组件

本章内容包括在使用模板撰写论文时常用的bookdown组件，包括代码块、图片、表格、引用、数学定理与方程。本章的大部分内容翻译自https://bookdown.org/yihui/bookdown/components.html。由于bookdown的建立是基于pandoc的，我们从一些pandoc语法开始。

## markdown语法

### 行内样式

你可以通过`_斜体_`或`*斜体*`来使用*斜体*；用`**粗体**`或`__粗体__`来使用**粗体**。两个`~`中间的文字会变为下标如`X~1~,X~2~,$\cdots$,X~n~`，会生成X~1~,X~2~,$\cdots$,X~n~；同样俩个`^`间的文字会变为上标如`X^2^`会生成X^2^。超链接将使用`[text](link)`创建，如`[RStudio](https://www.rstudio.com)`[RStudio](https://www.rstudio.com)。可以使用`^[]`添加脚注，如`^[这是一个脚注]`^[这是一个脚注]

### 数学表达式

你可以在一对`$`中间插入行内LaTex数学表达式，例如`$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$`会输出$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$，或者在一对`$$`中插入行间数学表达式，例如`$$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$$` 会输出 $$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$$。

同样，你还可以在一对`$`或`$$`中间使用其他数学环境，比如

``` array
$$
\begin{array}{ccc}
x_{11} & x_{12} & x_{13}\\
x_{21} & x_{22} & x_{23}
\end{array}
$$
```

$$
\begin{array}{ccc}
x_{11} & x_{12} & x_{13}\\
x_{21} & x_{22} & x_{23}
\end{array}
$$


你可以引用更多的数学环境如矩阵、行列式等等，详情可以参考latex中文简介

## bookdown支持的markdown拓展

为了有效的给数学公式标数字且引用，你可以在公式的数学环境中加入标签`(\#eq:标签)`，并引用他们，例如：

```latex
\begin{equation} 
  f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
  (\#eq:binom)
\end{equation}

```
将得到：
\begin{equation} 
  f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
  (\#eq:binom)
\end{equation}


那么你就可以使用`\@ref(eq:binom)`来引用此公式，例如见\@ref(eq:binom)

## 定理与证明{#theorems-proof}

bookdown中支持另一种定理环境，是基于code chunk来完成的，例如


输出结果为：


在引用时你可以使用`\@ref(prefix:label)`，prefix是定理环境的简写，对于theorem为thm，那么我们要引用此定理，就可以用`\@ref(thm:pyth)`，即，见定理\@ref(thm:pyth)

对于更多的定理环境以及他们对应的prefix可以见[theorems](https://bookdown.org/yihui/bookdown/markdown-extensions-by-bookdown.html#theorems)。

## 图片

你可以通过knitr来输出图片并加载至文章中：

```{r}
par(mar = c(4, 4, 0.1, 0.1))
plot(pressure, pch = 19, type = "b")
```

当然，在使用LaTex制作论文并插入图片时，你几乎不可避免的会遇到图片浮动的问题，即图片可能会出现在文章的其他位置。如果你不常使用LaTex并且不希望这种情况发生，你应该注意图片的浮动问题，通过修改图片的尺寸来解决这个问题。

和前面的定理环境相似，你也可以通过chunk option对代码块设定标签并在后面进行引用，同时你还可以使用更多knitr中R code chunk的设定来对图片进行更好的控制。



```{r pressure, fig.caption = '这是一个用knitr chunk option 设定的图像', fig.width = 6, fig.asp = 0.7, fig.aligin = 'center'}
par(mar = c(4, 4, 0.1, 0.1))
plot(pressure, pch = 19, type = "b")
```
在输出这个图片时，我们使用了`fig.cap`来设定图片标题，用`fig.width`设定了图片的宽度，用`fig.asp = 0.7`设定图片的长宽比例固定在0.7，`fig.aligin = 'center'`令图片居中。你还可以使用其他的R chunk option来对图片进行设置。更多的设置可以见[option-plots](https://yihui.name/knitr/options/#plots)。

## 插入本地图片

在使用Rmarkdown的过程中，你同样可以使用markdown/LaTex/html的语法插入本地图片，不过我们更推荐你使用`knitr::include_graphics()`，主要原因有：

1. 你不需要担心文档的输出格式，`knitr::include_graphics()`可以根据你的文档输出格式来自适应的选择输出函数`![]()`（markdown）、`\includegraphics`（LaTex）或是其他的输出函数；
2. 在使用knitr函数的过程中，你可以像上面一样轻松的使用chunk option来对图片进行设定和约束；
3. 当输出PDF文件时，`include_graphics()`可以自动帮助你将原有的png或jpg图片替换为pdf格式，可以在输出pdf文档时获得更好的体验。

## 表格

在bookdown中，你可以使用markdown语法的表格，或者LaTex语法的表格，或者使用R中的一些制表的辅助包、辅助函数如`knitr::kable()`、`huxtable`或`xtable`等。使用`kable`，你可以轻松的将R中的数据框输出为html或LaTex制式的表格，例如：

```{r kb-table, echo = TRUE}
knitr::kable(
  head(mtcars[, 1:8], 10), booktabs = TRUE,
  caption = 'kable()输出的一个表'
)
```

当然，如果熟悉markdown，你也可以使用makrdown语法的表格
```
Table: A simple table in Markdown.

 Sepal.Length   Sepal.Width   Petal.Length   Petal.Width
-------------  ------------  -------------  ------------
          5.1           3.5            1.4           0.2
          4.9           3.0            1.4           0.2
          4.7           3.2            1.3           0.2
          4.6           3.1            1.5           0.2
          5.0           3.6            1.4           0.2
          5.4           3.9            1.7           0.4
```

基于bookdown的便利性，你也可以像引用图片一样方便的引用这些表格。

### 回归结果

对于回归分析的结果，你可以调用[`huxtable`]()包来轻松的进行学术化的制表，甚至可以对多个回归方程轻松的联合制表。

```{r, message=FALSE, warning=FALSE}
library(dplyr)
library(huxtable)
data(diamonds, package = 'ggplot2')
lm1 <- lm(price ~ carat + depth, diamonds)
lm2 <- lm(price ~ depth + factor(color, ordered = FALSE), diamonds)
lm3 <- lm(log(price) ~ carat + depth, diamonds)
```

```{r,fig.pos='H'}
color_names <- paste0('factor(color, ordered = FALSE)', LETTERS[5:10])
names(color_names) <- paste('Color:', LETTERS[5:10])

huxreg(lm1, lm2, lm3, 
  coefs = c('Carat' = 'carat', 'Depth' = 'depth', color_names)) %>% 
  theme_article()

```

更多的关于`huxreg()`的用法可以见[这里](https://hughjonesd.github.io/huxtable/huxreg.html)。

## 交叉引用与引文

与前面的引用图标、公式、定理的方法相同，你也可以用`\@ref(label)`来引用章节标题，如果是英文标题，pandoc将自动为之分配一个标签，如章Reference 将拥有一个标签reference。如果是中文标题，可以考虑使用Peng Zhao开发的包[`pinyin`](https://github.com/pzhaonet/pinyin)，它可以自动给中文章节分配一个与其拼音拼写对应的标签。

不过这可能会导致某个章节的标签过长，所以我们还是建议你自己为每个章节定制标签，在每个章节后添加{#ID}，ID即为本章的标签。

### bibtex与文献引用

为了方便的引用和排列参考文献，你应该使用bibtex来对参考文献进行管理。pandoc可以利用[`pandoc-citeproc`](https://github.com/jgm/pandoc-citeproc)单元来处理文献引用的问题，当输出格式为LaTex时，利用BibTex可以更好的处理参考文献。

一个BibTex database文件时一个纯文本文件（文件拓展名为`.bib`），其中一个书目条目(bibliography entry)的主要内容应该如：

```

@Manual{R-base,
  title = {R: A Language and Environment for Statistical
    Computing},
  author = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address = {Vienna, Austria},
  year = {2016},
  url = {https://www.R-project.org/},
}
```
每一个书目条目以`@type{`起始，其中type包括`article`、`book`、`Manual`等类型，然后每个书目条目中有一个引用关键字，如上面的`R-base`，你可以使用`@R-base`
或`[@R-base]`来引用它，后者将会在括号中引用文献，如[@R-base]。

同时在`knitr`中还有一个辅助函数`knitr::write_bib()`可以帮助你引用在写论文时使用到的包。例如：
```{r write_bib, echo = TRUE}
knitr::write_bib(c("knitr", "stringr"), "bib/Rpackage.bib", width = 60)
```

会生成一个名为`Rpackage`内容如下的`.bib`文件

```bib
@Manual{R-knitr,
  title = {knitr: A General-Purpose Package for Dynamic Report
    Generation in R},
  author = {Yihui Xie},
  year = {2018},
  note = {R package version 1.20.22},
  url = {https://yihui.name/knitr/},
}
@Manual{R-stringr,
  title = {stringr: Simple, Consistent Wrappers for Common
    String Operations},
  author = {Hadley Wickham},
  year = {2018},
  note = {R package version 1.3.1},
  url = {https://CRAN.R-project.org/package=stringr},
}
```
如果你有一个或多个bib文件，你需要在index.Rmd的YAML metadata（即文档开头一对`---`中间的内容）中的`bibliography`中引用它们，如：
```
---
bibliography: [bib/bib.bib, bib/Rpackage.bib]
---
```
然后你就可以在文章中引用添加在`.bib`中的文献，如[@R-knitr]。