目标:将现有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()即可。