總結(jié)一下目前學(xué)習(xí)的，基于Rstudio的創(chuàng)建R包流程。
Part1：創(chuàng)建R包基本流程
step1：建立R包開發(fā)環(huán)境
- 目的是創(chuàng)建一個文件夾，用于儲存編寫R包的各種文檔；在創(chuàng)建之前想 好R包的名字，以及文件夾的路徑。
- 這里示例R包名為
newPackage。 - 進入Rstudio界面，依次點擊
File → New project → New Directory → R package,會出現(xiàn)如下界面，填寫好R包名字，選擇好開發(fā)包的工作目錄（其它暫時都不用考慮）；最后點擊Creat Project即可。
-
如上操作后，會進入新的工作環(huán)境，即R包開發(fā)環(huán)境；同時已經(jīng)創(chuàng)建好R包開發(fā)所需的所必須的模板文檔。主要包括4個部分：
（1）R 文件夾：用于存放R函數(shù)腳本的文件夾；里面有一個示例文件hello.R
（2）man 文件夾：用于存放對應(yīng)上述R函數(shù)的說明文檔Rd文件的文件夾；里面有一個示例文件hello.Rd。
（3）DESCRIPTION：關(guān)于R包的說明文檔。
（4）NAMESPACE：聲明R包導(dǎo)出以供外部使用的函數(shù)以及R包從其他包導(dǎo)入的外部函數(shù)。
其中只有R函數(shù)腳本與DESCRIPTION需要我們細心準備外，其它可通過一些辦法自動寫入、更新。
step2：編寫函數(shù)
2.1 首先先刪除R文件夾里的示例文件、整個man文件夾、NAMESPACE文件；
2.2 然后在R文件夾內(nèi)創(chuàng)建后綴名為.R的函數(shù)腳本，編寫自定義的函數(shù)；
-
（1）如下在新創(chuàng)建的
add.R腳本中，編寫一個簡單的加法函數(shù)。
-
（2） 然后鼠標放置在函數(shù)上（如上圖），按
Ctrl+Alt+Shift+R組合快捷鍵為函數(shù)添加說明文檔模板（Insert Roxygen Skeleton）(下左)；根據(jù)自己函數(shù)的功能完成注釋(下右)
（3）測試編寫的函數(shù)，有沒有問題
#激活R文件夾內(nèi)的所有函數(shù)，供測試使用
devtools::load_all()
# i Loading newPackage
add(1,6)
# [1] 7
重復(fù)上述1~3步驟，不斷添加新的函數(shù)?？梢允且粋€函數(shù)對應(yīng)一個腳本，也可以將同一類的函數(shù)都放置在一個腳本內(nèi)。
- （4）為所有函數(shù)在man文件夾(如果沒有，會創(chuàng)建)下逐一自動建立Rd文檔，以及更新
NAMESPCAE文檔
# 重復(fù)上述1~3步驟，又創(chuàng)建了一個減法的函數(shù)腳本
devtools::document()
# i Updating newPackage documentation
# i Loading newPackage
# Writing NAMESPACE
# Writing NAMESPACE
step3：編寫DESCRIPTION文件
- 函數(shù)寫好了之后，就需要對這個包的總體功能等信息進行描述與說明，這些信息主要包含在
DESCRIPTION文件中
3.1 先如下圖所示，修改其中的四點說明：Title包的名字，Authors@R、Maintainer作者以及維護者信息、Description包的簡要描述
3.2 然后使用下述函數(shù)，自動編寫License部分
# 如果沒有依賴到別的具有不同版權(quán)的第三方包的話，一般選擇最為廣泛使用的 MIT 即可
usethis::use_mit_license()
此外，如果版本有更新，可手動修改 Version部分
3.3 之后再補充依賴包的信息。分為兩類：Imports、Suggests、Depends。
- 三者的區(qū)別還沒完全清楚，暫時覺得還是第一個常用。
- 可使用函數(shù)
usethis::use_package(package, type = "Imports", min_version = NULL); - 假設(shè)其中的一個自定義的函數(shù)必須要用到dplyr包的
filter()函數(shù)（因為實際中并未沒有使用，之后會刪去）
usethis::use_package("dplyr", type = "Imports",
min_version = "1.0")
# √ Adding 'dplyr' to Imports field in DESCRIPTION
# * Refer to functions with `dplyr::fun()`
# 在函數(shù)腳本中使用的過程調(diào)用其它包的函數(shù)時，必須按照`package::function`，如`dplyr::filter()`的形式調(diào)用。
如上，DESCRIPTION最基本的信息就填寫好了。
3.4 最后再check一下上述的所有文件，包括函數(shù)腳本，看看有沒有問題
- 在R包不斷完善的過程中，可以隨時
check一下，保證之前的修改沒有什么問題
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
install.packages("path/to/newPackage_0.1.0.tar.gz",
repos=NULL, type="source")
Part2：R包進階操作
上面介紹了編寫R包的最簡單的流程，還有很多進階知識點值得學(xué)習(xí)。下面總結(jié)其中三個方面的整理。
2.1 添加示例數(shù)據(jù)集
（1）存儲為rdata格式并使其對用戶可用
- 使用
usethis::use_data()函數(shù)，將數(shù)據(jù)對象（字符串、表格）儲存到data文件夾里的rdata文件。
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')
- 根據(jù)提示，需要在R文件夾下，創(chuàng)建內(nèi)容框架如下的
data.R說明文件
#' x
#'
#' Just test number(Description)
#'
#' @examples
#' head(x)
"x"
#' dataframe
#'
#' Just test dataframe(Description)
#'
#' @examples
#' head(dataframe)
"dataframe"
（2）儲存為原始文件的形式（例如.csv，.xlsx等）
- 創(chuàng)建
inst/extdata文件夾，用于儲存這些文件即可
dir.create("inst/extdata", recursive = T)
write.csv(mtcars, file = "inst/extdata/example.csv")
（3）調(diào)用這些數(shù)據(jù)
- 先
document()、check()一下；重新安裝，加載
devtools::document()
devtools::check()
點擊Build → Install and restart
- 調(diào)用示例數(shù)據(jù)
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）代碼美化
# 安裝 {styler}
# install.packages("styler")
# 對整個包進行代碼美化
styler::style_pkg()
（2）代碼規(guī)范性檢查
# 安裝 {lintr}
# install.packages("lintr")
# 對整個包進行不符合規(guī)范的代碼查詢（當然，都沒有寫多少代碼，當然不會出現(xiàn)什么錯誤結(jié)果）
lintr::lint_package()
2.3 上傳github以及后續(xù)相關(guān)操作(☆)
在我理解，將個人創(chuàng)建的R包上傳到github中，可以高效的實現(xiàn)版本的控制、備份以及與他人共享，自己的使用等
（1）上傳至github
- 已經(jīng)基本完成了R包的成形工作（Part1），或者剛建立好R包開發(fā)環(huán)境也可以。
- 下載安裝 Github Desktop，并登陸自己的個人賬戶。
- 如下圖，將R包開發(fā)環(huán)境目錄關(guān)聯(lián)到respository倉庫內(nèi)。
點擊之后，一般會提示關(guān)聯(lián)的R包開發(fā)環(huán)境目錄不在Git的倉庫列表中，點擊
creat a repository即可
最后再點擊
Publish respository，并設(shè)置是否code private即可成功上傳到github。
（2）commit → push
- 之后對包的文檔進行修改、更新等操作時，都可以通過Github Desktop進行方便的提交
-
如下，對包添加了一個函數(shù)：在Github Desktop左下角填寫更改的描述、點擊Commit to main，再push到github上。之后在github主頁看到的就是更新后的版本。
（3）創(chuàng)建README文件
# 引入必備包 {rmarkdown}
# install.packages("rmarkdown")
# 默認的 README.Rmd 模版就創(chuàng)建完
usethis::use_readme_rmd()
# 然后在README.Rmd文件中進行修改
# 最后Knit即可
# 最后再在Github Desktop里 commit→push即可再github頁面創(chuàng)建美觀的read.me文檔
參考教程：
1、為新手準備的現(xiàn)代化 R 包開發(fā)流程 https://cosx.org/2021/02/writing-r-packages-a-modern-workflow-for-beginners/
2、R包的開發(fā) https://zhuanlan.zhihu.com/p/336425664
3、https://r-packages-zh-cn.readthedocs.io/zh_CN/latest/index.html
補充
- (1) 在代碼腳本中引入管道符
%>%
usethis::use_pipe() #在R中使用管道符
