---
title: "Bookdown包`.docx`输出下的Latex公式测试"
subtitle: "评估自定义R包`xmerit`的公式显示函数"
author: "胡华平"
date: "2023-10-21"

knit: (function(inputFile, encoding) { 
  outFile <- sub(pattern = "(.*)\\..*$", replacement = "\\1", basename(inputFile));
  out_dir <- 'public';
  rmarkdown::render(inputFile,
                    encoding=encoding,
                     output_file=file.path(dirname(inputFile), out_dir, outFile)) })
output:
  bookdown::word_document2:
    fig_caption: yes
    toc: no
    toc_depth: 4
    number_sections: true
    global_numbering: true
    #reference_docx: template/template-word-lab-exrecise.docx

---


```{r global_options, echo=F,message=FALSE,warning=F}
source("R/set-global-only.R", encoding = "UTF-8")
require(rmarkdown)
require(bookdown)
require(knitr)
require(xmerit)
```


# 测试说明

## 测试环境

系统环境如下：

```{r}
R.version
session <- utils::sessionInfo()
```

## 测试包的版本信息

相关R包版本如下：

```{r}
pkg <- list(rmarkdown = "rmarkdown", 
            bookdown = "bookdown", 
            xmerit = "xmerit")
sapply(pkg, packageVersion)

```



## `.Rmd`文档的yaml参数

```
output:
  bookdown::word_document2:
    fig_caption: yes
    toc: no
    toc_depth: 4
    number_sections: true
    global_numbering: true
```

# bookdown包`.docx`输出的公式语法

## 基本语法规则

`bookdown`解决的`Rmarkdown`生态下公式书写中自动标号和交叉引用的问题。

对于`.docx`格式输出，`bookdown`下公式语法规则如下：

- 添加公式标签（label）：`(\#eq:your-label)`

- 公式引用（cross-reference）：正文中`\@ref(eq:your-label)`

- 公式自动标号（numbering）：为确保公式自动标号，请**不要**使用双美元符号对`$$...$$`环境

> **经验规则**：`bookdown::word_document2`输出`.docx`使用情境下，任何时候都不建议使用双美元符号对`$$...$$`环境。

## 嵌套环境规则

经测试，如下嵌套环境规则是受到支持的（也正是自定义R包`xmerit`（版本`0.0.11`）目前所采用的语法规则）：

- 支持的有效单一LaTex公式环境（environment）：

a）`equation`环境

```
\begin{equation}
  ...
\end{equation}
```

b）`align`环境

```
\begin{align}
  ...
\end{align}
```

- 支持的有效嵌套LaTex公式环境（environment）：

> a）局部对齐排列的嵌套环境


```
\begin{align} 
  \begin{split}
   ... 
  \end{split} 
\end{align}
```

> b）完全对齐排列的嵌套环境

```
\begin{equation} 
  \begin{alignedat}{999}
   ... 
  \end{alignedat} 
\end{equation}
```


# latex公式测试

## equation（正常）

```
\begin{equation}
S_n = \frac{X_1 + X_2 + \cdots + X_n}{n}
      = \frac{1}{n}\sum_{i}^{n} X_i +5
      \quad \text{(equation)}
(\#eq:equation)
\end{equation}

引用语法 `\@ref(eq:equation)`显示为 \@ref(eq:equation)。

```

\begin{equation}
S_n = \frac{X_1 + X_2 + \cdots + X_n}{n}
      = \frac{1}{n}\sum_{i}^{n} X_i +5
     \quad \text{(equation)}
(\#eq:equation)
\end{equation}

引用语法 `\@ref(eq:equation)`显示为 \@ref(eq:equation)。

## align+多公式（正常）

```
\begin{align}
a & = b + c &&  \text{(nodollar-align-1)} (\#eq:align1) \\
c & = d + e &&  \text{(nodollar-align-2)} (\#eq:align2)
\end{align}

引用语法 `\@ref(eq:align1)`显示为 \@ref(eq:align1)；引用语法 `\@ref(eq:align2)`显示为 \@ref(eq:align2)。

```

\begin{align}
a & = b + c && \text{(align-nodollar1)} (\#eq:align1) \\
c & = d + e && \text{(align-nodollar2)} (\#eq:align2)
\end{align}


引用语法 `\@ref(eq:align1)`显示为 \@ref(eq:align1)；引用语法 `\@ref(eq:align2)`显示为 \@ref(eq:align2)。


## `$$`常规公式（显示公式和引用，但不显示公式标号）

```
$$
S_n = \frac{X_1 + X_2 + \cdots + X_n}{n}
      = \frac{1}{n}\sum_{i}^{n} X_i
      \quad \text{(dollar)}
      (\#eq:dollar)
$$

引用语法 `\@ref(eq:dollar)`显示为 \@ref(eq:dollar)。

```

$$
S_n = \frac{X_1 + X_2 + \cdots + X_n}{n}
      = \frac{1}{n}\sum_{i}^{n} X_i
      \quad \text{(dollar)}
      (\#eq:dollar)
$$

引用语法 `\@ref(eq:dollar)`显示为 \@ref(eq:dollar)。



## `$$`+aligned

```
$$
\begin{aligned}
S_n = \frac{X_1 + X_2 + \cdots + X_n}{n}
      = \frac{1}{n}\sum_{i}^{n} X_i +5
      \text{(dollar-aligned)}
(\#eq:dollar-aligned)
\end{aligned}
$$

引用语法 `\@ref(eq:dollar-aligned)`显示为 \@ref(eq:dollar-aligned)。

```

$$
\begin{aligned}
S_n = \frac{X_1 + X_2 + \cdots + X_n}{n}
      = \frac{1}{n}\sum_{i}^{n} X_i +5
      \text{(dollar-aligned)}
(\#eq:dollar-aligned)
\end{aligned}
$$

引用语法 `\@ref(eq:dollar-aligned)`显示为 \@ref(eq:dollar-aligned)。



## aligned（不显示公式，显示引用）

```
\begin{aligned}
S_n &= \frac{X_1 + X_2 + \cdots + X_n}{n} \\
    &= \frac{1}{n}\sum_{i}^{n} X_i +5
      \text{(aligned)}
(\#eq:aligned)
\end{aligned}

引用语法 `\@ref(eq:aligned)`显示为 \@ref(eq:aligned)。

```

\begin{aligned}
S_n &= \frac{X_1 + X_2 + \cdots + X_n}{n} \\
    &= \frac{1}{n}\sum_{i}^{n} X_i +5
      \text{(aligned)}
(\#eq:aligned)
\end{aligned}

引用语法 `\@ref(eq:aligned)`显示为 \@ref(eq:aligned)。


## alignedat（不显示公式，显示引用）

```
\begin{alignedat}{999}
&\widehat{mpg}=&&+43.54&&-1.78cyl_i&&+0.01disp_i\\ 
&(s)&&(4.8601)&&(0.6139)&&(0.0120)\\ 
&(t)&&(+8.96)&&(-2.91)&&(+0.58)\\ 
&(cont.)&&-3.79wt_i&&-0.49gear_i &&\\ 
&(s)&&(1.0818)&&(0.7903) &&\\ 
&(t)&&(-3.51)&&(-0.62) &&
\quad \text{(alignedat)}\quad
(\#eq:alignedat)
\end{alignedat}

引用语法 `\@ref(eq:alignedat)`显示为 \@ref(eq:alignedat)。

```

\begin{alignedat}{999}
&\widehat{mpg}=&&+43.54&&-1.78cyl_i&&+0.01disp_i\\ 
&(s)&&(4.8601)&&(0.6139)&&(0.0120)\\ 
&(t)&&(+8.96)&&(-2.91)&&(+0.58)\\ 
&(cont.)&&-3.79wt_i&&-0.49gear_i &&\\ 
&(s)&&(1.0818)&&(0.7903) &&\\ 
&(t)&&(-3.51)&&(-0.62) && 
\quad \text{(alignedat)}\quad
(\#eq:alignedat)
\end{alignedat}

引用语法 `\@ref(eq:alignedat)`显示为 \@ref(eq:alignedat)。



# xmerit包公式语法

## 数据集

```{r}
library(xmerit)

data(mtcars)
df <- mtcars
mod <- mpg ~ cyl + disp + wt +gear
lm.fit <- lm(formula = mod, data = df)
summary(lm.fit)

xvars <- all.vars(mod)[-1]
yvars <- all.vars(mod)[1]
```

## xmerit::lx.psm（align+split）

`xmerit::lx.psm()`函数默认形式为嵌套结构`\begin{align}`内含`\begin{split}`。

```{r, eval=FALSE, results='asis', echo=TRUE}
lx.out <- xmerit::lx.psm(
  x = xvars, y = yvars,
  begin = 0,
  #greek.n = length(xvars)+1,
  n.row = 3,
  lm.label = "lx-psm",
  lm.tag = "(lx.psm)",
  no_dollar = TRUE)
```

```
\begin{align}
\begin{split}
mpg_i=&+\beta_{0}+\beta_{1}cyl_i+\beta_{2}disp_i\\&+\beta_{3}wt_i+\beta_{4}gear_i+u_i
\end{split}
\quad \text{(lx.psm)}\quad
(\#eq:lx-psm)
\end{align}

引用语法 `\@ref(eq:lx-psm)`显示为 \@ref(eq:lx-psm)。

```

\begin{align}
\begin{split}
mpg_i=&+\beta_{0}+\beta_{1}cyl_i+\beta_{2}disp_i\\&+\beta_{3}wt_i+\beta_{4}gear_i+u_i
\end{split}
\quad \text{(lx.psm)}\quad
(\#eq:lx-psm)
\end{align}

引用语法 `\@ref(eq:lx-psm)`显示为 \@ref(eq:lx-psm)。


## xmerit::lx.est（equation + alignedat）

`xmerit::lx.est()`函数默认形式为嵌套结构`\begin{equation}`内含`\begin{alignedat}{999}`。

```{r, results='asis', echo=TRUE, eval=FALSE}
lx.out <- lx.est(lm.mod = mod,lm.dt = df,lm.n = 3,lm.label = "lx-est", lm.tag = "lx.est",
                 no_dollar = TRUE)
```

\begin{equation}
\begin{alignedat}{999}
&\widehat{mpg}=&&+43.54&&-1.78cyl_i&&+0.01disp_i\\ 
&(s)&&(4.8601)&&(0.6139)&&(0.0120)\\ 
&(t)&&(+8.96)&&(-2.91)&&(+0.58)\\ 
&(cont.)&&-3.79wt_i&&-0.49gear_i &&\\ 
&(s)&&(1.0818)&&(0.7903) &&\\ 
&(t)&&(-3.51)&&(-0.62) &&
\end{alignedat}
\quad \text{(lx.est)}\quad
(\#eq:lx-est)
\end{equation}

引用语法 `\@ref(eq:lx-est)`显示为 \@ref(eq:lx-est)。