总结一下目前学习的,基于Rstudio的创建R包流程。

Part1:创建R包基本流程

step1:建立开发环境

  • 目的是创建一个文件夹,用于储存编写R包的各种文档;在创建之前想 好R包的名字,以及文件夹的路径。
  • 这里示例R包名为newPackage
  • 进入Rstudio界面,依次点击File → New project → New Directory → R package,会出现如下界面,填写好R包名字,选择好开发包的工作目录(其它暂时都不用考虑);最后点击Creat Project即可。
  • 如上操作后,会进入新的工作环境,即R包开发环境;同时已经创建好R包开发所需的所必须的模板文档。主要包括4个部分:

(1)R 文件夹:用于存放R函数脚本的文件夹;里面有一个示例文件hello.R (2)man 文件夹:用于存放对应上述R函数的说明文档Rd文件的文件夹;里面有一个示例文件hello.Rd。 (3)DESCRIPTION:关于R包的说明文档。 (4)NAMESPACE:声明R包导出以供外部使用的函数以及R包从其他包导入的外部函数。

其中只有R函数脚本与DESCRIPTION需要我们细心准备外,其它可通过一些办法自动写入、更新。

step2:编写函数

  • 首先先删除R文件夹里的示例文件、整个man文件夹、NAMESPACE文件;

  • 2.2 然后在R文件夹内创建后缀名为.R的函数脚本,编写自定义的函数;

(1)如下在新创建的add.R脚本中,编写一个简单的加法函数。

(2) 然后鼠标放置在函数上(如上图),按Ctrl+Alt+Shift+R组合快捷键为函数添加说明文档模板(Insert Roxygen Skeleton)(下左);根据自己函数的功能完成注释(下右)

(3)测试编写的函数,有没有问题

1
2
3
4
5
#激活R文件夹内的所有函数,供测试使用
devtools::load_all()
# i Loading newPackage
add(1,6)
# [1] 7

重复上述1~3步骤,不断添加新的函数。可以是一个函数对应一个脚本,也可以将同一类的函数都放置在一个脚本内。 (4)为所有函数在man文件夹(如果没有,会创建)下逐一自动建立Rd文档,以及更新NAMESPCAE文档

1
2
3
4
5
6
7
# 重复上述1~3步骤,又创建了一个减法的函数脚本

devtools::document()
# i Updating newPackage documentation
# i Loading newPackage
# Writing NAMESPACE
# Writing NAMESPACE

step3:编写DESCRIPTION文件

函数写好了之后,就需要对这个包的总体功能等信息进行描述与说明,这些信息主要包含在DESCRIPTION文件中

  • 首先如下图所示,修改其中的四点说明:Title包的名字,Authors@RMaintainer作者以及维护者信息、Description包的简要描述
  • 然后使用下述函数,自动编写License部分
1
2
# 如果没有依赖到别的具有不同版权的第三方包的话,一般选择最为广泛使用的 MIT 即可
usethis::use_mit_license()

此外,如果版本有更新,可手动修改 Version部分

  • 之后再补充依赖包的信息。分为两类:Imports、Suggests、Depends。三者的区别还没完全清楚,暂时觉得还是第一个常用。

    • 可使用函数usethis::use_package(package, type = "Imports", min_version = NULL);

    • 假设其中的一个自定义的函数必须要用到dplyr包的filter()函数(因为实际中并未没有使用,之后会删去)

1
2
3
4
5
6
usethis::use_package("dplyr", type = "Imports",
                     min_version = "1.0")
# √ Adding 'dplyr' to Imports field in DESCRIPTION
# * Refer to functions with `dplyr::fun()`

# 在函数脚本中使用的过程调用其它包的函数时,必须按照`package::function`,如`dplyr::filter()`的形式调用。

  • 最后再check一下上述的所有文件,包括函数脚本,看看有没有问题

在R包不断完善的过程中,可以随时check一下,保证之前的修改没有什么问题

1
2
3
4
5
devtools::check()
# -- R CMD check results --------------------- newPackage 0.1.0 ----
#   Duration: 19s
# 
# 0 errors √ | 0 warnings √ | 0 notes √

step4:收尾工作–安装包

  • (1)将包安装到本地的电脑 点击Build → Install and restart,可将进行安装R,重启R,加载该包三个步骤。
  • (2)将包制成压缩包(*.tar.gz),方便传输或者分享 点击Build → Build Source Package
1
2
install.packages("path/to/newPackage_0.1.0.tar.gz", 
                 repos=NULL, type="source")

Part2:R包进阶操作

上面介绍了编写R包的最简单的流程,还有很多进阶知识点值得学习。下面总结其中三个方面的整理。

2.1 示例数据集

  • (1)存储为rdata格式并使其对用户可用

使用usethis::use_data()函数,将数据对象(字符串、表格)储存到data文件夹里的rdata文件。

1
2
3
4
5
6
7
8
9
x <- sample(1000)
usethis::use_data(x)
# √ Saving 'x' to 'data/x.rda'
# * Document your data (see 'https://r-pkgs.org/data.html'

dataframe = mtcars
usethis::use_data(dataframe)
# √ Saving 'dataframe' to 'data/dataframe.rda'
# * Document your data (see 'https://r-pkgs.org/data.html')

根据提示,需要在R文件夹下,创建内容框架如下的data.R说明文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
#' x
#'
#' Just test number(Description)
#'
#' @examples
#'   head(x)
"x"

#' dataframe
#'
#' Just test dataframe(Description)
#'
#' @examples
#'   head(dataframe)
"dataframe"
  • (2)储存为原始文件的形式(例如.csv,.xlsx等)

创建inst/extdata文件夹,用于储存这些文件即可

1
2
dir.create("inst/extdata", recursive = T)
write.csv(mtcars, file = "inst/extdata/example.csv")
  • (3)调用这些数据

document()check()一下;重新安装,加载

1
2
devtools::document()
devtools::check()

点击Build → Install and restart

调用示例数据

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
data(x)
?x
str(x)
# int [1:1000] 134 448 373 532 823 646 567 146 776 503 ...

data(dataframe)
dim(dataframe)
# [1] 32 11

system.file("extdata", "example.csv", 
            package = "newPackage")
# [1] "C:/Users/******/Documents/R/win-library/4.1/newPackage/extdata/example.csv"

2.2 代码整理

  • (1)代码美化
1
2
3
4
5
# 安装 {styler}
# install.packages("styler")

# 对整个包进行代码美化
styler::style_pkg()
  • (2)代码规范性检查
1
2
3
4
5
# 安装 {lintr}
# install.packages("lintr")

# 对整个包进行不符合规范的代码查询(当然,都没有写多少代码,当然不会出现什么错误结果)
lintr::lint_package()

2.3 上传github

在我理解,将个人创建的R包上传到github中,可以高效的实现版本的控制、备份以及与他人共享,自己的使用等

  • (1)上传至github

已经基本完成了R包的成形工作(Part1),或者刚建立好R包开发环境也可以。

下载安装 Github Desktop,并登陆自己的个人账户。

如下图,将R包开发环境目录关联到respository仓库内。

点击之后,一般会提示关联的R包开发环境目录不在Git的仓库列表中,点击creat a repository即可

最后再点击Publish respository,并设置是否code private即可成功上传到github。

  • (2)commit → push

之后对包的文档进行修改、更新等操作时,都可以通过Github Desktop进行方便的提交

如下,对包添加了一个函数:在Github Desktop左下角填写更改的描述、点击Commit to main,再push到github上。之后在github主页看到的就是更新后的版本。

  • (3)创建README文件
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# 引入必备包 {rmarkdown}
# install.packages("rmarkdown")

# 默认的 README.Rmd 模版就创建完
usethis::use_readme_rmd()

# 然后在README.Rmd文件中进行修改
# 最后Knit即可

# 最后再在Github Desktop里 commit→push即可再github页面创建美观的read.me文档

https://github.com/lishensuo


参考教程: 1、为新手准备的现代化 R 包开发流程 https://cosx.org/2021/02/writing-r-packages-a-modern-workflow-for-beginners/ 2、R包的开发 https://zhuanlan.zhihu.com/p/336425664 3、https://r-packages-zh-cn.readthedocs.io/zh_CN/latest/index.html


补充

  • (1) 在代码脚本中引入管道符 %>%
1
usethis::use_pipe() #在R中使用管道符
  • (2) 本地安装R包方式

    1
    2
    3
    4
    5
    6
    7
    
    ## 情况1
    install.packages("RJSONIO_0.2-3.tar.gz", repos = NULL, type="source")
    
    ## 情况2
    list.files("BayesPrism-main/BayesPrism/")
    # [1] "DESCRIPTION" "inst"        "man"         "NAMESPACE"   "R" 
    devtools::install_local("BayesPrism-main/BayesPrism/")