开放科学：四步流实现研究结果的可再生性

Good Habits to Make your Work more Reproducible

作者：孙丹

声明：文章是个人学习心得，如有错误欢迎指正。

开放与重复(open & replicable) 近年来一直在学术圈广泛讨论，心理学的可重复性危机也已经有多篇文章讨论过。但是质疑可重复性(Replicability)的同时，可再生性(Reproducibility)依旧不可或缺。本文主要从理论与实践两部分来介绍可再生性。

1 

理论(Be reproducible!)

1.1定义

其实一开始的时候，笔者对这两个单词也是经常混着用，区分不了二者的差异。但是在被科普之后，才知道二者还是有本质的区别的。简而言之，

计算水平的可再生性：原始数据 + 原始方法 + 一致的分析环境 = 同样的结果 (computationally Reproducible : original data + original code + same environment  = same results)

可重复性：不同的数据 + 不同的方法 = 同样的结果，这里的前提是针对同一个研究问题，可以是不同的范式，也可以是同样的范式，但是用新一批被试测试 (Replicability: different data + different methods = same research findings)

1.2原因

那么为什么要倡导可再生性呢？

（未来的）自己。翻开自己的某一个课题，你对它的熟悉度，精确度是随着时间变化的。比如独自完成的第一份代码，现在来看，也许会发现有些地方还能完善。如果你的注释不够清晰，那么某些代码甚至要花费点时间才能理解。

 其他人。你需要给导师汇报实验结果，同意公开自己文章对应的数据和代码，又或者将内容分享给你的合作者，来共同完成某个项目等等，都需要保证计算水平的可再生性。

 但是，当代码和数据，甚至运行环境都一致时，你是否能保证这份课题具有很强的可读性，操作明确呢？那么如何养成一个好的习惯，搭建一个可再生性高的课题项目呢？下面将推荐几个有用的工具！

2

工作流(workflow)

2.1设置课题setting up a project

课题结构 (Wilson et al., 2017)

● 一个独立的母文件：每个课题设置独立的文件名，便于区分

●  子文件：不同的文件类型，包括但不限于只读性质的(raw data, read-only)，人为产生的(human-generated: code, paper, documentation)， 课题有关的(project-generated: clean data, figures, models)

● Readme file

    o 内容(Wikipedia readme page)

    o 制作: 编写格式采用Markdown

●  开放与许可Publication & Licensing

    o 设置公开权限时，注意敏感数据

    o 设置许可协议

  ▪强推WTFPL - Do What the Fuck You Want to Public License(http://www.wtfpl.net/)上手超级简单

2.2实时备份 Establishing a robust backup (version control system)

     Git

2.3撰写代码 writing good code

     Good code: easy and correct

● 可读性(readable)

     o 有效使用空格whitespace和换行符newlines

     o 编写函数和变量时名字注意可读性

     o 统一格式

● 重复使用(reusable)

     o 代码和数据分开

     o 巧用函数

     o Do one thing (and do it well)

         ▪ 一个函数一个目的

         ▪ 一个脚本一个目的

● robust

    o Error management ：巧用try/catch 进行代码调试

    o Unit testing

         ▪ in R with the testthat/testthis packages

2.4撰写文档 writing documentation

      理由很简单，文本说明一来可以便于自己以后快速熟悉课题内容，二来可以帮助合作者或同行之间交流学习。常见的说明包括代码里的注释部分，课题下的readme 文件等等。

2.5设置开放权限 Making your project accessible

3

版本控制(Version control)

      为什么要版本控制？99%的相关介绍里会引用如下的图片，这也是很多人写论文时最常用或者曾经常用的命名模式……final之后永远有新的版本123…直到最后论文结束。你有没有遇到过这些情况：

1）想改某一个代码，改完发现，额，没有保存上一个版本，那咋整？已有的备份的还是上一个的上一个？到底哪一个时间保存的是对的？

2）又或者，在某个合作项目里，你改了某个地方，怎么加个标记提醒自己以及合作者？怎么将你的某个内容分享给你的合作者 等等。简而言之，版本控制可以解决上述烦恼，不仅有历史追踪，还可以根据自定义的权限分享给你想分享给的任何人，相信处女座和强迫倾向的小伙伴一定很喜欢。至于理论总结版本控制的优势，感兴趣的朋友，右转这里：

https://stackoverflow.com/questions/1408450/why-should-i-use-version-control

Git，实现版本控制的一个工具，入门简单，不仅有GUI界面，还可以和RStudio结合。（Tip: Git != GitHub, 就像R != RStudio）。

3.1前期准备

●  本地课题文件夹(Project structure见前文)

  o 当然也有推荐模板，比如基于cookiecutter写的模板。

  o在RStudio里也有一个工具包，rrtools 详情

（https://github.com/benmarwick/rrtools），欢迎有兴趣的小伙伴撰文分享学习经验~

●  个人GitHub账号

●  安装Git

注意：不同的操作系统安装方法不一致

●  设置SSH KEY: 先产生随机密钥再添加到GitHub上

On GitHub

确保已经登陆GitHub -- Settings -- SSH and GPG keys --- new SSH KEY  -- paste your public key in the “Key” boc -- give it an informative title -- add ssh key

3.2实践操作(Practice)

      参考HappyGitWithR分别罗列了三种情形1)new project, GitHub first (Chap 15); 2) Existing project, GitHub first(Chap 16); 3) Existing project, GitHub last (Chap 17)。有兴趣的同学可以查看对应章节，以下实践操作主要介绍前两种情况。

3.2.1 New project, GitHub first （cookiecutter template + git bash操作)

       正如前文介绍，一个好的课题需要包括几个主要的部分，你可以借助RStudio来创建不同的文件，也可以用现成的模板。这里模板是Cookiecutter写的（作者 Dr. Barbara Vreede ）

3.2.1.1安装cookiecutter

● a. 打开command prompt,确认是否安装了 pip, 输入 pip --version

● b. 在命令窗口输入pip install cookiecutter即可安装

● c. 打开git bash 下载模板

    o 定位到指定路径

    o 下载指定模板，并回答对应问题

3.2.1.2 初始化本地课题

3.2.1.3 Connecting to GitHub

● 建立新的repository

●  填写基本信息，注意这里不要勾选readme file，可以后期自己编辑

●  链接本地文档到远程端

● 上传到远程端

 刷新远程端就会看到本地文件夹已经在github页面啦

3.2.2 Existing project, GitHub first(HappyGitWith R_Chap 16)

● Make a repo on GitHub 方法和之前类似

● New RStudio Project via git clone

    o 本地路径A

● Bring your existing project ever

    o 将已有的课题（本地路径B)移动或拷贝到本地路径A的课题下

    o In RStudio, git pane页面下会看到所有成功拷贝过去的文件，并且显示为untracked files

● Stage and commit 

    o Click the “git” tab

    o 选择你想同步的所有文件后，勾选staged

       ▪ Default: stage it

       ▪ When to reconsider: 即你可以选择该文件只存在本地文件，而不同步到远程端，那就不要点击staged. 

       ▪ 如果这是永久性的属性（即不同步到远程端），那么可以在.gitignore文件里设置

    o 如果git tab页面没有单独跳出来，点击commit

    o 在commit message 添加合适的备注

    o 点击 commit

● Push your local changes to GitHub

    o 点击 push 按钮

●Confirm the local change propagated to the GitHub remote

    o 刷新浏览器，就会看到你github页面里的指定同步的课题已经更新了

    o 点击 commit，会看到带有“init”的备注信息

● The end

    o Repeat,

    o do work somewhere. Commit it 

    o Pull it or push it（二者顺序看情况，如和他人合作某一课题时，最好先下载最新的网页端的课题） ，synced up between local and remote

(Image credit: Software Carpentries)

3.2.3 .gitignore文件

      设置隐藏文件，这样可以控制文件的开放权限。比如示例操作里调用的cookiecutter template默认数据文件夹不上传。具体可以参考下文的拓展资源。

4

网络资源

4.1 paper

      -good enough practices in scientific computing 

(https://doi.org/10.1371/journal.pcbi.1005510)

4.2 Version control

      -Why version control 

(https://stackoverflow.com/questions/1408450/why-should-i-use-version-control)

- Version control for the solo data scientist 

(https://stackoverflow.com/questions/2712421/r-and-version-control-for-the-solo-data-analyst)

4.3 Git

      -cheetsheet

(https://www.atlassian.com/git/tutorials/atlassian-git-cheatsheet)

      -gitignore

(https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#Ignoring-Files)

4.4 GitHub and RStudio tutorials

      -webinar

(https://rstudio.com/resources/webinars/rstudio-essentials-webinar-series-managing-part-2/)

4.5 rrtools: tools for writing reproducible research in R

      - https://github.com/benmarwick/rrtools

4.6 E-book

      - happy git with R

(https://happygitwithr.com/)

      -Git Magic

(http://www-cs-students.stanford.edu/~blynn/gitmagic/)

  致谢：Open Science Community Utrecht (OSCU) & Research Data Management Support (RDM support) 联合组织的工作坊 Best practice for Writing reproducible and version control以及主讲者Dr. Barbara Vreede 在工作坊中介绍的以Cookiecutter为基础写的Project的模板。

 关于作者：孙  丹 

荷兰乌特勒支大学（Utrecht University）社会心理学博士在读，目前主要关注自由意识(conscious will)和行为动作(action)之间的关系以及动作控制(Action control) 有关的加工过程。

  本期排版：孟  雪

  往期热门：

    最后，正值新春佳节，荷兰心理统计联盟全体成员恭祝大家平安喜乐，鼠年大吉。也借此机会向所有奋斗在前线的医护人员，处在疫情区的民众致敬！

    “隔离病毒，但不能隔绝爱。众志成城，没有我们过不去的坎。加油武汉，加油中国！”