在 R 包中重命名和隐藏导出的 Rcpp 函数 [英] Renaming and Hiding an Exported Rcpp function in an R Package

问题描述

编写R包，我有一个R函数调用特定的Rcpp函数.Rcpp 函数仅用作辅助函数，我不想为其创建 .Rd 文件.到目前为止，我的解决方案是在命名空间文件中导出这两个函数，这会导致警告在我运行 check 命令后立即为 Rcpp 函数创建一个 .Rd 文件.如果我删除命名空间文件中的辅助函数，我将摆脱这个警告，现在导致 R 函数无法再找到它的问题.

Writing an R package, I have a R function that calls a specific Rcpp function. The Rcpp function just serves as a helper function and I do not want to creat a .Rd file for it. My solution so far is to export both functions in the Namespace file which causes the warning to create an .Rd file for the Rcpp function as soon as I run the check command. If I remove the helper function in the Namespace file, I get rid of this warning causing now the problem that the R function is not able to find it anymore.

有没有办法解决这个问题.这意味着要使 Rcpp 函数对 R 函数仍然可见，同时消除 Rcpp 函数不存在 .Rd 文件的警告?

Is there a way to solve this problem. That means to make the Rcpp function still visible for the R function and at the same time to get rid of the warning that there exists no .Rd file for the Rcpp function?

非常感谢:-)

推荐答案

注册问题的起源:NAMESPACE 文件

我假设在您的 NAMESPACE 文件中有:

exportPattern("^[[:alpha:]]+") 

这基本上是自动"导出以字母开头的任何函数.因此，您通过 //[[Rcpp::exports]] 导出的 Rcpp 函数正在被拾取.

This basically "automatically" exports any function that begins with alphabet letter. Thus, your exported Rcpp function via // [[Rcpp::exports]] is being picked up.

要解决这个问题，有两种解决方案.第一个更像是黑客"，第二个涉及在 NAMESPACE 文件中正确使用 export().

To solve this, there are two solutions. The first is more of a "hack" and the second involves properly using export() in the NAMESPACE file.

对于第一个解决方案，您可以更改导出 Rcpp 函数的方式，明确说明该函数应如何出现在 R 中.由于 NAMESPACE 的配置注册了所有以字母开头的函数，因此名称更改的重要方面是在函数名称前加上句点 (.)，例如:

For the first solution, you can change how you export the Rcpp function explicitly stating how the function should appear in R. The important aspect of this name change, due to the configuration of the NAMESPACE registering all functions that start with an alphabetic letter, is to prefix to the function name a period (.), e.g.:

// [[Rcpp::export(".function_name")]]

作为一个现实生活中的例子，以函数 C++ function some_function() 为例:

As a real life example, take the function C++ function some_function():

// [[Rcpp::export]]
void some_function(int value)

这里使用Rcpp属性会将函数名some_function()

The use of the Rcpp attributes here will export into R the function name some_function()

现在，要为 R 显式命名该函数，将是:

Now, to explicitly name the function something different for R would be:

// [[Rcpp::export(.some_function)]]
void some_function(int value)

将作为 .some_function() 导出到 R 中.可能更具说明性的是我们可以将其更改为完全不同的名称，例如

which will be exported into R as .some_function(). Probably more illustrative is we could change it to be a completely different name, e.g.

// [[Rcpp::export(toad)]]
void some_function(int value)

这意味着调用 C++ 函数的导出的 R 函数是 toad().

This would mean the exported R function that calls the C++ function is toad().

您可能希望采用的另一种方法是明确声明应该导出哪个函数以及应该不导出哪个函数.为此，NAMESPACE 文件必须去掉 exportPattern("^[[:alpha:]]+") 条目，并且每个应该可用的函数都必须是指定为 export(function).例如，cIRT 包的NAMESPACE 具有每个应该公开"导出的函数.

The other approach that you may wish to take is to explicitly declare which function should be exported and which function should not be exported. To do this, the NAMESPACE file must be rid of the exportPattern("^[[:alpha:]]+") entry and each function that should be available must be specified as export(function). For example, the cIRT package's NAMESPACE has each function that should be "public" exported.

话虽如此，大多数用户使用 生成文档roxygen2.在此文档生成器下，您可以在 roxygen2 标签中指定，例如#' @tag 或 //' @tag，该函数应该导出到NAMESPACE:

With this being said, a majority of users generate documentation with roxygen2. Under this documentation generator, you can specify in the roxygen2 tags, e.g. #' @tag or //' @tag, that the function should be exported into the NAMESPACE with:

# R code
#' @export

或

// C++ code
//' @export

在 C++ 的函数文档中，这看起来像:

Within the function documentation for C++ this would look like:

//' Title
//'
//' Description
//' 
//' @export

如果你不想导出一个函数，那么你所要做的就是不要用//'@export记录它.

If you do not want a function exported, then all you have to do is not document it with //' @export.

这篇关于在 R 包中重命名和隐藏导出的 Rcpp 函数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！