12.2.2 Markdown语法与Rmarkdown图表设置
Rmarkdown文件的一个组成部分是Markdown文本,那么什么是Markdown文本呢?按照Markdown语法创建者约翰·格鲁伯(John Gruber)的观点,Markdown是一种轻量级标记语言,也是一个将作者的文本转换为html格式文本的工具。Markdown使用易于阅读、易于编写的文本格式进行编写,方便将其转换为xhtml(或html)格式的文件。本节将首先介绍Markdown的基本语法与示例,之后讲解Rmarkdown中的图表设置技巧。
1.Markdown语法
Rmarkdown中的Markdown文本沿袭了Markdown的语法,所以在编写Rmarkdown文件前需要先熟悉Markdown的常用语法。
(1)文本的换行、斜体和粗体
在Markdown文本中,换行需要在结尾输入两个或两个以上的空格。
在Markdown文本中,输入“*斜体*”可以输出得到斜体的文本;输入“**粗体**”可以输出得到粗体的文本。
(2)文本创建链接和邮箱
Markdown支持html格式的输出,如果需要在Markdown文本中嵌入一些链接,可以通过以下方式实现:
Markdown也支持链接插入本地或者网络端的图片,代码如下:
如果在Markdown文本中以邮箱作为联系方式,可以使用name＠gmail.com为邮箱添加链接,方便读者获取邮箱信息。
(3)文本的标题和引用
为了使得撰写的内容逻辑清晰、层次分明,我们可以在Markdown文本的标题前添加“＃”号,同时,“＃”号和标题之间以空格隔开。不同级的标题可以通过不同数量的“＃”号来区别,Rmarkdown最多支持六级标题。添加三级标题的代码和结果(如图12-9所示)如下:
图12-9 Markdown文本中的标题设置
在Markdown文本中添加引用的方式和添加标题类似。在段落开头加上“”号即代表引用,每多一个“”号就多一层缩进。添加三级引用的代码和结果(如图12-10所示)如下:
图12-10 Markdown文本中的引用设置
(4)文本的列表
Markdown语法提供了有序列表和无序列表两种输出方式,添加示例如下:
值得注意的是,无论手动输入的序号为何,有序列表的序号都会自动递增,示例如下:
需要指出的是,行首每多一个空格,列表就会多缩进一层,因此空格不要随意增减。
掌握这些基本语法后就可以使用Rmarkdown编写报告了。如果忘记了某种语法,可以通过“Help→Markdown Quick Reference”的方式来获取帮助。
2.Rmarkdown的图表设置
使用Rmarkdown编写数据分析报告会遇到各种各样图表的编排,这些图表的样式从简单到复杂,从静态到交互,需要根据不同情形采取相适应的方法。下面重点讲解Rmarkdown的图表设置技巧,以方便用户的使用。
(1)在Rmarkdown文件中插入图片
之前介绍过插入图片的一种方式,即使用以下代码插入网络链接或本地链接的图片:
除了上述方式外,还可以使用knitr::include_graphics指令在Rmarkdown文件中插入图片,该指令能自适应输出html和pdf两种格式。另外,当目录下同时存在name1.png和name1.pdf文件时,程序会自动选择在html格式输出中展示name1.png文件,在pdf格式输出中引入name1.pdf文件。
如果有多张图需要同时展示,用户可以将图名称以vector形式传给include_graphics函数,通过设置“out.width＝1/number-pics”和“fig.show＝＂hold＂”实现多图并排展现。
(2)在Rmarkdown文件插入表格
在Rmarkdown文件中插入表格有多种方法,最简单的方法就是使用Markdown语法插入表格,示例如下:
根据表格数据来源的不同,Rmarkdown文件中插入表格可以分为内部表格插入和外部表格插入两种方式,详述如下。另外,下面还介绍了使用DT包、kableExtra包输出表格的相关示例。
①插入内部表格
对于来源于Rmarkdown生成数据的表格创建,推荐使用knitr::kable函数在Rmarkdown文件中插入内部表格,代码示例及输出结果(如图12-11所示)如下:
图12-11 使用knitr::kable函数插入内部表格
使用“?knitr::kable”阅读相关文档,可以了解定制表格的其他方式。如果想要更加深入地定制表格,可以使用xtable、stargazer、pander、tables和ascii等包,这些包都提供了一套根据R代码生成格式化表格的函数。
②插入外部表格
对于外部来源的数据,可以通过安装RStudio的插件insert_table来快速生成表格代码,步骤如下。
首先,在RStudio console中输入以下代码,安装插件insert_table:
然后,打开Rmarkdown文件,将鼠标停放在带有R代码块的空白行处,选择“Addins→Insert Table”插件,即可插入表格内容。
③使用DT包输出交互式表格
如果用户想要输出html格式的研究报告,推荐使用DT包。DT包提供了JS库DataTables与R的接口,调用该接口可使得R对象(矩阵或者数据框)在html页面显示为表格。此外,这种表格具有交互功能,如筛选、排序等。更重要的是,DT包对参数进行了封装,这使得用户操作起来更加简单、快捷。
首先安装并加载DT包,然后以mtcars数据集为例输出交互式表格,如图12-12所示。
图12-12 使用DT包输出交互式表格示例
DT包还封装了许多Data Tables的功能,熟悉Data Tables的用户可以定制DT包输出的表格,不熟悉Data Tables的用户可以参考下面的内容进一步设置参数。
a.数据格式的设置
一般来说,在“干净”的数据中,数据格式以列为单位划分,DT包中的format*()函数可将表列格式转化为货币、百分比或整数。
用户可以分别使用formatCurrency()函数和formatPercentage()函数将mtcars的wt列和qsec列转化为货币和百分比形式。另外,还可以使用format Date()函数对日期、时间列进行格式化,方便数据表的展示。输出结果如图12-13所示。
b.标题和行列名设置
Rmarkdown包提供了为表格和图片命名并且自动编号的功能,此外,通过设置DT包中datatable()函数的caption参数可为表格设置名称,示例代码及输出结果(如图12-14所示)如下:
图12-13 DT包表格输出的数据格式设置示例
图12-14 DT包设置表格标题示例
在DT包的datatable()函数中,行列名分别由rownames和colnames参数控制,用户可以通过设置逻辑值控制是否显示行名和列名,示例代码及输出结果(如图12-15所示)如下:
图12-15 DT包设置表格行列名示例
datatable()函数中的rownames和colnames参数可以对行名和列名进行设置,示例代码如下:
c.组件控制设置
DT包输出表格中的交互式组件如图12-16所示,其中,框内部分为表格组件,DT包输出的表格在HTML页面显示时具有人机交互的特性,有助于用户筛选、搜索感兴趣的数据子集。
图12-16 DT包输出表格中的交互式组件
如果要在HTML页面显示表格交互式组件,可以通过参数options＝list(dom＝‘lftipr’)控制是否显示组件,同时设置这些组件的位置。DT包变换表格组件元素显示位置示例如图12-17所示,其中,l、f、i、p分别对应图12-17所示的位置,t和r用于组件定位,即上述参数添加到字符串则显示对应的元素,根据参数在字符串中与t的位置可变换元素显示的位置。
图12-17 DT包变换表格组件元素显示位置示例
④使用kableExtra包输出复杂表格
用户如果想引用内部表格数据,创造更为复杂、更为精美的表格样式,可以通过安装kableExtra包来完成。该包可以解决90%以上的复杂制表问题,示例代码如下:
a.使用kableExtra包生成HTML表格
使用kableExtra包中的kable函数可以生成HTML、La TeX和Markdown三种格式的表格。其中,HTML表格可以高度定制,以mtcars数据集为例,生成HTML表格的代码如下:
b.使用kableExtra包定制表格风格
如果用户熟悉bootstrap,相信不会对以下CSS类感到陌生:striped、bordered、hover、condensed以及responsive等。不熟悉bootstrap的用户,可以查看bootstrap帮助文档。用户可以通过kable_styling()函数快速定制不同样式的表格风格,示例代码及输出结果(如图12-18所示)如下:
图12-18 kableExtra包定制表格风格示例
bootstrap_options参数提供了固定的行距,如果需要更为紧凑的表格样式,可以通过condensed参数值进行微调,示例代码及输出结果(如图12-19所示)如下:
图12-19 kableExtra包调整表格行距示例
令参数full_width＝F可将表格宽度设置为100%容器宽度,调整表格宽度的示例代码及输出结果(如图12-20所示)如下:
图12-20 kableExtra包调整表格宽度示例
在Rmarkdown文件中,使用kableExtra包可以帮助用户绘制精美复杂的表格,满足用户日常大部分的工作与科研需求。感兴趣的读者可以阅读kableExtra包的说明文档。