介绍
这个古宇宙R包是一个社区驱动的软件为古生物学分析提供通用工具的图书馆。核心古宇宙的原理是：（1）流线分析，（2）增强代码可读性，以及（3）提高结果的再现性。
本文件描述了这个古宇宙R包。自然，总是有关于最佳实践和惯例的分歧，以及古宇宙也不例外。尽管如此中的基本要素古宇宙鼓励创造生活开发人员和用户都更容易。值得注意的是核心结构和采用的惯例古宇宙是深受哈德利·威克姆和珍妮·布莱恩的影响R包装和tidyverse风格指南,这也是谷歌目前的指南。
“好的编码风格就像正确的标点符号：你可以没有它就可以管理，但它使事情更容易阅读。”tidyverse风格指导
R型导轨
我们建议使用以下约定来简化代码让我们（和社区）了解和使用：
分配：使用箭头（<-）而不是等号签名以分配。
评论：请全面解释您的代码使用注释（#），因为这将帮助我们理解您的意图并检查代码。
包装：请使用尽可能少的外部包（即依赖项），因为包更有可能损坏对这些进行更改时；如果代码使用包，请加载它们都在脚本的开头（即在教程或示例中）。这对用户来说比拥有各种包更透明贯穿整个代码。
进度：如果您的代码可能需要很长时间才能运行（超过一分钟），包括进度条，如“txtProgressBar（）”在您的功能中。
部分：使用“-”或“=”行表示分段符。很难提供具体的时间细节分节符应该是。然而，我们倾向于将其视为段落在我们的代码中。提示：在RStudio中，您可以使用“#节名称###”制作一个被解释的部分通过轮廓特征。您还可以通过添加更多内容来创建子部分'#"在节名称之前。如果您正在使用RStudio，您也可以使用键盘快捷键命令/Ctrl+Shift+R.
间距：在代码中添加空格以使其更丰富人可读。
物体：使用简短但与它们的内容相关，最好是“小写snakecase”。
包装：将长命令分成多行，通常，行的长度不应超过75–80个字符。
语言：使用普通英语（英式拼写首选，但不是必需的）。
#不！
x= 1
年<-x+1
#太棒了！
x<- 1
年<-x+ 1
数据
通常，我们可能希望将数据纳入古宇宙。这可能会发生以测试功能的示例数据集的形式（例如化石事件），参考数据集，如2020年地质时间刻度，甚至是运行函数的基本数据。在古宇宙中结构，我们目前认识到四种将数据包含在包取决于其用途。
但是，为了提高文件大小效率，请仅包括函数将使用的文件中的数据和变量。注：为了在CRAN上发布，R包必须大小小于5 MB。请仅包含绝对对你的功能至关重要。将数据包含到中的首选解决方案古宇宙函数通过API或下载URL调用数据（即外部数据）。
原始数据
原始数据应始终包含在安装/扩展数据.如果您想在中包含已清理/已处理的数据数据/，是的通常，最好包含用于处理原始数据的代码。如果您需要复制或更新已清理的数据，这将为您节省宝贵的时间。处理数据的代码应该是包含在数据采集/严格来说，原始数据不需要记录。但是，最好将原始源代码和版本（包括下载日期）代码。
内部数据
您不希望直接提供给用户的数据应该是另存为R/系统数据.rda。这是运行函数所需的预先计算的数据表。严格地说说出内部数据不需要记录。然而，它是一个最好在函数中记录内部数据文档。
导出的数据
应存储您希望提供给用户的包数据在里面数据/。此目录中的每个文件都应该是“.rda”或'.R数据'。此文件类型很快，小而明确。包含导出数据的最合适方法是使用usethis:：use_data（）.
在使用大型数据集时，我们希望确保文件不会臃肿，占用用户机器太多空间。像这样的，您可能想尝试中的压缩设置usethis:：use_data（）一般来说，x赫兹和gzip公司可以创建比默认值小的文件b拉链2。您还可以实现几个“hack”来生成对于大型数据集，可能需要考虑较小的文件（取决于您的数据是否对此类更改敏感）。数据具有许多小数位占用大量内存，请考虑有多少个小数位重要数字与您的数据相关，以及圆形（）相应地。您还可以通过乘以用X表示数据（例如1000），以完全删除小数位数。注：调用时记住撤消任何转换或使用数据。
外部数据
外部数据是贡献者首选的包括数据到古宇宙几乎所有项目都需要案例。这是为了确保包不会变得不必要当数据只能通过下载调用时，所有用户都会感到膨胀链接。目前，外部数据存储在GitHub回购中（重建文件古旋回). 很可能由于GitHub不是一个数据，未来它将迁移到其他地方存储库（如果资金允许，最好是一个专用服务器！）。如果你希望包含外部数据，请联系古宇宙开发者，我们可以讨论什么是最好的解决方案。
#生成临时目录
文件夹<- 临时目录()
#下载文件
下载.file(网址= “www.goo.com”,目标文件= 粘贴0（文件，“/mgoo.csv”))
#使用下载运行某种功能
#记住：删除下载的文件
取消链接(x= 粘贴0（文件，"/",列表.files（文件））
数据文档
中的对象数据/默认情况下始终导出，并且应相应记录。为了正确记录数据，必须记录数据集的名称并将其保存在R/数据例如，用于文件GTS2020另存为R/数据。R（右）和类似于以下内容（此处简化）：
#2020年地质时间刻度
#'
#“2020年地质时间尺度的数据集。年龄数据来自：
#“\ url{https://straterraphy.org/timescale网站/}.
#'补充信息也包含在数据集中
#'绘图功能（例如GTS2020配色方案）。
#'
#'@format包含189行和20个变量的数据帧：
#“\描述{
#'\item{index}{数据集中所有间隔顺序的索引号}
#'\item{stage_number}{阶段的索引编号}
#'\item{series_number}{序列的索引号}
#'\item{system_number}{系统索引号}
#'\item{interval_name}{数据集中间隔的名称}
#' ...
#' }
#“@节参考：
#‘Gradstein，F.M.、Ogg，J.G.、Schmitz，M.D.和Ogg、G.M.编辑（2020年）。
#“2020年地质时间尺度。爱思唯尔。
#“@source由Lewis A.Jones编译。有关详细信息，请参阅项目说明。
“GTS2020”
记录数据意味着什么？
记录您的数据是为了提供对数据和任何与理解相关的信息。很好文档是可复制科学的关键，也将帮助我们确保我们承认所有为提供数据的数据收集者这个古宇宙包裹。当向我们提供数据集时，请提供以下信息：
作者：谁收集数据，并准备当前格式？如果相关，请提供引文。让作者为要包含在古宇宙包裹？
描述：数据集的简要描述。
产地：数据收集的时间和方式？数据集是什么时候以当前形式定稿的？
尺寸：请说明完整的未压缩大小文件。
变量：描述您的数据集，尽可能提供有关变量、数据类型（例如连续、离散、类别等），单位，以及如何收集。
功能
习俗
函数另存为'.R’中的文件“R”文件夹。文件名需要与函数，例如文件time_bins。R（右）包含函数time_bins（）。函数名称和参数应为信息丰富，旨在与可用功能保持一致古宇宙例如，bin数据的所有函数，无论是时间还是空间，从垃圾桶_，而分类学相关功能始于税收_（例如税务_唯一,税务_支票). 如果可能，参数名称也应该与包中的函数组成。对于例如，如果函数需要一个occurrence数据帧作为输入，则参数名称应为occdf（occdf）。很难给出所有约定的完整静态摘要如下古宇宙无疑会随着时间的推移而演变。我们也希望对贡献者保持灵活性，前提是它不损害了包装的用户友好性。我们欢迎贡献者检查的源代码古宇宙对于函数示例。
文档
对于文档，我们使用氧气2标题，简介描述和每个参数（包括输入类和默认值输入）和功能输出需要记录在氧气2样式，例如：
#“示例性功能
#'此函数用于演示函数的文档。
#'@param example\code{character}。参数是函数输入。
#'@param another_example\code{logical}。所有论据都需要记录在案。
#在这个示例函数中，“@return A\code{list}作为输出返回。
#“@details如有必要，请描述更多细节，如适用，请列出来源。
#“@节开发人员：
#'你的名字
#“@节审阅者：
#'姓名
#“@示例
#'#展示示例函数
#'示例函数（示例=“documentation”，另一个示例=TRUE）
#“@导出
添加“@导出”用于生成函数的namespace标记可用。
开始氧气2，设置您的工作目录到包目录，或到存储您的作为'.R’文件。R命令开发工具：：document（）在目录，其中包含'.路'文件对应于您的文档功能。在RStudio中打开该文件，可以创建一个预览以查看文档的外观。在你完成之后实现更改，使用Ctrl+Shift+B重新生成文档文件或开发工具：：document（）.
效率
如果可能，您应该做出编码决策，以确保你的代码是最有效的-这可能会有很大的不同对于希望将您的函数应用于大型数据集的用户。少许一般示例包括：
- 使用中的函数
“应用”家庭可以更快而不是为了跑步。然而，for-loop几乎总是更多读者友好，所以尽量平衡两者！
- 将对象存储为列表或列表列表，而不是数据帧内部函数
- 尽可能矢量化。这样，一个函数可以对所有向量的元素，而无需循环遍历每个元素。
- 避免使用
rbind（）和cbind（）到在for-loops中以行或列方式编译对象；指定使用迭代编号的行或列编号通常更快备选方案。
然而，请不要让这件事阻碍你——我们欢迎提交来自所有经验水平的R用户，以及我们的内部代码团队评估人员可以帮助您解决任何有关效率的问题。
错误消息
为了确保正确使用函数，错误消息应该在函数接收输入时生成专为设计。错误消息包括对发生的情况的简要描述错了。有时，指定出错的地方和原因是有意义的应输入类型。或者，错误消息可以包括提示以引导用户进行正确的输入。
错误消息的示例包括
- 输入了错误的格式，例如
“错误：'x'必须是数字向量。”
- 输入了错误的尺寸，例如
“错误：'x'必须是具有两列的data.frame。”
- 输入不带必填名称，例如
“错误：'x'没有列'stage'。
“x”必须是列为“stage”和“age”的data.frame。“
要在R中实现错误消息停止（）功能可用于：
#生成错误消息
如果(!是数字的（x） ）{
停止(“错误：'x'必须是数字向量。”)
}
警告消息
一般来说，我们尽量减少在古宇宙因为这些很容易被用户忽略，或者管道分析中完全跳过(看见更多？). 然而，与生活中的大多数事情一样，有时间和地点。所以，在使用警告（）通常是如果抛出一个错误就足够了，我们不鼓励使用中的警告消息古宇宙，在适当的情况下。警告消息对于向用户提供附加信息很有用关于函数输出。例如，在古旋回如果一个或多个点不能由于地理参考板不存在于所需的重建时间。
要在R中实现警告消息警告（）可以使用以下功能：
#生成警告消息
如果(!是数字的（x） ）{
警告(“警告：'x'必须是数字向量。”)
}
测验
测试可能是开发功能。如果您还没有，我们建议您通读第章12–测试'右程序包'在此继续之前古宇宙跟随本指南。
将函数添加到之前古宇宙，它需要进行正式测试。这是必需的，希望您函数将非常流行，我们需要确保它的行为希望避免任何问题。为此，我们使用R包测试那个.
功能测试的初始设置测试那个是已经建立在古宇宙目录下'测试/测试/'.测试文件的组织必须与之匹配“R/”中的文件古宇宙。对于示例，函数time_bins（）另存为time_bins。R（右）在中对/目录，并且具有关联的测试文件'测试时间_ bins。R’在中'测试/测试'目录。这确保了功能测试是明确的。
提示：这个用这个包提供了一对有用的函数，用于在这些函数之间创建/交替文件夹：
使用此：：use_（）usethis:：use_test（）
确保在您的右文件到涵盖函数的所有可能变体。这包括创建覆盖大多数或所有可选参数以及大多数这些参数的选项（以及必需的参数）。记住，甚至如果您个人出于特定原因不使用函数，您必须尝试覆盖可能出现的大多数边缘情况函数允许。
相关测试应捆绑在test_that（）电话结合文本字符串来确定每种情况的大致原因测试包（例如，测试一个功能与特定类型一起工作数据）。最后，如果测试依赖于古宇宙社区必须有，如果这些数据或包不可用。
最终，我们的目标是使代码覆盖率超过90%（首选95%），这意味着我们代码库中90%的代码行应该由至少一次测试。将代码推送到GitHub将触发代码覆盖率检查，这将提醒您是否需要写更多测验。
#测试预期结果等于实际结果
测试_那(“time_bins（）有效”, {
预期相等（_E）(nrow公司(时间（_B）(间隔= c(“马斯特里赫特阶”))),1)
})
对古宇宙的贡献
在古宇宙我们采用了一套结构和标准为促进古宇宙。如果您想为古宇宙工具箱，我们强烈建议阅读此文档优先。如果您计划为古宇宙，您应该首先提高问题通过GitHub存储库（请参见下文）。这样开发团队可以评估功能是否适合或需要古宇宙工具包提交之前。
Git和GitHub
我们通过Github使用git（在古宇宙GitHub伞)管理我们的R代码和数据。如果您不熟悉这些工具，网上有一些优秀的免费资源：
如何做出贡献
次要更改
您可以修复直接在GitHub上创建文档，前提是在源代码中这样做文件。这意味着您需要在右文件，而不是.道路文件。
实质性变化
如果您想进行实质性更改，应首先提交并确保开发团队的人员同意这是需要的。如果发现错误，请提交一个问题用一个可复制的示例说明了该错误。
拉取请求流程
您（贡献者）应该克隆所需的存储库（即古宇宙R包裹)连接到您的个人电脑。在进行更改之前，您应该切换到新的git分支（即，不是主分支）。当您的更改完成后，您可以通过拉请求GitHub上的（“PR”）。请注意，完整的拉取请求应该包括简洁的描述(看见函数模板)代码更改的作用，适当的文档（通过氧气2)、和单元测试（通过测试那个). 只需要描述初始拉请求和代码审查（见下文），但拉请求将在它们包含完整的文档和测试之前，不能进行合并。
如果您对git/GitHub不满意，可以联系一个核心开发人员(看见合作者)通过电子邮件，他们可以向您的代表。然而，您需要回复任何审阅者对GitHub的评论（见下文）。
如果您对自己实施更改感到不自在，您可以提交错误报告或功能请求作为GitHub问题存储库（例如古宇宙问题).
代码审查
所有拉入请求都必须由以下两个核心开发人员审查古宇宙(看见合作者)在合并之前。审查过程将确保贡献1）满足上述标准和期望，2） 成功执行他们声称要执行的功能，以及3）不要破坏代码库的任何其他部分。
向提交拉入请求古宇宙包裹将自动启动R（右）CMD检查,短绒检查、和测试覆盖检查通过GitHub操作。虽然这些检查会自动进行检查以确保包没有被新代码破坏，并且如果代码与样式指南匹配（参见上文），则需要进行手动检查在合并pull请求之前仍然需要。
审阅者在审阅您的推送请求时可能会有问题。你希望通过GitHub回答任何这些问题。如果修复了和/或需要进行更改，您需要进行这些更改。如果所需的更改很小，审阅者可能会为您进行更改，但这是意料之外的。如果您有任何问题或缺少要进行所需的更改，您应该使用评审员决定攻击计划。