R package 笔记

1. license: 把你的作品释放到公有领域，授予其他人特定权利来使用你的产品。
   常见的license: GPL, BSD, MIT
   usethis: use_lgpl_license(version = "2.1") 自动更新description文件
2. 删除整个man directory，用devtools: document()会自动生成/更新新的man directory，里面会通过Roxygen自动生成.R file对应的Rd文件，不用自己写函数的documentation。如?hello可以预览自动生成的hello.Rd documentation
3. 把scratch code放在新建一个inst目录里，不会被build进R包
4. roxygen注释对这一类命名空间有一系列标签，如一个函数的文档中若标记了#' @export，那么这个函数将来就会出现在NAMESPACE（命名空间）文件中（被导出），若写了#' @importFrom foo bar，那么foo包的bar对象也会被写在NAMESPACE中。
5. 命名空间（NAMESPACE）是R包管理包内对象的一个途径，它可以控制哪些R对象是对用户可见的，哪些对象是从别的包导入（import），哪些对象从本包导出（export）。为什么要有这么个玩意儿存在？主要是为了更好管理你的一堆对象。写R包时，有时候可能会遇到某些函数只是为了另外的函数的代码更短而从中抽象、独立出来的，这些小函数仅仅供你自己使用，对用户没什么帮助，他们不需要看见这些函数，这样你就可以在包的根目录下创建一个NAMESPACE文件，里面写上export(函数名)来导出那些需要对用户可见的函数。自R 2.14.0开始，命名空间是R包的强制组成部分，所有的包必须有命名空间，如果没有的话，R会自动创建。
6. DESCRIPTION:
   Depends 加载这个包会依赖加载进来的包
   Imports 只是导入命名空间，不直接加载（被导入的包中的函数对用户不直接可见）
   Suggests 推荐安装的包，通常不涉及到本包的核心功能，但如果有这些包的话，本包会更强大
7. usethis:use_data_raw() 生成了一个新的data-raw目录，里面有一个DATASET.R文件。把dataset放进data-raw目录下，在DATASET.R里将dataset保存成变量名，编写代码，如：
   ukb_accel <- readRDS("accel.rds")
usethis::use_data(ukb_accel, overwrite = TRUE)
   运行以上代码会在data目录下保存进一个ukb_accel.rda的数据。之后可以直接data(“ukb_accel”)来获取包中的数据。
8. 对每一个数据，都必须有相应的Rd文档，它可以通过roxygen生成。
   在R目录下创建data.R文件
   • @docType必须为data
   • 必须有@name，因为roxygen不能从底下的R代码中推导出这份文档的名字（对普通函数文档来说，可以从赋值符号的左边推导出来）
   • R代码不能为空（否则roxygen会跳过这段文档），通常可以用NULL填充
   • 其它标签可选，例如@format说明这份数据的格式，@source说明它的来源

#' @name ukb_accel
#' @docType data
#' @keywords data
NULL

?ukbaccel即可查看数据的文档
9. 函数文档：@examples

#' @examples
#' data(ukb_accel)
#' accel_plot(ukb_accel[1:1000,])

@aliases 可以给函数设置别名，需要另外export？

#' @aliases spec_sig
spectral_signature <– function(...) {}

#' @export
spec_sig <- spectral_signature

10. 轻量版检查: devtools::check()
    • 遇到 note 如 no visible binding for global variable 'X'但X是列名（如dplyr、ggplot时会直接用，check会把它当作全局变量），在R目录下建一个globals.R的文件，里面写utils::globalVariables(c("X", "Y", "Z")) 就不会再报note
    • 遇到warning如 LazyData of xxMB without LazyDataCompression set: 在DESCRIPTION中删除 LazyData: true 这一行
11. 可以用 {usethis} 来快速设定编写测试所需要的 {testthat} 的环境。

usethis::use_testthat() # 设定环境

弹出运行结果：(会自动生成tests/testthat)的路径

✓ Adding 'testthat' to Suggests field in DESCRIPTION
✓ Setting Config/testthat/edition field in DESCRIPTION to '3'
✓ Creating 'tests/testthat/'
✓ Writing 'tests/testthat.R'
● Call `use_test()` to initialize a basic test file and open it for editing.

install.packages("testthat") # 安装 {testthat}
usethis::use_test() # 快速创建测试文件

如要test plot这个函数则在console中运行usethis::use_test("plot")，会在tests/testthat/下创建一个test-plot.R的文件
测试方法例子：expect_true(),expect_error() 等
devtools: test()即可运行测试检查是否通过

12. covr: :report() 会给出测试覆盖比例的report，可以点进去看哪些行有被test文件运行到，哪些行没有被覆盖
13. expect_doppelganger("first-100-samples", p)可以将p保存成svg格式的图片存储在tests/testthat/_snaps/plot目录下，名字为引号中的内容，用来看输出是不是自己想要的。第一次test()的时候会报warning表示添加了一个新的svg文件，再run一次test()就没有warning了。 如果更改了p，test会fail，因为"first-100-samples.svg"和新的p不再一样，同时会保存一个新的snap，同样的文件名加上了.new后缀。（如果确实要改的话就把原先的snap删了）
    简单来说这个函数做两件事：1. 将snap里名字为第一个参数的文件和第二个参数进行比较是否相同 2. 如果没有名字为第一个参数的文件的话就先生成一个
14. 上传该项目到github：
    • 先在github上创建一个repository
    • 在rstudio的terminal中输入（注意路径是该项目）git init，这会在这个项目下生成一个.git的路径（但是这是隐藏文件，可以在terminal中输入 ls -lah看到）
    • 在.Rbuildignore里写入^\.git$
    • 点击version control -> commit，选中除了.DS_Store以外的所有东西，commit
    • 在terminal中输入github上的示例：
      git remote add origin [email protected]: githubUserName/projectName.git
git branch -M main
git push -u origin main
    • 如果显示要输入用户名和密码，用户名是github的username，密码是token
      如果没有的话要先在github上设置：settings -> developer settings -> personal access tokens -> Tokens (classic) -> generate new token
    • 设置ssh key可以使得以后push不再需要输入密码，
      教程：https://blog.csdn.net/weixin_42310154/article/details/118340458
15. use_readme_rmd()会自动添加一个README.rmd模版，可以在上面更新。点击knit会生成对应的README.md文档。（第一次knit需要运行devtools::install_github("xxx")这行代码）
16. github actions可以进行一些自动检查的流程
    • usethis: use_github_action_check_standard()：在.github/workflows目录下生成一个R-CMD-check.yaml的文件，以后每次将项目更新push到github后都会对项目自动进行一些基本检查(check()?)
    • lintr::lint_package()会对整个包进行代码规范性检查，如R中最好不使用=而是用-> 赋值。usethis::use_github_action("lint")会添加一个github action（生成一个.github/workflows/lint.yaml文件），每次push后自动进行lint检查，如果没有问题显示pass，有需要修改的地方则显示fail
    • usethis::use_coverage()会在包里生成一个codecov.yml文件，同时会在README里自动添加一个Codecov test coverage 的badge （注意要先library(covr)）。
      [或者rcompendium::add_github_actions_codecov_badge()添加badge。-不确定这个代码]
      badge点进去是一个codecov的链接，要点进去登陆，同步github信息才能直接在badge的link里显示百分比。codecov.io可以可视化测试覆盖率。这样就可以通过badge里的链接看见coverage的report了。
    • usethis::use_github_action("test-coverage")会添加一个.github/workflows/test-coverage.yaml的文件，生成一个github action，相当于每次push后都会自动更新coverage的比例。[个人理解：use_coverage()与use_github_action(“test-coverage”)的关系和lint_package()与use_github_action(“lint”)的关系是一样的]
    • 参考：https://www.r-bloggers.com/2022/03/developer-diary-for-ggshaker-0-1-2-a-package-for-soccer-analytics-viz-implementing-github-actions-ci-tools-codecov-lintr-etc-into-the-workflow/
17. vignette

一些有帮助的博客/reference：
https://swsoyee.vercel.app/2021/02/writing-r-packages-a-modern-workflow-for-beginners
https://bookdown.org/yihui/r-ninja/r-package.html