【冰糖R语言】创建R包（打包R程序）

目标：将现有R程序打包

可能涉及知识点：devtools包、usethis包、Rstudio软件

一、R包的类型

通常一个R包中包含以下元素：

1）R文件夹：函数代码

2）man文件夹：存放每个函数的注释文件

3）DESCRIPTION文件：描述文件，描述该包的相关信息，包括名称、开发者等

4）NAMESPACE文件：命名空间文件，描述该包与其他包的依赖关系，比如用到了其他包的函数

5）LICENSE文件：许可证文件

通常，使用的R包通常分为Source Package和Binary Package两种：

Source Package：源代码包，可跨平台使用，安装时有编译步骤

Binary Package：二进制代码包，不同平台不通用，安装时无编译步骤

两者解压后的文件不同，比如R文件夹下的内容，Source Package的R文件夹包含源码R文件，Binary Package的R文件夹下是解析后的文件。两者安装后，函数功能不会有差异。

二、devtools包

devtools包是一款用于R包开发的工具。其功能包括创建、更新、安装、检查等。

详见官网：Tools to Make Developing R Packages Easier • devtools

常用函数：

devtools::load_all()：模拟安装和加载R文件夹中的所有函数，默认路径为当前文件夹

devtools::document()：更新man文件夹的注释，以及‘NAMESPACE’文件

devtools::check()：在本地检查和构建包，输出可能存在问题

devtools::install_github()：从github安装包

三、usethis包

usethis包是一个工作流包，用于自动化处理项目设置和开发过程中出现的重复任务（R包或者非R包项目），在创建R包时常与devtools一起使用。

详见官网：Automate Package and Project Setup • usethis

常用函数：

usethis::create_package()：创建一个R包，生成R文件夹、DESCRIPTION文件等内容

usethis::use_mit_license()：使用MIT的许可证，会更新DESCRIPTION文件中的许可证信息

四、Rstudio软件生成包

Rstudio可通过一系列操作完成devtools和usethis的工作，比如构建包时便调用了devtools::build()

步骤：

1、新建Rstudio项目-“R Package”，填写包名称、工程文件夹路径，此步骤会在指定目录下生成R包的相关要素，包括R文件夹、man文件夹、DESCRIPTION文件等，以及工程文件.Rproj等。

2、在DESCRIPTION文件中添加该包的相关信息，包括包名称、开发者等。

其中许可证License可使用usethis添加，比如usethis::use_mit_license()。依赖项Imports可使用usethis::use_package()添加，此处引用了e1071和pROC两个包。

3、在R文件夹中添加R脚本文件，其中放入定义的函数，这些函数可放在一个或者多个R文件中。默认生成该文件夹时会自带一个示例R文件，删去即可。

4、在每个定义的函数内插入注释，补充函数说明信息。具体地，将光标放在某个函数内，在Rstudio工具栏中“Code”-“Insert Roxygen Skeleton”，会在该函数前生成注释字段，需要手动输入方法名称、参数含义等内容。

下图给出一个定义的读取数据文件的函数的说明：

Title 处填写函数名称，之后可填写函数相关描述。

@param 字段后自动给出参数变量名，可在其后添加参数说明，此处一个参数fileName

@return 字段后添加函数返回内容说明

@export 字段使得该函数可被外部调用

@importFrom 字段后标明此函数中引用关系，比如此处使用了utils包中的read.csv函数

@example 字段后可添加一个该函数的使用示例，需定义有意义的变量，而不是文本说明

此段说明内容对应于使用help查看该函数的说明文档时获得的内容。

5、执行devtools::document()更新函数文档，会在man文件夹下为每个函数生成Rd文件，即为上一步为每个函数添加的函数说明。同时会更新NAMESPACE文件，函数注释中@export 字段和@importFrom 字段的内容都会出现在NAMESPACE文件中。

6、执行devtools::check()对包进行检查。会显示详细的errors、warnings、notes信息，可根据这些信息进行修改。

7、点击Rstudio工具栏“Build”-“Build Source Package”或“Build Binary Package”构建不同类型的R包，即在本地生成对应压缩包。

8、进一步地，可使用devtools::build_manual()生成参考手册。前提是系统中有pdflatex，可通过安装tex发行版本MiKTeX实现。安装MiKTeX后，重新打开R包工程，重新check。可能会提示“!pdfTeX error: pdflatex.EXE (file t1-zi4r-0): Font t1-zi4r-0 at 600 not found”，此时以管理员身份运行cmd，执行命令“initexmf –-mkmaps”重建映射，重新check正常（实际并没有单独安装该字体）。执行devtools::build_manual()即可。