建立副本名称冲突_包的建立(一）

这次的内容&＃xff0c;涉及到 R 语言包的建立。事实上&＃xff0c;CRAN 提供的官方参考指南&＃xff0c;并不适合快速阅读&＃xff0c;且内容繁杂。比较适合作为后期提高的 教材。而 http://r-pkgs.had.co.nz/ 上 的教程则更适合作为 R 包编写的帮助指南。这里&＃xff0c;仅仅讲述整个过程中需要注意的一系列的问题&＃xff1a;

目前&＃xff0c;我个人只涉及到 Windows 系统&＃xff0c;因此本文仅适用于 Windows 系统下&＃xff0c;R 包的创建&＃xff1a;Rtools 是必须具备的工具&＃xff0c;当然这个工具也只适用于 Windows 系统。关于 Rtools 的安装并没有过多可强调的内容。需要明确的是&＃xff1a;R 语言目前已经进入了 4.0 的时代&＃xff0c;对应的也从 Rtools35 过渡到了 Rtools40.目前所有的配置要求必然是&＃xff1a;  以及   旧版的 Rtools 需要在安装时勾选&＃xff1a;Add rtools to system PATH&＃xff0c; 但新版本并无此操作。仍然需要注意的是&＃xff1a;必须安装在 C 盘的默认路径下&＃xff0c;不能更改安装路径&＃xff01;在完成安装之后&＃xff0c;R 语言环境下&＃xff0c;运行代码&＃xff1a;

> Sys.which(&＃39;make&＃39;)
                              make 
"C:\\rtools40\\usr\\bin\\make.exe" 
返回上述信息&＃xff0c;才能证明 Rtools 配置已完成。需要强调的是&＃xff1a;不能修改安装路径&＃xff01;且 C 盘文档下的 .Renviron 不能删除&＃xff01;除此之外&＃xff0c;还需要&＃xff1a;设置 R 的 path 环境变量&＃xff0c;这一步已经在 《R语言环境配置》一文讲过&＃xff0c;因此&＃xff0c;实在没有重复的必要性。并且&＃xff0c;这篇文章也不是针对零基础而讲的。仅仅只会涉及到重点内容以及各种易错点。只有环境变量设置成功&＃xff0c;后续才能调用 R CMD 进行一系列的操作。至此环境配置已完成&＃xff0c;当然&＃xff0c;还需要准备&＃xff1a;RStudio

R 包的建立&＃xff0c;最佳建议方案&＃xff1a;在 RStudio 中通过新建项目来完成。法一&＃xff1a;File > New Project > New Directory >  R Package &＃xff0c;或者选择&＃xff1a;R Package using devtools法二&＃xff1a;

library(devtools)
create_package()
或者选择 create_package() 直接创建一个包所需要的基本内容。至于 create_package() 如何使用&＃xff1a;RTFM基本的路径设置&＃xff0c;绝对路径&＃xff0c;相对文件&＃xff0c;文件管理&＃xff0c;如何保存到合适的位置&＃xff0c;以及 R 语言包的建立&＃xff0c;不能直接输入任何中文字符&＃xff0c;这些都属于基础入门内容。不是现如今应该重复叙述的内容。从这篇文章开始&＃xff0c;今后不会再涉及针对基础入门的帮助性文章。

需要说明的是&＃xff1a;

1/  devtools 包必须使用&＃xff0c;导入 devtools 的同时&＃xff0c;会默认加载 usethis包

2/  而 roxygen2 则被 RStudio 的操作环境下使用了&＃xff0c;并没有被显式调用。

3/  这三个包&＃xff0c;构成了 R 包创建的整个工具支持。

整个项目文件夹下包括了&＃xff1a;

     ---R

     ---man

     ---NAMESPACE

     ---DESCRIPTION

以及 Rproj 和 LICENSE 

这些部分是包的创建所必须的&＃xff0c;但 Data 和 vignette文件夹并不是默认需要的&＃xff0c;这一点需要引起重视。

RStudio 界面的些许变化&＃xff1a;只有在创建 R 包的项目文件中&＃xff0c;Build 菜单栏才会显示与创建包相关的一系列选项&＃xff01;当然&＃xff0c;除了鼠标点击执行以外&＃xff0c;利用 代码操作&＃xff0c;才是最直接了当的方式。

创建之前&＃xff0c;需要把工作路径设置到创建包的路径下&＃xff01;

一般&＃xff0c;第一步通常是修改&＃xff1a;DESRITION 文件

Package: 
Title: 
Version: 
Date: 
Authors&＃64;R: 
    person(given &＃61; ,
           family &＃61; ,
           role &＃61; c("aut", "cre"),
           email &＃61; )
Author: [aut,cre]
Depends: R (>&＃61; 4.0.0)
Description: 
License: 
Imports: 
Encoding: UTF-8
LazyData: true
Roxygen: list(markdown &＃61; TRUE)
RoxygenNote: 7.1.1


相关的内容&＃xff0c;需要个人补齐。这一块&＃xff0c;不再强调。

Imports 内容&＃xff0c;涉及到编写函数时使用到的其他包。必须在 Imports 项中指出&＃xff0c;否则建立包时&＃xff0c;会产生报错信息。

这一块&＃xff0c;倒没有过多需要强调的内容。

在编写函数之前&＃xff0c;需要确保当前环境下&＃xff0c;所有的变量被清空&＃xff1a;

rm(list &＃61; ls())
所有的代码均位于 R 文件夹下&＃xff0c;通过一个个 .R 为后缀名的脚本来记录。但目前&＃xff0c;仍然无法支持 R 文件夹下涉及子目录&＃xff0c;也就意味着&＃xff0c;所有的函数都必须通过处于同一级的 R  的脚本来保存。在编写函数之前&＃xff0c;需要明确&＃xff1a;R 包函数分为两大类&＃xff1a;1/   支持导出的函数2/   仅在包内使用的内部函数创建文件及删除文件&＃xff1a;

edit_file(&＃39;./R/read.R&＃39;)
file.remove(&＃39;R/read.R&＃39;)


当然设置路径是包的主路径&＃xff0c;而 R 是子目录&＃xff0c;所以创建 R 脚本是必须添加上子目录名称&＃xff0c;而不需要时&＃xff0c;则通过 file.remove() 删除路径。

需要说明的是&＃xff1a;file.remove() 操作的文件&＃xff0c;将直接被清理&＃xff0c;不会进入回收站中&＃xff0c;因此需要谨慎对待。

R 文件夹下的脚本名并不一定等于函数名。一个脚本下可以存在多个函数均被导出。

对于导出的函数&＃xff0c;需要添加注释内容。而 R 包的内部函数&＃xff0c;则不需要注释内容。

所有的注释内容&＃xff0c;以 #&＃39; 开头&＃xff0c;或者可以选择&＃xff1a;##’ 开头。

简单的示例&＃xff1a;

#&＃39; &＃64;title 
#&＃39; &＃64;description 
#&＃39; &＃64;param 
#&＃39; &＃64;examples
#&＃39; &＃64;export
#&＃39; &＃64;author
scan.str  function(string){
  return(scan(text &＃61; string))
}


&＃64; 后面的每一项内容都需要补齐&＃xff0c;但 &＃64;author, &＃64;examples 并不是必须项。

其中&＃xff0c;title, description, param, export 则是基础内容&＃xff0c;需要完善&＃xff0c;而 param 则是针对函数中参数内容的注释。

&＃64;return   用于解释函数的返回内容

&＃64;importFrom 则是至关重要的内容

例如&＃xff1a;

#&＃39; &＃64;importFrom  utils read.table

read.txt function(text,header &＃61;  T,...) {
  return(read.table(text &＃61; text, header &＃61; header,...))
}


函数中使用到了除 base 包以外的函数&＃xff0c;均需要通过 &＃64;importFrom 进行指明&＃xff01;

格式为&＃xff1a;&＃64;importFrom pkgname funtion1 function2 function3 ...

编写完成&＃xff0c;保存后&＃xff0c;下面进行自动生成相关信息的操作&＃xff1a;

> rm(list &＃61; ls())
> document()
Updating ... documentation
Loading ...
Writing NAMESPACE
Writing NAMESPACE


document() 用于生成相关的内容&＃xff1a;完善 NAMESPACE 文件以及 man 文件夹下的 rd 文件&＃xff0c;但在此之前&＃xff0c;必须保证当前环境不与所创建的包中的函数相冲突。所以建议习惯性执行&＃xff1a;rm() 操作。

---end---