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

在前一章节&＃xff0c;我们纤细的介绍了如何进行R包的制作&＃xff08;手把手教你制作R包&＃xff08;一&＃xff09;&＃xff09;。接下来&＃xff0c;我们详细来介绍每一部分。

1、创建包

• 包的名称只能包含字母数字和点号(不建议使用点号&＃xff0c;可能会和文件拓展名或者S3方法混淆)&＃xff1b;
• 包的名称必须以字母开头并且不能以点号结尾
• 创建包使用usethis::create_package(path)函数

如何将之前已经存在的源码包文件夹转化成一个Rstudio项目&＃xff1a;

• File > New Project > Existing Directory
• 使用create_package()参数是已经存在的目录
• 使用usethis::use_rstudio() 在已经存在的源码包目录内部使用

注意&＃xff1a;在开发的时候&＃xff0c;工作路径最好是源码包的top-level

2、元数据

元数据一般保存在DESCRIPTION文件中。其中&＃xff0c;Rstudio和devtools将含有该文件的目录就认为是包目录。
DESCRIPTION的初始化内容为&＃xff1a;

Package: toypackages
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors&＃64;R: person(given &＃61; "First",family &＃61; "Last",role &＃61; c("aut", "cre"),email &＃61; "first.last&＃64;example.com",comment &＃61; c(ORCID &＃61; "YOUR-ORCID-ID"))
Description: What the package does (one paragraph).
License: &＃96;use_mit_license()&＃96;, &＃96;use_gpl3_license()&＃96; or friends topick a license
Encoding: UTF-8
LazyData: true
Roxygen: list(markdown &＃61; TRUE)
RoxygenNote: 7.1.1


详细内容如下

• DESCRIPTION文件的格式为DCF (Debian contral format)&＃xff1b;每一行都有一个filed名称和值&＃xff0c;两者用冒号分开&＃xff1b;当值有多行的时候需要缩进
• Title字段一般比较短&＃xff0c;只显示65个字符
• Version表示版本号&＃xff0c;版本号最少要有2个整数中间用点号或者横线隔开

版本推荐的格式&＃xff1a;

• released 版本由3个数字构成&＃xff1a;\.\.\
• In-development 版本由4个数字构成&＃xff0c;第四个是开发版本&＃xff0c;从9000开始&＃xff0c;所以包的第一个版本是0.0.0.9000

• Auther&＃64;R字段是作者的信息&＃xff0c;是R代码&＃xff1a;

Authors&＃64;R: person(given &＃61; "First",family &＃61; "Last",role &＃61; c("aut", "cre"),email &＃61; "first.last&＃64;example.com",comment &＃61; c(ORCID &＃61; "YOUR-ORCID-ID"))


person函数有4个主要的参数&＃xff1a;

• 作者名&＃xff1a;given在前(名)&＃xff0c;family在后(姓)
• email地址
• role有四个&＃xff1a;
  1. cre creator or maintainer 有问题时应该联系的维护者
  2. aut 对包贡献最大的人
  3. ctb 贡献者
  4. cph&＃xff1a;copyright holder 如果版权是作者以外的人或机构&＃xff0c;要注明

• Description&＃xff1a;是对包的描述&＃xff0c;每行不超过80个字符&＃xff0c;第二行使用4个空格分开
• license &＃xff1a;可以是开源许可&＃xff1a;MIT、GPL-2/GPL-3、CC0
• 添加依赖依赖包&＃xff1a;描述依赖用的是Imports和Suggests

Imports:pkgname
Suggests:pkgname


两者的区别&＃xff1a;

• Imports描述的是包工作所必需的包&＃xff0c;在我们的包被安装的时候&＃xff0c;如果这些包之前没有被安装&＃xff0c;这个时候会被安装
• Suggests不是必需安装的&＃xff0c;可能在示例数据&＃xff0c;运行测试&＃xff0c;创建vignettes或者包里面只有少量函数使用这些包&＃xff0c;所以我们要在需要这些包的函数里面检查这些包是否安装
• use_package(package, type &＃61; "Imports", min_version &＃61; NULL)&＃xff1a;type参数指定是Imports还是Suggests&＃xff0c;min_version参数指定包的最低版本

3、函数文档化&＃xff1a;man目录

标准方法是在man/文件夹下写.Rd文件&＃xff0c;再渲染成&＃96;&＃96;HTML和PDF&＃xff1b;但是可以使用roxygen2将R-code中特定格式的注释转化成.Rd文件&＃xff0c;roxygen2除了生成.Rd文件外还可以更改NAMESPACE和DESVRIPTION中的Collate字段。

基本的流程有4步&＃xff1a;

• 将roxygen格式的注释添加到.R文件中
• 使用devtools::document()(或者使用快捷键&＃xff1a;Ctrl/Cmd &＃43; Shift &＃43; D)将注释转化成.Rd文件
• 使用?预览文档
• 修改&＃xff0c;直到满意

# 创建add函数
use_r("add") # 添加roxygen2格式的注释
#&＃39; Add together two numbers
#&＃39;
#&＃39; &＃64;param x A number.
#&＃39; &＃64;param y A number.
#&＃39; &＃64;return The sum of \code{x} and \code{y}.
#&＃39; &＃64;examples
#&＃39; add(1, 1)
#&＃39; add(10, 1)
add <- function(x, y) {x &＃43; y
}# 创建 .Rd 文件&＃xff1a;该文件自动在man目录下添加
devtools::document()


roxygen2格式的注释

• Roxygen注释以#&＃39;开头&＃xff0c;并且在函数的前面&＃xff1b;每一行不超过80个字符
• 一般采用三段式&＃xff1a;该部分会被特殊解释&＃xff08;只需要保持三段式即可&＃xff09;
  1. 标题&＃xff08;&＃64;title&＃xff09;&＃xff0c;在注释中属于第一段&＃xff08;或者第一句&＃xff09;
  2. 描述&＃xff08;&＃64;description&＃xff09;&＃xff0c;在注释中属于第二段
  3. 详细信息&＃xff08;&＃64;detail&＃xff09;&＃xff0c;在注释中属于第三段
• 可插入其他内容&＃xff1a;
  1. web资源&＃xff1a;\url{https://www.r-project.org}
  2. 包中的内容&＃xff1a;\code{\link{functioname}}
  3. 其他包中的内容&＃xff1a;\code{\link[packagename]{functioname}}

文档化函数&＃xff1a;添加参数注释
大部分函数有3个tag&＃xff1a;&＃64;param, &＃64;examples, &＃64;return

• &＃64;param name description
  1. &＃64;param参数后面接参数的名称和描述&＃xff1b;
  2. 描述必须以大写字母开头&＃xff0c;点号结尾&＃xff0c;可以是多行甚至多段&＃xff1b;
  3. 可以同时对多个参数进行说明&＃xff0c;用逗号隔开如:&＃64;param x,y Numeric vectors.
• &＃64;examples 提供如何使用这个函数的R代码
  1. 可以使用\dontrun{}来包含会报错的代码&＃xff1b;
  2. 可以将示例放到另外的文件夹中&＃xff0c;并使用&＃64;example path/relative/to/package/root来插入&＃xff0c;注意这种用法是&＃64;example没有s
• &＃64;return description 对输出的描述
  示例

#&＃39; Sum of vector elements
#&＃39;
#&＃39; \code{sum} returns the sum of all the values present in its arguments.
#&＃39;
#&＃39; This is a generic function: methods can be defined for it directly
#&＃39; or via the \code{\link{Summary}} group generic. For this to work properly,
#&＃39; the arguments \code{...} should be unnamed, and dispatch is on the
#&＃39; first argument.
#&＃39;
#&＃39; &＃64;param ... Numeric, complex, or logical vectors.
#&＃39; &＃64;param na.rm A logical scalar. Should missing values (including NaN)
#&＃39; be removed?
#&＃39; &＃64;return If all inputs are integer and logical, then the output
#&＃39; will be an integer. If integer overflow
#&＃39; \url{https://en.wikipedia.org/wiki/Integer_overflow} occurs, the output
#&＃39; will be NA with a warning. Otherwise it will be a length-one numeric or
#&＃39; complex vector.
#&＃39;
#&＃39; Zero-length vectors have sum 0 by definition. See
#&＃39; \url{https://en.wikipedia.org/wiki/Empty_sum} for more details.
#&＃39; &＃64;examples
#&＃39; sum(1:10)
#&＃39; sum(1:5, 6:10)
#&＃39; sum(F, F, F, T, T)
#&＃39;
#&＃39; sum(.Machine$integer.max, 1L)
#&＃39; sum(.Machine$integer.max, 1)
#&＃39;
#&＃39; \dontrun{
#&＃39; sum("a")
#&＃39; }
sum <- function(..., na.rm &＃61; TRUE) {}


4、数据文档化

有3个主要的方法可以在包中包含数据&＃xff1a;

• 如果想要在包中包含二进制数据&＃xff0c;并且可以被用户使用&＃xff0c;将这些数据放在data/文件夹中&＃xff0c;这是放示例数据的最好的地方
• 如果想要包含解析后的数据&＃xff0c;并且用户不可以使用&＃xff0c;将这些数据放到R/sysdata.rda&＃xff0c;这些数据可以是函数运行所需要的
• 如果想要存储原始数据&＃xff0c;可以放到inst/extdata里面

创建数据
data/文件夹中应该是.Rdata格式&＃xff0c;含有单个对象&＃xff0c;并且名字和文件名是一样的&＃xff0c;可以使用usthis::use_data()来创建

> x <- sample(1000)
> usethis::use_data(x, mtcars)
✓ Adding &＃39;R&＃39; to Depends field in DESCRIPTION
✓ Creating &＃39;data/&＃39;
✓ Saving &＃39;x&＃39;, &＃39;mtcars&＃39; to &＃39;data/x.rda&＃39;, &＃39;data/mtcars.rda&＃39;
● Document your data (see &＃39;https://r-pkgs.org/data.html&＃39;)


数据文档化
对这些数据进行docment的时候&＃xff0c;是对这些数据的名称进行说明&＃xff0c;并存放到R/目录下的data.R文件中&＃xff0c;比如在ggplot2包中对diamonds数据的说明存放在R/data.R中&＃xff1a;
对数据进行document有额外的两个tag:

1. &＃64;format 是对数据的overview&＃xff0c;包含对每个变量的说明
2. &＃64;source 是对数据来源的说明&＃xff0c;通常是网址\url{}

#&＃39; Prices of 50,000 round cut diamonds.
#&＃39;
#&＃39; A dataset containing the prices and other attributes of almost 54,000
#&＃39; diamonds.
#&＃39;
#&＃39; &＃64;format A data frame with 53940 rows and 10 variables:
#&＃39; \describe{
#&＃39; \item{price}{price, in US dollars}
#&＃39; \item{carat}{weight of the diamond, in carats}
#&＃39; ...
#&＃39; }
#&＃39; &＃64;source \url{http://www.diamondse.info/}
"diamonds"