R Markdown

定义

R Markdown是一种面向R语言的写作格式,用来生成可重复的动态文档、演示文稿和报告。它把轻量标记语言Markdown的核心语法,与嵌入文档中的R代码块结合起来,代码块会被执行,输出结果随之进入最终文件。承载R Markdown的源文件是扩展名为.Rmd的纯文本文件,其中通常包含3类内容:用短横线围起来的YAML元数据头、用反引号围起来的代码块,以及与简单文本格式混排的正文。

作为格式的规范说明,一份R Markdown文档是作者格式(authoring format),目标是把数据、代码和写作思路整合成一份体面的成品文档,而不是单纯的代码文件^[1]。同一份.Rmd源文件可以输出HTML网页、PDF、Word文件、幻灯片等多种形态^[1]。

原理

渲染一份R Markdown文档,由两个工具先后接力完成。第一步由knitr把.Rmd文件中的代码块全部执行,生成一份新的Markdown文件,其中既有代码,也有代码产生的输出。第二步由Pandoc接手,把这份Markdown转换成最终的成品格式,例如网页、PDF或Word文档^[2]。这个过程被封装在rmarkdown包的render()函数里,使用者只需调用一次。

代码块可以带标签和选项,用来控制它在成品中的呈现方式,常用选项包括是否执行代码的eval、是否显示源码的echo、是否把输出纳入成品文档的include、是否显示警告的warning、是否显示消息的message,以及控制图片宽高和标题的fig.width、fig.height、fig.cap^[3]。正文中也可以嵌入行内R代码,单个反引号加字母r即可让一个计算结果直接出现在句子里^[4]。

渲染在独立的R会话中进行,文档需要的每个对象都必须在文档自身内部创建^[3]。代码块在渲染时严格自上而下依次执行,一个对象必须先于引用它的代码被定义^[3]。文档头部的元数据还可以写入参数(params)字段,使同一份源码套用不同数据集重复出报告^[2]。

发展历程

R Markdown的思路承接自更早的技术。2002年,Friedrich Leisch提出Sweave,用文学化编程的方式在LaTeX文档中嵌入R代码,以动态生成统计报告^[5]。2011年,谢益辉创建了knitr包,2012年该包正式发布,在Sweave的基础上扩展了可动态生成的报告能力^[6][5]。

按照谢益辉本人的说明,早期的R Markdown基于markdown包而非Pandoc,后来被称为R Markdown v1;v1更接近一个实验,只支持HTML输出,不支持LaTeX等其他格式^[7]。此后开发的重心转向v2,也就是今天通常所说的rmarkdown包,它以Pandoc和knitr为基础^[7]。关于rmarkdown包的发布时间,有资料记为2014年,用于让RStudio环境中的Markdown具备执行R代码的能力^[5]。

R Markdown后来衍生出多个围绕文档生产的扩展包,例如用于撰写书籍和技术文档的bookdown,以及用于搭建网站的blogdown^[6]。2022年发布的Quarto被其开发公司描述为R Markdown的下一代产物,该平台不再局限于R语言,同时支持Python、Julia等语言,不过R Markdown本身仍然保留^[8]。

应用

R Markdown的主要用途是数据分析和统计报告。数据分析人员用它把分析代码与文字说明放进同一文档,代码产生的图表和表格会自动加入报告,从而减少手工复制粘贴和反复调整格式的工作。当数据或分析方法发生变化时,重新编译即可得到更新后的结果,而不必重建图件或逐个修改数值^[9]。

在输出形态上,R Markdown内置支持HTML、PDF、Word、ODT、RTF、Markdown等文档格式,以及Beamer、slidy、ioslides、reveal.js等幻灯片格式,还可以生成网站、仪表板、书籍、讲义和包的说明文档^[2]。由于HTML格式能嵌入交互式图表并容纳较宽的表格,在不需要PDF或Word时通常被推荐作为起始输出格式^[3]。在科研场景中,它也被用来撰写可重复的稿件,把图件、参考文献与分析代码放在同一项目中^[10]。

局限

R Markdown的渲染环境与交互式会话不同,这带来一类常见问题:在控制台里单独测试过的代码,如果依赖当前环境中手工载入的对象而没有写进文档,渲染就会失败^[11]。代码块若被乱序执行,或运行后被修改过,也可能让人误以为文档已包含得到该结果的完整代码^[11]。

跨输出格式的兼容性也受到限制。有技术文档指出,一份较为复杂的R Markdown文档通常只在面向某一特定输出格式构建时才顺利成功,许多文档组件是为PDF或HTML之一设计的,并不天然同时对两者兼容;把原本面向HTML的文档改为生成PDF,往往会遇到较多障碍^[12]。该文档还提到,YAML元数据的设置较为复杂,用制表符缩进YAML会导致致命错误,而HTML输出依赖外部的MathJax框架显示数学公式,读者处于离线状态或该服务不可用时会无法正常显示公式^[12]。

另一个层面的限制来自排版精度。用LaTeX体系可以把论文、学位论文和技术书籍排得完全符合规定格式,但需要作者相当熟悉LaTeX;使用现成的模板虽能减轻负担,却仍可能无法满足严格的格式要求^[13]。此外,把全部源码展示在成品报告中,对论文和技术书籍这类正式出版物而言会分散读者注意力,通常需要借助代码块选项将其隐藏^[13]。

参见

• knitr —— 执行R Markdown文档中代码块的R包,是渲染流程的第一步。

• Pandoc —— 把knitr生成的Markdown文件转换成HTML、PDF、Word等成品格式的文档转换工具。

• 谢益辉 —— knitr的主要作者,R Markdown相关工作的重要推动者。

• Markdown —— R Markdown所采用的轻量标记语法基础。

• Quarto —— 由R Markdown发展而来的技术出版平台,支持R以外的多种语言。

• Sweave —— knitr之前用于在LaTeX文档中嵌入R代码、动态生成统计报告的工具。