为Bioconductor构建软件包

本指南的目的是为希望为Bioconductor编写包的新包作者提供入门。本文将介绍使用广泛使用的IDE RStudio中的工具完成此任务所需的步骤。它还将尝试解释包装结构的最基本方面，目的是帮助您的包装最终达到或超过生物导体封装指南．我们还有其他资源可以帮助开发人员进行包开发的各个方面。2021欧洲杯体育投注开户对于那些对这个非常介绍性的指南不感兴趣的人，在Bioconductor网站上有其他开发人员资源在这里．还有其他的如何制作文件可以用来回答关于为Bioconductor开发的各种问题。

生物导体包装实际上只是R包装。因此，关于如何使用它们的最终决定可以在这份文件中找到在这里．

但是由于该文档非常详细，初学者很难知道他们需要为Bioconductor编写R包。本文档将尝试简化讨论，重点关注使R代码作为Bioconductor包运行所需的最少内容。

包类型

Bioconductor项目认识到R包有许多不同的一般用途。从广义上讲，一些包主要用于保存数据集的注释或示例，而其他包主要用于分发软件。出于本文档的目的，我们主要关注软件包，因为它们是迄今为止创建和维护最复杂的。换句话说，这些包包装了一些功能，以便其他R用户也可以轻松地复制和构建您的工作。

使用RStudio创建包

现在很多人都在使用RStudio，这是一个很好的开始，因为RStudio已经添加了一些工具，可以让最终用户更容易地创建包。但在我们开始之前，让我们配置一些东西，以便您的代码将格式化的方式，我们更喜欢它为Bioconductor。

要使用RStudio制作第一个包，请转到“文件”菜单并选择“新项目”。从这里你可能想要选择“新建目录”，然后你肯定想要选择“R包”来设置一个新的R包。这将把你带到开始的最后一步，它将询问你想要给你的新包命名什么以及把它放在哪里。花点时间选择一个您认为喜欢的名称，并将包放在一个您可以舒适工作的位置是值得的。这些东西以后可以很容易地改变，但最好现在就改正。

在这个例子中，我们将我们的包称为“MyPkg”。现在继续填写这些信息，并按下“创建项目”按钮。

如果您现在查看屏幕，您将看到文件选项卡中列出了几个文件。这些是制作包所需的文件(RStudio可以方便地为您创建这些文件)。其中一些文件是RStudio放置在那里的“额外文件”，以帮助它管理您的包构建(`。Rbuildignore '， ' Read-and-delete-me ' and ' MyPkg.Rproj ')你可以忽略这些文件，但我想让你明白它们不是' required ' R包结构的一部分。

［回到顶部］

基本包装

现在让我们看看RStudio放在这个目录下的核心文件和目录，并描述它们各自的用途:

这些只是RStudio将为您放入的部件。你需要知道的其他一些重要的事情是:

在接下来的几节中，我们将更详细地介绍这些组件。但请记住，这是一个高层次的指南，只是让你开始。所以我不打算把所有东西都放在这里。对于那种指南，我真的认为你应该看看CRAN的官方指南编写R扩展．

［回到顶部］

DESCRIPTION文件

DESCRIPTION文件在R包中有很多角色。严格来说，它是一个'。dcf的文件。它通过详细描述一系列字段来告诉R包中的内容以及如何使用这些信息来完成其工作。一个是自动生成的你应该已经看起来像这样:

包:MyPkg类型:包标题:包的功能(短行)版本:1.0日期:2014-06-04作者:谁写的维护者:向谁投诉描述:更多关于它的功能(可能不止一行)许可:它在什么许可下?

这对于几乎所有的DESCRIPTION文件都是一个很好的开始。你会看到，对于一些字段，他们会提示你要在那里放什么，而对于其他字段，他们已经填好了。为了为Bioconductor制作一个包，您至少需要填写同样多的字段(甚至更多)。让我们从描述在我们的例子中已经存在的字段开始，然后我将讨论一下添加一些不存在的字段。

这些是RStudio将为您创建的字段。以下是一些你也应该考虑的问题:

现在我们已经讨论了DESCRIPTION文件，让我们填写我们的描述文件，以便它可以实际工作在我们的测试包中:

包:MyPkg类型:包标题:A hello world包版本:0.99.1日期:2014-06-04作者:Some person 维护者:Some person 描述:我们通过练习来学习如何最好地编程。因此，为了练习创建包，我们将把这些东西复制到一个实际的description文件中，并自己进行测试。许可:艺术- 2.0

一旦你这样做了。通过点击' Ctrl+Shift+B '来为自己构建包(或者你可以在' Build '菜单上找到' Build and reload '命令)。

［回到顶部］

R目录

R目录用于保存您的`。R '源文件。这个例子为你创建了一个名为“MyPkg.R”的小文件。

让我们在这个包中创建一个小的测试函数，像这样:

myFun <- function(arg1){arg1 + 1}

现在你在' R '目录中已经有了一个简单的R函数的代码，点击' Ctrl+Shift+B '来构建并重新加载。现在你会看到，如果你像这样列出你的包的内容，你不仅可以加载你的包，而且你刚刚写的函数是可用的:

库(MyPkg) ls(“包:MyPkg”)

你甚至可以像这样测试调用你的新函数:

myFun (5)

［回到顶部］

NAMESPACE文件

NAMESPACE文件用于控制包(对最终用户)公开哪些对象，以及哪些对象对它可用(从其他包导入)。与DESCRIPTION文件不同，命名空间文件不是'。dcf的文件。它实际上包含R代码。通过查看为您生成的NAMESPACE文件，您可以看到一个简单的示例。它包含以下代码行:

exportPattern(" ^[[:α:]]+”)

这基本上告诉R导出包中的所有内容。这通常不是一个好主意。事实上，这是一个非常糟糕的想法，如果您发送给我们一个这样做的包，我们可能会要求您更改它。

这样做将向最终用户公开包的所有内容。包括您可能只打算在内部使用的任何帮助函数或实用程序。这意味着您的用户可能不得不筛选许多他们不需要了解的功能，以便了解他们需要了解的功能。这也意味着您将不得不花费大量时间来记录所有这些实用程序(甚至是那些您不打算让任何人使用的实用程序)。这导致手册页上写着“仅供内部使用”之类的内容。有时，记录内部使用的东西可能是一个好主意。但是，您必须权衡将所有内容都记录下来的好处，以及每个人都必须阅读他们并不真正需要的文档的后果。一般来说，最好只记录最终用户打算使用的东西。

有很多命令通常都放在NAMESPACE文件中。第一个大类是有选择地导出希望为最终用户记录的内容的命令。其中最常见的是export()，它是这样使用的:

出口(“myFun”)

现在你自己试试。将exportPattern()命令替换为只公开函数的export()调用。然后按“Ctrl+Shift+B”，并确保它像预期的那样工作。

NAMESPACE文件的另一个重要用途是从其他包中导入函数。当您导入一个函数时，您不需要将该包附加到搜索路径。这很好，因为在搜索路径上有很多东西可以降低R的速度。因此，通过导入，您可以允许您的包访问这些代码，而无需支付性能损失。假设您想要使用GenomeInfoDb包中的genomeStyles函数。在这种情况下，您需要做两件事。首先，您需要向DESCRIPTION文件中的Imports字段添加GenomeInfoDb。这意味着你需要在你的DESCRIPTION文件中添加如下一行:

进口:GenomeInfoDb

然后在命名空间文件中添加如下内容。

进口(“GenomeInfoDb”)

或者你也可以把这个添加到你的命名空间文件中:

importFrom(“GenomeInfoDb”、“genomeStyles”)

这两种方法中的任何一种都可以让您从GenomeInfoDb包中访问基因组函数，而无需将GenomeInfoDb包完全加载到搜索路径上。第一种情况更一般，将使GenomeInfoDb包中的所有变量可用。但是第二种情况只能从“GenomeInfoDb”包中获得“genomeStyles”函数。

有关如何使用NAMESPACE文件的详细信息，您应该看到这“编写R扩展”手册的部分。

练习1:

现在创建另一个新函数。这一次，让函数只返回导入的genomeStyles函数的名称。

［回到顶部］

记录手册页面

R手册页面以“Rd格式”编写。该样式基本上是不言自明的，并且示例文件' MyPkg-package. zip。为你提供的路值得花点时间看一看。关于如何编写这些类型的文件、不同字段的含义以及如何填写这些字段的主题已经有了很好的文档在这里在“Writing R Extensions”手册的特定章节中。不过有几件具体的事情值得一提。

现在再次查看RStudio为新包生成的手册页(“Rd格式”)。您将注意到示例部分没有被填充。如果你现在尝试检查你的包，你会得到一个错误。去尝试一下，看看会发生什么。在“Build”菜单中，选择“Check Package”(CTRL-SHIFT-E)。您应该得到一个错误。

要纠正这个问题，请在手册页中放一个简单的例子。这只是描述包的页面，因此没有太多需要演示的内容。现在，只需添加以下简单的示例部分作为当前存在的替换:

myFun (10)

然后再次运行check。您仍然会看到警告，但它至少应该完成这个过程。

现在让我们看看rstudio的另一个更好的特性。让我们为我们的新功能添加一个手册页。

要做到这一点，转到“文件”菜单，选择“新建文件”和“Rd文件”。请务必选择一个预先配置为“函数”的手册页，并确保在我们的新函数之后将其命名为“myFun”。这应该会将一个新的“预制”手册页放到你的包现有的“man”目录中。

现在显然你需要在手册中填写实际的描述和工作示例等。但是现在为新的手册页标题填充一个值，以便R能够再次构建和检查包。

［回到顶部］

写作小品文

您可能想知道，如果已经有了一系列的手册页，为什么还需要小插图。答案是，最终用户需要一个高级指南来告诉他们如何将这些点连接起来。仅仅展示所有部件是如何工作的是不够的。你还需要知道他们应该如何一起工作。一个好的小插图首先应该解释这个包是用来干什么的，然后它应该提供一个通用的工作流，说明如何使用这个包来完成这个任务。在此过程中，它将所有函数和类放入上下文中，以便新用户能够找到自己的方法。

从结构上讲，vignettes在' vignettes '目录中。它们由和组成。Rnw '或。rmd '文件。该R稍后将呈现为.pdf或html文档。过去，大多数小短文都是用Sweave写的在这里，但现在越来越多的用户选择使用所描述的knitr包来编写它们在这里．任何一种形式的小插图都是可以接受的，但写一个'。Rmd '文档更容易做到。

要让RStudio为你创建一个小插图，只需转到“文件”菜单，并在“新建文件”下查看。从这里你可以选择创建一个新的“R Sweave”或“R Markdown”文件。但是在这个演示中，选择一个“R Markdown”文件。现在，RStudio将为您创建一个示例R Markdown文件。但是与手册页的情况不同，它不会将它放在适合您的正确位置(至少在撰写本文时不会)。再次打开“文件”菜单，选择“另存为”。这将打开一个小部件，供您指定希望如何保存这个markdown文件。从这里点击左下角的按钮“新建文件夹”，并在你的MyPkg目录中创建一个名为“vignettes”的子目录。然后告诉小部件以“MyPkg.Rmd”的名称保存标记文件。

最后，你必须添加以下行到你的描述文件:

VignetteBuilder:针织

这些是需要的，因为knitr需要支持非sweave的markdown文件作为小插图，而knitr不是base R的一部分。

你现在有了一个小插图的开始。现在，一个小插图必须总是做两件事:1)它必须解释足够的背景信息，以便新用户能够确定一个包是否能帮助他们解决问题(即使他们是新手)2)它必须演示如何以预期的方式使用包中的各种功能。为了做到后者，你有时需要重复你可能已经在手册的示例部分中展示过的例子。运行两次这些示例可能效率很低。怎样才能避免这个问题呢?你可以把代码块标记为eval=FALSE。下面是一个标记为不计算的markdown代码块的示例:

{r chunkName, eval=FALSE} myFun(3)' ' '

如果你在使用Sweave，它应该是这样的:

<>= myFun(3) @

练习2:

现在，用手册页记录您的“基因组类型”函数，并更新您的小插图。确保在每个案例中都包含演示如何使用它的示例。当您将示例放入小插图时，将代码块标记为FALSE。

［回到顶部］

在包中存储数据

如上所述，R包基本上可以在两个地方存储有用的用户数据。第一种情况是当数据已经在R对象中。在这种情况下，你可能只需要将R对象保存在' data '目录中。这个目录是你可以放'。通过调用load()来记录和在示例中使用的Rda对象。

第二种情况是' inst/extdata '目录。“inst”目录只是一个地方，你可以把东西，将存储在您的安装包以后检索。你可以把它想象成一个存放杂项物品的地方。例如，一些用户会在他们的包中放置一个' inst/scripts '目录作为存储脚本的地方。但是这里特别提到了' inst/extdata '子目录组合，因为很多包都把它用作存储额外数据的地方，比如数据库或' .csv '文件等。基本上，你应该把它用于任何面向数据的，而不是。Rda的文件。这出现了很多次，因为并不是你想要加载到R会话中的所有东西都必须以'开头。Rda的文件。

最后，我们为软件包构建的tarball设定了一个最大值(5兆字节)。如果你需要更多的数据，是时候考虑制作配套包了。配套包可以是实验数据包或注释包。在这两种情况下，它的主要用途是为最终用户保存数据。实验数据包和注释包之间最大的实际区别主要是它们更新的频率。注释是人们需要依赖的最新数据，因此这些数据需要为每个版本更新(或检查以确保它们仍然是最新的)。相比之下，大多数实验数据在实验运行后从未真正改变，因此主要是为了让人们有一个真实的数据集来运行他们的算法。

练习3:

第1部分:genomestyle()返回一个列表对象。将该列表对象保存到文件系统中，并将其添加到“data”目录中，以便最终用户可以加载它。

第2部分:现在调用基因组类型(' Homo_sapiens ')并捕获结果。然后使用write.table()在磁盘上用data.frame的内容创建一个以制表符分隔的文件。最后，将该信息存储在inst/extdata中，并使用system编写提取器函数。将数据拉回R会话的文件。

［回到顶部］

BiocCheck

如果你看我们的计划的指导方针你会看到包不仅必须通过R CMD构建和R CMD检查而没有错误或警告，而且它还必须通过一堆其他要求，以确保您的代码被良好地记录，并且它将很好地集成到项目的其余部分。幸运的是，我们有一个工具可以帮助你。在RStudio中，您可以运行构建并从“构建”菜单中检查。但是你也可以像这样测试你自己的包是否符合BiocCheck:

library(BiocCheck) pathToPkg <- file.path(".."，"MyPkg")

如果到目前为止您已经按照说明进行了操作，那么调用上面的函数将生成一个列表对象作为输出，以告诉您您的包需要哪些内容才能与生物导体包装指南．BiocCheck输出分为三个不同的类别:

［回到顶部］

编写好的包的技巧

关于良好的编码实践已经有很多书了。但这里只是编写好的Bioconductor包的一些技巧。

［回到顶部］

练习答案:

练习1:

你应该创建一个这样的函数:

genomeStyleNames <- function(){names(genomeStyles())}

你应该已经导出了它，这样你的命名空间现在看起来应该是这样的:

出口(“myFun”、“genomeStyleNames”)导入(“GenomeInfoDb”)

练习2:

您可以选择在手册页中记录此功能，方法是向旧的手册页添加一个新别名，或者完全创建一个新页面。无论哪种方式，对于如何记录事物都没有真正的“正确”答案(或者至少R不会告诉你)。

练习3:

第1部分:您应该使用这样的简单代码将R对象保存到文件中

gs <- genomeStyles() save(gs, file='gs.rda')

然后一旦文件' gs。Rda '存储在'数据'，你可以这样做，一旦你的包被加载。

(包= MyPkg)数据(gs)

第2部分:现在调用基因组类型(' Homo_sapiens ')并捕获结果。然后使用write.table()在磁盘上用data.frame的内容创建一个以制表符分隔的文件。最后，将该信息存储在inst/extdata中，并使用system编写提取器函数。将数据拉回R会话的文件。

res <- genomeStyles('Homo_sapiens')写道。table(res, sep="\t"，row.names=FALSE, col.names=FALSE, file='human.txt')

然后如果你把它移动到inst/extdata，你可以写一个简单的函数来提取它，像这样:

getData <- function(){read.delim(file= system.file('extdata'，'human.txt'， package="MyPkg")， header=FALSE)} getData()

联系我们:support.bioconductor.org

欧洲杯冠军投注