使用 RMarkdown 的 child 参数，进行文档拼接。
这样拼接以后的笔记方便复习。
相关问题提交到 GitHub

本文主要介绍了R开发包的内容，主要需要了解几个相关内容

Git 和 Github相关
devtools包(???)的相关函数

建议在一个已经完成的包上进行学习，copy 函数、vignette等。

knitr::opts_chunk$set(eval=F)

1 首次准备工作

下载Git
打开Git Bash
输入pwd，查看当前路径
更改路径，cd d:/lijiaxiang，就是更改到D盘lijiaxiang这个文件夹
git clone https://github.com/JiaxiangBU/add2md，会在当前文件夹内产生一个add2md文件夹，这就是我们现在一起开发的包
点击.Rproj文件
command + . 打开文件DESCRIPTION，修改author，加上自己。
1. 这里建议在Github修改，比较友好，少代码。
2. 在Git Bash ，
  1. cd add2md
  2. git status
  3. git add -A
  4. git commit -m 'add author name'
  5. git push，第一次记得输入账号和密码
    1. 免密码的方式，参考博客
git config 设置下自己的邮箱和名字

devtools::install_github('JiaxiangBU/add2md')
devtools::install_github('JiaxiangBU/add2md@m-func')

@m-func是我们使用Git开发包，master是branch的主线，m-func是另外一个branch，主要做预发布。

2 快速创建包

devtools::create函数可以直接完成，path为包的名称。(???)

一个包的建立最少分为五个步骤。(???)

create()
document() - help 文档
test()
build()
check()

3 使用`dump`录入函数

# What is in the R directory before adding a function?
dir("datasummary/R")

# Use the dump() function to write the numeric_summary function
dump("numeric_summary", file = "datasummary/R/numeric_summary.R")

# Verify that the file is in the correct directory
dir("datasummary/R")

我们也可以新建.R，把函数复制粘贴，但是这样的话，比较费时费力。可以尝试使用dump函数完成，在测试函数成功后，进行。 (???)

4 测试函数

写完函数后，需要去测试，这时候不需要git push后去下载，而是 devtools::load_all()就好，并且load的函数，不是在global中，放心使用。 STAT545

使用快捷键

shift + alt + L

5 `use_testthat()`

This will create a tests directory that contains:

A script testthat.R.

A directory testthat. You save your tests in the tests/testthat/ directory in files with filenames beginning with test-. So, for example, the simutils package has tests named:

test-na_counter.R

test-sample_from_data.R [(???),

Setting up the test structure | R ]

6 help 文档模版

STAT545

#' Get a badge for the download count of your package
#'
#' Input your github name and repo name,
#' this function will feedback the download count of your package.
#'
#' @param your_github_name character
#' @param your_github_repo character
#' @param type character
#'
#' @return character
#' @export
#' @examples
#' add2blog::badge_download(
#' your_github_name = 'JiaxiangBU'
#' ,your_github_repo = 'add2prep'
#' ,type = 'total')

badge_download <- function(
    your_github_name = 'JiaxiangBU'
    ,your_github_repo = 'add2prep'
    ,type = c('total')
){
    glue('  [![GitHub All Releases](https://img.shields.io/github/downloads/{your_github_name}/{your_github_repo}/{type}.svg)](https://github.com/JiaxiangBU/add2prep)') %>%
        print
    glue('<<<Copy it above nto your README.md>>>>')
}

6.1 解读模版

#' Title goes here
#'
#' Description goes here
#'
#' Details go here

(???, * A simple function header | R)

如果没有@export，那么这个函数是不会打首字母被联想输入的，因为直观上表示包的作者不想使用者使用这个函数。这种函数的调用不能通过library包或者package::的方式调用，而是package:::来调用。

\dontrun{}让例子不跑 37
\code实现latex
\link[packageName]{functionName} 链接其他函数，包的名字需要主要是如果这个函数不是此包的时候。
@seealso 列出一些其他函数，读者会感兴趣。
@notes 加一些备注。
@author Jiaxiang Li \email{alex.lijiaxiang@foxmail.com} 加入作者
@importFrom tidyr gather 只引入函数 [(???),

Additional documentation | R ]

@param的arg后面不要加.因为document后.会作为变量名称的一部分。

6.2 List

#' \itemize{
#'  \item ID
#'  \item min
#'  \item median
#'  \item sd
#'  \item max
#' }

6.3 包的help文档

?package

#' add2blog: help your blog site
#'
#' The goal of add2blog is to help you build some materials like wall paper for your blog website !
#'
#' @docType package
#' @name add2blog
#' @keywords internal
"_PACKAGE"

(???, * Adding package documentation | R)

6.4 给data加help文档

#' blogdown_meta_data blodgown meta data
#'
#' A dataset containing the real blodgown meta data
#'
#' @format A data frame of 287 rows and 6 columns
#' \describe{
#'  \item{dir}{Character}
#'  \item{author}{Character}
#'  \item{categories}{Character}
#'  \item{categories}{Character}
#'  \item{date}{Character}
#'  \item{tags}{Character}
#'  \item{title}{Character}
#' }
#' @source https://jiaxiangli.netlify.com
"blogdown_meta_data"

不要忘记最后一个。

7 加入数据

R package 为了举例，需要加入举例的数据集，使用 devtools::use_data(x, mtcars)完成，具体见 Data · R packages

8 加入 Vignettes

build_articles会读取文件夹vignettes内的所有.Rmd文档，建立一个新文件夹articles，内含.html，用于展示具体见pkgdown

9 加入 link

> use_github_links()
✔ Setting active project to '/Users/vija/Downloads/180805_folder_01/tmp_jli/trans/projIN/add2evaluation'
✔ Setting URL field in DESCRIPTION to 'https://github.com/JiaxiangBU/add2evaluation'
✔ Setting BugReports field in DESCRIPTION to 'https://github.com/JiaxiangBU/add2evaluation/issues'

10 加入 MIT

use_mit_license("Jiaxiang Li")

11 加入需要使用的包

注意一次加一个包 (Misha Balyasin)

library(usethis)
use_package("dplyr", "data.table")
use_package("dplyr", "data.table",type = "Suggests")

11.1 Depends 和 Imports 的区别

In the majority of cases, you should only list the version of R required in the Depends field and the package in the Imports field. (???, * Depends or imports? | R)

12 加入 badge

use_lifecycle_badge('experimental')

参考 (???) 可以按照不同阶段给包安装不同的徽章。具体可以参考 Lifecycle badges - Tidyverse

> use_travis()
✔ Writing '.travis.yml'
✔ Adding '^\\.travis\\.yml$' to '.Rbuildignore'
● Turn on travis for your repo at https://travis-ci.org/profile/JiaxiangBU
● Add a Travis build status badge by adding the following line to your README:
Copying code to clipboard:
  [![Travis build status](https://travis-ci.org/JiaxiangBU/add2blog.svg?branch=master)](https://travis-ci.org/JiaxiangBU/add2blog)

参考 Carl Boettiger

add2blog::badge_download()

13 加入 Travis CI

Travis CI (continuous integration) is A way of running checks every time you update your code. (???, * Setting a package up for using Travis | R)

14 加入 vignette

use_vignette("intro")

"intro"是名字，可以自定义。参考 Carl Boettiger

15 修改 Description

options(
  usethis.name = "Jiaxiang Li",
  usethis.description = list(
    `Authors@R` = 'person("Jiaxiang", "Li", email = "alex.lijiaxiang@foxmail.com", role = c("aut", "cre"))',
    License = "MIT + file LICENSE",
    Version = "0.1.0"
  )
)

16 namespace

这是R自动生成的文件，建议不要乱修改。

getwd()
list.files('../picbackup')

17 使用 `.Rmd` Readme

use_readme_rmd() 参考 Carl Boettiger

18 NEWS.md 作用

$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   .RData
        modified:   .Rhistory

no changes added to commit (use "git add" and/or "git commit -a")
$ git checkout .RData
$ git checkout .Rhistory

(???) 建议每一次改动、新增函数、新增vignette，都标注。并且，版本更新按照从高到低排序，这样方便使用者阅读。

19 Git 使用注意事项

数据量太大，git push会失败，并反馈，主要重新进行Git 命令即可进行。

19.1 Can’t do a git pull

error: The following untracked working tree files would be overwritten by merge:
<myFileName>
Please move or remove them before you can merge.

git clean -dn
git clean -df

参考 Stack Overflow

19.2 超过1000个文件

Sorry, we had to truncate this directory to 1,000 files. 6 entries were omitted from the list.

只是展示列表中不会显示超过1000的多余文件，但是文件不会被删除。 (Github)

19.3 撤销修改

$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

        modified:   .RData
        modified:   .Rhistory

no changes added to commit (use "git add" and/or "git commit -a")
$ git checkout .RData
$ git checkout .Rhistory

19.4 跳过检验

$ git commit -m 'knit readme rmd'
README.Rmd and README.md should be both staged
use 'git commit --no-verify' to override this check

报错如上。 git commit --no-verify -m "commit" 就可以跳过代码检查。参考博客园

19.5 上传 100 MB 文件

需要 git lfs
测试 push 单位上传速度明显下降
超过1GB的大文件总储存量，需要收费因此长期方案是拆分数据集在50MB以下。

代码执行参考

git lfs track "your_file"
git add
git commit -m 
git push

主要参考 CSDN社区的文章。

因此如果大文件如果是.csv文档，建议进行一定程度的压缩。这里使用Hadley Wickham 开发的feather包，可以将数据压缩到一半以上，参考的代码如下。

creditcard <- fread(here::here('data','creditcard.csv'))
creditcard %>% 
    feather::write_feather(here::here('data','creditcard.feather'))
creditcard2 <- feather::read_feather(here::here('data','creditcard.feather'))
setequal(creditcard,creditcard2)
# [1] TRUE

然后将之前错误的100MB 记录删除参考 Stack Overflow

git filter-branch --tree-filter 'rm -rf path/to/your/file' HEAD

git filter-branch --tree-filter 'rm -rf data/creditcard.csv' HEAD

这一步耗时也非常长，因此不建议经常上传大文件。

$ git filter-branch --tree-filter 'rm -rf data/creditcard.csv' HEAD
Rewrite cc99ca814f02eaef4d05a419c5fbd179b22b5316 (1/12) (1 seconds passed, remaiRewrite 04aecba01e088bd3f6018111476684f39f65c17c (1/12) (1 seconds passed, remaiRewrite ada96dff71f7f63b14fca5fd83aeb4176ac00ace (3/12) (22 seconds passed, remaRewrite c3ba0ab0615483a0d8cedf53fb8aab61535533e6 (4/12) (34 seconds passed, remaRewrite 234f341434c177b8a6fb04162ed15ed859dbc3ff (5/12) (46 seconds passed, remaRewrite dad387eda4ac1c2681d7d3710a049b43ea099a32 (6/12) (59 seconds passed, remaRewrite de483472bce9e9b6c18c84ce46aa33cee17a1e32 (7/12) (70 seconds passed, remaRewrite 229764d3b115d3adfe9a98a61a45fa99c3eb5537 (8/12) (82 seconds passed, remaRewrite 88ae0043da98ce78dce3a4f93dc684dab0e7eb6d (9/12) (96 seconds passed, remaRewrite 17810ac414a4bdb32723a2d36252bff8bcf7a132 (10/12) (106 seconds passed, reRewrite 1ae5fb3512033e877e179a8b403861572c1e9635 (11/12) (120 seconds passed, reRewrite 49ca72801f3f4d288c93cfa51000ae427a7aba4f (12/12) (136 seconds passed, remaining 0 predicted)
Ref 'refs/heads/master' was rewritten

然后需要 git pull

$ git pull
fatal: refusing to merge unrelated histories

这个时候需要对 unrelated histories 进行处理参考 CSDN社区

git pull origin master --allow-unrelated-histories

19.6 上传 50 MB 文件

安装 git lfs 即可但是传的很慢参考 [Github]](https://help.github.com/articles/working-with-large-files/)、 CSDN博客

git lfs track "data/creditcard.feather"

如果是小鱼50MB的文件，传输非常快的。

20 版本设置

这是手动设置的 (???, * Description and Namespace files | R)

21 拼写检查

devtools::check() 函数跑的比较慢。 (???)

22 快捷键

console

ctrl + 2
terminal

shift + alt + T

{{< hl-text [info] >}} 测试 {{< /hl-text >}}

23 使用if 判断写函数

# Create numeric_summary() function
numeric_summary <- function(x, na.rm) {

    # Include an error if x is not numeric
    if(!is.numeric(x)){
        stop("Data must be numeric")
    }
    
    # Create data frame
    data.frame( min = min(x, na.rm = na.rm),
                median = median(x, na.rm = na.rm),
                sd = sd(x, na.rm = na.rm),
                max = max(x, na.rm = na.rm))
}

# Test numeric_summary() function
numeric_summary(airquality$Ozone,T)

先判断是否字段一致等的使用。 (???)

24 pkgdown

options(pkgdown.internet = FALSE) 不联网。

24.1 fail to `build_site`

在Github上这个Issue给了临时答案，下一次PR会更新。

remotes::install_github("r-lib/pkgdown#877",force=T)
pkgdown::build_site(new_process = FALSE)

25 `check`

An R package check includes: (???, * Why check an R package? | R)

If the package can be installed

Description information is correct

Dependencies

Code syntax errors

Documentation is complete

Tests run

Vignettes build

26 addins

it’s just allowing you to execute that function through some UI rather than manually writing and executing the function yourself.

参考 RStudio Addins 创建inst/rstudio/addins.dcf文件，可以参考RStudio的例子

27 Github 加入 collaborators

Inviting collaborators to a personal repository - User Documentation

28 安装特定版本的github包

remotes::install_github("ThinkR-open/remedy@e278fc6") 参考github

29 更新功能能够在其他 Rproj 使用

如load_all('../add2md') 那么在当前路径下可以使用更新的功能和函数但是快捷方式在Win7没有更新。

30 上传 R CRAN 官方

参考 (???)

点击官方上传页面，填写相关信息。

这是所有R包的更新列表The Comprehensive R Archive Network 只更新到前一天的数据。因此一般需要等一天。

knitr::include_graphics('/pic/add2md_upload_proof.png')

一般开发会出现报错。

注意需要将原来的文件删除，否则报错不回消除。参考 Stack Overflow

其中 WARINGS也是需要修改的

31 import pipeline

importFrom(magrittr,"%>%") 参考 Stack Overflow

32 版本控制

版本控制编码参考 Semantic Versioning 2.0.0

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

主版本号：当你做了不兼容的 API 修改，
次版本号：当你做了向下兼容的功能性新增，
修订号：当你做了向下兼容的问题修正。

使用use_version完成

> use_version()
✔ Setting active project to 'D:/work/add2md'
Error: Uncommited changes. Please commit to git before continuing.

Commit 完修改后，下面的code会自动commit

> use_version()
Current version is 0.2.7.
Which part to increment? 

1: major --> 1.0.0
2: minor --> 0.3.0
3: patch --> 0.2.8
4: dev --> 0.2.7.9000

Selection: 3
✔ Setting Version field in DESCRIPTION to '0.2.8'
✔ Checking into git [Increment version number]

use_version参考，自动commit的函数。

33 importFrom

不要写成

#' @importfrom stringr str_c str_replace_all str_remove

否则会在NAMESPACE中加入包str_c str_replace_all str_remove，这是错误导入，因而导致不能build包。

完成Github Issue

34 加入warning

warning("The request failed")

参考DataCamp

35 加入stop

stop("This is an error")

36 加入 Bibtex

参考 tidyverse/lubridate放到paper/lubridate.bib

直接放到 vignettes 路径 https://github.com/tidyverse/tidyverse/tree/584f43d88d9e62cf53919666638518f3531fc10a/vignettes

37 dontrun

\dontrun{} 还是不run的，但是表现是这样的，好奇怪。 http://r-pkgs.had.co.nz/man.html

image

正常应该这样