计划的指导方针

版本1.0—2021-04-08

本页提供了有关指导原则和所需格式的详细信息Bioconductor包。另请参阅bob体育取款很慢对于提交过程的概述和期望作为一个Bioconductor维护者。

简介

的Bioconductor项目促进高质量、文档良好且可互操作的软件。这些准则有助于实现这一目标;它们并不意味着要给包的作者带来不必要的负担，难以满足指南的作者应该寻求有关指南的建议bioc-devel邮件列表。

包维护者在开发时应尽可能严格地遵循这些指导原则Bioconductor包。

有关生产包装的一般说明，请参阅编写R扩展手册，可从R (RShowDoc(“R-exts”))或在R网站．

请记住，这些是包装验收的最低要求，包装仍将遵守以下其他准则和由培训人员进行的正式技术审查Bioconductor包评论家。

［回到顶部］

1.总体包装开发

1.1版本Bioconductor和R

包开发人员应该始bob电竞体育官网终使用Devel版本Bioconductor在开发和测试要贡献的包时。

根据R的发布周期，使用Bioconductordevel可能也可能不涉及使用r的devel版本使用devel版本的Bioconductor查阅最新资料。

1.2正确性、空间和时间

1.2.1 "Bioconductor包必须最小限度地通过R CMD构建(或R CMD安装—构建)和通过R CMD检查没有错误和警告使用最近的R-devel。作者还应该尝试处理构建或检查过程中出现的所有注意事项。1

1.2.2包也必须通过BiocCheckGitClone ()而且BiocCheck ()没有错误和警告。的BiocCheck包是包含的一组测试Bioconductor最佳实践。应该尽一切努力处理在此构建或检查期间出现的任何注意事项。1

1.2.3不要使用只区分大小写的文件名，因为不是所有的文件系统都区分大小写。

1.2.4运行产生的源包R CMD构建占用磁盘不超过5MB。

1.2.5包运行时间不超过10分钟R CMD检查—没有构建小插图．使用——no-build-vignettes选项确保只构建一次小插图。2

1.2.6小插图和手册页示例不应该使用超过3GB的内存，因为R不能在32位Windows上分配超过3GB的内存。

1.2.7对于软件包，单个文件大小必须<= 5MB。此限制即使在包被接受并添加到_Bioconductor_存储库。

1.2.8原始包目录不应包含不必要的文件、系统文件或隐藏文件，如.DS_Store、.project、.git、缓存文件、日志文件、.Rproj、.so等。这些文件可能存在于您的本地目录中，但不应该提交给git(请参阅.gitignore)．

1.3 R CMD检查环境

它可以激活或停用一些选项中的R CMD构建而且R CMD检查．选项可以设置为单独的环境变量，也可以设置为在文件中列出．所有可用的不同选项的描述都可以找到在这里．Bioconductor已选择自定义这些选项中的一些传入提交期间R CMD检查．可用的标志文件可以从Github．该文件可以按照指示放置在默认目录中在这里或可通过环境变量设置R_CHECK_ENVIRON使用类似的命令

export R_CHECK_ENVIRON = <下载文件>的路径

［回到顶部］

1.4 README文件

如果README文件包含在包或github存储库中，并且它提供了安装说明，这些说明也应该包括Bioconductor安装说明。如果是README。Rmd is provided (rather than README.md, or other) those installation instructions should be in aneval = FALSE代码块。在代码(R代码、手册页、小插图、Rmd文件)中，任何人都不应该试图安装或下载系统依赖项、应用程序、包等。bob电竞体育官网开发人员可以提供指示，但不执行，并且应该假设所有必要的依赖项、应用程序或包已经在用户系统上设置好了。

2.描述文件

DESCRIPTION文件必须正确格式化。下一节将回顾关于DESCRIPTION字段和相关文件的一些重要注意事项。

2.1“Package:”字段:这是包的名称。这应该匹配github存储库名称，并区分大小写。包名应该是描述性的，并且不是已经存在的当前包(不区分大小写)Bioconductor或凹口．避免使用容易与现有包名混淆的名称，或者包含临时名称的名称(例如，ExistingPackage2)或定性的(例如，ExistingPackagePlus)的关系。检查您的名称是否已被使用的一种简单方法是检查以下命令是否失败

如果(!requireNamespace("BiocManager")) install.packages("BiocManager") BiocManager::install("MyPackage")' ' '

2.2“标题”字段:标题要简短但具有描述性

2.3“版本:”字段:所有Bioconductor包使用X.Y.Z版本方案。看到版本编号关于如何发布和开发的细节Bioconductor版本控制收益。当第一次提交给Bioconductor，一个包应该有预发布版本0.99.0。适用规则如下:

2.4“Description:”字段:描述应该是一个相对简短但详细的包功能概述。至少要有三个完整的句子。

2.5“Authors@R:”字段:Authors@R字段应该被使用。维护者指定(creAuthors@R)需要一个积极维护的电子邮件。此电子邮件将用于联系有关您的包在未来出现的任何问题。对于有ORCID识别码的人士(请参阅ORCiD以获取更多信息)在person()的注释参数中通过名为“ORCID”的元素提供标识符。例子:person("Lori"， "Shepherd"， email=Lori.Shepherd@roswellpark.org, role=c("cre"， aut")， comment =c(ORCID = "0000-0002-5910-4010")))．

只有一个人应该被列为维护人员确保一个单一的接触点。默认情况下，这个人将拥有git存储库的提交访问权。上的请求可以将提交访问权限授予其他开发人员bob电竞体育官网bioc-devel邮件列表。另一种选择是将合作者添加到github存储库中。这种方法使许多人能够开发，但限制了对git.bioconductor.org的推送访问。

2.6“许可证:”字段:最好是指标准许可证维基百科)使用R的标准规范之一。具体说明应用的任何版本(例如，GPL-2)。限制使用的许可证，例如，学术或非营利研究人员，不适合Bioconductor．核心Bioconductor软件包通常是在artist -2.0下授权的。要指定非标准许可证，请在包中包含一个名为license的文件(包含许可证的完整条款)，并在“许可证:”字段中使用字符串“file license”(不带双引号)。包应该只包含可以根据包许可证重新分发的代码。注意软件包中所依赖的软件包的许可协议。并不是所有的包都是开源的，即使它们是公开可用的。

2.7 " LazyData: "字段:对于包含数据的包，我们建议不包含LazyData:真．这很少被证明是一件好事。根据我们的经验，它只会降低包含大数据的包的加载速度。

2.8“依赖/导入/建议/增强:”字段:

2.9“SystemRequirements:”字段:该字段用于列出任何需要的外部软件，但不是通过正常的软件包安装过程自动安装的软件。如果安装过程不是简单的，那么应该包含一个顶级的README文件来记录这个过程。

2.10 " biocViews: "字段:REQUIRED!指定至少两个叶节点biocViews．鼓励使用多个叶术语，但术语必须来自相同的主干或包类型(即Software、AnnotationData、ExperimentData或Workflow)。

2.11“BugReports:”字段:鼓励包含到Github的相关链接，以便报告问题。

2.12“URL:”字段:该字段引导用户访问源代码存储库、其他帮助资源等;详情请见“书写”R扩展”,RShowDoc(“R-exts”)．

2.13“Video:”字段:该字段显示指向教学视频的链接。

2.14“Collates:”字段:这可能是在包安装过程中对类和方法定义进行适当排序所必需的。

2.15“BiocType”字段:如果提交了一个码头工人或工作流．否则，该字段可以选择定义Bioconductor包的类型软件，ExperimentData，注释．

［回到顶部］

3.名称空间

一个名称空间文件定义导入到名称空间并为用户导出的函数、类和方法。Bioconductor审稿人将寻找:

3.1导出函数应使用驼峰大小写或下划线，不包含"。表示S3调度。

3.2一般importFrom ()建议不要导入整个包，但是如果一个包中有很多函数，进口()是好的。

导出with的所有函数exportPattern(" ^[[:α:]]+”)强烈反对。

［回到顶部］

4.新闻

应该包含一个NEWS文件，以跟踪从一个版本到下一个版本的代码更改。它可以是一个顶级文件，也可以在inst/目录中。应该只存在一个NEWS文件。以下是可接受的格式和位置:

1. 本月。/ / NEWS.Rd 乳胶
2. 本月。/ /新闻 格式化文本见?新闻
3. 本月。/ / NEWS.md mardown
4. 。/ NEWS.md 减价
5. 。/新闻 格式化文本见?新闻

格式的详细信息可以在帮助页上找到新闻吗?．Bioconductor使用NEWS文件创建半年一次的发布公告。它必须包含列表元素和不能是一个纯文本文件。格式示例:

0.99.0版本变更(2018-05-15)+提交Bioconductor 1.1.1版本变更(2018-06-15)+修正错误。从1开始索引而不是2 +进行了以下重大更改o添加了一个子集方法o向数据库添加了一个新字段

安装包后，可以运行以下命令查看NEWS是否正确格式化:

Utils::news(package="<您的包的名称>")

输出应该类似如下所示

1.1.1版本变更(2018-06-15):o修正错误。从1开始索引，而不是从2开始索引o进行了以下重大更改o添加了一个子集方法o在数据库中添加了一个新字段0.99.0版本更改(2018-05-15):o提交给Bioconductor

如果你得到类似下面的东西，有格式错误，需要纠正:

版本:0.99.0发布日期:2018-05-15文本:提交Bioconductor版本:1.1.1发布日期:2018-06-15文本:修复错误。从1开始索引，而不是从2开始版本:1.1.1日期:2018-06-15文本:进行了以下重大更改o添加了一个子集方法o向数据库添加了一个新字段

［回到顶部］

5.引用

适当的引用必须包括在帮助页(例如，在另见部分)和小插图;文档的这一方面与任何科学工作没有什么不同。该文件本月/引用可用于指定如何引用包。如果使用了这个选项，维护人员可以通过运行来检查CITATION文件的格式是否正确readCitationFile(“本月/引用”)；这必须在没有错误的情况下运行，才能在包的登录页上准确地显示CITATION。

无论是否存在引文文件，自动生成的引文将出现在包的登陆页面上Bioconductor网站。若要优化作者名称的格式(如果没有CITATION文件)，请使用Authors@R字段指定包的作者和维护者，如中所述编写R扩展．

［回到顶部］

6.包括数据

一个很好的实践是开发一个软件包，并提供或使用现有的实验数据包，注释数据或数据ExperimentHub或AnnotationHub对软件包中的方法作了较为全面的说明。

如果现有数据不可用或不适用，或者包中的示例需要一个新的较小的数据集，则可以将数据作为单独的数据包(用于较大的数据量)或包含在包中(用于较小的数据集)。

6.1附加实验数据包

实验数据包包含特定于特定分析或实验的数据。它们通常伴随在示例和小插图中使用的软件包，通常不定期更新。如果您需要工作流或示例的一般数据子集，首先检查AnnotationHub资源中的可用文件(例如，BAM、FASTA、BigWig等)。Bioconductor强烈建议创建利用ExperimentHub或AnnotationHub(参见[创建中心包][createHub)的实验数据包，但封装数据的传统包也是可以的。相关软件包的提交bob体育取款很慢请参见软件包提交包。

6.2向已有包中添加数据

Bioconductor强烈鼓励使用现有数据集，但如果没有可用数据，则可以直接将数据包含在包中，以便在手册页、小插图和包的测试中的示例中使用。这是哈德利·维克汉姆写的很好的推荐信有关数据．正如前面提到的Bioconductor但是不鼓励使用LazyData:真尽管在本文中有建议。现将一些要点总结如下。

6.3导出数据和数据/目录

数据数据/导出给用户并随时可用。可以在R会话中通过使用数据()．它将需要有关其创建和来源信息的文档。它通常是一个.RData使用save ()但其他类型也是可以接受的数据()?．请记得压缩数据。

6.4原始数据和本月/ extdata /目录

通常需要显示一个涉及解析或加载原始文件的工作流。Bioconductor建议在另一个包或集线器中查找已提供的现有原始数据，但如果不适用，则原始数据文件应包含在本月/ extdata．这些类型的文件通常使用执行()．Bioconductor类型中需要关于这些文件的文档本月/脚本/目录中。

6.5内部数据

很少情况下，包可能需要内部使用的解析数据，但不应该导出给用户。一个R / sysdata.rda通常是包含这类数据的最佳位置。

6.6其他

应避免下载到网络上的文件和外部数据。如果有必要，至少应该缓存文件。看到BiocFileCache用于Bioconductor文件缓存的推荐包。

［回到顶部］

7.包的文档

包文档对于用户理解如何使用您的代码非常重要。Bioconductor需要一个装饰图案通过演示如何使用包来完成任务的可执行代码，手册页对于所有带有可运行示例的导出函数，有良好文档的数据结构，特别是如果没有pre-exiting类的数据，以及有良好文档的数据集数据而在本月/ extdata．也希望引用所使用的方法以及其他类似或相关的项目/包。如果数据结构不同于类似的包，Bioconductor审稿人会期待一些理由。请记住，扩展现有的类总是可能的。

7.1小插曲

一个小插图演示了如何完成体现包核心功能的重要任务。有两种常见的小插图。一个Sweavevignette是一个. rnw文件，包含LaTeX和R代码块。R代码块以一行«»=开始，以@结束。期间对每个块进行评估R CMD构建，在LaTeX编译为PDF文档之前。一个R减价小插图类似于Sweave小插图，但使用减价而不是LaTeX来构造文本部分并产生HTML输出。的knitr包装可以处理大多数Sweave和所有R markdown小插图，产生令人满意的输出。指写包装小插图bob彩票平台获取技术细节。看到BiocStyle包提供了一种使用通用宏和标准样式的方便方式。

小插图提供了可再现性:小插图产生的结果与将相应的命令复制到R会话中相同。因此至关重要的小插图嵌入执行R代码。捷径(例如，使用LaTeX逐字记录环境，或使用Sweave eval=FALSE标志，或markdown中的等效技巧)破坏了小插图的好处一般不允许；例外情况可以有适当的理由，并在Bioconductor评论者自由裁量权。

所有包装都要求至少有一个小插图。小插图放在小插曲包的目录。小插图通常作为独立文档使用，因此最佳做法是包含一个信息丰富的小插图标题，初级作者小插图的最后修改日期小插图，以及包登录页的链接。我们鼓励使用BiocSytle进行格式化。

生物导体的一些最佳编码实践如下:

7.1.1增加“简介”部分，作为摘要，介绍与同类包不同的目标、模型、独特功能、要点等。

7.1.2添加“安装”部分，向用户展示如何下载和加载软件包Bioconductor．这些说明和任何安装说明应该在一个eval = FALSE代码块。在代码(R代码、手册页、小插图、Rmd文件)中，任何人都不应该试图安装或下载系统依赖项、应用程序、包等。bob电竞体育官网开发人员可以提供指示，但不执行，并且应该假设所有必要的依赖项、应用程序或包已经在用户系统上设置好了。

7.1.3如果合适，我们强烈建议建立目录

7.1.4重要的可执行代码是必须的!!静态小插图是不可接受的。

7.1.5使用SessionInfo ()

7.1.6只有小插图文件(。Rnw or .Rmd) and any necessary static images should be in the vignette directory. No intermediate files should be present.

7.1.7记住包含任何对方法的相关引用。

7.2“man”页面

参见编写R扩展一节手册页获取用于记录包、函数、类和数据集的详细指令或格式信息。所有的帮助页都应该是全面的。

7.2.1所有导出的函数和类都需要一个手册页。描述新类的手册页必须非常详细地说明结构和存储的信息类型。

7.2.2Bioconductor鼓励使用包手册页，其中包含包的概述和到主要函数的链接。

7.2.3数据手册必须包含源信息和数据结构信息。

7.2.4所有的手册页都应该有一个可运行的示例。Donttest和dontrun不鼓励，通常不被允许;例外情况可以有适当的理由，并在Bioconductor评论者自由裁量权。如果使用此选项，也会更可取不而不是dontrun；不需要有效的R代码dontrun没有。

［回到顶部］

7.3本月/脚本/

这个目录中的脚本可能会有所不同。最重要的是，如果数据包括在本月/ extdata /，这个目录中必须有一个相关的脚本，非常清楚地记录数据是如何生成的。它应该包括源url和任何关于过滤或处理的重要信息。它可以是可执行代码、sudo代码或文本描述。用户应该能够下载并能够大致重现作为数据呈现的文件或对象。

［回到顶部］

8.单元测试

强烈推荐单元测试。我们发现它们对于包开发和维护都是不可或缺的。用于测试的两个主要框架是RUnit而且testthat．文中提供了示例和解释在这里．也有机会创建一个比传统测试指南更深入的完整测试套件，但这将需要使用长时间测试．如果包开发人员正在考虑使用长测试，我们强烈建议与bioc-devel邮件列表联系，以确保正确使用和证明。

［回到顶部］

9.R代码和最佳实践

每个人都有自己的编码风格和格式。然而，有一些最佳实践指南Bioconductor会寻找(看到了吗编码风格)．还有其他一些关键点:

9.1只包含可以在指定的许可下发布的代码(参见2.6)。

9.2许多常见的编码和语法问题被标记R CMD检查,BiocCheck ()．(见R CMD检查备忘单而且BiocCheck装饰图案。一些比较突出的违规者:

9.3一些额外的格式和语法指南

9.4避免重新实现功能或类(参见2.8)。利用适当的现有包(例如，biomaRt, AnnotationDbi, Biostrings, GenomicRanges)和类(例如，SummarizedExperiment，AnnotatedDataFrame，农庄，DNAStringSet)，以避免重复其他Bioconductor包。另请参阅常见的Bioconductor方法和类．这鼓励了互操作性并简化了您自己的包开发。如果需要新的表示，请参见必备S4接口的部分健壮高效的代码．一般来说，Bioconductor将坚持与常见的类验收。

9.5避免大量重复的代码。如果代码被重复，这通常是可以实现辅助函数的良好迹象。

9.6也应避免过长的函数。编写小函数。最好每个函数只需要做一项工作。而且如果它在尽可能少的代码行中完成这项工作也是最好的。如果你发现自己编写的大函数超过了一个屏幕，那么你应该花点时间把它分解成更小的辅助函数。较小的函数更容易读取、调试和重用。

函数的参数名应该是描述性的，并且有良好的文档。参数通常应该有默认值。根据有效性检查检查参数。

9.8 Vectorize !许多R操作是在整个对象上执行的，而不仅仅是对象的元素(例如，总和(x),而不是X [1] + X [2] + X[2] +…)．特别是，相对较少的情况需要明确为循环。看到Vectorize的部分健壮高效的代码更多细节。

9.9遵循指导原则查询Web资源如果适用的话

9.10并行实现请使用BiocParallel．另请参阅平行的建议的部分健壮高效的代码．内核的最小数量(1或2)应该设置为默认值。

9.11下载的文件应该缓存。看到BiocFileCache用于Bioconductor文件缓存的推荐包。

9.12不要在用户系统上安装任何东西。应该假定系统依赖项、应用程序和额外需要的包已经下载。如果有必要，维护者应该提供下载和安装的说明，但不应该为用户执行。

［回到顶部］

10.C或Fortran代码

如果包包含C或Fortran代码，则应遵循系统和外文界面部分的写作R扩展手册。特别是:

10.1使用R内部函数，例如:R_alloc和随机数发生器，超过系统提供的。

10.2使用C函数注册(参见注册本机例程)．

10.3在C级循环中使用R_CheckUserInterrupt，当它们有可能不会因为某些参数设置而终止，或者当它们的运行时间在典型参数设置下超过10秒时，并且该方法用于交互使用。

10.4在包中明智地使用Makevars和Makefile。这些通常根本不是必需的(请参阅配置和清理)．

10.5在包开发过程中，启用所有警告并禁用优化。如果你打算使用调试器，告诉编译器包含调试符号。执行这些最简单的方法是在名为“. r”的子目录中创建用户级Makevars文件用户的主目录)。有关通用工具链的标志，请参阅下面的示例。请参阅Writing R Extensions Manual关于Makevars文件的详细信息．

11.第三方代码

强烈不鼓励使用功能与已支持的库冗余的外部库。在外部库比较复杂的情况下，作者可能需要为某些平台提供预构建的二进制版本。

通过包含第三方代码，包维护者承担了维护该代码的责任。维护职责的一部分包括在为主线第三方项目发布错误修复和更新时保持代码的更新。

有关包含来自特定第三方源代码的代码的指导，请参见外部代码源部分c++最佳实践指南。

［回到顶部］

12.闪闪发光的应用

闪亮的应用程序是允许的。请将所有相关R代码放在包的R主目录下。大量的代码不应该直接在光鲜的应用程序中实现。

［回到顶部］

13.gitignore文件

Bioconductor需要一个git存储库来提交。有一些系统文件不应该被git跟踪，并且不可接受包含。这些文件可以保留在本地系统中，但应该从git存储库中排除.gitignore文件。

检查的文件如下Bioconductor被标记为不可接受的:

Hidden_file_ext =("。renviron”、“。rprofile”、“。rproj”、“.rproj。用户”、“。rhistory”、“.rapp。”、“历史。o”、“。sl”、“。所以”、“。dylib”、“。A "， ".dll"， ".def"， "。ds_store”、“unsrturl。Bst "， ".log"， "。辅助”、“。备份”、“。cproject”、“。目录”、“。dropbox”、“。exrc”、“.gdb。”、“历史。gitattributes", ".gitmodules", ".hgtags", ".project", ".seed", ".settings", ".tm_properties" )

结论

下面的练习如何构建BioconductorRStudio包可能也会有帮助。

记住每一个人Bioconductor软件包要经过正式的审查过程，仍然可能收到来自指定人员的技术反馈Bioconductor评论家。提交过程的概述可以在这里找到在这里和一个包可以提交给新的包跟踪器．

  1. 的Bioconductor在提交过程中被指派审查包的团队成员将期望所有错误、警告和注意事项都得到解决。如果有任何剩余，则需要说明为什么没有改正。↩↩2

  2. 这对于软件包来说是正确的。实验数据、注释和工作流包允许额外的空间和检查时间。↩

源代码和构建报告»

源代码存储在Git．

每个晚上都要构建和检查软件包。构建报告:

开发版»

正在开发的Bioconductor包:

开发人员资源:

联系我们:support.bioconductor.org

版权所有©2003 - 2021，生物导体