计划的指导方针

版本1.0 - 21004-08

本页提供有关指导原则和所需格式的详细信息Bioconductor包。另请参阅匈牙利瑞士比分了解提交过程的概述以及作为Bioconductor维护者。

简介

的Bioconductor项目促进高质量、文档记录良好、可互操作的软件。这些准则有助于实现这一目标;它们并不是为了给包的作者增加不必要的负担，如果作者很难满足指南的要求，则应该寻求有关的建议bioc-devel邮件列表。

在进行开发时，建议包维护人员尽可能严格地遵循这些指导方针Bioconductor包。

制作包的一般说明可在编写R扩展手册，可从R (RShowDoc(“R-exts”))或在R的网站．

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

［回到顶部］

1.一般包装开发

1.1版本的Bioconductor和R

包开发人员应该始2021欧洲杯体育投注开户终使用重击的版本Bioconductor当开发和测试要贡献的包时。

根据R发布周期，使用Bioconductordevel可能也可能不涉及使用r的devel版本【2021欧洲杯官方合作伙伴】 获得最新的信息。

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检查——不构建小vignettes．使用——no-build-vignettes选项确保小插图只构建一次。2

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

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自述文件

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

2.描述文件

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

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

' ' ' if (!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应该使用字段。维护人员名称(cre为Authors@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。bioconductor。org上提交访问git仓库的权限。的请求可以将提交访问权授予其他开发人员2021欧洲杯体育投注开户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: " field: 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.名称空间

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

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

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

3.3导出所有函数withexportPattern(" ^[[:α:]]+”)强烈气馁。

［回到顶部］

4.新闻

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

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

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

0.99.0(2018-05-15)版本更改+提交给Bioconductor 1.1.1(2018-06-15)版本更改+修复bug。从1开始索引，而不是从2 +开始索引

安装包后，可以运行以下程序来查看NEWS是否被正确格式化:

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

输出应该类似于以下内容

1.1.1版本更改(2018-06-15):o修正错误。在0.99.0(2018-05-15)版本的更改:o提交给Bioconductor

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

版本:0.99.0发布日期:2018-05-15文本:提交给Bioconductor版本:1.1.1发布日期:2018-06-15文本:修正错误。版本:1.1.1日期:2018-06-15文本:做了以下重大更改，添加了一个子集方法，添加了一个新的字段到数据库

［回到顶部］

5.引用

适当的引用必须包括在帮助页(例如，在see also部分)和小插图;文档的这一方面与任何科学工作并无不同。该文件本月/引用可用于指定如何引用包。如果使用了此选项，维护人员可以通过运行readCitationFile(“本月/引用”)；这必须在没有ERROR的情况下运行，以便在包登陆页面上准确显示CITATION。

的包登陆页上会显示自动生成的引用文件，无论是否存在引用文件Bioconductor网站。若要优化作者名的格式(如果没有提供CITATION文件)，请使用Authors@R字段指定包的作者和维护人员编写R扩展．

［回到顶部］

6.包括数据

一个优秀的实践是开发一个软件包，并提供或使用现有的实验数据的包，注释数据或者数据ExperimentHub或AnnotationHub对软件包中的方法进行了全面的说明。

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

6.1附加实验数据包

实验数据包包含特定于特定分析或实验的数据。它们通常随软件包一起用于示例和小插图中，通常不定期更新。如果您需要工作流或示例的一般数据子集，首先检查AnnotationHub资源中的可用文件(例如，BAM、FASTA、BigWig等)。Bioconductor强烈鼓励创建使用ExperimentHub或AnnotationHub(参见[创建集心器包][createHub])的实验数据包，但封装数据的传统包也可以。相关包的提交请参匈牙利瑞士比分见“Package Submission”包。

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减价vignette类似于Sweave vignette，但使用减价而不是LaTeX来构造文本部分并产生HTML输出。的knitr包装可以处理大多数Sweave和所有R markdown小插图，产生令人满意的输出。指写包小插曲欧洲杯2021体育彩票技术细节。看到BiocStyle包提供了一种使用通用宏和标准样式的方便方式。

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

所有包装必须至少有一个小插图。小插图放在小插曲包的目录。Vignettes通常作为独立的文档使用，因此最佳实践是包含一个信息性的标题,主作者小插画的最后修改日期的小插图，和一个链接到包的登陆页面。我们鼓励使用BiocSytle进行格式化。

以下是bioconductor的一些最佳编码实践:

7.1.1增加“引言”部分，作为摘要，介绍与同类软件包的区别于其他软件包的目标、模型、独特功能、要点等。

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

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“男人”页面

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

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

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

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

7.2.4所有的手册页都应该有一个可运行的示例。不要和dontrun不鼓励，一般不允许;在有正当理由的情况下，可以作出例外Bioconductor评论者自由裁量权。如果使用了这个选项，也最好使用它不而不是dontrun；不需要有效的R代码，而dontrun没有。

［回到顶部］

7.3本月/脚本/

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

［回到顶部］

8.单元测试

强烈推荐使用单元测试。我们发现它们对于包的开发和维护都是不可或缺的。两个主要的测试框架是RUnit而且testthat．给出了例子和解释在这里．也有机会创建一个比传统测试指南更深入的完整测试套件，但这将需要使用长时间测试．如果软件包开发人员正在考虑使用长时间的测试，我们强烈建议与bio -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, genome icranges)和类(例如，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遵循以下指导原则查询网络资源如果适用的话

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文件用户的主目录。参见下面的示例，了解常见工具链的标志。参考写作R扩展手册关于Makevars文件的详细信息．

11.第三方代码

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

通过包含第三方代码，包维护人员承担起维护该代码的责任。维护责任的一部分包括保持代码的更新，因为为主线第三方项目发布了bug修复和更新。

有关包含来自某些特定第三方来源的代码的指导，请参阅外部源代码部分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" )

结论

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

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

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

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

源代码和构建报告»

源代码存储在Git．

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

开发版»

正在开发的生物导体包:

开发人员资源:

联系我们:support.bioconductor.org

版权所有©2003 - 2021,Bioconductor