[R语言学习笔记] - Windows下使用Rstudio制作package教程

参考

Creating R Packages: A Tutorial https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf
https://community.rstudio.com/t/creating-an-r-package-with-function-sourcing-from-several-scripts/18499/2

创建package项目

1. 使用Rstudio创建package project。具体步骤如下：Rstudio File -> New Project -> New Directory -> R Package -> Create Project。
2. 项目建好后，基本目录及功能如下：
   • DESCRIPTION，package的基本信息，如package名，版本号，标题，作者，描述，编码，协议版本等。关键的就是package名与版本号。
   • xxx.Rproj工程配置文件。不用管。
   • NAMESPACE，命名空间。不用管。
   • man文件夹，存放R Document，即help内容。
   • R文件夹，存放R文件，最好不要有子目录，R对多层目录的文件调用并不友好，写法比较麻烦。如果没有特别需求，建议不要有多层目录。
3. 生成并安装该包。Build -> Clean and Rebuild。
4. 发布包。Build -> Build Source Package或者Build -> Build Binary Package。
5. 安装。Tools -> Install Packages -> (.zip; tar.gz) 。

.Rd说明

使用File -> New File -> R Documentation创建默认的.Rd文件。文件里对每个功能项都有注释说明，基本都能看得懂。重点说明几个。

1. \name，显示在帮助信息里的文档名，与.Rd的文件名可以不一致，与.R文件的文件名可以不一致，三者没有必然关系。
2. \alias，字面意思别名。这里需要填关联的函数名，这样加载package后，通过?functionname就可以关联到这个.Rd文档的信息。示例如下。f1，f2，f3三个函数使用？均可以访问到该.Rd文档内容。

\alias{
f1
f2
f2
}

3. \title，帮助文档的标题。一定要有内容。空值会导致编译失败。
4. \description，帮助文档描述，适合填写大量的文字内容。推荐。
5. \usage，用途。
6. \arguments，参数列表。说明参数的含义及使用方式。推荐。
7. \details，细节。
8. \examples，使用示例。推荐。

.R说明

遵守先定义后使用的规则。

1. 如果都是函数，不用很严格的遵守先定义后使用的规则。

# R/aardvark.R
aardvark <- function(x) {
  zebra(x)
}
# R/zebra.R
zebra <- function(x) {
  x + 1
}

When a package is built, every file in the R/ subdirectory is run, and then the objects they’ve created are part of the package. By default, you shouldn’t assume they’re run in a specific order. And usually, that’s fine. Let’s say we have a package with two .R files:
Even if aardvark.R is run before zebra.R, the package will build just fine. By the time anything calls the aardvark() function, zebra() has already been defined.

翻译与理解：
当一个package编译，里面的所有文件和子目录都被加载，它们成为了这个package的一部分。一般来说，不应认为它是按某种顺序加载这些.R文件，虽然实际上，它确实是按顺序加载，但不影响。就像上面的两个文件，他们两个的加载顺序并不影响到结果。
实际运行中，先加载了aardvark.R然后是zebra.R，虽然加载aardvark.R时，zebra()没有定义，但不会报错，它只是描述了这个调用关系。当实际使用aardvark()时，如果仍找不到/未加载zebra()才会真正的报错。

2. 如果因为特殊需求需要保持加载顺序（比如全局变量的定义需要在最开始完成初始化），则可以在文件名上下手。可以通过重命名文件，如加上0_，1_等前缀的方式将文件区分先后顺序。这样就能保证加载顺序，调用不会出现未定义的情况。

0_xx.R
0_xxx.R
0_ff.R
0_qq.R
1_www.R
1_aaa.R

3. 习惯用packagename::functionname的方式使用其他第三方package函数，这样才能保证代码的清晰准确。
4. R不是面向对象语言，命名空间的功能不足，所以尽可能的不要使用很多的.R文件，这样会给代码的管理带来负担。当然，如果所有内容都放在一个.R文件里，代码的可读性及分类可能就差一些。保持一个平衡即可。

其他

1. 如果编译失败，Build的窗口里的编译报错信息可以定位错误。
2. 在别的机器上安装，安装后要校对安装后的版本号正确。如果安装失败，先卸载之前的package，或者删除对应目录下的package文件夹，在重新安装。