R包开发过程记录

目的

走一遍R包开发过程，并发布到Github上使用。

步骤

1. 创建R包框架

Rsutdio ——> File——> New Project——> New Directory ——> R Package

image.png

创建完成后，在R包文件夹下有如下文件（夹）：

man：存放*.Rd文件
R：存放R脚本
DESCRIPTION： R包描述信息
NAMESPACE：命令空间
rmytools.Rproj： R工程文件

image.png

2. 自定义R包

上面是Rstudio为开发者创建的一个框架，接下来是对自己开发的R包进行编写和注解。

①编写功能函数
点击Rstudio右下角Files中的R目录新建R函数（自带了一个hello.R）。要实现什么样的功能就编写相应函数，函数功能的组织和构建也是开发者重要的技能之一。这里作为示例，随便写了个画饼图的函数（因为现有画饼图的函数都不友好）。

my_pie <- function(data,ncol){
  plotdat <- as.data.frame(table(data[,ncol])) %>% dplyr::arrange(-Freq)
  plotdat$Label <- paste(plotdat$Var1, paste0("(",round(((plotdat$Freq/sum(plotdat$Freq))*100),2),"%)"))

  p <- ggplot(plotdat, aes (x="", y = Freq, fill = factor(Var1))) +
        geom_col(position = 'stack', width = 1) +
        geom_text_repel(aes(label = Label, x = 1.3),size=5,
                        position = position_stack(vjust = 0.5)) +
        theme_classic() +
        theme(plot.title = element_text(hjust=0.5),
              axis.line = element_blank(),
              axis.text = element_blank(),
              axis.ticks = element_blank()) +
        labs(fill = "Category",x = NULL,y = NULL) +
        coord_polar("y")
}

与一般的函数编写不同的是，我们需要对这个函数编写文档，这就是为什么我们在用R包中函数时可用?来查看函数帮助。

编写完成后。。。

第一步，给函数添加注释，这里是对函数整体进行roxygen注释，方便文档生成，而非普通代码注释。光标放在函数名上，使用Ctrl+Shift+Alt+R快捷键即可生成一个基本模板，我们根据需要进行相应修改即可。

#' Using a dataframe specific column to plot a pie figure
#'
#' @param data a dataframe or tibble
#' @param ncol specific column, factor
#'
#' @return a figure as ggplot2 object
#' @export
#'
#' @examples
#' my_pie(mtcars,ncol=2)
#' my_pie(diamonds,ncol=3)
#' my_pie(diamonds,ncol=3)+guides(fill="none")
#'
my_pie <- function(data,ncol){
  plotdat <- as.data.frame(table(data[,ncol])) %>% dplyr::arrange(-Freq)
  plotdat$Label <- paste(plotdat$Var1, paste0("(",round(((plotdat$Freq/sum(plotdat$Freq))*100),2),"%)"))

  p <- ggplot(plotdat, aes (x="", y = Freq, fill = factor(Var1))) +
        geom_col(position = 'stack', width = 1) +
        geom_text_repel(aes(label = Label, x = 1.3),size=5,
                        position = position_stack(vjust = 0.5)) +
        theme_classic() +
        theme(plot.title = element_text(hjust=0.5),
              axis.line = element_blank(),
              axis.text = element_blank(),
              axis.ticks = element_blank()) +
        labs(fill = "Category",x = NULL,y = NULL) +
        coord_polar("y")
}

第二步，运行devtools::document()，会在man文件夹下生成该函数的Rd文件：

image.png

如果修改了函数的注释，需要重新执行第二步。

每个函数都是这样添加注释和文档，比如再添加一个ID转换的函数：

image.png

②修改DESCRIPTION
点击右下角Files中的DESCRIPTION对模块进行修改。

image.png

添加一些主要的信息即可：

Package: 包名
Description: 描述信息
Depends: 依赖R版本（要注意空格，否则后续会报错）
Suggest：建议包，非必需
Imports：依赖包（这里编写的函数依赖了图中5个R包）
License：协议

③安装R包
Rstudio ——> Build，可构建源码包或者二进制包。

image.png

点击后会进行编译以及更新文档。

image.png

使用?my_pie等编写的函数，已经可以查看文档了，说明编译成功，已经可以使用R包了。

image.png

3. 上传Github

如果只是自己使用，可以放在本地。本着R语言开源精神，要想分享给其他人使用，需要有地方托管。权威认可的地方如CRAN、Bioconductor等，但如果专业度不够高或者处于开发阶段，还是托管在Github上吧。

从本地仓库上传到Github远程仓库，与一般代码上传无异。

首先，进入本地R包目录。

git init
git add .
git commit -m 'my first r package'

然后，登录Github新建Repository（建议用SSH地址，尽量不要用HTTPS地址）。

image.png

第三，本地仓库关联GitHub，上传代码。

git remote add origin git@github.com:***/test.git
git pull origin master #先pull下
git push -u origin master

有个小插曲，我在pull的过程中，遇到了如下错误：

image.png

原因是SSH keys没有设置或者过期了，SSH keys 可以在没有密码的情况下信任当前工作的计算机。解决办法是生成并设置SSH keys。具体可参考这篇教程：解决github Permission denied (publickey)问题。

上传成功。

image.png

4. 安装使用

devtools工具为我们提供了Github的R包安装方式：

devtools::install_github("**/my_rpackage/rmytools")
library(rmytools)

用内置数据集试下：

my_pie(mtcars,2)
my_pie(diamonds,ncol=3)
my_pie(diamonds,ncol=3)+guides(fill="none")  #ggplot2对象，自由编辑

image.png

用R包来管理组织自己平时经常用的代码是一种非常高效的方式，后续想添加任何功能或修改原有脚本，只需git push，重新装一下R包即可。是时候整理整理之前混乱的代码了（俗称屎山）。

Ref：
Kai Gu：如何快速写一个R包
 如何上传本地代码到github