张金龙的博客分享 http://blog.sciencenet.cn/u/zjlcas 物种适应性、分布与进化

博文

在windows中创建R程序包简明指南(2016年8月15日修订)

已有 23216 次阅读 2009-8-5 16:18 |个人分类:科研笔记|系统分类:科研笔记|关键词:学者| R语言, windows, 程序包

Windows下创建R程序包简明指南


2016815日修订)

张金龙 jinlongzhang01@gmail.com

R软件中CRAN镜像已经有8957个程序包在线发表(截至2016815日),几乎涉及统计编程的所有领域。CRAN上每个程序包都包含源代码以及编译好的Windows MacOS版本,可在多种平台上使用。除了使用CRAN上的R程序包,用户还可以自己编写R程序包。在数据处理中,如果积累了一定量的R函数,最好将为它们准备好帮助文档,并制作成自己的R程序包,便于管理和使用。

那么在Windows环境下如何编写R程序包并提交到CRAN?本文拟简要说明:

Windows下编写R程序包通常包括以下几步:

1.  安装工具软件RtoolsMikTeX并配置启动路径。

2.  利用R中自带的package.skeleton()函数生成R程序包的模板。

3.  填写程序包的DESCRIPTIONNAMESPACERd等模板文件。

4.  R包的编译和检查

下面我们来创建一个简单的R程序包,其中只包含一个函数F2C

1安装工具软件RtoolsMikTeX并配置启动路径1.1 Rtools

Rtools(图1)是在windows下制作R包的一系列工具,其中主要包括MinGW编译器,其中的gccg++, gfortran等可用来编译带有CC++Fortran等语言的R程序包源代码。

下载地址为:https://cran.r-project.org/bin/windows/Rtools/

安装Rtools时,必须允许其修改启动路径(图2),这样之后才能正常使用。安装大约需要3-5min


1 Rtools下载页面,应该以最新版本的为准


2 安装Rtools时应该允许其修改system PATH

1.2 MikTeX

MikTex用来生成PDF帮助文档,R程序包做检查时是必须的(图3)。

下载地址:http://miktex.org/downloadMikTex在使用时会自动安装程序包,所以第一次使用时要保证联网。


3 Mitex在安装中

1.3 设置文件启动路径

设置启动路径的目的是在cmd命令行可以直接调用Rcmd, gcc等命令(找到gcc.exe, Rcmd.exe所在的文件夹,并将其添加到启动路径4)。


4含有Rcmd.exe的文件夹,该文件夹需要添加到PATH

方法如下:

右键点击:我的电脑 > 属性 > 高级 > 环境变量 > 系统变量 PATH一项,点击编辑,在弹出的窗口中,值Variable Value应该含有如下路径(Rgcc Miktex因安装的版本而异):

c:Rtoolsbin;c:Rtoolsmingw_32bin;c:Rtoolsbin;c:Rtoolsgcc-4.6.3bin;C:ProgramFilesRR-3.3.1bini386;C:Program FilesRR-3.3.1binx64;C:ProgramFilesMiKTeX 2.9miktexbinx64;

通常Rtools Miktex等在安装时已经自动配置好启动路径,而R的路径(C:ProgramFilesRR-3.3.1bini386;C:Program FilesRR-3.3.1binx64; )必须手动添加。每个路径与之前一个路径用英文的分号分隔。

2利用package.skeleton()函数生成R程序包模板

假如现在现有R函数F2C,用来将华氏温度转换为摄氏温度, 保存在C:JinlongpackageTEMP.R中。

函数如下所示:

##############################################

F2C <-function(x){

   res <- (x - 32) / 1.8

   return(res)

}

##############################################

则可以用package.skeletons()函数生成R程序包的框架。方法为:

登陆R例如:开始 > 所有程序 > R > R i386 3.3.1

2.1清除内存中的对象

目的是删除R内存中所有不需要的数据或函数:

rm(list=ls())

2.2设定工作目录

这里设定为C:\Jinlong\package

setwd("C:\Jinlong\package")

2.3 导入脚本中的所有R函数

source()函数读取TEMP.R脚本中的所有函数。

source("TEMP.R")

2.4生成R程序包框架

程序包可以命名为TEMP。输入以下命令生成R包的骨架:

package.skeleton(name="TEMP",list = ls())

此时,R控制台中显示:

>setwd("C:\Jinlong\package")

>source("TEMP.R")

>package.skeleton(name="TEMP", list = ls())

Creatingdirectories ...

CreatingDESCRIPTION ...

CreatingNAMESPACE ...

CreatingRead-and-delete-me ...

Savingfunctions and data ...

Makinghelp files ...

Done.

Furthersteps are described in './TEMP/Read-and-delete-me'.

>

可以看到C:Jinlongpackage文件夹下出现了一个TEMP文件夹,该文件夹结构如下:

└─TEMP

   │ DESCRIPTION

   │ NAMESPACE

   │ Read-and-delete-me

   │  

   ├─man

   │     F2C.Rd

   │      TEMP-package.Rd

   │    

   └─R

           F2C.R

           

以上就是R包的框架,包括DESCRIPTIONNAMESPACERead-and-delete-me三个纯文本文件,以及R文件夹,man文件夹。

3. 填写程序包的DESCRIPTIONNAMESPACERd等模板文件。3.1. Read-and-delete-me 文件

该文件主要介绍如何创建R


文件内容如下:

#################################################################

* Editthe help file skeletons in 'man', possibly combining help files for multiplefunctions.

编辑man文件夹中的帮助文件模板

* Editthe exports in 'NAMESPACE', and add necessary imports.

编辑NAMESPACE文件,显示需要导出或者导入的函数。

* Put anyC/C++/Fortran code in 'src'.

C/C++/Fortran 的源代码应该放入src文件夹下

* If youhave compiled code, add a useDynLib() directive to 'NAMESPACE'.

如果含有已经编译好的代码(Windows下是DLL文件),NAMESPACE中需要加入 useDynLib() 标记。

* Run RCMD build to build the package tarball.

创建R程序包使用命令 R CMD build 程序包名称

* Run RCMD check to check the package tarball.

检查R程序包使用命令 R CMD check 程序包名称

Read"Writing R Extensions" for more information.

请阅读编写R扩展的相应信息。

#################################################################

不过,这里的R CMD说的是在Linux的终端输入的命令,实际上在Windows环境中应该输入 Rcmd (见第四节 R包的编译和检查)

3.2 编辑DESCRIPTION文件和帮助文件

DESCRIPTION文件是该程序包的简介,内容如下:

####################################

Package:TEMP

Type:Package

Title:What the package does (short line)

Version:1.0

Date:2016-08-15

Author:Who wrote it

Maintainer:Who to complain to <yourfault@somewhere.net>

Description:More about what it does (maybe more than one line)

License:What license is it under?

#####################################

冒号右边的内容需要修改。其中不能有非ASCII码的字符。

如果程序包中使用了其它程序包的函数或者数据,则应该在Description文件中加入Suggests或者Depends, imports某程序包的选项,详情参见 Writing R Extensions中的 1.1.3 Package Dependencies 一节。编写DESCRIPTION文件的相信指南,请参考 Writing R Extensions 1.1.1 The DESCRIPTION file 一节。

更改后:

Package: TEMP 程序包名称

Type: Package 类型为程序包

Title: Convert Temperature 程序包安装后显示的标题

Version: 1.0 程序包的版本

Date: 2016-08-15 日期,以年月日的格式提供

Author: Jinlong Zhang 作者

Maintainer:Jinlong Zhang <jinlongzhang01@gmail.com>  作者的联系方式

Description:Containing functions for converting temperatures. 程序包的详细功能

License: GPL-2 程序包遵循的版权协议。

3.3 编辑man文件夹中的.rd文件

man文件夹中包含两个文件 F2C.RdTEMP-package.Rd,分别是F2C()函数和TEMP包的帮助文件。

Rd文件的格式与Tex的格式很像。在花括号中输入要更改的内容即可。Rd文件的项目中不能留空,否则在检查时会显示警告。其中title是必须填写的内容。同时要注意:在Rd文件中,不要出现非ASCII码字符,否则在Rcmd check中将不能通过。

F2C.Rd文件:单个%为注释,编译时将直接忽略。两个百分号%%为需要修改的内容,

##############F2C.Rd修改之后###############################

name{F2C}

alias{F2C}

title{

Fahrenheit to Celsius

}

description{

Convert Fahrenheit to Celsius Degrees

}

usage{

F2C(x)

}

arguments{

item{x}{

Fahrenheit in decimal.

}

}

details{

Convert Fahrenheit to Celsius Degreesusing the formula C =(F - 32)/ 1.8

}

value{

Celsius degrees

}

references{

url{http://www.21ic.com/calculator/sheshiwendu.htm}

}

author{

Jinlong Zhang

}

note{

This is just an example

}

examples{

F2C(100)

}

keyword{ Temperature }

keyword{ Fahrenheit }

keyword{ Celsius }

######################################################################

TEMP-package.Rd中帮助文件的填法与F2C.Rd的类似。

4 R包的编译和检查4.1直接在cmd输入命令编译和检查程序包

R 程序包的编译和检查,一般都通过在cmd输入命令。

在开始,运行 cmd的窗口,输入 cd C:JinlongpackageTEMP 转入当前的工作目录(图5)。

键入Rcmd check TEMP TEMP_1.0.tar.gz代码的各项内容进行检查。

键入Rcmd INSTALL --build TEMP 建立Window压缩包

键入Rcmd build TEMP建立源代码压缩包

键入Rcmd INSTALL TEMP 安装到当前的R


5 通过cmd编译TEMP文件夹

4.2 通过.bat文件编译和检查程序包

cmd中输入的命令可以保存在Windows的批处理文件中。下面准备编译或安装R程序包的Windows批处理命令:

(1)点击鼠标右键新建一个纯文本文件,将以下内容拷贝到该文件夹中,重命名为check package.bat

Rcmd check TEMP

PAUSE

双击该bat文件,可以对skycalc程序包中的错误进行检查。

(2)点击鼠标右键新建一个纯文本文件,将以下内容拷贝到该文件夹中,并重命名为build Windows Binary.bat

Rcmd INSTALL --build TEMP

PAUSE

双击该文件,可以建立Windows系统下的R程序包。

(3)点击鼠标右键新建一个纯文本文件,将以下内容拷贝到该文件夹中,重命名为build Linux Source Code.bat

Rcmd build TEMP

pause

双击该文件,可以建立Linux系统下的安装包。

(4)点击鼠标右键新建一个纯文本文件,将以下内容拷贝到该文件夹中,命名为install package.bat

Rcmd INSTALL TEMP

PAUSE

双击该文件,可以安装skycalc到当前的R中。

将以上四个.bat文件,放置到TEMP文件夹所在的文件夹, 双击文件,即可完成程序包的安装,编译和检查等

命令运行完之后可以发现,在c:/pa/文件夹下分别生成了TEMP.zipTEMP_1.0.tar.gz压缩包(图6)。


6. 编译程序包

如果作者希望将自己制作的Package上传到CRAN,则必须要检查gzLinux压缩包,通过R CMD check --as-cranpackage_name.gz,并且其中不能有任何错误或警告。

进一步阅读

https://cran.r-project.org/doc/contrib/Leisch-CreatingPackages.pdf

http://kbroman.org/pkg_primer/  

http://r-pkgs.had.co.nz/

https://www.hsph.harvard.edu/statinformatics/soft/files/buildingrpackages.pdf





https://m.sciencenet.cn/blog-255662-247614.html

上一篇:生物多样性与宏生态学链接(2016年9月5日)
下一篇:统计结果的保存:Sweave in R

2 陈昌春 任文龙

该博文允许注册用户评论 请点击登录 评论 (16 个评论)

数据加载中...
扫一扫,分享此博文

Archiver|手机版|科学网 ( 京ICP备07017567号-12 )

GMT+8, 2024-3-29 15:15

Powered by ScienceNet.cn

Copyright © 2007- 中国科学报社

返回顶部