用R markdown & bookdown生成深度分析报告

Jean

刚翻译好 《精通Shiny》一书（ 在线英文版），它是用 bookdown包写的，这是对 rmarkdown包的扩展。作者 谢益辉是Rstudio的工程师，主要的研究方向是统计计算与交互式统计图，与J. J. Allaire及Garrett Grolemund合著有 《R Markdown: The Definitive Guide》一书（ 开源在线版，中文版 《R Markdown 权威指南》正在写作之中，预计于2023年出版）。之前已经介绍过J. J. Allaire与François Chollet合著的书 《Deep Learning with R》，J. J. Allaire是 Rstudio的创始人与CEO， 谢益辉则创建了网站 统计之都并在中国推广R语言平台的相关技术和活动。

因为 《Mastering Shiny》的作者 Hadley Wickham（Rstudio首席科学家）询问能否把译本转换为R markdown脚本，以便把译本转换为网站与网页，尝试了解一下R markdown。这是一种编著语言系统，提供了动态的格式报告：给定参数，运行程序，根据模板生成word、pdf、html等固定格式的报告（ 简单例子）。同时也通过 knitr包支持 Python等多种语言。所以它的功能类似于Python平台的 Jupyter Notebook，不过功能更强大，比如通过R语言在后台运行Shiny App并合并其输出到报告中。其实我更感的兴趣是，了解这样的一种编著系统，以在大数据应用中根据模板与参数动态的生成深度分析报告——《Mastering Shiny》（ 项目源码）一书本身就可以看成是这样的一篇报告，虽然没有使用动态的参数。基本上搞数据分析的人都要写分析报告，这在各种实际应用场景中还是比较有用的，比如每月、每季自动生成一些深度分析报告。因为基于程序，背后有整个R语言或Python语言等数据科学平台的支持，它能做任何你能想象的深度分析。

本篇以《Mastering Shiny》一书的 项目源码为例，把项目的第1章 《Your First Shiny App》翻译为中文，并在Windows与Linux平台上输出它的html、word、pdf渲染结果，来了解R markdown这个流行的编著体系。

一、建立项目环境

1、下载项目源码

在 项目主页上按“Code”按钮，选“Download Zip”下载压缩文件解压即可。

2、安装项目依赖的包

install.packages(c(
"gapminder", "ggforce", "gh", "globals", "openintro", "profvis",
"RSQLite", "shiny", "shinycssloaders", "shinyFeedback",
"shinythemes", "testthat", "thematic", "tidyverse", "vroom",
"waiter", "xml2", "zeallot"
))

3、导入项目

Rstudio菜单上选择File->Open Project，选择上面解压的源码目录到有.Rproj项目描述文件的一级，并选择该项目文件打开。这时getwd()返回的工作目录就是该目录。

4、修正项目bug

有两个小bug，第一个可能是软件包版本变化引起的问题，书中列出了当时使用的包版本，而上面安装的是最新的版本。

1）common.R

把最后修饰错误信息的registerS3method()与error_wrap()函数注释掉，否则build整个项目时会出错，因为registerS3method()运行出错了。

2）basic-case-study.Rmd中第79行下载neiss的URL，因项目源码结构的改变，其中/raw/master/neiss/要改成/raw/main/neiss/。

5、build项目测试

这时可以在Rstudio菜单上选择Build->Build All来试着执行所有章节的Rmd脚本渲染生成各章节的html、word文件了。然后会看到在执行到basic-reactivity.Rmd的184-190行时中断了，因为它需要向shinyapps.io部署一个Shiny App，需要有它的API账号。

6、连接shinyapps.io
到shinyapps.io上注册一个账号，我是直接用github的账号登录的。然后创建访问shinyapps.io的API令牌和密码。选择Account->Tokens->Add Token。 拷贝token和secret，在Rstudio Console中运行一次下面的语句：

library(rsconnect)
setAccountInfo(name='your account name', token='your token', secret='your secret')

这样Rstudio->Tools->Global Options->Publishing中就会记住你的发布账号，以后就会自动引用。

现在，在Build菜单下选择Clear All清空上次Build的痕迹，然后重新运行Build All。

然后还是会在action-graphics.Rmd被中断执行，build的错误信息是部署的Shiny App数量超出了上限： shinyapps.io上显示这时一共部署了5个App，这应该是免费账号的上限。如果要build完整本书，那就要注册一个付费账号了。 7、单独执行一个Rmd渲染

现在先清空shinyapps.io上部署的App。点击每个App后面的Archive按钮归档，然后再点击Delete按删除，必须先归档，然后才可以删除。

然后单独执行下面的命令渲染action-graphics.Rmd：

rmarkdown::render('action-graphics.Rmd','word_document',output_dir = "./docx")

该脚本只部署了3个App，可以看到顺利的执行完了。该Rmd脚本把程序、Shiny App输出的图表与文字叙述合并到一起，这是典型的数据分析报告形式。 逐章翻译的时候可以逐章渲染，不过有一个小问题是里面章节的序数及相互之间交叉引用等bookdown扩展标签，在逐章渲染时没有执行，它们在整个项目build时才会执行，这是需要注意的，现在可以先不管它。

执行下面的命令渲染输出html文件：

rmarkdown::render('action-graphics.Rmd','html_document',output_dir = "./docx")

渲染输出pdf文件要做一些安装配置，后面再详细介绍。 二、翻译basic-app.Rmd

1、翻译

因为书已经翻译好了，翻译Rmd源码脚本的工作是很直接的，就是把译稿里的 译文，逐段逐句替换掉 Rmd源码里的英文，主要的工作量在于大量起格式化作用的R markdown及bookdown标签的处理，因为要保留这些标签以保留原格式，这比翻译的工作量都要大，整整搞了1天。这是翻译好的脚本，另存为 basic-app-zh.Rmd。执行下面的命令渲染输出word文件：

rmarkdown::render('basic-app-zh.Rmd','html_document',output_dir = "./docx")

2、Word格式输出 上图可以看到书中的脚注显示在页面底部，在横线以下。下图可以看到该脚本合并了整个Shiny App的运行界面（然而渲染时并没有显示界面窗口，它是在后台运行的）：

3、本地运行

可以看看后台运行在Rmd脚本中的实现：

```

{r basic-server, echo = FALSE, out.width = "75%", fig.cap = "现在我们提供了连接输出和输入的服务器函数，我们有了一个功能齐全的应用程序", message = FALSE}
demo <- demoApp$new("basic-app/server", ui, server)
demo$takeScreenshot()
```

通过新建一个demoApp对象在后台运行它{r basic-server, echo = FALSE}，然后调用它的takeScreenshot()函数截取它应该显示的界面。所以这个App运行在本机的R进程中，不需要发布到shinyapps.io等服务器上。渲染结果会显示界面截图而不是上面的脚本程序。

R6Class对象demoApp在 demo.R中定义，它在basic-app-zh.Rmd的开始处加载：

```{r, include = FALSE}
source("common.R")
source("demo.R")
```

4、shinyapps.io服务器上部署运行

作为比较，看看前面提到的 acttion-graphics.Rmd中是怎样把Shiny App部署到shinyapps.io上并截图的，它同样也是后台运行，没有显示界面。

```{r puppies, echo = FALSE, message = FALSE, fig.cap = demo$caption("An app that displays cute pictures of puppies using `renderImage()`."), out.width = "50%"}
demo <- demoApp$new("action-graphics/puppies", ui, server, assets = "puppy-photos")
demo$takeScreenshot("corgi")
demo$setInputs(id = "KCdYn0xu2fU")
demo$takeScreenshot("lab")
demo$deploy()
```

嗯，通过调用demoApp对象的deploy()函数实现。

渲染效果如下： 有关后台运行Shiny App的详细说明，可以参阅《Mastering Shiny》一书的 《Testing》一章（ 中文译文）。 5、html格式输出

执行下面的语句输出html格式文件：

rmarkdown::render('basic-app-zh.Rmd','html_document',output_dir = "./docx")

注意它的脚注集中显示在页面的底部，与Word格式不同。 6、pdf中文支持
为支持中文渲染输出为pdf，Rmd脚本的开头处增加了以下的YAML定义，详细安装配置后面再介绍：
---
header-includes:
- \usepackage{ctex}
output:
pdf_document:
latex_engine: xelatex
---

执行下面的命令渲染输出pdf文件：

rmarkdown::render('basic-app-zh.Rmd','pdf_document',output_dir = "./docx")

7、直接输出结果的代码
上面运行交互式Shiny App的R markdown界面截图代码稍为有点复杂，那是比较特殊的情况，因为交互式Shiny App需要一个UI界面以接受交互式输入，所以通过demoApp对象作特殊处理，不显示UI界面以在后台运行（可以通过Shiny App的session对象由程序根据R markdown脚本传入的参数设定App的输入来模拟人机交互，上面的例子中demoApp对象提供了函数setInputs()直接实现：demo$setInputs(id = "KCdYn0xu2fU")）。一般的代码就可以直接合并输出，比如 introduction.Rmd中最后列出软件包版本的一段，与 Jupyter Notebook的用法相似：

执行下面的语句渲染输出html文件：

rmarkdown::render('introduction.Rmd','html_document',output_dir = "./docx")

渲染结果如下：

8、不运行的代码

对于渲染时只显示而不运行的代码，通过以下格式来定义：

{r, = FALSE}

三、Windows上渲染pdf安装配置

Rmd脚本渲染输出pdf需要TeX和LaTeX系统。

LaTeX 是 TeX的封装，主要的设计目标是分离内容与格式，以便作者能专注于内容创作而非版式设计，LaTeX 使用 TeX作为它的排版（格式）引擎，R markdown通过 tinytex包使用LaTeX，渲染pdf时把Rmd脚本编译为TeX脚本并执行，所以需要先安装配置它们。它非常适用于生成高印刷质量的科技类和数学类文档。它也能够生成所有其他种类的文档，小到简单的信件，大到完整的书籍。

可以参阅 这个文档来开始了解各操作系统平台上的安装。参阅中文的 LaTeX简介与 texlive指南。 texlive各操作系统安装版可以从这里下载。

1、安装MiKTeX

MiKTeX是Windows上比较流行的TeX发行版，安装配置简单，可以从这里 下载，安装说明参阅该 文档，按向导执行即可。它的安装文件与安装目录大概需要1G。需要注意安装后的两个设置：

1）在系统环境变量path中加入xelatex.exe等可执行文件的安装路径，后面将使用xelatex引擎来处理中文。

2）打开MiKTeX Console，更改宏包安装选项为“总是”自动安装缺失的宏包，否则使用支持中文的ctex宏包时找不到，会出错提示"GUI framework cannot be initialized"，参阅该 Issue文档。 2、中文的处理

1）测试MiKTeX

新建一个utf8编码文本文件test.tex如下：

2）在命令行窗口中运行xelatex test.tex生成pdf，第一次运行时需要的时间要长一点，因为要连线下载ctex相关的包： 3）查看生成的pdf，测试通过，安装成功。看到上面最后输出：Output written on test.pdf (1 page)就表示成功生成了pdf文件。 4）测试rmarkdown。在Rstudio中建立一个utf8编码的Rmd文件，然后用rmarkdown::render()函数直接渲染它，如图所示。注意测试用例的写法与上面例子的不同，在Rmd脚本的头部，定义了使用ctex宏包来处理中文，然后用xelatex引擎处理，它比pdflatex引擎更适合处理unicode字符集。具体可以参阅该 文档，那里有各种中日韩字符处理的例子。 5）查看输出的pdf文件，测试通过。 四、Linux上渲染pdf安装配置

Linux平台上比较流行的TeX发行版是 texlive，我在云端虚拟主机上装的是CentOS 7.6，它所带的texlive版本比较旧，没有处理中文的ctex等宏包（参阅 文档），因此下载最新的texlive-2022镜像安装完整的版本，参阅 文档及 清华大学最新镜像地址。镜像文件大约4.3G，安装另需6.8G。

1、安装texlive

如果安装了老版本的texlive，要先删除干净，参阅 文档与 文档2。

# yum erase texlive\*.*

下载：

# cd /root

# wget https://mirrors.tuna.tsinghua.edu.cn/CTAN/systems/texlive/Images/texlive2022-20220321.iso

挂载：

# mount -o loop texlive2022-20220321.iso /mnt/

安装：

# cd /mnt

# ./install-tl

输出环境变量：

# vi /etc/profile

# Added for texlive

export MANPATH=${MANPATH}:/usr/local/texlive/2022/texmf-dist/doc/man
export INFOPATH=${INFOPATH}:/usr/local/texlive/2022/texmf-dist/doc/info
export PATH=${PATH}:/usr/local/texlive/2022/bin/x86_64-linux:/usr/lib/rstudio-server/bin/pandoc

重启系统或source激活环境变量。

# source /etc/profile

卸载镜像：

# umount /mnt/

2、测试安装

1）测试texlive安装。测试用例test.tex同Windows平台，命令行输出要详细一点，生成的pdf是一样的。

2）在Rstudio中测试rmarkdown，注意/etc/profile中设置的texlive环境变量不会带入Rstudio Linux Server的 R session中，需要在Renviron配置文件中加进去，主要是PATH变量，具体可以参阅 文档1和 文档2。

# which R

/usr/lib64/R-4.1.2/bin/R

# cd /usr/lib64/R-4.1.2/lib64/R/etc

# ls

javaconf ldpaths Makeconf Renviron repositories

# vi Renviron

# Added by Jean for texlive 2022/09/15
PATH=${PATH}:/usr/local/texlive/2022/bin/x86_64-linux

然后重启Rstudio Linux Server以使路径生效：

# cd /usr/sbin

# ./rstudio-server stop&

# ./rstudio-server start&

在Rstudio Console窗口中，可以用Sys.getenv("PATH")查看路径设置是否已经生效，然后运行下面的命令来测试pdf渲染：

rmarkdown::render('~/testPDF.Rmd','pdf_document',output_dir = "~/")

测试用例testPDF.Rmd与Windows平台相同，生成的pdf文件也相同。

五、小结

《R Markdown: The Definitive Guide》的作者 谢益辉开发或参与开发了knitr、rmarkdown、bookdown等R markdown编著体系的主要R包，他将这种叙述、程序与结果混合的编程模式称为 文学化编程（由高德纳[Donald E. Knuth，TeX系统的开发者。]在 1984 年提出），与传统的结构化编程及Shiny的反应式编程都很不一样。后两种编程模式，人们在代码中写少量的注解，然后另外写完整的文档，这对于读者很少的专业编程来说，是最清晰高效的。在文学化编程模式下，人们边想、边描述、边解释，然后附上程序、附上运行结果。读者既看文章，也看代码和结果，看的过程就是思考的过程，更接近于人们日常的思考与行为模式，这对于数量众多的非专业编程读者来说是最容易理解最有效的。显然更适合于写数据分析报告及学术论文等图文并茂，需要大量文字充分论述说明的东西。

《Mastering Shiny》一书的R markdown 源码，是了解学习R markdown编著体系的一个不错的例子。IT领域有learn by example的传统，通过本篇翻译第一章Rmd脚本的例子，已经了解到该体系的大致框架，这是一个知识体系相当丰富的新领域。在一周的工作日内完成，已经很满意了。这只是一个开始，重要的是它跑通了！深入的了解和应用，还是要把上面R markdown的两本书慢慢读透。

最后，引用J.J. Allaire在2016年的专访 《RStudio 的前世今生》中的一段话来结束本篇，我觉得对深度分析来说是言之有理的。一家之言，仅作参考：

可重复性是我们专注于教人们如何编写和使用代码进行数据分析的原因之一。我们没有投入精力开发数据分析的图形界面工具，因为基于图形界面的操作不可重现，不容易检查，不容易共享，也不容易自动化。我们专注于代码。这是一个核心原则，无论如何，我们宁愿让代码更容易运行，而不是试图消除它。