R package, 中文是 R 包. R 包是一种包装 R 代码, 数据和文档的方式. R 包是 R 语言强大的扩展性和灵活性的基础, R 发行版本身就包括三十多个高质量的 R 包.
使用已经安装的包
R 发行版中的包已经有强大的功能, 仅仅使用 R 发行版中的包已经可以干几乎所有 R 能干的事情. 但是在打开一个 R 实例的时候, 并不是所有想用的包都包括在其中了. 想要方便地使用已经安装的包, 则需要先加载包.
加载包分别可以用 library 函数和 require 函数.
library 函数和 require 函数都可以接受在 lib.loc 所指明的 library 路径中的 R 包的名字,
并把 R 包的命名空间加载到 R 的搜索路径中去.
两者的不同在于, library 函数会直接加载 R 包, 而不管 R 包本身是否已经加载,
而 require 函数则会在 R 包没有加载的时候加载而在已经加载 R 包的时候不加载.
另外, 如果加载成功, library 函数会返回已经加载到搜索路径的的 R 包的名称, 而 require 函数则返回 TRUE;
如果加载失败 library 函数会返回错误, 而 require 函数则返回 FALSE.
可以用参数 lib.loc 来指定特定的 R 包搜索路径.
如果 library 的 R 包名称的参数为空, 则返回所有在 R library 搜索路径上的 R 包的名称.
library("whatever")
library("whatever", lib.loc = "~/Rlib")
require("whatever")
有的包在加载的时候会显示很多信息, 可以使用 suppressPackageStartupMessages 函数来抑制这些信息的输出.
suppressPackageStartupMessages(library("whatever"))
还需要提及的是如何从 R 的搜索路径移去已经加载的 R 包.
可以使用 search 函数, 其会列出现在已经加载的包, 名字为 "package:" 加上包的名称.
如果想要移去某个包, 则可以使用 detach 函数, detach("package:whatever").
安装已经有的包
很多时候需要借用别人写好并发布在 CRAN 上的 R 包,
但是如果本地电脑上没有安装的话, 则需要先安装 R 包才能使用.
安装 CRAN 上的包, 需要使用 install.packages 函数.
install.packages 函数接受需要安装的包的名字作为参赛, 可以是一个, 或者多个的字向量.
R 包的结构
一个 R 包的源代码 (source) 文件夹中有两个文件和若干子文件夹. 文件包括 DESCRIPTION 和 NAMESPACE 分别描述包的信息和命名空间的信息, 有的时候还会有其他文件, 如描述 R 包更新的 NEWS, ChangeLog, 描述协议的 LICENSE 或 LICENCE, INDEX, configure, cleanup 等. 若干子文件夹包含其他文件, 包括 R, data, demo, exec, inst, man, po, src, tests, tools 和 vignettes 等文件夹 (这些文件夹有的是可以没有或空的, 有的必须要有并且不为空, 不同的包不同). 除了这些文件和文件夹之外, 源代码文件夹中也可以放其他的文件或文件夹, 但是这些自行添加的文件或文件夹会被 R 忽略.
利用 devtools 开发 R 包
一个 R 包包括复杂的结构, 纯粹手写会很繁琐, 可以利用 devtools 包来帮助开发 R 包. devtools 包会调用 roxygen2 包, roxygen2 可以把根据特殊语法写在 R 代码文件中的信息转化为 R 函数的 man 文件.
加载包
如果已经开发好一个包, 想要做一下测试使用, 可以使用函数 load_all 函数, 加载 R 包中的函数.
例如, 正在开发的 R 包的地址为 path/to/package:
> load_all('path/to/package')
加载包后, 相应的帮助文档也会被加载.
如果不是利用 R 函数生成的 R 包的框架的话, 在加载包之前, 应该先查看包的相关文件是否存在. 在包的目录中应该包含 DESCRIPTION 文档, 其中说明了包的基本信息.
例如:
Package: enrich
Title: Gene list enrichment on KEGG pathway, GO term, Transcript Factor Targets
and so on.
Description:
Version: 0.1
Author: Wolfson Liu <wolfsonliu@gmail.com>
Maintainer: Wolfson Liu <wolfsonliu@gmail.com>
License: LGPL-3
URL:
Imports:
memoise,
utils,
methods
RoxygenNote: 5.0.1
生成文档
如果想要自动生成 R 帮助文档, 可以使用 document 函数, 该函数调用 roxygen2 包生成 R 帮助文档.
> document('path/to/package')
生成的文档会保存在 R 包目录下面的 man 文件夹中.
文档是通过 roxygen2 来生成的, 其支持特定的语法.
测试包
如果在 test 文件夹中有相应的测试文件的话, 可以使用 test 函数来运行测试文件.
> test('path/to/package')
test 函数会调用 R 包目录下的 test 文件夹中的测试函数.
如果没有写专用的测试函数, 也可以使用 devtools 包中提供的通用测试函数 check.
> check('path/to/package')
check 函数会做所有的通用测试, 如果只想要测试帮助文档中的示例, 可以用 run_examples 函数.
安装包
devtools 提供了若干方便安装包的函数.
