使用markdown,knitr和pandoc在R语言中编写可重现的报告

​​

​​

您有了一些代码,数据和一个不错的结果,现在需要与您的协作者(或主管)进行交流了。你该怎么做?

在本指南中,我们想向您展示如何使用现在提供的一些奇妙,免费的工具和软件包编写美观,可重复的报告。这些工具将帮助您交流科学知识,并希望您再也不会复制和粘贴R输出。

首先,让我们回顾一下进行良好分析的关键组成部分:

  1. 数据
  2. 用于分析数据的代码
  3. 代码生成的图表
  4. 文本,解释图形和结果,并描述方法。

这些元素以报告的形式合并在一起。作为科学家,我们写了许多大小报告。像纸张这样的大型报告很少见,但是我们一直在编写较小的报告。这些包括在项目生命周期内编写的所有初步结果,每周更新,带有数字的电子邮件以及自己的笔记。传统上,大多数生物学家会在R中执行阶段2和3,然后启动Word或Powerpoint并复制粘贴阶段4的所有内容。这是可行的,但是这种方法有一些缺点:

  • 浪费大量时间,加上复制和粘贴很烂
  • 您的解释与代码分开
  • Word不提供语法高亮显示功能,因此很难读取以这种方式显示的代码,
  • 在版本控制下无法很好地跟踪Word文档
  • 如果不进行所有复制和粘贴操作,则无法重新生成报告。

值得庆幸的是,现在有一个更好的方式来写报告,用包  knitr,并称之为通用文档转换程序  pandoc。现在还可以将您的解释(阶段4)与R代码(阶段2)和结果(阶段3)结合起来,以生成美观,独立且可重复的报告。这些共同为希望节省时间和进行可重复研究的科学家提供了强大的工具集。

为什么要使用Markdown?

此Markdown的目标是“ 在可行的情况下尽可能易于阅读和编写 ”。实际上,它是应用于纯文本文档的一组简单的格式设置命令,可以轻松地将其转换为格式精美的html,pdf或word docs。但不像  html,  rtf,  latex,或几乎任何其他标记文本,Markdown是非常具有可读性。并且由于使用  纯文本,因此文件很小,并且可以在各种设备上轻松编辑。

作为科学家,我们不仅撰写论文,而且还撰写笔记,代码,电子邮件,提醒,待办事项列表,博客文章等。不仅如此,我越来越多地使用markdown进行笔记和报告写作。

因为它是纯文本,所以您可以在任何程序中编写markdown。但是,最好的测试编辑器还允许您以格式化的html格式查看代码。

Markdown文档通常以extension .md或  结尾  .markdown

RMarkdown

Markdown被证明非常有用,以至于许多不同的编码小组都采用了它,但同时也增加了自己的“风味”。到目前为止,我们了解以下内容:

  • 原始Markdown
  • github风格的markdown,
  • PandocMarkdown,以及
  • multimarkdown。

这些中的每一个都提供一组稍微不同的功能。

RStudio实现了一种称为“ RMarkdown”(或RMarkdown)的东西。此外,它包括“代码块”,这些代码块将由R运行。这些代码如下所示:

产生:

Markdown会像这样渲染:

R markdown在Rstudio中使用,并允许将R代码与文本段一起编入。以R markdown编写的文件具有扩展名  .Rmd

将R markdown视为可以编译  为上述markdown变体之一的东西  。

knitr 报告

该  knitr 软件包的编写是在单个文档中结合了RMarkdown和R代码的元素  。从一个例子开始。

打开Rstudio并安装Knitr软件包

然后打开  此演示文件  并单击  knit HTML 按钮

该文件是用RMarkdown编写的,包括一些文本和代码。

点击可以  knit HTML 做几件事

  1. 它运行文件中的所有代码
  2. 它会生成一个markdown文件,包括原始文档的位及其输出。
  3. 它将markdown文档转换为html。

您还可以使用以下命令从控制台制作文档:

注意,要使此代码正常工作,示例文件必须位于您的工作目录中,或者您需要提供RMD文件的路径:

好的,因此您有一个文档(html文件),您可以在其中记录您的分析。现在,只需将示例代码替换为一些实际的材料,然后您便可以使用。

这种方法的一些好处包括:

  • 禁止复制和粘贴
  • 一旦有了更多数据,新想法等,您的报告就可以轻松更新
  • 因为它们就像其他任何代码一样,所以您可以在版本控制下跟踪knitr脚本。
  • 如果重要的话,可以显示用于生成结果的代码位。
  • 您的分析是完全透明和可重复的。

人们现在将 knitr 用于各种用途,例如

  • 编写有关其数据的报告
  • 准备教程
  • 撰写博客文章。

避免麻烦

我们建议您使用  setwd() 中的脚本。这在这里更重要。在Rmd文件中更改工作目录将导致麻烦。因此,建议您假设所有Rmd文件都在项目的根目录中运行,以使其运行。

显示和隐藏代码及输出

通过为每个代码块设置选项,您可以选择要包含在虚拟报告中的内容。

  • echo= TRUE:如果要在报告中显示代码,FALSE 或者要隐藏代码,请选择此项  。
  • results= "hide":如果要隐藏运行代码的结果,请选择此选项。
  • eval =FALSE:导致不评估当前块。

有关这些选项的更多详细信息,请参考

转换为不同的文档格式

现在,如果要生成其他文档类型而不是html文件怎么办?输入pandoc。

根据其创建者的说法  ,“如果您需要将文件从一种标记格式转换为另一种标记格式,那么pandoc是您的瑞士军刀。它可以读取各种输入,包括markdown,reStructuredText,HTML,LaTeX,MediaWiki标记和DocBook XML。它可以编写纯文本,markdown,reStructuredText,XHTML,HTML 5,LaTeX(包括投影仪幻灯片),ConTeXt,RTF,DocBook XML,OpenDocument XML,ODT,Word docx,GNU Texinfo,MediaWiki标记,EPUB,FictionBook2,Textile ,groff手册页,Emacs Org-Mode,AsciiDoc和Slidy,Slideous,DZSlides或S5 HTML幻灯片放映。它还可以在安装LaTeX的系统上产生PDF输出。”

首先,您需要下载并  安装pandoc。安装后,您便可以使用pnadoc knitr软件包随附的  功能将生成的md文件转换为所需的任何格式。例如,要将上面的示例转换为word文档,我们编写:

可重复的研究

因此,有了它,您便可以使用一组工具在R中进行可重复的研究。


​非常感谢您阅读本文,如需帮助请联系我们!


随时关注您喜欢的主题

在wechat上关注我们

最新洞察

技术干货


 
QQ在线咨询
售前咨询热线
15121130882
售后咨询热线
0571-63341498