手把手教你制作R包（一）

一、准备工作

• 安装开发所需的R包：devtools

install.packages("devtools")
library(devtools)

install.packages("roxygen2")
library(roxygen2)

二、创建R包

2.1 初始化R包

• 基于create_package()函数初始化一个名为plotAUC的R包；基于roxygenize()函数生成帮助文档（一般产生一个空的man目录）。
• 执行完成后，将在当前目录下创建plotAUC文件夹，并在新生成的文件中，自动创建多个必须的文件和R目录（文件夹），如DESCRIPTION，NAMESPACE… 及 项目工程文件plotAUC.Rproj等各种文件（可以自行查看）
• 执行结束后，会自动开启一个新的IDE窗口。
• 目录结构如下：
  

> usethis::create_package("./plotAUC")
√ Creating './plotAUC/'
√ Setting active project to 'D:/worktask/RandomForest/plotAUC'
√ Creating 'R/'
√ Writing 'DESCRIPTION'
Package: plotAUC
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R (parsed):
    * First Last <[email protected]> [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.1.2
√ Writing 'NAMESPACE'
√ Writing 'plotAUC.Rproj'
√ Adding '^plotAUC\\.Rproj$' to '.Rbuildignore'
√ Adding '.Rproj.user' to '.gitignore'
√ Adding '^\\.Rproj\\.user$' to '.Rbuildignore'
√ Opening 'D:/worktask/RandomForest/plotAUC/' in new RStudio session
√ Setting active project to ''

> roxygenize("D:/worktask/RandomForest/plotAUC")

2.2 修改 DESCRIPTION 文件

Package: plotAUC
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R: 
    person(
    	given="First", 
    	family="Last",
    	email="[email protected]", 
    	role=c("aut", "cre"),
        comment=c(ORCID = "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.1.2

2.3 创建第一个函数

在新开启的IDE窗口中，

• 执行usethis::use_r()函数，创建R函数；
• 或者，将已经完成的R文件(如test.R)直接放到R目录下

> usethis::use_r("plotAUC")
√ Setting active project to 'D:/worktask/RandomForest/plotAUC'
* Modify 'R/plotAUC.R'
* Call `use_test()` to create a matching test file

• 执行usethis::use_r()函数之后，在R目录下自动创建一个R函数，并在R窗口中打开
• 接下来，为这个函数添加程序。

在编写程序过程中，如果依赖其他的R-packages，可以使用use_package("Package-names")函数，将相应的包加载到当前包环境中。
此时，也会在元数据文件中增加一个条目：Imports: ggplot2, ggprism

> use_package("ggplot2")
√ Adding 'ggplot2' to Imports field in DESCRIPTION
* Refer to functions with `ggplot2::fun()`
> use_package("ggprism")
√ Adding 'ggprism' to Imports field in DESCRIPTION
* Refer to functions with `ggprism::fun()`

2.4 测试函数

使用devtools::load_all()函数加载创建的函数（执行了building-installing-attaching）

> devtools::load_all()
i Loading plotAUC
> plot_cum_auc(imp, auc, rawdata)

2.5 包检查

• 主要是核验包的其他文件或附件是否合法

> devtools::load_all()
> usethis::use_mit_license()
> devtools::check() # 不需要任何参数
i Updating plotAUC documentation
i Loading plotAUC
-- Building ------------------------------------------------------------------------------ plotAUC --
Setting env vars:
* CFLAGS    : -Wall -pedantic
* CXXFLAGS  : -Wall -pedantic
* CXX11FLAGS: -Wall -pedantic
* CXX14FLAGS: -Wall -pedantic
* CXX17FLAGS: -Wall -pedantic
* CXX20FLAGS: -Wall -pedantic
----------------------------------------------------------------------------------------
........

0 errors √ | 1 warning x | 2 notes x

• 备注：只要没有error，基本不影响整个包的创建；自己可以基于自己的实际情况自行查找修改warning和notes

2.6 为函数添加说明/帮助文档

我们可以为函数加上一些帮助文档，文档放在man文件夹里面；帮助文档的后缀是.Rd，一种Rmarkdown文件。

有两种方法可以添加帮助文档：

• 直接在每一个函数上方以标准格式形式写注释
• 打开code文件（如plotAUC.R），点击Code>Insert roxygen skeleton(注意，这个时候光标要在函数内部)。随后，自动在函数上面插入模板，可在此基础上进行修改。

#' Title
#'
#' @param imp 
#' @param auc 
#' @param rawdata 
#' @param sec_axis_percent 
#'
#' @return
#' @export
#'
#' @examples

最后，使用roxygen2::roxygenize()和devtools::document()生成.Rd帮助文档（存在于man目录下）

> roxygenize("D:/worktask/RandomForest/plotAUC")
i Loading plotAUC
> devtools::document()
i Updating plotAUC documentation
i Loading plotAUC
Writing NAMESPACE
Writing plot_cum_auc.Rd
> ?plot_cum_auc
i Rendering development documentation for "plot_cum_auc"

2.7 添加内置数据集

2.7.1. 手动添加内置数据

• 在包目录下，添加data文件夹
• 将*.RData文件迁移至data文件夹下

2.7.2. 自动添加内置数据

• 先将数据读入包环境中，然后执行devtools::use_data(dat1, dat2, dat3,...)。
• 自动在包目录中添加data目录，并保存数据为*.rda文件（RData数据类型）

> usethis::use_data(imp, auc, rawdata, group, dat1)
√ Adding 'R' to Depends field in DESCRIPTION
√ Creating 'data/'
√ Setting LazyData to 'true' in 'DESCRIPTION'
√ Saving 'imp', 'auc', 'rawdata', 'group', 'dat1' to 
	'data/imp.rda', 'data/auc.rda', 'data/rawdata.rda', 
	'data/group.rda', 'data/dat1.rda'
* Document your data (see 'https://r-pkgs.org/data.html')

备注：一般在加载R包后，使用data("auc")加载数据文件。

2.7.3. 内置数据集注释

• 撰写data.R
  对这些数据进行docment的时候，是对这些数据的名称进行说明，并存放到R/目录下。比如，在ggplot2包中对diamonds数据的说明存放在R/data.R中：

#' @docType data
#' @name auc
#'
#' @title Test data
#' @description  A dataset containing the prices and other attributes of almost 54,000
#' diamonds.
#' @details Success!!
#'
#' @format A data frame with 53940 rows and 10 variables:
#' \describe{
#'   \item{AUCs}{The cumulative AUC value }
#'   \item{Lable}{Is it selected?}
#'   \item{NumberOfFeatures}{The rank of features}
#'   ...
#' }
#' @source \url{NULL}
NULL

备注：\describe{...}中可以仅填写...省略号，一匹配所有的信息；@name必须与数据文件同名

• 创建document文档

> document()
i Updating plotAUC documentation
i Loading plotAUC
Writing NAMESPACE
Writing NAMESPACE
Writing auc.Rd
Writing imp.Rd
Writing group.Rd
Writing dat1.Rd
Writing rawdata.Rd

2.8 包检查和创建readme文件

最后，我们可以use_readme_rmd()和build_readme()生成readme文件，对R包进行说明，包括packages的描述；安装；示例。

> devtools::check()
> use_readme_rmd()
√ Writing 'README.Rmd'
√ Adding '^README\\.Rmd$' to '.Rbuildignore'
* Modify 'README.Rmd'
* Update 'README.Rmd' to include installation instructions.
> build_readme()
i Installing plotAUC in temporary library
i Building D:/worktask/RandomForest/plotAUC/README.Rmd

> build() # 创建R包：*.tar.gz

# 需要重新启动R编辑器
> devtools::install() # 安装R包

3. 总结

基本的流程是：

create_package 创建一个R包
use_r()写函数,插入roxygen注释和tag，使用document()生成文档
# usr_data() 添加内置数据
load_all()载入包
use_***_license 添加license
# install安装包
# use_testthat() 和use_test()生成测试文件；test()进行测试
check对整个包进行检查
use_readme_rmd()和build_readme()生成readme文件
build() 创建R包