7

编写 R 程序包的基本步骤和注意事项 [简略版]

 3 years ago
source link: https://yihui.org/cn/2007/11/steps-to-write-r-packages/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
neoserver,ios ssh client

编写 R 程序包的基本步骤和注意事项 [简略版]

谢益辉 / 2007-11-06

本文已经过期，请参考统计之都上的最新文章：开发 R 程序包之忍者篇。

这两天在忙着写一个 R 程序包 “animation”，因此被迫得学习 R 包的基本写法，粗略看了看”Writing R Extensions” 这本 Manual，现提供大致步骤如下：

  1. 系统准备工作：对于 Linux 系统来说就基本没什么需要准备的了，但 Windows 用户必须首先安装一系列的 “Windows Toolset”，详细情况参见”R Installation and Administration” 的 Appendix E；其中 Rtools 是必须的，但是为了能顺利编译 LaTeX 文档（帮助文件以及 Vignette 等），系统最好也装上 MikTeX。安装这些软件的时候尽量按照默认目录安装，否则你必须明白 “环境变量” 是什么意思（主要是其中的 PATH）。安装完成之后可以打开一个 Command 窗口（开始–> 运行：cmd）测试一下，例如 Linux 下的命令 ls 等能否在 Windows 的 Command 窗口（类似 Linux 的 “终端”）正常运行，ls 命令类似 Windows 的 dir 命令；关于 LaTeX，可以用 latex -help 测试是否可以正常运行。
  2. 装好软件之后如果上面的测试命令无法正常运行，那就得检查环境变量的 PATH 中是否包含相应的路径（有一些路径是在安装 Rtools 之后就会被自动添加的）。“我的电脑”–>“属性”–>“高级”–>“环境变量”–>“系统变量”–>PATH，这个里面应该包含诸如 c:\Rtools\bin; c:\Rtools\perl\bin; c:\Rtools\MinGW\bin; 等一系列路径；为了 R CMD INSTALL 等命令能正常运行，C:\Program Files\R\bin 这样的路径也是应该包含在这里（取决于 R 安装在什么位置，这里是我安装的位置）。到这里基本的准备工作就够了。
  3. R 自身提供了一个构建包的框架的函数：package.skeleton()；这个函数对于写包来说非常方便，因为它会自动帮你把包的架子搭好，你要做的工作只是：写函数的源程序（.R）和帮助文档（.Rd）；函数用法参见我这篇 Blog“用 R 编写自己的 Package”，主要是参考 R 帮助，自己看吧。需要注意的是 path 参数，否则构造了一个框架自己都找不着放到哪儿去了（如果不指定 path 参数，那么构造的框架放在 getwd() 下面）。打包的函数会把你的 functions 放在 R 文件夹下，把 data（如数据框）放在 data 文件夹下。
  4. 包中的函数怎么写我就不说了。写好一系列函数（可能还有数据）之后，用 package.skeleton() 搭好架子，就可以在该文件夹下面开始修改、补充包的详细内容了。（1）DESCRIPTION 文件，里面是关于你这个包的基本说明，包括版本、作者、版权、维护者、相关包等，里面需要看文档的可能只是 Depends, Imports, Suggests, Enhances 等那几项，稍有点费脑子；（2）帮助文档，这个在 man 文件夹下面，以 Rd 作为扩展名（R documentation），刚才的 package.skeleton() 函数已经把基本的项目都自动生成好了，我们需要把相应的内容填上，比如函数说明、参数说明、详细说明、返回值、示例、关键词（在 R 提供的关键词中选择）等。这些文本里面可以用链接 \link {}、字体修饰 \emph {} \code {} 等，具体参见 R-exts 文档。
  5. 修改好了之后就可以开始编译了；打开一个 Command 窗口，cd 到你的包源文件所在的文件夹，比如你的包写在 C:\pkg 这里，那么就 cd C:\，然后用 R CMD 系列命令，如检查包是否有错误：R CMD check pkg；编译包：R CMD build pkg（需要编译为 binary 的话就加上相应选项 --binary）；安装包：R CMD install pkg；如果你的包有任何错误，在 check 的时候会给出提示。

这样一个 R 包就基本上完成了，build 出来的 *.tar.gz（或者 binary 形式的 *.zip）就可以交给别人使用了（前提是 check 完全通过）。进一步可以为你的包写 vignette，也就是 PDF 说明文档，类似一篇文章的形式。如果要写 vignette 的话，最好会用 Sweave，这在 R-exts 中有相应的介绍，总体说来它的大致用途就是把 LaTeX 文档和 R code 结合起来，你可以在 LaTeX 文档中仅仅放 R code，不必把 code 的输出（文本或者图形）事先准备好，Sweave 文档在编译的时候会自动执行你的 R 代码生成相应的输出并插入到 LaTeX 文档中，这实在是太方便了 —— 动态生成报告。Vignette 文档（*.Rnw）放在包的 inst/doc 目录下，在 build 包的时候这个文档会被自动编译生成 PDF（实际上是转换给 LaTeX 编译的），安装包的时候这个文档会被装到 doc 目录下。关于 Sweave 的用法也可以参见 COS 论坛上这篇帖子：https://cosx.org/cn/topic/8434，momozilla 对 Emacs、ESS 和 Sweave 比较熟悉，可以向他请教。

编写包的过程中不妨参考一下别人的源文件，看大概是怎么写的。

注意事项：

  1. 写代码的时候不要把 TRUE/FALSE 简写为 T/F，虽然它们基本是等价的，但是这样写的话在编包的时候会给出警告和错误信息！我费了半天心思才琢磨明白这一点。
  2. 注意 LaTeX 语法，在写帮助文件的时候有些符号如下划线_是不能直接用的，因为 LaTeX 语法要求这样的字符必须由 \ 引导。如果 Rd 文件不符合 LaTeX 语法，build 的时候也会报错。之所以提到下划线，是因为 package.skeleton() 生成的数据文件的 Rd 文件中包含下划线（不知道是否应该给 R Core 写邮件说明一下），这些下划线应该删掉。
← 叽里咕噜叽里咕噜归来 Sir Arthur Conan Doyle 对统计建模的指导 →
Disqus Utterances Preferences
© Yihui Xie 2005 - 2020

report

Recommend

About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK