如何使用roxygen文档化数据集？

Question

在roxygen过程中，是否可以将.R文件包含在数据目录中？

我已经将多个.R文件放入数据目录中。当它们通过data()被调用时，它们会读取原始数据文件并执行一些转换。

- Karsten W.

Answer 1

Roxygen 可以在 R 文件中的任何位置使用（换句话说，它不必后跟函数）。它还可以用于记录 R 文档中的任何 docType。

因此，您可以在单独的块中记录数据（类似于以下内容）：

#' This is data to be included in my package
#'
#' @name data-name
#' @docType data
#' @author My Name \email{blahblah@@roxygen.org}
#' @references \url{data_blah.com}
#' @keywords data
NULL

- Shane

---

最好使用NULL而不是roxygen()，这样你就不会在运行时依赖于roxygen。 - hadley

@hadley：可以考虑在roxygen用户指南中添加类似这样的示例，并强调关于roxygen依赖性的要点吗？我发现在文件结构方面，这有一点令人困惑。 - Shane

感谢Shane和Hadley的出色帮助。现在我更清楚如何使用roxygen了；现在R CMD check不再抱怨了。还有一个问题：我需要将数据文档放在R子目录中吗？如果roxygenize也能查看数据目录，那就太好了... - Karsten W.

@Karsten：我认为数据子目录中应该放置的唯一内容是数据。Roxygen提供了R代码的可读性编程，因此我喜欢将其全部放在我的R文件中。但除此之外，您可以尝试这样做：roxygenize使用一个环境变量“R.DIR”。将其设置为“data”而不是默认值，它应该可以处理数据目录中的R文件。@hadley：你可以制作一个简单的补丁来允许R.DIR向量吗？ - Shane

@Shane：我已经向roxygen开发人员投诉了，下一个版本应该会有所改变。 - hadley

@hadley，现在我正在使用roxygen2。这个版本是否已实施？我将一个.R文件放在那里来描述我的数据对象，但是R CMD Check似乎无法解析它。 - Faustin Gashakamba

Answer 2

从roxygen2 >4.0.0版本开始，您可以通过使用定义的对象名称（以字符串形式）来记录在其他地方定义的数据对象：

#' This is data to be included in my package
#'
#' @author My Name \email{blahblah@@roxygen.org}
#' @references \url{data_blah.com}
"data-name"

- hadley

---

请返回翻译文本。 - stevec

Answer 3

我发现研究ggplot2包中的示例非常有用。

请参阅github上ggplot2.r

需要注意的几件事：

• 所有数据集的Roxygen代码都可以包含在包的R目录下的单个.r文件中。

例如，可以查看diamonds数据集：

#' Prices of 50,000 round cut diamonds
#'
#' A dataset containing the prices and other attributes of almost 54,000
#'  diamonds. The variables are as follows:
#'
#' \itemize{
#'   \item price. price in US dollars (\$326--\$18,823)
#'   \item carat. weight of the diamond (0.2--5.01)
#'   \item cut. quality of the cut (Fair, Good, Very Good, Premium, Ideal)
#'   \item colour. diamond colour, from J (worst) to D (best)
#'   \item clarity. a measurement of how clear the diamond is (I1 (worst), SI1, SI2, VS1, VS2, VVS1, VVS2, IF (best))
#'   \item x. length in mm (0--10.74)
#'   \item y. width in mm (0--58.9)
#'   \item z. depth in mm (0--31.8)
#'   \item depth. total depth percentage = z / mean(x, y) = 2 * z / (x + y) (43--79)
#'   \item table. width of top of diamond relative to widest point (43--95)
#' }
#'
#' @docType data
#' @keywords datasets
#' @name diamonds
#' @usage data(diamonds)
#' @format A data frame with 53940 rows and 10 variables
NULL

这将生成一个看起来像这样的帮助文件：

- Jeromy Anglim

---

可能是因为Roxygen文档已经更新了，这里是现在的样子。 - vlad1490

现在的工作方式是因为“Lazyload：true”而起作用。如果您不使用“Lazyload”，那些数据对象就没有定义。在这种情况下，您需要使用“旧”的Roxygen2代码。 - Eli Holmes