R包简单教程

R包概述

R包是什么

R包，类似C、Python中库的概念，指包含特定领域的函数、数据、文档等的集合。通过调用包，可以直接使用包中现成的数据、函数等，使开发方便快捷高效。

为什么学习R包

• R的强大在于包含了各种各样的包，使用包非常有利于便捷开发。
• 一些功能在现有的包中并不存在，需要自己实现，实现后通过打包方便代码的复用。
• 每个包涵括一个领域相关的函数数据文档等，通过包可以有效地组织代码结构，有利于开发。

R包的结构

创建R包后，在包的根目录下，一般包含以下几个部分（粗体表示必需）：

• R/： R函数目录，包含包中定义的函数。
• DESCRIPTION：包的描述，包括包名、作者、依赖等。
• NAMESPACE：名称空间。
• man/： R函数手册目录，包含了包中定义函数的手册。
• vignettes/： R项目目录，包含了本项目的使用指导。
• tests/： R函数测试目录，包含了包中定义函数的测试及包功能的测试。
• data/： 包中附带的数据文件。

R包的工作流程

为了有效利用R包，一般遵循以下的工作流程：

1. 指定名字，创建R包，并编写DESCRIPTION文件，对R包进行简单的描述。
2. 如有必要，在data/中添加数据文件。
3. 在R/中编写对应功能的R文件
4. 编写好R文件后，生成R文档。
5. 在tests/中编写R文件的测试文件。
6. 在vignettes/中编写项目的说明文档。
7. 生成R包与发布。

下面，将以一个HelloWorld的例子，沿着上述工作流程，开发R包。

R包的创建

预先准备

安装R包，需要执行以下代码：

install.packages(c("devtools", "roxygen2", "testthat", "knitr"))
install.packages("rstudioapi")
rstudioapi::isAvailable("0.99.149")
devtools::install_github("hadley/devtools")

同时，还需要C编译器以及一些命令行工具，建议使用和RStudio，其会自动安装相关程序。
准备完毕，使用下面代码进行验证，返回为TRUE即成功。

library(devtools)
[1] TRUE

包的创建

首先，确定包的名字与工作路径，然后通过下述指令创建包hello：

# 确定路径为E:/Github/
# 确定名字为hello
devtools::create('E:/Github/hello')

然后生成文档结构如下：

hello:.
    │  .gitignore
    │  .Rbuildignore
    │  DESCRIPTION
    │  hello.Rproj
    │  NAMESPACE
    │
    └─R

DESCRIPTION的编写

打开DESCRIPTION文件，按照里面的要求编写即可，这里我们把Title改成HelloWorld，把Version改成0.1，修改后的文件如下：

Package: hello
Title: HelloWorld
Version: 0.1
Authors@R: person("First", "Last", email = "first.last@example.com", role = c("aut", "cre"))
Description: What the package does (one paragraph).
Depends: R (>= 3.3.1)
License: What license is it under?
Encoding: UTF-8
LazyData: true

数据文件

一般来说，为了复用性与测试，需要包中包含一些测试文件。
添加数据文件的方法如下，先生成数据文件，然后通过use_data函数添加到hello库中，这样当加载库的时候，相应的数据文件也被加载进来了，可以直接使用。

countries = c('CHINA','USA')
devtools::use_data(countries, hello)

R函数

每个包的目的都是完成特定的功能。为了完成特定的功能，需要编写R函数。这里，我们编写R函数如下，其功能是读取countries数据，并且打印形如hello countries的字符串：

hello_country <- function(countries) {
    hellos = paste('Hello',countries)
    for (i in hellos ){
        print(i)
    }
}

通过在包中编写R函数，以后每次需要包中函数的时候，直接载入包就可以了，方便快捷。

R文档

对于每个R函数，需要编写R文档，包含R函数的功能、调用、使用方法等。 R文档的编写方式如下：

#' Hello Country

#' @param countries string vertices countaining countries.
#' @examples
#' hello_country(countries)
#' @export
hello_country <- function(countries) {
    hellos = paste('Hello',countries)
    for (i in hellos ){
        print(i)
    }
}

其中，第一行是标题，@param后面是输入参数，@examples后面是例子，@export表示该函数可以被外部调用。

编写完成后，执行devtools::document()即可生成文档，生成的文档在\man目录下，此例中生成了hello_country.Rd文件。
重新建立包，执行?hello_country即可预览生成的R文档。

测试R文件

每个R函数编写完成后，需要对其进行测试，测试的文件放在\test文件夹下。
本例的测试文件为：

hello_country(countries)

其会输出：

[1] "Hello CHINA"
[1] "Hello USA"

项目文档

每个项目需要有一个完整的说明文档。生成文档的方法如下：

devtools::use_vignette("hello-tutorial")

生成文档后，使用rmarkdown的语法进行编写如下：

---
title: "Hello_Tutorial"
output: html_document
---

This is a simple illstration of hello package. It only contains one main functin which is `hello_country` and one dataset `countries`.

The use of this funciton is:

 ```{r}
library(hello)
hello_country(countries)
 ```

生成

建议使用RStudio，生成包只需要点击Build标签页中的Build and Reload即可。

同样的，使用devtools::build()亦可。

参考资料

1. R packages