如何制作自己的R包

如何制作自己的R包？

摘自 方匡南 等编著《R数据分析-方法与案例详解》.电子工业出版社


R包简介

R包提供了一个加载所需代码、数据和文件的集合。R软件自身就包含大约30种不同功能的包，这些基本包提供了R软件的基本功能。与此同时，R作为一个开源软件，它提供了各种统计计算函数，从而方便使用者能够灵活机动的进行数据分析，甚至创造出符合特定需要的新统计计算方法，而这些函数大多是以包的形式提供，这些都是世界各地R用户自己编写的，并上传到网上分享。因此，制作出属于用户自己的R包，并与全世界的R用户共享是一件非常有意思的事情。
在开始R包的制作之前，首先对R包的基本结构进行简要的介绍。R包的基本结构如下：
package (包的名字)
|
|--DESCRIPTION (描述文件，包括包名、版本号、标题、描述、依赖关系等)
|--NAMESPACE (包的命名空间文件)
|--R (函数源码)
   |--function1.R
   |--function2.R
   |--...
|--man (帮助文档，存放函数说明文件的目录)
   |--function1.Rd
   |--Package.Rd
   |--...
|--...
其中，DESCRIPTION是包描述文件，它是一个纯文本文件，其中记录了与R包有关的信息，它没有扩展名，Windows用户可以用记事本打开。DESCRIPTION包含以下基本内容，注意只有几个字段是必须的，其它都可选：
Package: package name        /表示包的名称
Type: Package               /表示R-Project的类型，R包对应的为“Package”
Title: What the package does (short line)     /标题，简要描述R包功能
Version: 1.0                            /记录R包的版本信息
Date: when the package is built           /记录R包的制作时间
Author: Who wrote it                    /记录R包的作者
Maintainer: Who to complain to    /记录R包的维护者
Description: More about what it does (maybe more than one line)  /详细描述R包的功能
License: What license is it under?           /表示R包的使用许可

包的命名空间NAMESPACE是R包管理包内对象的一个途径，它可以帮助R包的作者控制保内的哪些函数对象是对用户可见的，哪些对象是从别的包导入（import），哪些对象从包中导出（export）。当我们在写一个R包时，有时候会涉及到许多函数，但是其中一些函数可能只是为了方便其它函数的编写而被抽象独立出来的子函数，这些子函数只需要被R包中的其他函数调用，对于外界用户而言并没有什么帮助，因此它们不需要对外界用户可见。NAMESPACE文件就提供了这样一个功能，我们可以通过在包的根目录下创建一个NAMESPACE文件，通过写上`export(函数名)`来导出那些需要对用户可见的函数。自R 2.14.0开始，所有的R包都必须有命名空间，如果没有的话，R也会自动创建。
R文件夹下存放的是R包中所涉及到的，以.r格式保存的函数源文件。
man文件夹下存放的是Rd文件，也就是R帮助的源代码，一般情况下，R会自动创建与R目录下的函数对应的.Rd文件以及一个额外的用以描述整个R包情况xxx-Package.Rd文件。
18.2         在windows中制作R包
(1)        制作R包前的R环境配置
首先确保正确安装R软件，RGUI或者Rstudio，注意安装路径以及软件语言最好选择英文以避免可能因为语言出现的错误。
目前最新版本的RGUI为R-3.0.2，RGUI的下载地址为(厦门大学镜像)：
http://mirrors.xmu.edu.cn/CRAN/bin/windows/base/
目前最新版本的Rstudio为RStudio v0.98，下载地址为：
http://www.rstudio.com/ide/download/
而制作R包的工具软件主要有Rtools，MikTeX或Ctex (如果不需要pdf的帮助手册，则不需要安装)
其中，Rtools是制作R包最重要也是最主要的工具，Rtools包含了windows环境下制作R包的一系列工具，其中包括：
1.        CYGWIN，用以在windows环境模拟UNIX环境。
2.        MinGW编译器，用以编译C和Fortran语言。
3.        Perl编译器，用以编译Perl语言。
最新版本的Rtools的下载地址为(厦门大学镜像)：
http://mirrors.xmu.edu.cn/CRAN/bin/windows/Rtools/
在完成上述软件的安装后，我们需要对文件的启动路径进行设置从而使得可以通过cmd命令行直接调用Rtools等相应软件。
具体操作为：右键点击计算机>属性>高级系统设置>环境变量>系统变量  PATH一项，点击“编辑”，检查是否具有以下路径。通常软件在安装时已经自动配置好了启动路径。如果没有，需要手工添加：
C:\Rtools\bin;c:\Rtools\perl\bin; C:\Rtools\MinGW\bin; C:\CTEX\MiKTeX\miktex\bin;
C:\CTEX\CTeX\ctex\bin; C:\CTEX\CTeX\cct\bin;C:\CTEX\CTeX\ty\bin;
C:\Program Files\R\R-3.0.2\bin\;



在完成上述步骤之后，打开cmd命令行窗口，输入R cmd –help 以检测R环境是否成功配置，正确配置后返回的结果如下图所示：


(2)        制作R包前的R环境配置
在Windows下编写R程序包通常包括以下几步：
1．        编写.r函数源代码，也就是用来生成R程序包的函数脚本。
在本文的演示中，假如现在我们已经有了一个编好的R函数Hello，用来在屏幕上输出问候：
hello<-function(name)
{
                       print(paste("Hello",name))
}
存成了r脚本的格式,文件名为Hello.r
2．        利用R软件自带的package.skeleton()函数，生成R包中的Description 文件和帮助文件.rd。
运行的代码为：
rm(list=ls())       
#清空R工作内存
setwd("D:/R-Pkg-Produce")    
#设定R软件“工作目录”，即R包的生成目录，但需要提前在路径建立对应的文件夹
package.skeleton(name="hello",code_files="D:/R-Pkg-Produce/hello.r")
#将待打包函数装载进工作内存，构建R包文件结构，生成相应的文件夹及其下面的文件，软件包名为"hello",文件是“hello.r”

R软件回显信息如下，表明包搭建成功。
Creating directories ...
Creating DESCRIPTION ...
Creating NAMESPACE ...
Creating Read-and-delete-me ...
Copying code files ...
Making help files ...
Done.
Further steps are described in './hello/Read-and-delete-me'.

3．        按要求填写生成的Description 文件和帮助文件.rd
上述代码执行完毕之后，将在目录D:\R-Pkg-Produce下自动生成一个与R包名字相同的文件夹，该文件夹下的内容就是R包的基本框架，包括Read-and-delete-me，DESCRIPTION文件，r文件夹，man文件夹，接下来所要进行的工作就是用记事本打开相应的文件，按要求将其填写完整，再进行相应的编译即可。
本例子中的hello-package.Rd文件编写如下：
\name{hello-package}
\alias{hello-package}
\title{a hello function demo}
\description{
a hello function demo
}
\usage{
hello(name)
}
\arguments{
  \item{name}{a word}
}
\details{
nothing
}
\value{
no return
}
\references{
nothing
}
Hello.rd文件的编写与hello-package.Rd文件类似，需要注意的是，rd文件中的\title项一定需要填入内容，否则会导致R CMD的check过程出错。本例子中的hello.Rd文件编写如下，注意，与hello-package.Rd文件相比，在hello.Rd我们有选择地保留了一小部分内容。
\name{hello}
\alias{hello}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
function hello(x) to say hello x
}
\description{
this function hello() provides a package demo
}
\usage{
hello(name)
}

DESCRIPTION文件编写如下：
Package: hello
Type: Package
Title: Say hello
Version: 1.0
Date: 2013-12-23
Author: Developer 
Maintainer: Developer
Description: This package provides a package demo
License: GPL (>= 2)

特别地，在Rstudio这一R语言的IDE( Integrated Development Environment，集成开发环境)中，Rstudio提供了完全可视化的R包制作接口，上述的R包描述性文件均可在Rstudio中直接编辑。
4．在windows cmd的命令行中输入相应的命令，生成zip文件或者.tar.gz,并进行相应的检查。
打开Cmd窗口：<开始>\<运行>\
首先输入：cd D:/R-Pkg-Produce   #其目的是将工作目录更改至先前设定的R包路径下
再输入：R CMD check D:/R-Pkg-Produce/hello   #检查r包hello
执行结果如下：

最后输入：R CMD build D:/R-Pkg-Produce/hello
运行成功后显示如下信息：

将在C:\Users\用户名(在本例中为C:\Users\Administrator)路径下生成一个hello_1.0.tar.gz，即为我们所需要的R包。
在Rstudio的控制台中输入：
install.packages("C:/Users/Administrator/hello_1.0.tar.gz", repos = NULL, type = "source")
回显信息如下，R包成功安装。
* installing *source* package 'hello' ...
** R
** preparing package for lazy loading
** help
*** installing help indices
** building package indices
** testing if installed package can be loaded
* DONE (hello)
调用生成的R包进行测试，运行结果如下：
> library(hello)
> hello("world")
[1] "Hello world

摘自 方匡南 等编著《R数据分析-方法与案例详解》.电子工业出版社