【R包开发：入门】 简介+ 包的结构

时间：2024-03-07 07:53:08

简介

本书的目的是教你如何开发包，以便你可以写出自己的包，而不只是使用别人的包。

为什么要写一个包？

一个令人信服的理由是，你想要与他人分享代码。把你的代码打成一个包，可以方便他人使用，因为他们像你一样也知道如何使用包。如果你的代码在包中，则任何 R 用户都可以轻松地下载、安装和学习如何使用它。

【在 R 中，可分享代码的基本单位是包】

即使你从不分享你的代码，包也很有用。它主要是节省你自己的时间。”把代码组织在一个包中会让你工作起来更容易，因为包有一些通用的约定。标准化的规范带来标准化的工具

1.1　开发理念

任何可以自动化的都应该自动化。把手动工作量降到最小。目标是让你将时间用于思考你想要包做什么，而不是包结构的各种细节。

这一理念主要是通过 devtools 包+RStudio 来实现的

1.2　入门

确保你有最新版本的 R（至少是 3.1.2),获得你将要用到的包

install.packages(c("devtools", "roxygen2", "testthat", "knitr"))

H还需要一个 C 编译器和几个命令行工具

  • 在 Windows 下，下载并安装 Rtools（RTools: Toolchains for building R and R packages from source on Windows）。注意：这不是一个 R 包！

  • 在 Mac 下，确保你有 Xcode（可在 App Store 上免费获取）或 Xcode 命令行工具（Sign In - Apple）。

  • 在 Linux 下，确保你不仅安装了 R，而且还安装了 R 开发工具。例如，在 Ubuntu 和 Debian 上，你需要安装 Ubuntu 的 r-base-dev 包。

1.3　约定

    在本书中，foo() 指函数，bar 指变量或函数参数，baz/ 指路径，#> 是输出注释，# 是常规的注释。

包的结构

2.1　给包命名

2.1.1　命名的要求

选择一个很容易被搜索到的独特的名字。这很容易让潜在的用户找到你的包，并且容易记住的包名。

2.1.2　命名的策略

找到一个和这个问题相关的词，修改它，如：plyr，lubridate，knitr，testdat  

使用缩略词：Rcpp，lvplot 

 增加一个额外的 r：stringr，tourr， gistr 

2.2　创建一个包

第一种方法：

(1) 单击 File | New Project（文件 | 新项目）。

(2) 选择 New Directory（新的目录）

(3) 下一步，选择 R Package（R 包）

(4) 最后，给出你的包名，然后单击 Create Project（创建项目）

 第二种方法：

 R 里面通过命令来创建

devtools::create("path/to/package/pkgname")

以上两种方法创建的包都属于最小的可用包，它有三个组成部分。

(1) 一个 R/ 目录，

(2) 一个描述文件 DESCRIPTION，

(3) 一个命名空间文件 NAMESPACE，

这个包还包括一个 RStudio 项目文件 pkgname.Rproj，这将使你的包易于在 RStudio 中使用。 

如果你的包中不包含.Rproj文件， 可以使用  devtools::user_rstudio("path/to/package")  来添加它。

.Rproj 文件只是一个文本文件。不需要手动来修改这个文件。通常，可以使用友好的 Project Options（项目选项）对话框，通过 RStudio 右上角的 Projects（项目）菜单来访问

2.3　RStudio 项目

使用Rstudio的好处

  • 每个项目都是独立的，在一个项目中运行的代码不会影响任何其他项目。

  • 你可以获得方便的代码导航工具，如 F2 可以跳转到函数的定义，Ctrl+. 可通过名字来查找函数。

  • 有用的快捷键，用于通用的包开发任务

2.4　什么是包

2.4.1　源码包

源码包只是包含 R/ 子目录、DESCRIPTION 等组件的一个目录。

2.4.2　压缩包

压缩包是一个已经压缩为单个文件的包，R 中的压缩包使用 .tar.gz 扩展名。这意味着多个文件已经被打包成一个文件（.tar）并用 gzip（.gz）压缩过。

如果你解压一个压缩包，会看到它和你的源码包看起来几乎一样。解压的包和源码包的主要区别如下。

  • 使用指南被创建，你可以得到 HTML 和 PDF 输出而不是 Markdown 或者 LaTex 的输入。

  • 你的源码包中可能包含开发时产生的一些临时文件，比如 src/ 目录下编译生成的中间文件，它们在解压的包中是不存在的。

  • .Rbuildignore 文件中列出的任何文件都不会出现在解压的包中。

.Rbuildignore的介绍

.Rbuildignore 防止源码包中的文件出现在压缩包中。它允许你在源码包中包含比压缩包中更多的目录。这在你从其他文件生成包的内容（比如数据）时特别有用。这些文件应该包含在源码包中，但是只有结果需要发布。这对于 CRAN 包（顶层目录的个数是固定的）来说特别重要。

一个典型的 .Rbuildignore 文件

2.4.3　二进制包

二进制包是一个单独的文件。如果将它解压缩，你会看到它的内部结构和源码包大不一样

二进制包是平台相关的：不能在 Mac 上安装一个 Windows 二进制包，也不能在Windows 上安装一个Mac 二进制包

Meta/ 目录包含大量 Rds 文件：这些文件缓存了包的一些元数据，比如帮助文件包含了什么主题，以及解析出的 DESCRIPTION 文件中的版本信息。

html/ 目录包含 HTML 的帮助文件

如果包中 src/ 目录下有代码，那么现在将有一个 libs/ 目录，其中包含了编译过的 32 位（i386/）和 64 位（x64/）代码。

inst/ 目录下的内容被移到了顶层目录

2.4.4　已安装的包

已安装的包只是解压到一个包库的二进制包。在理想的情况下，安装一个包包括一系列简单的步骤：源码包→压缩包，压缩包→二进制包，二进制包→已安装的包。

支持所有包安装的工具是 R 的命令行工具 R CMD INSTALL，它可以安装源码包、压缩包和二进制包。

  • devtools 的函数封装了这个工具，devtools::install() 有效地封装了 R CMD INSTALL。devtools::build() 封装了 R CMD BUILD，可以把源码包打包成压缩包。devtools::install_github() 从 GitHub 下载源码包，运行 build() 来生成使用指南，然后使用 R CMD INSTALL 安装包。
  • install.packages() 用于下载和安装 CRAN 编译的二进制包。他的工作方式是它载源码包，编译，然后安装。

2.4.5　内存中的包

library() 和 require() 会加载和附加一个已安装的包。在写脚本的时候，加载和附加包之间的区别并不重要；但是在写包的时候，这个区别是非常重要的。

2.5　什么是库

库是一个包含已安装包的目录。

你的电脑中可以有多个库。事实上，几乎每个人都至少有两个库：一个用来放已经安装的包，另一个用来放 R 安装时自带的包（如 base、stats 等）。通常情况下，用户安装包的目录在不同的 R 版本下有所不同。这就是为什么你重新安装 R 以后，以前安装的包好像都丢了，实际上它们仍然在你的硬盘上，只是 R 找不到它们而已。

使用 .libPaths() 来查看当前正在使用的库是哪个

.libPaths()

参考文献

中文书籍 (ituring.com.cn)

R Packages (2e) (r-pkgs.org)

英文书籍Writing R Extensions (r-project.org) (官方 R 扩展开发手册)

相关文章