Roxygen2：记录 S3 class 在重载 R 基本函数时用作 S4 (cor)
Roxygen2: documenting S3 class used as S4 when overloading R base function (cor)
我有以下上下文：
我确实重载了 cor 基本函数，所以我的包 .R 文件中有以下语句：
#'export
setGeneric("cor")
现在我想为我的对象（class 命名为 stranger）创建一个特定的函数——为了简单起见，我只是认为我的对象是一个带有附加列的 data.table名为 .id.
#' Correlation for stranger objects
#' describeIn cor Correlation method for stranger objects.
setMethod("cor",signature(x="stranger"),function(x, method = c("pearson", "kendall", "spearman")){
selectMethod("cor","ANY")(x[,-'.id',with=FALSE],y=NULL, use="everything",method=method)
})
如果我理解 setGeneric，它依赖于 S4 classes -- 因此 signature 参数。
但是，我不使用 S4 classes，而是使用简单的旧方法构建我的 stranger 对象：
buildClass <- function(x,...){
#... prepare out object as data.table with .ìd column
class(out) <- c("stranger", class(out))
return(out)
}
也就是说，我的对象没有 S4 classes。
Dispatching 仍然有效：在我的对象上正确调用 cor 应用专用方法。
我的问题是关于使用 ROxygen2 正确记录的问题。目前，在加载我的函数时，我遇到以下消息：
Updating stranger documentation
Loading stranger
Creating a generic function for 'cor' from package 'stats' in package 'stranger'
in method for 'cor' with signature 'x="stranger"': no definition for class "stranger"
我已经仔细阅读了关于 roxygen2 的 Hadley vignette 以及一些似乎与 Whosebug 相关的问题，但它们只涉及 classical S3 机制或纯 S4，而我没有 S4 构造函数 setClass 和 setGeneric 依赖于 S4。
您可以将其重新定义为 S3 泛型并为其定义方法，而不是为 cor() 设置 S4 泛型方法。为了说明，我创建了一个只有两个 R 文件的 R 包，"buildClass.R" 和 "cor.R"，转载如下：
buildClass.R:
#' Stranger Class Constructor
#'
#' Put some details about it
#'
#' @param x an object
#'
#' @export
buildClass <- function(x){
class(x) <- c("stranger", class(x))
return(x)
}
cor.R
#' Cor
#'
#' Put some details about it
#'
#' @param x an object
#' @param ... other arguments
#'
#' @rdname cor
#' @export
cor <- function(x, ...) {
UseMethod('cor', x)
}
#' @rdname cor
#' @export
cor.stranger <- function(x, ...) {
return(1)
}
#' @rdname cor
#' @export
cor.default <- function(x, ...) {
return(stats::cor(x, ...))
}
然后，如果你加载你的包（在我的例子中命名为 "anRpackage"），用户将被警告包掩码 stats::cor，但定义方式 cor.default()， stats::cor() 为不属于 class stranger:
的对象调用
library(anRpackage)
Attaching package: ‘anRpackage’
The following object is masked from ‘package:stats’:
cor
set.seed(1234)
regular_mat <- matrix(rnorm(100), nrow = 25)
stranger_mat <- buildClass(regular_mat)
cor(regular_mat)
[,1] [,2] [,3] [,4]
[1,] 1.00000000 0.1531414 -0.01948986 -0.3737424
[2,] 0.15314141 1.0000000 0.17531423 -0.1752925
[3,] -0.01948986 0.1753142 1.00000000 0.4371213
[4,] -0.37374237 -0.1752925 0.43712127 1.0000000
cor(stranger_mat)
[1] 1
使用默认值 cran = TRUE（检查 "using the same settings as CRAN uses"）检查 devtools::check() 包时，没有出现错误、警告或注释：
> check(current.code)
Updating anRpackage documentation
Loading anRpackage
Setting env vars ----------------------------------------------------------------
CFLAGS : -Wall -pedantic
CXXFLAGS: -Wall -pedantic
Building anRpackage -------------------------------------------------------------
'/usr/lib/R/bin/R' --no-site-file --no-environ --no-save --no-restore --quiet \
CMD build '/home/duckmayr/anRpackage' --no-resave-data --no-manual
* checking for file ‘/home/duckmayr/anRpackage/DESCRIPTION’ ... OK
* preparing ‘anRpackage’:
* checking DESCRIPTION meta-information ... OK
* checking for LF line-endings in source and make files and shell scripts
* checking for empty or unneeded directories
* building ‘anRpackage_1.0.tar.gz’
Setting env vars ----------------------------------------------------------------
_R_CHECK_CRAN_INCOMING_USE_ASPELL_: TRUE
_R_CHECK_CRAN_INCOMING_ : FALSE
_R_CHECK_FORCE_SUGGESTS_ : FALSE
Checking anRpackage -------------------------------------------------------------
'/usr/lib/R/bin/R' --no-site-file --no-environ --no-save --no-restore --quiet \
CMD check '/tmp/RtmpTcdHJ5/anRpackage_1.0.tar.gz' --as-cran --timings \
--no-manual
* using log directory ‘/tmp/RtmpTcdHJ5/anRpackage.Rcheck’
* using R version 3.4.3 (2017-11-30)
* using platform: x86_64-pc-linux-gnu (64-bit)
* using session charset: UTF-8
* using options ‘--no-manual --as-cran’
* checking for file ‘anRpackage/DESCRIPTION’ ... OK
* checking extension type ... Package
* this is package ‘anRpackage’ version ‘1.0’
* checking package namespace information ... OK
* checking package dependencies ... OK
* checking if this is a source package ... OK
* checking if there is a namespace ... OK
* checking for executable files ... OK
* checking for hidden files and directories ... OK
* checking for portable file names ... OK
* checking for sufficient/correct file permissions ... OK
* checking whether package ‘anRpackage’ can be installed ... OK
* checking installed package size ... OK
* checking package directory ... OK
* checking DESCRIPTION meta-information ... OK
* checking top-level files ... OK
* checking for left-over files ... OK
* checking index information ... OK
* checking package subdirectories ... OK
* checking R files for non-ASCII characters ... OK
* checking R files for syntax errors ... OK
* checking whether the package can be loaded ... OK
* checking whether the package can be loaded with stated dependencies ... OK
* checking whether the package can be unloaded cleanly ... OK
* checking whether the namespace can be loaded with stated dependencies ... OK
* checking whether the namespace can be unloaded cleanly ... OK
* checking loading without being on the library search path ... OK
* checking dependencies in R code ... OK
* checking S3 generic/method consistency ... OK
* checking replacement functions ... OK
* checking foreign function calls ... OK
* checking R code for possible problems ... OK
* checking Rd files ... OK
* checking Rd metadata ... OK
* checking Rd line widths ... OK
* checking Rd cross-references ... OK
* checking for missing documentation entries ... OK
* checking for code/documentation mismatches ... OK
* checking Rd \usage sections ... OK
* checking Rd contents ... OK
* checking for unstated dependencies in examples ... OK
* checking examples ... NONE
* DONE
Status: OK
R CMD check results
0 errors | 0 warnings | 0 notes
我有以下上下文：
我确实重载了 cor 基本函数，所以我的包 .R 文件中有以下语句：
#'export
setGeneric("cor")
现在我想为我的对象（class 命名为 stranger）创建一个特定的函数——为了简单起见，我只是认为我的对象是一个带有附加列的 data.table名为 .id.
#' Correlation for stranger objects
#' describeIn cor Correlation method for stranger objects.
setMethod("cor",signature(x="stranger"),function(x, method = c("pearson", "kendall", "spearman")){
selectMethod("cor","ANY")(x[,-'.id',with=FALSE],y=NULL, use="everything",method=method)
})
如果我理解 setGeneric，它依赖于 S4 classes -- 因此 signature 参数。
但是，我不使用 S4 classes，而是使用简单的旧方法构建我的 stranger 对象：
buildClass <- function(x,...){
#... prepare out object as data.table with .ìd column
class(out) <- c("stranger", class(out))
return(out)
}
也就是说，我的对象没有 S4 classes。
Dispatching 仍然有效：在我的对象上正确调用 cor 应用专用方法。
我的问题是关于使用 ROxygen2 正确记录的问题。目前，在加载我的函数时，我遇到以下消息：
Updating stranger documentation
Loading stranger
Creating a generic function for 'cor' from package 'stats' in package 'stranger'
in method for 'cor' with signature 'x="stranger"': no definition for class "stranger"
我已经仔细阅读了关于 roxygen2 的 Hadley vignette 以及一些似乎与 Whosebug 相关的问题，但它们只涉及 classical S3 机制或纯 S4，而我没有 S4 构造函数 setClass 和 setGeneric 依赖于 S4。
您可以将其重新定义为 S3 泛型并为其定义方法，而不是为 cor() 设置 S4 泛型方法。为了说明，我创建了一个只有两个 R 文件的 R 包，"buildClass.R" 和 "cor.R"，转载如下：
buildClass.R:
#' Stranger Class Constructor
#'
#' Put some details about it
#'
#' @param x an object
#'
#' @export
buildClass <- function(x){
class(x) <- c("stranger", class(x))
return(x)
}
cor.R
#' Cor
#'
#' Put some details about it
#'
#' @param x an object
#' @param ... other arguments
#'
#' @rdname cor
#' @export
cor <- function(x, ...) {
UseMethod('cor', x)
}
#' @rdname cor
#' @export
cor.stranger <- function(x, ...) {
return(1)
}
#' @rdname cor
#' @export
cor.default <- function(x, ...) {
return(stats::cor(x, ...))
}
然后，如果你加载你的包（在我的例子中命名为 "anRpackage"），用户将被警告包掩码 stats::cor，但定义方式 cor.default()， stats::cor() 为不属于 class stranger:
library(anRpackage)
Attaching package: ‘anRpackage’
The following object is masked from ‘package:stats’:
cor
set.seed(1234)
regular_mat <- matrix(rnorm(100), nrow = 25)
stranger_mat <- buildClass(regular_mat)
cor(regular_mat)
[,1] [,2] [,3] [,4]
[1,] 1.00000000 0.1531414 -0.01948986 -0.3737424
[2,] 0.15314141 1.0000000 0.17531423 -0.1752925
[3,] -0.01948986 0.1753142 1.00000000 0.4371213
[4,] -0.37374237 -0.1752925 0.43712127 1.0000000
cor(stranger_mat)
[1] 1
使用默认值 cran = TRUE（检查 "using the same settings as CRAN uses"）检查 devtools::check() 包时，没有出现错误、警告或注释：
> check(current.code)
Updating anRpackage documentation
Loading anRpackage
Setting env vars ----------------------------------------------------------------
CFLAGS : -Wall -pedantic
CXXFLAGS: -Wall -pedantic
Building anRpackage -------------------------------------------------------------
'/usr/lib/R/bin/R' --no-site-file --no-environ --no-save --no-restore --quiet \
CMD build '/home/duckmayr/anRpackage' --no-resave-data --no-manual
* checking for file ‘/home/duckmayr/anRpackage/DESCRIPTION’ ... OK
* preparing ‘anRpackage’:
* checking DESCRIPTION meta-information ... OK
* checking for LF line-endings in source and make files and shell scripts
* checking for empty or unneeded directories
* building ‘anRpackage_1.0.tar.gz’
Setting env vars ----------------------------------------------------------------
_R_CHECK_CRAN_INCOMING_USE_ASPELL_: TRUE
_R_CHECK_CRAN_INCOMING_ : FALSE
_R_CHECK_FORCE_SUGGESTS_ : FALSE
Checking anRpackage -------------------------------------------------------------
'/usr/lib/R/bin/R' --no-site-file --no-environ --no-save --no-restore --quiet \
CMD check '/tmp/RtmpTcdHJ5/anRpackage_1.0.tar.gz' --as-cran --timings \
--no-manual
* using log directory ‘/tmp/RtmpTcdHJ5/anRpackage.Rcheck’
* using R version 3.4.3 (2017-11-30)
* using platform: x86_64-pc-linux-gnu (64-bit)
* using session charset: UTF-8
* using options ‘--no-manual --as-cran’
* checking for file ‘anRpackage/DESCRIPTION’ ... OK
* checking extension type ... Package
* this is package ‘anRpackage’ version ‘1.0’
* checking package namespace information ... OK
* checking package dependencies ... OK
* checking if this is a source package ... OK
* checking if there is a namespace ... OK
* checking for executable files ... OK
* checking for hidden files and directories ... OK
* checking for portable file names ... OK
* checking for sufficient/correct file permissions ... OK
* checking whether package ‘anRpackage’ can be installed ... OK
* checking installed package size ... OK
* checking package directory ... OK
* checking DESCRIPTION meta-information ... OK
* checking top-level files ... OK
* checking for left-over files ... OK
* checking index information ... OK
* checking package subdirectories ... OK
* checking R files for non-ASCII characters ... OK
* checking R files for syntax errors ... OK
* checking whether the package can be loaded ... OK
* checking whether the package can be loaded with stated dependencies ... OK
* checking whether the package can be unloaded cleanly ... OK
* checking whether the namespace can be loaded with stated dependencies ... OK
* checking whether the namespace can be unloaded cleanly ... OK
* checking loading without being on the library search path ... OK
* checking dependencies in R code ... OK
* checking S3 generic/method consistency ... OK
* checking replacement functions ... OK
* checking foreign function calls ... OK
* checking R code for possible problems ... OK
* checking Rd files ... OK
* checking Rd metadata ... OK
* checking Rd line widths ... OK
* checking Rd cross-references ... OK
* checking for missing documentation entries ... OK
* checking for code/documentation mismatches ... OK
* checking Rd \usage sections ... OK
* checking Rd contents ... OK
* checking for unstated dependencies in examples ... OK
* checking examples ... NONE
* DONE
Status: OK
R CMD check results
0 errors | 0 warnings | 0 notes