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

在前一章节，我们纤细的介绍了如何进行R包的制作（手把手教你制作R包（一））。接下来，我们详细来介绍每一部分。

1、创建包

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

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

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

注意：在开发的时候，工作路径最好是源码包的top-level

2、元数据

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

Package: toypackages
Title: What the Package Does (One Line, Title Case)
Version: 0.0.0.9000
Authors@R: 
    person(given = "First",
           family = "Last",
           role = c("aut", "cre"),
           email = "first.last@example.com",
           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
LazyData: true
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.1

详细内容如下

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

版本推荐的格式：

• released 版本由3个数字构成：\<major\>.\<minor\>.\<patch\>
• In-development 版本由4个数字构成，第四个是开发版本，从9000开始，所以包的第一个版本是0.0.0.9000

• Auther@R字段是作者的信息，是R代码：

Authors@R: 
    person(given = "First",
           family = "Last",
           role = c("aut", "cre"),
           email = "first.last@example.com",
           comment = c(ORCID = "YOUR-ORCID-ID"))

person函数有4个主要的参数：

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

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

Imports:
   pkgname
Suggests:
   pkgname

两者的区别：

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

3、函数文档化：man目录

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

基本的流程有4步：

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

# 创建add函数
use_r("add") 

# 添加roxygen2格式的注释
#' Add together two numbers
#' 
#' @param x A number.
#' @param y A number.
#' @return The sum of \code{x} and \code{y}.
#' @examples
#' add(1, 1)
#' add(10, 1)
add <- function(x, y) {
  x + y
}

# 创建 .Rd 文件：该文件自动在man目录下添加
devtools::document()

roxygen2格式的注释

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

文档化函数：添加参数注释
大部分函数有3个tag：@param, @examples, @return

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

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

4、数据文档化

有3个主要的方法可以在包中包含数据：

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

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

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

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

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

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