如何将自己的R包提交到CRAN上!

如何将自己的R包提交到CRAN上!

经过两天不厌其烦的提交,终于在今天中午收到了通过的回复!

提交经过

我曾经试图写过很多渣渣的 R 包,都丢在我的 GitHub @czxa 上,这些 R 包极不稳定,甚至不能在别人的 Windows 电脑上安装。最近几个月试图整理了一波,至今还没整理完。这其中的一个重要环节是把包里的中文全部换成英文(真心累,感觉是在给老外打工)。

‘hwordcloud’ 包是基于 ‘htmlwidgets’ 开发的一款用于绘制交互式词云图的 R 包。其中使用了 ‘Highcharts’图表库,该图表库是一个商业的 JavaScript 图表库,但是 Highcharts 同时也提供了免费的非商业使用许可。因此,在使用本软件前请留意相关的许可条款。

第一次将自己的作品提交到 CRAN 上,我感到非常的激动,因此迫不及待地写下这篇推文分享自己在提交过程中的经验和教训。

我是使用 RStudio 开发的这个包:

第一条注意事项:不要使用中文。
中文可能会被认为是 ‘non-ASCII’。这意味着你的 R 包不能在 Windows OS 上安装。

R 包编写完成之后首先可以使用 RStudio 右下角的 check 进行检查。首先配置构建工具:

Check Package - R CMD check additional options 里填写: --as-cran。表示按照 CRAN 的要求进行检查。然后点击 OK

回到 RStudio 主界面点击 Check 对编写的 R 包进行检查,最优的状态是 0 errors ✔ | 0 warnings ✔ | 0 notes ✔。绝不能有错误和警告,否则肯定通不过 CRAN 的预检查的。

这项检查没有问题并不代表真的没问题,接下来进行进一步检查,下面 Build Source Package,可以在界面上操作,也可以使用下面的命令:

1
2
3
4
5
6
7
8
9
10
11
devtools::build()
#> ✔ checking for file ‘/Users/czx/Documents/我的项目/hwordcloud/DESCRIPTION’ (495ms)
#> ─ preparing ‘hwordcloud’: (402ms)
#> ✔ checking DESCRIPTION meta-information ...
#> ─ installing the package to build vignettes
#> ✔ creating vignettes (4.7s)
#> ─ checking for LF line-endings in source and make files and shell scripts
#> ─ checking for empty or unneeded directories
#> ─ building ‘hwordcloud_0.1.0.tar.gz’

#> [1] "/Users/czx/Documents/我的项目/hwordcloud_0.1.0.tar.gz"

最后一行结果是生成的 Source Package 的位置。

下面打开终端,运行:

1
R CMD check /Users/czx/Documents/我的项目/hwordcloud_0.1.0.tar.gz --as-cran

然后终端中显示的结果的最后是:

1
2
3
4
5
6
7
8
9
10
11
* checking CRAN incoming feasibility ... WARNING
Maintainer: ‘Zhenxing Cheng <[email protected]>’

Insufficient package version (submitted: 0.1.0, existing: 0.1.0)

······

Status: 1 WARNING
See
‘/Users/czx/Documents/我的项目/hwordcloud/hwordcloud.Rcheck/00check.log’
for details.

这是因为我刚刚提交了 0.1.0 版本,所以再对这个版本的 R 包进行 CRAN 检查就会被警告和 CRAN 上的 R 包冲突了。不过在提交之前我进行这一步检查的时候的结果是一个 NOTE,不过这个 NOTE 仅仅是提醒我 Maintainer: ‘Zhenxing Cheng <[email protected]>’。这个NOTE不会让你的 R 包被否掉。

执行该项检查还会获得一个 hwordcloud.Rcheck 文件夹。里面有一个 hwordcloud-manual.pdf 文件,这个文件就是你的包文档了,如果你的包里面有中文,这个文档的编译是会失败的。还有一个 00check.log 文件,这个是刚刚执行的检查的日志文件,可以在里面找到详细的错误、警告或注意事项。

检查完毕并不代表你的 R 包就没问题了。下面开始提交给 CRAN,提交链接是: https://cran.r-project.org/submit.html

一步步提交就好,提交完成之后:

在 10min ~ 6h 内你会收到一个邮件问题你是否确认提交:

点进这个链接,确认提交即可:

大约一分钟之后会收到一条反馈邮件,接下来继续等待,下一步 CRAN 会运行预检查程序。这个预检查比刚刚在终端进行的检查要严格一些,主要是检查 DESCRIPTION 文件里面的一些东西。这里面需要注意:

  1. title 需要使用英文 title 的格式,例如我的:Rendering Word Clouds;否则会被拒;
  2. Description 不能只用一句话、不能出现拼写错误,包名、软件的名字和API的名字应该用单引号括起来,就像我提一次被人工检查否掉的时候收到的回复:

Please write package names, software names and API names in single quotes (e.g. ‘shiny’) in your Description.

  1. 函数示例中的代码应该这样括起来:

    1
    2
    3
    if(interactive()){
    your example code
    }
  2. “Please ensure that you do not install packages in your functions without the user’s permission.” 这个非常重要,是一个开源软件安全性的保证。包内函数和小品文中使用的其它 R 包应该在 DESCRIPTION 文件中被 ImportSuggest,例如我的:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    Suggests:
    knitr,
    rmarkdown
    VignetteBuilder: knitr
    Imports:
    htmlwidgets,
    wordcloud2,
    shiny,
    colourpicker
  3. 许可证文件的格式。在 DESCRIPTION 文件中需要声明许可,例如我的是 License: MIT + file LICENSE,对应包里有个 LICENSE 文件,这个文件的内容应该是:

1
2
YEAR: 2019
COPYRIGHT HOLDER: Zhenxing Cheng

大概就是这些注意事项了!我也终于成为了 CRAN 的万分之一了,我也终于光荣的拥有这些可爱的小标签了,其中第一个是使用 travis 部署产生的,第二个是这个包在 CRAN 上的最新版本。后面三个是会显示这个包通过 CRAN 的下载量。

‘hwordcloud’ 包在 CRAN 上的页面链接是: hwordcloud @CRAN

‘hwordcloud’ 包的 pdf 文档链接为: hwordcloud.pdf

我还写了一篇小品文介绍这个包的使用: Rendering Word Clouds

这也意味着,可以直接使用 install.packages("hwordcloud") 安装该包了!

‘hwordcloud’ 的使用教程

安装

1
2
3
install.packages("hwordcloud")
# 或者
devtools::install_github('czxa/hwordcloud')

一个最简单的示例:

1
2
3
4
library(hwordcloud)
library(wordcloud2)
df <- head(demoFreq, 50)
hwordcloud(text = df$word, size = df$freq)

我在函数里内置了九款主题:darkgreen/darkblue/avocado/darkunica/gray/gridlight/grid/sandsignika/sunset,例如 grid 主题:

1
2
3
hwordcloud(text = df$word, size = df$freq,
width = "100%", height = "600px",
theme = "grid")

其它的主题我不再一一展示。

其它参数的使用。一个比较完整的示例:

1
2
3
4
5
6
7
8
9
10
11
hwordcloud(text = df$word, size = df$freq,
width = "100%", height = "400px",
theme = "sunset",
title = "Word Cloud",
titleAlign = "center",
titleColor = "#333333",
titleSize = "20px",
subtitle = "czxa.top",
subtitleColor = "#666666",
subtitleAlign = "center",
subtitleSize = "16px")

为了直观的展示该包的用法,我还特意编写了一个 shiny 应用放在包里,运行下面的代码即可启用:

1
2
3
dir <- system.file("examples", "hwordcloud", package = "hwordcloud")
setwd(dir)
shiny::shinyAppDir(".")

其实我还制作了中文版本的使用介绍,参见使用R和HighCharts渲染词云图。例如:

1
2
3
4
library(hwordcloud)
library(wordcloud2)
df <- head(demoFreqC, 50)
hwordcloud(text = df$V2, size = df$V1)

同样运行下面的代码可以使用中文版本的 shiny 示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
#
# This is a Shiny web application. You can run the application by clicking
# the 'Run App' button above.
#
# Find out more about building applications with Shiny here:
#
# http://shiny.rstudio.com/
#
library(shiny)
library(colourpicker)
library(wordcloud2)

# Define UI for application that draws a histogram
ui <- fluidPage(

# Application title
titlePanel("词云示例"),

# Sidebar with a slider input for number of bins
sidebarLayout(
sidebarPanel(
selectInput(
inputId = "theme",
label = "选择一个主题:",
choices = c("darkgreen",
"darkblue",
"avocado",
"darkunica",
"gray",
"gridlight",
"grid",
"sandsignika",
"sunset"),
selected = "sandsignika"
),
textInput(
inputId = "title",
label = "输入图表的标题:",
placeholder = "Word Cloud",
value = "词云"
),
selectInput(
inputId = "titleAlign",
label = "图表标题的水平位置:",
choices = c("left", "center", "right"),
selected = 'center'
),
textInput(
inputId = "titleSize",
label = "图表标题的大小:",
placeholder = "20px",
value = "20px"
),
colourInput(
inputId = "titleColor",
label = "图表标题的颜色:",
value = "#333333",
showColour = "background",
allowTransparent = TRUE
),
textInput(
inputId = "subtitle",
label = "输入图表副标题:",
placeholder = "https://www.czxa.top",
value = ""
),
selectInput(
inputId = "subtitleAlign",
label = "图表副标题的水平位置;",
choices = c("left", "center", "right"),
selected = "center"
),
textInput(
inputId = "subtitleSize",
label = "图表副标题的大小: ",
placeholder = "10px",
value = ""
),
colourInput(
inputId = "subtitleColor",
label = "图表副标题的颜色: ",
value = "#666666",
showColour = "background",
allowTransparent = TRUE
),
textInput(
inputId = "iterm",
label = "工具箱里的属性名称:",
placeholder = "数量",
value = "数量"
),
textInput(
inputId = "height",
label = "图表高度:",
placeholder = "500px",
value = "500px"
),
textInput(
inputId = "width",
label = "图表宽度:",
placeholder = "100%",
value = "100%"
)
),

# Show a plot of the generated distribution
mainPanel(
hwordcloudOutput("shinyhwordcloud", height = "500px")
)
)
)

# Define server logic required to draw a histogram
server <- function(input, output) {
df <- head(demoFreqC, 50)
output$shinyhwordcloud <- renderHwordcloud({
hwordcloud(text = df$V2, size = df$V1,
theme = input$theme,
itermName = input$iterm,
width = input$width,
height = input$height,
title = input$title,
titleAlign = input$titleAlign,
titleSize = input$titleSize,
titleColor = input$titleColor,
subtitle = input$subtitle,
subtitleAlign = input$subtitleAlign,
subtitleSize = input$subtitleSize,
subtitleColor = input$subtitleColor
)
})
}

# Run the application
shinyApp(ui = ui, server = server)

欢迎使用并提供改进建议呀!

# R

评论

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×