How to Submit Your R package to CRAN!

How to Submit Your R package to CRAN!

After two days of tireless submission, I finally received the passed reply at noon today!

The process of submission

I’ve tried to write a lot messy R packages, all left on my GitHub @czxa. These R packages are so unstable that they can’t be installed on other people’s computer. In recently months, I have tried to rewrite them, but I haven’t done it yet. An important part of this work if translate all Chinese into English(really tired, feeling like work for foreigners).

The ‘hwordcloud’ package was build based on ‘htmlwidgets’ . By binding ‘Highcharts’ charting library, hwordcloud provides a simple way to draw word clouds in R. Notice that Highcharts is a commerical JavaScript charting library, which offers both a commerical license as well as free non-commerical license. Please review the licensing options and terms before using this software, as this package license neither provides nor implies a license for Highcharts.

As my first submission on CRAN, I feel so excited that I couldn’t wait to write down this blog to share my experience and lessons in the process of submission.

I developed the R Package using RStudio.

Note 1: Don’t use Chinese in R packages.

Chinese may be considered as ‘non-ASCII’ characters. This means your packages can’t be installed on Windows OS.

After your packages is written, it can be checked by RStudio.

Before checking, Configure the building tool. Fill Check Package - R CMD check additional options with --as-cran, which means to check in accordance with CRAN requirements. Then click ‘OK’.

Come back to the main panel of RStudio, click Check to check your R package, The best result is 0 errors ✔ | 0 warnings ✔ | 0 notes ✔. Errors are unacceptable. If there are any errors. I’m sure it can’t pass CRAN’s pre-check.

No errors in the result of the check doesn’t mean that it’s truly no problem. Further check need to be carried out next.

Next, Build Source Package. It can be operated on interface or use the following commands:

R
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"

The last line of results tells you where ‘hwordcloud_0.1.0.tar.gz’ is.

Open your terminal, run:

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

The result is:

Shell
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.

This is a warning result, it was because I just submitted version 0.1.0. However, before this submission, the result is a NOTE message.

This check also generates a folder named hwordcloud.Rcheck. There is a hwordcloud-manual.pdf in it, which is your package document. If you use Chinese in your Packages, the compilation of this PDF document will fail. There is also a 00check.log file it, which is a log file. You can find detailed errors, warnings and notes of the check.

Next, Submit the package source to CRAN: https://cran.r-project.org/submit.html

Submit step by step:

After finishing step 3, you will receive a email from CRAN in 10 minutes to six hours, this email is to let you confirm your submission.

Click on this link to confirm your submission:

After about a minute, you will receive a feedback email.

Continue to wait. Next, CRAN will run a pre-check on your submitted packages. This pre-check is more stringent than the check just made at our terminal, mainly checking iterms in Description file. It should be noted that:

  1. The title iterm should be in title-format, for example: Rendering Word Clouds;
  2. The Description should contains more than one sentence, without any spelling errors. Package names, software names and API names should be enclosed in single quotation marks, just like the response I received:

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

  1. Because the function in my package runs as an interactive graph, I need to enclose it in the following form:
R
1
2
3
if(interactive()){
your example code
}
  1. “Please ensure that you do not install packages in your functions without the user’s permission.” This is very important, it is a guarantee of open source software security. Other R packages used in your R functions or vignettes shou be import or suggest in DESCRIPTION file, such as mine:
1
2
3
4
5
6
7
8
9
Suggests:
knitr,
rmarkdown
VignetteBuilder: knitr
Imports:
htmlwidgets,
wordcloud2,
shiny,
colourpicker
  1. The format of license file. You need to declare the license in the DESCRIPTION file, such as mine: License: MIT + file LICENSE. Correspondingly, There is a license file in your package with contents like following:
1
2
YEAR: 2019
COPYRIGHT HOLDER: Zhenxing Cheng

That’s all. I’ve finally become one in ten thousand of CRAN, and I’m honored to have these cute tags:

This first one is generated by using Travis deployment, and the second one is the lastest version of this package on CRAN. The last three will show the downloads of this package through CRAN.

The page link of the ‘hwordcloud’ package on CRAN is: hwordcloud @CRAN

The Package document link of this package is: hwordcloud.pdf

I also wrote a vignette to introduce the basic usages of this packages: Rendering Word Clouds

Now, you can just use install.packages("hwordcloud") to install this package!

Tutorials for ‘hwordcloud’

Installation

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

A very simple example:

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

I built nine themes in the package: darkgreen/darkblue/avocado/darkunica/gray/gridlight/grid/sandsignika/sunset, for example, theme grid:

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

You can explore the rest by yourself.

As for other parameters, here is a complete example:

R
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")

To present the usage of ‘hwordcloud’ intuitively, I wrote a simple shiny applications, you can run it by executing following codes:

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

In fact, I also wrote a Chinese vignette, see: 使用R和HighCharts渲染词云图.

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

You can get Chinese shiny application by running following codes:

R
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)

Welcome to install and provide suggestions for further improvement.

# R

Comments

Your browser is out-of-date!

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

×