R包开发-2.1：在RStudio中使用Rcpp制作R-Package(更新于2023.8.23)

0-前言

1-在RStudio中创建R包项目

2-创建R包

2.1通过R函数创建新包

2.2在RStudio通过菜单来创建一个新包

2.3关于R包创建的说明

3-添加R自定义函数

4-添加C++函数

0-前言

目标：在RStudio中创建一个R包，这个R包中包含C++函数，接口是Rcpp。

为了实现这个目标，我们复现一个简单的R包Rcpp2doParallel，取名ReproduceRcpp2doParallel.

这个R包的相关内容：

From: rdrr.io（可以查看这个R包中R文件）

From: GitHub (包括创建这个R包的所有文件)

注：如果想看一个R包的源码状态

如果这个包发表在GitHub，在GitHub上搜索这个包的名字，可以找到这个R包的源码状态，尤其是当这个包还使用了C++函数的时候，可以在源码包中找到src/目录里的cpp文件；
如果这个包发表在CRAN，在GitHub上可以找到CRAN，在CRAN里检索包的名字，或者直接在GitHub上检索包的名字，尤其是当这个包还使用了C++函数的时候，可以在源码包中找到src/目录里的cpp文件；
rdrr.io这个网站只能看包里的R函数，如果这个包还使用了C++函数，在这个网站上是看不到这个包里的C++函数。

1-在RStudio中创建R包项目

建立与GitHub有连接的R包项目，具体参考R包开发一：R与Git版本控制

此时，我们得到名为ReproduceRcpp2doParallel的文件夹，如下图所示：

2-创建R包

创建R包有两种形式：

通过R函数create_package来创建新包；（本文使用的是该种方法创建新包）
在RStudio通过菜单来创建一个新包。（本文此处仅展示如何通过这种方式创建）

2.1通过R函数创建新包

键入创建R包的语句，第二行语句表示在当前路径下创建一个新包，创建R包函数为create_package()：

library(devtools)
create_package(getwd())

得到如下结果：

> library(devtools)
载入需要的程辑包：usethis
> create_package(getwd())
✔ Setting active project to 'D:/桌面/ReproduceRcpp2doParallel'
✔ Creating 'R/'
✔ Writing 'DESCRIPTION'
Package: ReproduceRcpp2doParallel
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R (parsed):
    * First Last <first.last@example.com> [aut, cre] (YOUR-ORCID-ID)
Description: What the package does (one paragraph).
License: `use_mit_license()`, `use_gpl3_license()` or friends to
    pick a license
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.2.3
✔ Writing 'NAMESPACE'
Overwrite pre-existing file 'ReproduceRcpp2doParallel.Rproj'?

1: No
2: Yeah
3: Not now

Selection: 2
✔ Writing 'ReproduceRcpp2doParallel.Rproj'
✔ Adding '^ReproduceRcpp2doParallel\\.Rproj$' to '.Rbuildignore'
✔ Adding '^\\.Rproj\\.user$' to '.Rbuildignore'
✔ Opening 'D:/桌面/ReproduceRcpp2doParallel/' in new RStudio session
✔ Setting active project to '<no active project>'

注意，“√”表示这个语句完成了哪些具体的工作，"●"表示需要我们手动操作的内容。（当然，上述创建R包的语句中没有●）；

上述代码中问道：是否重写ReproduceRcpp2doParallel.Rproj？选择yeah，即重写这个项目文件，对原来的项目文件进行覆盖。注意：这里每次的选项顺序不一样，要根据意思进行选择，而不是根据编号进行选择！

2.2在RStudio通过菜单来创建一个新包

直接在RStudio中建立新项目New Project. 其操作为New Project --> New Directory --> R package --> print R package name --> create Project.

2.3关于R包创建的说明

不管是使用RStudio的菜单栏还是使用R函数，得到的结果都是一样的：一个最小的可用包，它由以下三个部分组成：

一个R/目录；
一个描述文件DESCRIPTION;
一个命名空间文件NAMSESPACE。

这个包还包括一个RStudio项目文件ReproduceRcpp2doParallel.Rproj，这将使你的包易于在RStudio中使用。

一些解释性的内容，其中：

DESCRIPTION文件：描述了你的包需要依赖什么来工作，如果要分享你的包，也会用DESCRIPTION文件来描述它的功能，谁可以使用它（许可证），以及如果包出现了问题该和谁联系。是关于R包的元数据。
NAMESPACE命名空间文件：为了和其他的包很好地协作，你的包需要定义它可以输出什么函数供其他包使用，以及它需要使用其他包的什么函数，这是NAMESPACE文件的工作，通过roxygen2来生成它。（roxygen最初从2008年的Google编程夏令营中诞生，作用是用来写帮助文档，可以在一个R文件中上面部分敲文档，下面部分敲代码，不需要在两个文件中切来切去，这让码农从重复劳动和技术细节中解放出来专心写代码。）
R/目录：里面存放构成这个包的R文件，实际上R包就是将一堆R自定义函数打包在一起，所以R/目录这个文件夹中存放的是一堆R自定义函数，一个自定义函数一个R文件。
.gitignore和.Rbuildignore：包含Git或者R包构建时应该忽略的文件。

至此，初步的开发R包的框架已经搭建完成，并且已经与远程仓库（Github）建立连接，后续任何更新都可以很容易地提交到Github仓库（提交步骤：Staged --> Commit --> Push）。

3-添加R自定义函数

此时R/目录文件夹是空的，需要我们在里面添加一些自定义函数。

use_r("mean_parallel_compute")

由于这里是复现Rcpp2doParallel包，所以ReproduceRcpp2doParallel这个包里的所有函数，都来自于Rcpp2doParallel.

通过rdrr.io 或者GitHub 可以找到Rcpp2doParallel包自定义R函数，如mean_parallel_compute.R，函数如下：

#' Call an Rcpp function within a doParallel call
#'
#' Constructs an example showing how to use `foreach`, `iterators`, and
#' `doParallel` to perform a parallel computation with a C++ function written
#' using Rcpp.
#'
#' @param n       Number of Observations
#' @param mean    Center of Normal Distribution
#' @param sd      Standard Deviation of Normal Distribution
#' @param n_sim   Number of Simulations to Run
#' @param n_cores Number of CPU cores to use in parallelization task.
#'
#' @return
#' A `vector` of length `n_sim` containing the mean for each distribution.
#'
#' @export
#'
#' @importFrom foreach %dopar% foreach
#' @importFrom iterators icount
#' @importFrom doParallel registerDoParallel
#' @importFrom stats rnorm
#'
#' @details
#' The `mean_parallel_compute()` function performs a bootstrap computation in
#' parallel of a mean value from the normal distribution.
#'
#' @examples
#' # Compute the mean on 1000 observations with 50 replications across
#' # 2 CPUs.
#' mean_parallel_compute(1000, n_sim = 50, n_cores = 2)
mean_parallel_compute = function(n, mean = 0, sd = 1,
                                 n_sim = 1000,
                                 n_cores = parallel::detectCores()) {

  # Construct cluster
  cl = parallel::makeCluster(n_cores)

  # After the function is run, close the cluster.
  on.exit(parallel::stopCluster(cl))

  # Register parallel backend
  doParallel::registerDoParallel(cl)


  # Compute estimates
  estimates = foreach::foreach(i = iterators::icount(n_sim), # Perform n simulations
                               .combine = "rbind",           # Combine results
                                                             # Self-load
                               .packages = "Rcpp2doParallel") %dopar% {
    random_data = rnorm(n, mean, sd)

    result = mean_rcpp(random_data) # or use Rcpp2doParallel::mean_rcpp()

    result
  }

  estimates
}

可以看到这个R文件分成上下两个部分，上面是关于文档说明的部分，之后会来制作帮助页面，下面部分是代码部分。通常，首先我们在通过use_r("R文件名字")中敲完代码，之后将鼠标放在函数体内，在RStudio中找到code--> Insert Roxygen Skeleton，便自动插入函数注释信息模板。（注意，一定要把光标放在函数体内，否则会弹出报错提示信息，告知要把光标放在函数体内。）

第一步：我们只粘贴上面的代码部分

第二步：函数的注释部分通过code-->Insert Roxygen Skeleton来填充。得到下图，接着对照Rcpp2doParallel包中mean_parallel_compute自定义R函数文件，将其注释信息补充到我们当前打开的R文件中。

自动插入的函数注释信息为:@param、@return、@export、@ examples，其中@param后的参数是自动识别的，剩下的内容需要自己手动补充，就好像是按照要求填写表格。子弟哦那个插入函数的注释信息只出现在该R文件的函数上面，不会变动函数部分，换句话说，这样R文件被分成了两部分，上部分是函数注释信息，下部分是自定义R函数。其中函数注释信息，每行注释都以 #' 开头，@引导的关键词包括标题、描述、参数、返回值、工作示例，我们在这些关键词后面分别填写相应的内容。

@export表示导出该函数，这样做文档化时，会自动将这个函数添加到NAMESPACE文件。导出函数后，安装该包可以使用该函数，如果不添加@export，则不导出函数，这样的函数叫作内部函数，只供包里的其他函数使用。

有了上述帮助信息，就可以执行文档化，代码如下，这样将自动生成函数帮助，实际上是调用roxygen2包生成man/function_name.Rd,该文件在RStudio Help窗口显示就如同我们平时使用“？函数名”查看帮助文件所看到的一样。