创建和发布R数据包的详细指南：使用Devtools

一个逐步账户来开发我的“Richmondway” R 数据包，特色是罗伊·肯特的脏话计数

Erda Estremera的照片，来自Unsplash — 照片来自 Erda Estremera 在 Unsplash

当我被邀请在2023年的Posit会议上发表关于“动画和交互式叙事”的演讲时，我花了数月的时间思考完美的数据集。看起来每个有趣的数据集都已经被用尽了，我也没有灵感基于一个平凡无奇的数据集来做演讲。然而有一天，当我沉溺于《泰德·拉索》(Ted Lasso)这部美国运动喜剧剧集中，畅快地观赏了罗伊·肯特(Roy Kent)优雅地放置的脏话时，我突然有了一个想法。我重新看了这部剧集（当然是两倍速），并统计了罗伊使用或模仿“F**k”这个词的次数。这就成了我的数据集！在这篇文章中，我将带你逐步了解我是如何将这个数据集转化为R数据包的详细步骤，让你也能轻松地创建一个。

欢迎来到《Richmondway》的制作过程，这是我第一个R数据包，让你可以下载这些数据并深入了解罗伊·肯特的词汇，一集一集，一季一季的细节。最后，回答了从没人问过的问题——罗伊·肯特在哪个季度最多地说了F**k？

我为什么创建一个数据包？

我一直渴望学习如何创建R数据包。从一个简单的数据包开始是一个很好的尝试。
嵌入数据以进行功能测试是很重要的。这使用户熟悉包的功能，也是我未来任何复杂包的必要步骤。
这个数据集太有趣了，不想只留给我自己。打包它可以确保每个人都能轻松访问。

所以，不管你是对R数据包创建感兴趣，还是你是一个《泰德·拉索》的狂热粉丝，泡杯茶，我们马上开始！

我用来创建R数据包的详细步骤

步骤0：数据集和数据包名称

这是我数据集的快照，名为“richmondway”。它有34行，对应每一集，16个列对应不同的值，这些值将在我们要创建的数据包中进行描述。

给你的数据包命名就像给宠物命名一样——非常特别。你会想选择一个令人难忘的名字，同时确保它简洁，特别是如果你打算公开发布。我给我的数据包起了名字“Richmondway”——致敬于《泰德·拉索》中罗伊·肯特曾经效力的足球俱乐部阿夫克·里士满(AFC Richmond)，并且以“R”字母开头，这是一个幸运的巧合。我还希望这个名字能清晰地显示包内包含的内容。

步骤1：安装工具包

安装这些R包：devtools，usethis和roxygen2。它们能够极大地简化结构化和文档化新包的过程。

install.packages(c("devtools", "usethis", "roxygen2"))

步骤2：创建一个新的包作为项目

您可以使用devtools创建两种方法来创建一个包。Devtools负责处理大量需要初始化包结构设置。

方法1：直接从RStudio控制台中

Screen cast of project creation for R package using devtools — 使用devtools创建R包的项目创建的屏幕录像

方法2：使用usethis包

使用usethis::create_package()命令，您可以通过提供要创建包目录的路径直接创建一个新的包。在本文的其余部分，我将继续展示其他使包创建和文档编制步骤变得更简单和更快的usethis命令。

usethis::create_package("path/richmondway")

您刚刚创建了一个具有R包的基本要求的文件夹。如果您在内部看一看，您会发现一些神秘的文件。别担心，我们会逐个了解它们。这是您将看到作为项目的一部分被创建的文件。

Initial home directory of project — 项目的初始主目录

步骤3：添加数据集

我将数据集保存在本地环境中为“richmondway”。运行下面的命令将在您的包的根目录下添加一个“/data”目录，并在其中放置一个“.rda”文件。

usethis::use_data(richmondway)

A single file named “richmondway.rda” within the “data” folder — “数据”文件夹内的名为“richmondway.rda”的单个文件

步骤4：创建数据字典`data.R`：

这是您描述数据集的地方。相信我，描述得越好，他人就越容易发掘其潜力。这将在后续步骤中用于您的文档。您可以使用下面的命令创建此文件，然后稍后使用所有必需的详细信息更新它。

usethis::use_r("data")

此命令将在R文件夹中创建一个data.R文件。更新此文件的内容，包含您的数据集中的格式和列的详细信息。虽然我的数据集中还有许多列，但对于此示例，我只显示了下面的三列。您应该尽可能清楚地添加所有列的描述，因为它将出现在您的数据集包文档中。在data.R文件中使用以下格式来创建描述。

#'用于展示操**个数的数据#'#'通过罗伊·肯特在《泰德·拉索》中使用单词操**的次数创建的数据集。#'#'@format包含34行和16列的数据框。#'\describe{#' \item{字符}{单个值 - 罗伊·肯特}#' \item{Episode_order}{从第1集到最后一集的顺序}#' \item{Season}{与计数相关联的第1、2或3季}#' }#'@source由Deepsha Menghani通过观看节目并计算句子和手势中使用的操**的次数创建#'#'@examples#' data(richmondway)"richmondway"

让我们将该文件分解为其组成部分：

描述备注：

#' 提供了关于数据集的描述和评论#' 数据集包含了在电视剧《踢足球教练泰德·拉索》中罗伊·肯特使用脏话“f**k”的次数。

这是数据集的简短标题和描述。以#'开头的注释用于以特殊方式注释 R 对象，以便被 R 中用于生成文档的roxygen2包捕捉到。

格式备注：

#' @format 一个包含 34 行和 16 列的数据框。

这指定了数据的格式。在这种情况下，数据集是一个包含34行和16列的数据框。

变量说明：

#' \describe{#' \item{字符}{单个值 - 罗伊·肯特}#' \item{Episode_order}{从第一集到最后一集的顺序}#' \item{Season}{与计数相关的第1、2或3季}#' }

该部分详细说明了数据框中一些主要变量/列的情况。使用\describe块来列出并描述每个由\item标记表示的变量的名称和描述。

来源备注：

#' @source 由迪普夏·孟哈尼（Deepsha Menghani）通过观看节目并计算句子和手势中使用脏话的次数创建

这提供了关于数据的来源或来源的信息。给创作者以功劳，并提供收集数据的背景。

示例备注：

#' @examples #' data(richmondway)

这提供了用户如何访问和使用数据集的示例。在这种情况下，它简单地演示了一旦他们安装了你的软件包，如何将数据导入 R 中。

数据名称：

"richmondway"

这是数据集的名称。它在引号中，因为它表示这个文档与软件包中该名称的数据集相关联。

当用户在 R 中安装和加载您的软件包，然后键入?richmondway时，他们将以结构化格式呈现此文档，以帮助他们了解数据集的内容、结构和如何使用它。

步骤5：更新 “`DESCRIPTION"` 文件

描述文件是软件包的更高级文档。查看软件包主目录中的DESCRIPTION文件，应该预填有说明，需要更新为正确的描述。我在描述文件中更新的字段如下，其余部分保持默认。

Package: richmondway
Title: 一个包含了在电视剧《踢足球教练泰德·拉索》中罗伊·肯特使用脏话“f**k”的次数的数据集
Authors@R: person("迪普夏", "孟哈尼", email = "abc@gmail.com", role = c("aut", "cre"))
Description: 下载包含了在电视剧《踢足球教练泰德·拉索》中罗伊·肯特使用脏话“f**k”的次数的数据集。
License: file LICENSE

步骤6：创建 “LICENSE” 文件

这个文件就像是你的软件包的简历。请注意，在我的描述文件中，我提到了一个名为LICENSE的文件。该文件尚不存在，因此我们现在将创建它。这将引用一个存储有license信息的文件。license信息告诉软件包的用户如何使用通过该软件包提供的数据，也就是权利。在我这个例子中，我使用了CC0许可证，并使用以下命令将标准描述添加到我的LICENSE文件中。

license_text <- 'CC0 1.0通用（CC0 1.0）公共领域许可证与此规定关联一项作品的人，已根据版权法将作品在全世界范围内完全捐赠给公共领域，包括所有相关和相邻权利，尽法规所许可的范围，您可以复制、修改、分发和执行此作品，甚至用于商业目的，无需取得许可。有关更多信息，请参阅<http://creativecommons.org/publicdomain/zero/1.0/>'writeLines(license_text, con = "packagepath/LICENSE")

步骤 7：加载文档

现在，所有文件都已创建和更新，我们使用下面这个便捷的命令来加载文档。这个命令将使用我们添加了数据描述的data.R文件创建文档。该文档放置在一个新建的名为man（代表“手册”）的文件夹中。

devtools::document()

运行文档命令后，您可以使用帮助命令?richmondway，它将打开软件包文档。确保文档清晰，从data.R文件中显示出所需的详细信息。

步骤 8：检查

现在您可以通过运行以下命令来测试一切是否都运行顺利且完美无缺。此命令执行各种检查，以确保软件包的一致性和有效性。

devtools::check()

devtools::check()的输出会提供NOTES、WARNINGS和ERRORS，每个都需要不同程度的关注：

ERRORS：必须立即修复，因为它们表示重大问题。WARNINGS：应该解决，以确保功能和CRAN（Comprehensive R Archive Network，R综合归档网络）的一致性。NOTES：提供有用的建议和建议，有时需要为CRAN提交而解决。

创建和发布R数据包的详细指南：使用Devtools 四海第8张

步骤 9：在本地安装并测试软件包

以下来自devtools的命令可用于在本地安装软件包。然后，使用在data.R文件中共享的方法来测试数据访问。

devtools::install() # 在本地安装软件包data(richmondway) # 通过软件包访问数据

步骤 10：将全新的软件包发布到GitHub

现在，我们需要初始化Git仓库并使用一些方便的usethis命令将软件包推送到GitHub。在运行这些命令之前，请确保您拥有GitHub帐户，并已设置用于GitHub的SSH密钥或个人访问令牌（PAT）。

usethis::use_git() # Git集成usethis::use_github() # GitHub集成

usethis::use_git()做了什么

初始化Git：此函数在项目中初始化一个新的Git仓库。
首次提交：它使用项目的当前状态进行首次提交。

usethis::use_github()做了什么

创建GitHub仓库：此函数帮助创建一个新的GitHub仓库，并将本地Git仓库连接到远程GitHub仓库。
身份验证：帮助设置与GitHub的身份验证。它会检查您是否已在GitHub上进行了身份验证。如果没有，可能会提示您这样做。
推送：将本地Git提交推送到远程GitHub仓库。

现在您可以分享您的软件包仓库链接。任何人都可以使用 devtools::install_github(“your_username/packagename”) 直接从GitHub安装您的软件包并访问数据。

例如，在我的GitHub软件包中，可以使用以下命令访问 richmondway 中的数据：

devtools::install_github("deepshamenghani/richmondway")

你成功了！

如果您已经达到这一点，恭喜您！您刚刚把一次愉快的连续观看变成了既富有教育意义又愉快的经历。

请随意使用这份有趣的数据集，并在您的分析和可视化中标记我。或者您可以在GitHub上fork richmondway 并为Roy Kent词汇贡献力量。继续打包吧！

资源

Richmondway软件包仓库
R Packages By Hadley Wickham和Jennifer Bryan
Roxygen2 文档
Usethis 软件包
Devtools 软件包

愉快的编码！如果您愿意，可以在 Linkedin 上找到我。