计划的指导方针

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

简介

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

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

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

请记住，这些是包验收的最低要求，包仍将遵守以下其他指导方针和a的正式技术审查Bioconductor团队成员。

［回到顶部］

总体包装开发

版本的Bioconductor和R

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

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

正确性，空间和时间

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

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

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

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

  5. 该包的运行时间应该少于10分钟R CMD检查—没有构建小插图．使用——no-build-vignettes选项确保只构建一次小插图。2

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

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

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

R CMD检查环境

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

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

［回到顶部］

描述

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

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

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

  2. “标题”字段:有一个简短但描述性的标题

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

    • 对于尚未发布的包，X通常为0。
    • 对于发布中的包，Y是偶数，对于devel中的包，Y是奇数。一般来说，不要提高这个数字，尤其是在预发行版中。
    • Z在向包提交更改时递增。

  4. “Description:”字段:描述应该是一个相对简短但详细的包功能概述。它应该是一个或多个完整的句子。

  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存储库的提交访问权。上的请求可以将提交访问权限授予其他开发人员2021欧洲杯体育投注开户bioc-devel邮件列表。另一种选择是将合作者添加到github存储库中。这种方法使许多人能够开发，但限制了对git.bioconductor.org的推送访问。

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

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

  8. “看/进口/建议/提高:“字段:

    • 所有的包必须通过Bioconductor或凹口；用户和自动构建系统无法从其他来源安装包。
    • 重用(而不是重新实现或复制)来自其他包的经过良好测试的功能。使用适当的现有包(例如，biomaRt, AnnotationDbi, Biostrings)和类(例如，summarizeexperiment, GRanges, Rle, DNAStringSet)，并避免复制其他可用的功能Bioconductor包。看到常见的Bioconductor方法和类．Bioconductor审稿人在这一点上非常严格!新包应该与现有包可互操作Bioconductor类，而不是重新实现功能，特别是在导入/读取数据方面。

    • 一个包只能在依赖/导入/建议/增强之间列出一次。根据以下指南确定包装的位置:

      • 进口:用于提供在包名称空间内使用的函数、方法或类的包。这里列出了大多数软件包。
      • 取决于:是针对为您的包的用户提供基本功能的包，例如GenomicRanges的Depends:字段中列出了包GenomicAlignments．有三个以上的包被列为“Depends:”是不寻常的。
      • 建议:用于小插图、示例和条件代码中使用的包。通常，注释和实验包(例如，TxDb *)用于小插图和示例代码，从而避免用户昂贵的下载。在包代码需要外部一次性函数的情况下，可以通过检查外部包可用性if (!requireNamespace('extraPKG')) stop(…)．
      • 提高:是针对诸如Rmpi或平行它们增强了包的性能，但并不是它的功能所严格需要的。
    • 很少有必要详细说明R或作为依赖项的特定版本，因为Bioconductor发布策略和标准安装说明保证了这些约束。外部镜像的存储库Bioconductor每一个都应该包含分支吗Bioconductor发布时，可能会发现完全指定版本以强制执行由其他方式保证的约束是有用的Bioconductor安装实践。

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

  10. " biocViews: "字段:REQUIRED!至少指定两个biocViews类别．鼓励使用多个术语，但术语必须来自同一包类型(Software, AnnotationData, ExperimentData, Workflow)。

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

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

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

  14. “Collates:”字段:在包安装过程中，可能需要对类和方法定义进行适当的排序。

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

［回到顶部］

名称空间

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

  1. 导出的函数应使用驼峰大小写或下划线，且不包括"。表示S3调度。

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

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

［回到顶部］

新闻

应该包含一个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向数据库添加了一个新字段

［回到顶部］

引用

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

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

［回到顶部］

包括数据

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

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

附加实验数据包

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

向现有包中添加数据

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

导出数据和数据/目录

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

原始数据及本月/ extdata /目录

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

内部数据

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

［回到顶部］

包的文档

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

小插曲

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

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

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

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

  1. 添加一个“介绍”部分，作为一个摘要，介绍目标、模型、独特功能、关键点等，将包与其他类似类型的包区分开来。

  2. 添加“安装”部分，向用户展示如何下载和加载软件包Bioconductor．

  3. 如果合适的话，我们强烈建议使用目录

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

  5. 属性包含一个节SessionInfo ()

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

  7. 记住要包括对方法的任何相关引用。

“男人”页面

所有导出的函数和类都有一个手册页。Bioconductor还鼓励使用包手册页，其中包含包的概述和到主要函数的链接。数据手册页必须包括源信息和数据结构信息。描述新类的手册页必须非常详细地说明结构和存储的信息类型。所有的手册页都应该有一个可运行的示例。Donttest和dontrun不鼓励，通常不被允许;例外情况可以有适当的理由，并在Bioconductor评论者自由裁量权。如果使用此选项，也会更可取不而不是dontrun；不需要有效的R代码dontrun没有。参见编写R扩展一节手册页获取用于记录包、函数、类和数据集的详细指令或格式信息。所有的帮助页都应该是全面的。

［回到顶部］

本月/脚本/

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

［回到顶部］

单元测试

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

［回到顶部］

R代码和最佳实践

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

  1. 只包含可以在指定的许可下分发的代码。

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

    • 使用vapp ()而不是酸式焦磷酸钠()并使用各种apply函数而不是for循环。
    • 使用seq_len ()或seq_along ()而不是1:……
    • 用TRUE/FALSE代替T/F
    • 避免类()= =而且类()!＝而不是使用是()
    • 使用系统2 ()而不是系统
    • 不要使用set.seed任何内部R代码。
    • 没有浏览器()调用应该在代码中
    • 避免使用<<-．
    • 避免使用直接插槽访问@或槽()．应该创建和利用访问器方法

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

    • 使用<-而不是＝转让
    • 函数名应该是驼峰大小写或使用下划线＿没有一个点．表示S3调度。
    • 使用dev.new ()如有必要，启动图形驱动器。避免使用x11 ()或X11 ()因为它只能在能够访问X服务器的机器上调用。

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

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

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

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

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

  9. 遵循以下指引原则查询Web资源如果适用的话

  10. 对于并行实现，请使用BiocParallel．另请参阅平行的建议的部分健壮高效的代码．

［回到顶部］

C或Fortran代码

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

第三方代码

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

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

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

［回到顶部］

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

欧洲杯冠军投注