为数据框自动生成 roxygen2 文档的最佳方法是什么?
What's the best way to automatically generate roxygen2 documentation for a data frame?
在我的新 CRAN 包中,我有 10 个数据框,每个数据框在 data/ 文件夹中有 10 列左右的各种类型。类型有strings、int、floats、booleans等
我需要为每个数据源添加 roxygen2 文档。是否有一种方法可以在给定 data.frame 的情况下自动生成评论块?
类似于:makeDocs(游戏)
#' games
#' title character
#' score integer
#' value numeric
#' ...
我担心如果我手动完成,我可能会犯错误(~100 列),或者如果名称更改,我会不断地手动重新编辑内容。
我找到了这个关于记录数据集的好答案
How can I document data sets with roxygen?
...但这并没有说明我如何自动生成这些评论?
从框架的名称列表开始,然后像这样的东西是一个快速的技巧:
frames <- c("iris","mtcars")
unlist(sapply(frames, function(d) c(paste("#'", d), "#' @format data.frame",
gsub("^","#'",capture.output(str(get(d)))),
dQuote(d)),
simplify=FALSE), use.names=FALSE)
# [1] "#' iris"
# [2] "#' @format data.frame"
# [3] "#''data.frame':\t150 obs. of 5 variables:"
# [4] "#' $ Sepal.Length: num 5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ..."
# [5] "#' $ Sepal.Width : num 3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ..."
# [6] "#' $ Petal.Length: num 1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ..."
# [7] "#' $ Petal.Width : num 0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ..."
# [8] "#' $ Species : Factor w/ 3 levels \"setosa\",\"versicolor\",..: 1 1 1 1 1 1 1 1 1 1 ..."
# [9] "\"iris\""
# [10] "#' mtcars"
# [11] "#' @format data.frame"
# [12] "#''data.frame':\t32 obs. of 11 variables:"
# [13] "#' $ mpg : num 21 21 22.8 21.4 18.7 18.1 14.3 24.4 22.8 19.2 ..."
# [14] "#' $ cyl : num 6 6 4 6 8 6 8 4 4 6 ..."
# [15] "#' $ disp: num 160 160 108 258 360 ..."
# [16] "#' $ hp : num 110 110 93 110 175 105 245 62 95 123 ..."
# [17] "#' $ drat: num 3.9 3.9 3.85 3.08 3.15 2.76 3.21 3.69 3.92 3.92 ..."
# [18] "#' $ wt : num 2.62 2.88 2.32 3.21 3.44 ..."
# [19] "#' $ qsec: num 16.5 17 18.6 19.4 17 ..."
# [20] "#' $ vs : num 0 0 1 1 0 1 0 1 1 1 ..."
# [21] "#' $ am : num 1 1 1 0 0 0 0 0 0 0 ..."
# [22] "#' $ gear: num 4 4 4 3 3 3 3 4 4 4 ..."
# [23] "#' $ carb: num 4 4 1 1 2 1 4 2 2 4 ..."
# [24] "\"mtcars\""
然后您可以 cat
将其导出到一个文件中并拥有您需要的大部分内容。
我从他上面的回答中提取了 r2evans 代码并将其转换为一个函数。
makeDoc = function (dataFrame, title = substitute(dataFrame)) {
output = c(paste("#'", title), "#' @format data.frame", gsub("^","#'",capture.output(str(dataFrame))), dQuote(title))
cat(output, sep="\n")
}
您很可能会发现 sinew
R-package 提供的功能很有用;请参阅 R-bloggers post in here.
中提供的示例
以下示例适用于数据框和函数,并为它们创建氧气骨架。您自然需要手动修改一些字段,如大写字母所示:
> set.seed(1); dat <- data.frame(first = LETTERS[1:10], second = rnorm(10), third = 1:10)
> fun <- function(x, y) { x + y }
> sinew::makeOxygen(dat)
#' @title DATASET_TITLE
#' @description DATASET_DESCRIPTION
#' @format A data frame with 10 rows and 3 variables:
#' \describe{
#' \item{\code{first}}{character COLUMN_DESCRIPTION}
#' \item{\code{second}}{double COLUMN_DESCRIPTION}
#' \item{\code{third}}{integer COLUMN_DESCRIPTION}
#'}
#' @details DETAILS
"dat"
> sinew::makeOxygen(fun)
#' @title FUNCTION_TITLE
#' @description FUNCTION_DESCRIPTION
#' @param x PARAM_DESCRIPTION
#' @param y PARAM_DESCRIPTION
#' @return OUTPUT_DESCRIPTION
#' @details DETAILS
#' @examples
#' \dontrun{
#' if(interactive()){
#' #EXAMPLE1
#' }
#' }
#' @rdname fun
#' @export
如您所见,sinew
生成 #'
行,当放置在 .R
文件中的适当位置时,这些行与生成 roxygenized .Rd
文件兼容.请参阅包中的更多功能,这些功能可以自动将这些线放置到正确的位置。
在我的新 CRAN 包中,我有 10 个数据框,每个数据框在 data/ 文件夹中有 10 列左右的各种类型。类型有strings、int、floats、booleans等
我需要为每个数据源添加 roxygen2 文档。是否有一种方法可以在给定 data.frame 的情况下自动生成评论块?
类似于:makeDocs(游戏)
#' games
#' title character
#' score integer
#' value numeric
#' ...
我担心如果我手动完成,我可能会犯错误(~100 列),或者如果名称更改,我会不断地手动重新编辑内容。
我找到了这个关于记录数据集的好答案 How can I document data sets with roxygen?
...但这并没有说明我如何自动生成这些评论?
从框架的名称列表开始,然后像这样的东西是一个快速的技巧:
frames <- c("iris","mtcars")
unlist(sapply(frames, function(d) c(paste("#'", d), "#' @format data.frame",
gsub("^","#'",capture.output(str(get(d)))),
dQuote(d)),
simplify=FALSE), use.names=FALSE)
# [1] "#' iris"
# [2] "#' @format data.frame"
# [3] "#''data.frame':\t150 obs. of 5 variables:"
# [4] "#' $ Sepal.Length: num 5.1 4.9 4.7 4.6 5 5.4 4.6 5 4.4 4.9 ..."
# [5] "#' $ Sepal.Width : num 3.5 3 3.2 3.1 3.6 3.9 3.4 3.4 2.9 3.1 ..."
# [6] "#' $ Petal.Length: num 1.4 1.4 1.3 1.5 1.4 1.7 1.4 1.5 1.4 1.5 ..."
# [7] "#' $ Petal.Width : num 0.2 0.2 0.2 0.2 0.2 0.4 0.3 0.2 0.2 0.1 ..."
# [8] "#' $ Species : Factor w/ 3 levels \"setosa\",\"versicolor\",..: 1 1 1 1 1 1 1 1 1 1 ..."
# [9] "\"iris\""
# [10] "#' mtcars"
# [11] "#' @format data.frame"
# [12] "#''data.frame':\t32 obs. of 11 variables:"
# [13] "#' $ mpg : num 21 21 22.8 21.4 18.7 18.1 14.3 24.4 22.8 19.2 ..."
# [14] "#' $ cyl : num 6 6 4 6 8 6 8 4 4 6 ..."
# [15] "#' $ disp: num 160 160 108 258 360 ..."
# [16] "#' $ hp : num 110 110 93 110 175 105 245 62 95 123 ..."
# [17] "#' $ drat: num 3.9 3.9 3.85 3.08 3.15 2.76 3.21 3.69 3.92 3.92 ..."
# [18] "#' $ wt : num 2.62 2.88 2.32 3.21 3.44 ..."
# [19] "#' $ qsec: num 16.5 17 18.6 19.4 17 ..."
# [20] "#' $ vs : num 0 0 1 1 0 1 0 1 1 1 ..."
# [21] "#' $ am : num 1 1 1 0 0 0 0 0 0 0 ..."
# [22] "#' $ gear: num 4 4 4 3 3 3 3 4 4 4 ..."
# [23] "#' $ carb: num 4 4 1 1 2 1 4 2 2 4 ..."
# [24] "\"mtcars\""
然后您可以 cat
将其导出到一个文件中并拥有您需要的大部分内容。
我从他上面的回答中提取了 r2evans 代码并将其转换为一个函数。
makeDoc = function (dataFrame, title = substitute(dataFrame)) {
output = c(paste("#'", title), "#' @format data.frame", gsub("^","#'",capture.output(str(dataFrame))), dQuote(title))
cat(output, sep="\n")
}
您很可能会发现 sinew
R-package 提供的功能很有用;请参阅 R-bloggers post in here.
以下示例适用于数据框和函数,并为它们创建氧气骨架。您自然需要手动修改一些字段,如大写字母所示:
> set.seed(1); dat <- data.frame(first = LETTERS[1:10], second = rnorm(10), third = 1:10)
> fun <- function(x, y) { x + y }
> sinew::makeOxygen(dat)
#' @title DATASET_TITLE
#' @description DATASET_DESCRIPTION
#' @format A data frame with 10 rows and 3 variables:
#' \describe{
#' \item{\code{first}}{character COLUMN_DESCRIPTION}
#' \item{\code{second}}{double COLUMN_DESCRIPTION}
#' \item{\code{third}}{integer COLUMN_DESCRIPTION}
#'}
#' @details DETAILS
"dat"
> sinew::makeOxygen(fun)
#' @title FUNCTION_TITLE
#' @description FUNCTION_DESCRIPTION
#' @param x PARAM_DESCRIPTION
#' @param y PARAM_DESCRIPTION
#' @return OUTPUT_DESCRIPTION
#' @details DETAILS
#' @examples
#' \dontrun{
#' if(interactive()){
#' #EXAMPLE1
#' }
#' }
#' @rdname fun
#' @export
如您所见,sinew
生成 #'
行,当放置在 .R
文件中的适当位置时,这些行与生成 roxygenized .Rd
文件兼容.请参阅包中的更多功能,这些功能可以自动将这些线放置到正确的位置。