创建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包的所有文件)

1-在RStudio中创建R包项目

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

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

 2-创建R包

创建R包有两种形式

1. 通过R函数create_package来创建新包 本文使用的是该种方法创建新包
2. 在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函数得到的结果都是一样的一个最小的可用包它由以下三个部分组成

1. 一个R/目录
2. 一个描述文件DESCRIPTION;
3. 一个命名空间文件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窗口显示就如同我们平时使用“函数名”查看帮助文件所看到的一样。

 @importFrom  package_name  function 表示从什么包 导入 哪个函数也就是说我们下面的这个自定义函数用到了哪些包中的哪个函数这个需要一一的通过@importFrom列出来。

@importFrom stats rnorm从stats包导入函数rnorm函数。

@importFrom foreach %dopar% foreach从foreach包导入两个函数%dopar%和foreach是函数。

当包打包完成并在本地RStudio中加载过后通过?mean_parallel_compute得到下面的效果。

​ ​

(不知道是不是文章太长了导致保存的时候经常会出现问题接下来的内容以及参考放在新的文章中。)