发布日期: 2022-01-12

更新日期: 2024-10-20

workflowr是干什么的，特性，优点等直接到官方指南上看，跳过啦！

# 安装
install.packages("workflowr")

另外需要 git 进行版本控制。

准备工作完成后，打开 Rstudio，官方建议以下命令都在 R console(控制台)中运行，不要用 Rmarkdown。

library(workflowr)

start the project, 开启项目

在创建项目前，注意目标路径，以下命令会在当前工作目录下创建

wflow_start("myproject")

可以通过setwd()设置工作路径，或者对wflow_start设置 directory 参数。

创建的myproject/目录结构：

myproject/
├── .gitignore
├── .Rprofile
├── _workflowr.yml
├── analysis/
│   ├── about.Rmd
│   ├── index.Rmd
│   ├── license.Rmd
│   └── _site.yml
├── code/
│   ├── README.md
├── data/
│   └── README.md
├── docs/
├── myproject.Rproj
├── output/
│   └── README.md
└── README.md

其中，analysis/ 和 docs/是两个必要的子文件夹：

analysis/: 这个目录里面包含了该项目所有执行数据分析的Rmarkdown源文件，index.Rmd文件是初始化产生的，用来产生网页主页index.html。_site.yml可用来编辑主题、导航栏和其他的页面布局，详情参考: R markdown websites.
docs/:这个目录里面包含了该项目所有生成的 HTML 文件。HTML 文件基于 analysis/里面的 Rmarkdown 文件创建的。另外，Rmarkdown 文件创建的 figures图片，都会保存到这里，保存模式为：docs/figure/<insert Rmd filename>/<insert chunk name>-#.png.

_workflowr.yml用来检查所有Rmarkdown文件的可重复性。最重要的一个设置就是knit_root_dir,默认是.，如果只想执行 analysis/中的代码，改成knit_root_dir: "analysis"就好了。更多细节见?wflowr_html

❗warning: myproject.Rproj不要删除，即使没有使用Rstudio。

可选的子文件夹是：

data/：存放原始文件
code/：存放各种脚本
output/：可存放处理/预处理的文件，如代码生成的中间文件，以及其他途径产生的数据文件

build the website，创建网页

目前docs/还是空，因为还没有生成HTML文件。所以接下来要做的就是创建网页。

wflow_build()

这条命令为所有analysis/中的 Rmd 文件创建对应的 HTML 文件, 存放到 docs/中。每个文件都是使用其自己的 R session，从而避免了不同文件中相同名字变量的冲突。
最后，会在Rstudio viewer 或默认的浏览器打开生成的网页，默认是打开 index.html 。
每次重建网页，都只会针对有改动的文件，没有改动则不会重新生成 HTML 文件。除非设置参数republish = TRUE(没必要)。

publish the website，公开网页

workflowr 与 Rmarkdown 最大的一点不同，就是可以 publish。
查看 workflowr project 的状态：

wflow_status()

## Status of 3 Rmd files
## 
## Totals:
##  3 Unpublished
## 
## The following Rmd files require attention:
## 
## Unp analysis/about.Rmd
## Unp analysis/index.Rmd
## Unp analysis/license.Rmd
## 
## Key: Unp = Unpublished
## 
## The current Git status is:
## 
##    status substatus                 file
##  unstaged  modified   analysis/about.Rmd
##  unstaged  modified   analysis/index.Rmd
##  unstaged  modified analysis/license.Rmd
## 
## To publish your changes as part of your website, use `wflow_publish()`.
## To commit your changes without publishing them yet, use
## `wflow_git_commit()`.

输出显示了文件 published 的情况。

接下来就是对analysis/里面的文件进行 publish

wflow_publish(c("analysis/index.Rmd", "analysis/about.Rmd", "analysis/license.Rmd"),"Publish the initial files for myproject")

主要设置是文件和 message两个参数。
对输出结果的主要进行了摘录，如下：

## **Step 1: Commit analysis files**
## Summary from wflow_git_commit
## The following was run: 
## 
##   $ git add analysis/index.Rmd analysis/about.Rmd analysis/license.Rmd 
##   $ git commit -m "Publish the initial files for myproject" 
## 
## The following file(s) were included in commit 5c625e2:
## analysis/about.Rmd
## analysis/index.Rmd
## analysis/license.Rmd
## 
## **Step 2: Build HTML files**
## Summary from wflow_build
## Settings:
##  combine: "or" clean_fig_files: TRUE
## 
## The following were built externally each in their own fresh R session: 
## 
## docs/index.html
## docs/about.html
## docs/license.html
## 
## **Step 3: Commit HTML files**
## Summary from wflow_git_commit
## The following was run: 
## 
##   $ git add docs/index.html docs/about.html docs/license.html docs/figure/index.Rmd docs/figure/about.Rmd docs/figure/license.Rmd docs/site_libs docs/.nojekyll 
##   $ git commit -m "Build site." 
## 
## The following file(s) were included in commit fd97598:
## docs/about.html
## docs/index.html
## docs/license.html
## docs/site_libs/bootstrap-3.3.5/
## docs/site_libs/header-attrs-2.11/
## docs/site_libs/highlightjs-9.12.0/
## docs/site_libs/jquery-3.6.0/
## docs/site_libs/navigation-1.1/

publish 命令办了三件事：

step1. R 的 git commit 保存 Rmd 文件
step2. build HTML 文件
step3. git commit 创建的 HTML 文件和网页的配置文件（如 CSS 和 JavaScript 文件）

省的自己手动逐步执行，保证了网页和源码一直是同步的。
当再次使用wflow_status()查看 workflowr project 状态时，就会报告所有文件都 published 和 up-to-date：

## Status of 3 Rmd files
## 
## Totals:
##  3 Published
## 
## The current Git status is: working directory clean
## 
## Rmd files are up-to-date

*deploy the website，部署网页

如果需要公开到 GitHub，还需有GitHub的账户，并在本地进行配置（官方指南有详细说明）。
这和把文件上传到GitHub本质上是一样的，只不过在workflowr中有其自己的命令。
因为我是不打算上传到 GitHub 的，所以这一部分也跳过了。

可以将 index.html 文件加到 nginx 或者 apache 等服务器代理中，分享给在同一个局域网中的其他人。

add a new analysis file，添加新的分析文件

自己在analysis/文件夹中创建新的 .Rmd 文件进行编辑就好了，或者使用命令wflow_open("analysis/new.Rmd")。
为了更方面地导航到新的分析文件，你可以在 index page 中加上链接。首先，打开analysis/index.Rmd，然后在其中合适的位置加入链接，如下：

Click on this [link](first-analysis.html) to see my results.

所以，平时使用的时候，流程很简单：

wflow_start("ProjectName")开启项目
在analysis/、code中增加分析流程
wflow_build()预览网页效果（可选）
循环2、3步，直到满意
wflow_publish(files, "commit-message") 保留阶段性成果
修改 index.Rmd 文件，将新的分析文件加入到 index.html 中
如果你要上传到GitHub上，再push到GitHub

有用链接

关于rstudio的一些快捷键
 html document 设置html
free themes of bootstrap 爱折腾主题的来看这里

*个人经验

在写 .Rmd 时注意：

注意设置 setup 中的 knitr options:

```{r setup, include=FALSE}
  knitr::opts_chunk$set(
    echo = FALSE, message = FALSE, warning = FALSE
    )
```         '

之前使用 jupyter 有个习惯：每段数据处理的代码最后，都会 head(data) 看一下数据结构。但在 workflowr 中生成网页时，尤其是设置代码不可见，突然出现的数据会让别人看得一头雾水。所以，在 workflowr 中避免这样的操作
R markdown 中想要插入 bash ，或其他类型的代码（如 python），并且不想运行它，仅仅是做个记录，可以这样写:
```
```bash
ls ./
```         '
```
这实际上就是 markdown 的书写方式；
如果写成 {bash}，在创建网页时也会运行。在 Windows 下面这样往往会产生错误
代码标记符 ``` 顶格写和不顶格写形成的网页效果是不一样的。建议顶格写，会形成一个代码框出来，类似这种：
```
顶格写 ```是这种效果
```
而不顶格效果类似这种：不顶格长这样。
在 analysis中写 .Rmd 时，运行 R 代码块，位置是在 analysis/ 下，而在生成网页的时候，工作路径是在 Project 下面，也就是在 analysis/ 上一层（最顶级的目录），这样产生的一个问题就是：在写 .Rmd 的时候，导入，比如 output/input.csv 中的文件，要写为 ../output/input.csv，运行代码块正常，而当生成网页的时候，这样写会报错，正确的路径为 output/input.csv。所以在创建网页前，要将 ../ 删除；
而在 .Rmd 中插入图片的时候，比如 docs/figure/outer-image/image1.png，要写为 ../docs/figure/outer-image/image1.png 。确实有些困扰。（问题已解决，见关于r：使用opts_chunk $ set(root.dir =…)在knitr中设置工作目录不起作用）

首先这个问题的根源是执行目录的不同：Rmd 文档本身在 analysis/，而进行 build 或 public 的时候是在 console，也就是 project 的 root 下。
所以解决办法就是在 Rmd 内部设置全局更改工作路径：

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE
                     , comment = NA
                     , warning = FALSE
                     , error = FALSE
                     , message = FALSE
                     , tidy = TRUE)

knitr::opts_knit$set(root.dir = rprojroot::find_rstudio_root_file()) #设为本项目的根目录```

建议在写 .Rmd 的时候，每个 part 分成：目的，实现代码，结果；类似这种三段式结构，将目的和最终结果呈现给决策者/老板。
Rmarkdown 中链接文件时，要将文件放在 docs/或其子文件夹下，否则会找不到文件，链接失败。

梁绍波

https://liangshaw.github.io/2022/01/12/workflowr-learning/

本博客所有文章除特別声明外，均采用 CC BY 4.0 许可协议。转载请注明来源梁绍波 !

R workflowr

R数据科学，第五部分：沟通

这一部分包含了 Rmarkdown 和多样化的输出结果，以更好地向他人展示和交流结果

2022-01-13 R for data science

R data science handbook

R数据科学，第一部分：探索

第一部分主要是R入门和 ggplot2 的基础, 其中 dyplr 包的几个函数还是非常实用的。由于之前已经走过一遍《R数据可视化手册》，所以这里并没有消耗太多精力。

2022-01-11 R for data science

R data science handbook

workflowr 日常使用简易指南

start the project, 开启项目

build the website，创建网页

publish the website，公开网页

*deploy the website，部署网页

add a new analysis file，添加新的分析文件

further reading，进一步了解

有用链接

*个人经验