在vscode中开发R包并给函数添加帮助文档

在vscode中开发R包并添加帮助文档

使用过R语言的人都知道，在R里面是可以通过命令行查看函数的帮助文档的，查看命令为help或问号（？），例如我想要查看seq函数的帮助文档，那么可以输入help(seq)或?seq，在Rstudio或者VSCode中就会调出一个新的界面来显示函数的参数及用法。

有时候我们想要自己写R函数（自定义函数）来实现一些功能，比如需要对一百个文件做相同的处理，那么可以将操作写到一个函数中，然后用apply系列函数来多次调用这个函数，这样会比跑for循环快很多。

再比如我们可以将一些常用的操作写到函数里面，以后直接使用这些函数来实现这些操作即可，这样可以大大提升编程的效率。但这样做也有一个潜在的问题，那就是当自定义的函数多了以后，对它们的参数及用法可能会渐渐模糊（除非记忆力极好或者函数很常用，且参数较少），这个时候就需要翻看函数源代码才能回忆起来这个函数的功能以及用法等，这其实不是很方便，因为对于喜欢“优雅编程”的人来说，“不离开命令行就可以写出高质量代码”是最高的追求！

那么这个时候就可以参考R语言提供的做法，给自定义函数写上帮助文档，然后以R包的形式将自定义函数及其文档安装到R语言中，这样在打开新的R终端以后，就可以通过library来加载自己的R包，然后就可以通过help或问号来查看自定义函数的帮助文档啦。

下面简单介绍一下如何实现这个过程。

本文涉及的操作：

• 创建一个R包
• 自定义一个函数
• 给函数写帮助文档
• 安装该R包
• 加载R包，查看自定义函数的帮助文档

本文需要用到的R包：

• usethis
• devtools

1. 创建一个R包并写一个实用函数

打开vscode的R命令行，运行命令usethis::create_package(*path*='r.utils')来创建一个新的R包，该命令创建的R包名称为r.utils，其中utils是utilities（实用）的缩写。

运行完该命令以后会在当前文件夹创建一个名为r.utils的文件夹，R会自动将工作路径切换到该文件夹。这一步的输出信息如下：

然后给该包创建一个README.md文件，用来描述该包的功能，使用R命令：usethis::use_readme_md() ，输出信息如下：

这个README.md文件的内容可以自己修改，其目的是让其他人看到该文件就知道这个包的主要功能。

接下来在该文件夹下面的R目录下面创建一个R脚本（名为util_func.R，表示实用函数），可以使用R命令：file.create("R/util_func.R")也可以使用vscode的文件窗口创建该文件。

然后将下面的实用函数粘贴到刚才创建的脚本（R/util_func.R）中：

#' Check if file or directory exists
#'
#' It accepts numerous arguments of files or directories and check if all of them are existed. An error will occur if one of them does not exist and the file path will be reported.
#'
#' @param ... Files
#'
#' @return No return.
#' @export 
#' @examples
#' # check_files('a.tsv')
#' # check_files('/home/jjj/softwares')
check_files <- function(...){
    files <- list(...)
    # print(files)
    for(afile in files){
        # print(afile)
        if(! file.exists(afile)){
            stop('Error! File `', afile, '` does not exists! Please check it!')
        }
    }
}

该函数的作用是来检查文件是否存在，它可以接收多个参数，每个参数是文件或文件夹路径，并依次检查每个文件是否存在，若文件不存在则输出不存在的文件名并退出程序。该函数可以作为一个保障，以检查后续代码所需要的所有文件是否存在。

这一步完成后R/util_func.R文件内容如下：

注意该函数上面存在许多#’开头的行，这些行是roxygen skeleton，用来给函数添加文档，具有特定的格式：

• @param指定函数的参数
• @return指定函数的返回值
• @export表示将该函数导出到外部，这样在加载该包的时候就可以使用该函数
• @examples后面的行表示该函数的示例用法

关于roxygen skeleton的详细格式介绍可以参考roxygen2的说明。

然后运行命令devtools::document() 给该函数添加注释文档，输出如下：

至此已经写好了一个R包和一个函数，并给该函数添加了帮助文档，接下来需要将该包安装到R语言中，并应用该函数。

2. 安装R包

仔细观察刚才创建的R包，可以发现如下结构：

这个结构是标准的R包结构，该文件夹可以直接作为R包安装。

接下来新开一个R终端（必须是新的终端，刚才创建R包的终端不可以安装），然后运行命令：install.packages('/mnt/d/Desktop/path/blogs/05.build_r_package/r.utils', repos=NULL)来安装该包，这里建议使用绝对路径。

安装信息如下：

出现DONE则表示该包安装成功，接下来进行测试。

首先引入该包，然后查看刚才自定义的函数check_files：

接下来使用命令?check_files查看该函数的帮助文档，输出如下：

最后使用该函数进行测试：

• 当文件全部存在时，该函数不会输出任何信息，即第一条命令；
• 当某个文件不存在时，则会终止程序，并输出不存在的文件的路径。

测试完成！

3. 在vscode中给函数插入roxygen skeleton

最后还有一个问题需要解决，即函数文档依赖于roxygen skeleton，而roxygen skeleton又比较复杂，如果每次都手动写或者复制粘贴就过于麻烦了，好在有一个R包（即docthis）可以在vscode中基于函数信息来生成roxygen skeleton，下面来介绍如何安装和使用该包。

安装命令：devtools::install_github("mdlincoln/docthis")

使用方法：

首先将函数定义到R终端中，然后选中要加入文档的函数名，必须是选中！接下来有两种方式：

方式1：

定义一个add函数，并将其定义到终端中：

然后选中函数名，通过 ctrl + shift + P 调出vscode的命令窗口，然后输入 R: Launch RStudio Addin，步骤如下：

然后选择docthis的Document object命令

运行该命令，成功后效果如下所示：

方式2：使用快捷键来调用docthis的函数，即选中该函数名，然后调用快捷键。

下面介绍使用ctrl + ;键快速调用docthis函数的方法。

首先打开vscode的快捷键配置，步骤如下：

然后如下图点击该标签打开快捷键配置文件：

最后将下面的代码插入到keybindings.json文件的最下面，

    {
        "description": "insert roxygen skeleton",
        "key": "ctrl+;",
        "command": "r.runCommand",
        "when": "editorTextFocus",
        "args": "docthis:::doc_this_addin()"
    }

插入后如图所示：

接下来就可以使用ctrl + ;键来调用docthis函数给函数插入roxygen skeleton了。

4. 参考教程

Hadley Wickham写的《R Packages》: https://r-pkgs.org/

为新手准备的现代化 R 包开发流程：https://cosx.org/2021/02/writing-r-packages-a-modern-workflow-for-beginners/

最后

本文同步发表于微信公众号：水木的生信与编程世界，如果觉得本文对您有帮助欢迎关注公众号，我会持续分享更多关于生信的分析经验和实用技巧。