R Packages 泛读笔记

分享一下本人阅读R Packages这本书所做的一点简单的笔记，说不定能帮到谁嘞。

原书籍在线阅读网站：https://r-pkgs.org/

基础流程

R包构建最基础流程：

1. 编辑 R/ 文件
2. document() 更新文档
3. load_all() 加载更改
4. 交互测试
5. test() 运行测试
6. check() 全面检查

存放数据

不同数据有不同存放方法。

R包重要目录如下。

DESCRIPTION

DESCRIPTION 主要内容如下。

依赖

若开发的R包必须和另一个包一起用，则要添加依赖。

• Imports：核心功能必需的依赖
• Suggests：可选功能/测试/文档的依赖
• Depends：仅用于元包或强依赖场景

如下代码添加依赖：

# 核心依赖
usethis::use_package("dplyr", "Imports")

# 可选依赖
usethis::use_package("ggplot2", "Suggests")

执行后DESCRIPTION文件会自动生成：

Imports: 
    dplyr
Suggests: 
    ggplot2

另外在代码中还需显式声明使用了依赖函数，比如以dplyr::filter()举例如下：

clean_data <- function(data) {
  dplyr::filter(data, condition)  # 这里使用dplyr的filter
}

NAMESPACE

要更新NAMESPACE，运行devtools::document()。NAMESPACE文件相关操作：

许可证

许可证分为两种。

许可证相关核心文件有：

• DESCRIPTION中的License字段
• LICENSE文件（包含具体条款）
• LICENSE.md（完整许可证副本，CRAN不上传）

常用以下代码生成对应许可证。

# 代码许可证
usethis::use_mit_license()    # 最宽松的MIT
usethis::use_gpl_license()    # 要求衍生作品开源

# 数据许可证
usethis::use_cc0_license()    # 数据完全开放
usethis::use_ccby_license()   # 要求署名

测试

test相关设置

# 首次设置测试环境
usethis::use_testthat(3)  # 使用testthat第3版

会创建：

• tests/testthat/目录
• DESCRIPTION中添加testthat依赖
• tests/testthat.R入口文件

要创建对应脚本的测试文件，可用如下代码。

# 创建与R/foo.R对应的测试文件
usethis::use_test("foo")  # 生成tests/testthat/test-foo.R

测试用例基本结构：

test_that("描述测试内容", {
  # 准备测试数据
  test_data <- ...

  # 调用被测函数
  result <- your_function(test_data)

  # 验证结果
  expect_equal(result, expected_value)
  expect_true(is.numeric(result))
})

常用期望函数如下。

禁止在测试文件中显式调用 library(testthat)，因为 testthat 的依赖版本应通过 DESCRIPTION 文件声明（如 Suggests: testthat (>= 3.0.0)），而非在测试代码中硬编码，确保所有测试均使用同一版本。

roxygen

roxygen2 是 R 语言中用于自动化生成函数文档的工具。开发者直接在函数代码上方用特殊格式的注释（以 #' 开头）编写文档，然后通过 devtools::document() 自动生成 .Rd 文件（R 的官方文档格式）。支其编写支持 Markdown语法。

roxygen2 注释块格式：

#' 函数的标题（首句，简短描述）
#'
#' 函数的详细描述（可多段）。
#' 使用Markdown语法（如 `code`、*强调*、[链接]()）。
#'
#' @param 参数名 参数说明（类型、用途、默认值等）。
#' @returns 返回值说明（类型、结构）。
#' @examples 
#' 可执行的R代码示例（需自包含、无副作用）。
#' @export  # 标记为导出函数（公开给用户）
my_function <- function(x, y) {
  函数体
}

示例：

#' Add together two numbers
#' 
#' @param x A number.
#' @param y A number.
#' @returns A numeric vector.
#' @examples
#' add(1, 1)
#' add(10, 1)
add <- function(x, y) {
  x + y
}

关键标签如下：

Vignettes

Vignettes是R包的长篇教程，用于展示核心功能。可通过browseVignettes("包名")或vignette("名称", package="包名")查看。

初始化Vignette：

usethis::use_vignette("my-vignette")  # 创建模板文件`vignettes/my-vignette.Rmd`

这样就能：

• 自动生成vignettes/目录。
• 在DESCRIPTION中添加依赖（如knitr和rmarkdown）。

Vignettes默认开头如下，采取YAML格式，其中>表示下方均为文本。

---
title: "Vignette Title"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

README

README文件是用户接触包的第一站，需要有三个核心要素：

1. 为什么使用这个包（介绍）？
2. 如何快速上手（教程）？
3. 如何安装（CRAN/GitHub）？：

使用README.Rmd生成README.md

usethis::use_readme_rmd()  # 创建模板
devtools::build_readme()    # 渲染更新

NEWS

NEWS文件记录版本变更。结构如下：

# foofy (development version)

* Better error message when grooving an invalid grobble (#206).

# foofy 1.0.0

## Major changes

* Can now work with all grooveable grobbles!

## Minor improvements and bug fixes

* Printing scrobbles no longer errors (@githubusername, #100).

* Wibbles are now 55% less jibbly (#200).

建设R包网站

初始化配置：

usethis::use_pkgdown()       # 创建配置文件_pkgdown.yml
pkgdown::build_site()        # 首次构建网站

usethis::use_pkgdown_github_pages()  #GitHub用户一键配置

pkgdown会自动整合以下内容生成网站：

添加logo步骤如下：

1. 将logo图片保存为man/figures/logo.png

2. 使用命令

   usethis::use_logo("path/to/your_logo.png") 

这样一来，logo图片会自动调整尺寸并更新README显示，且网站导航栏会自动显示logo。

只要.github/workflows/pkgdown.yaml包含下列代码，每次git push后便会自动重建网站。

on: 
  push: 
    branches: [main]