107 |
108 | The following is an examplary excerpt of what you citations could look like:
109 |
110 |
111 | One of the most frequently utilized paradigms in the field of implicit learning is the serial reaction time task (SRTT) originating from @nissen_attentional_1987. [...] Even with more sensitive tests including the recently introduced wagering task [@dienes_gambling_2010; @haider_old_2011; @persaud_postdecision_2007] or the process-dissociation procedure [@destrebecqz_can_2001; @haider_old_2011; @jacoby_process_1991], explicit knowledge of the sequence is rare.
112 |
113 | ```
114 |
115 |
116 | ## Report statistical analyses
117 |
118 | ```{block, box.title = "Exercise 5", box.body = list(fill = "white"), box.icon = "fa-star"}
119 | Locate and open the R-script `analyses.R` and data folder `data` accompanying the example manuscript in the folder `exercises/3_papaja_example_manuscript`.
120 |
121 | Use `apa_print()` to report the results of one or more analysis using in-line code chunks in your **papaja** document.
122 | ```
123 |
124 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
125 | Use the section comments (e.g., `## ----setup----`) to split the R script into meaningful code chunks and use the section headings as chunk names.
126 |
127 | You may omit parts of the R script that are not necessary for the analysis you are trying to insert into your document.
128 | ```
129 |
130 | ```{block, box.title = "Solution 5", box.icon = "fa-check", solution = TRUE}
131 | The following is a minimal example of how to report one hypothesis test of one of the analyses.
132 |
133 |
255 | ```
256 |
257 |
258 | ```{block, box.title = "Bonus", box.body = list(fill = "white"), box.icon = "fa-medal", box.collapse = TRUE}
259 | Place the table in the appendix of your document. To start an appendix, use the following special heading:
260 |
261 |
293 | ```
294 |
295 |
296 | ## Captions and cross-referencing
297 |
298 | ```{block, box.title = "Exercise 7", box.body = list(fill = "white"), box.icon = "fa-star"}
299 | Use a text-reference for your table caption and reference the table in the body of the text.
300 | ```
301 |
302 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
303 | Text reference definitions must be on their own line, surrounded by empty lines, and start with `(ref:reference-name)`.
304 | ```
305 |
306 | ```{block, box.title = "Solution 7", box.icon = "fa-check", solution = TRUE}
307 |
308 |
(ref:table-caption) Means ($M$) and standard errors ($\mathit{SE}$) of proportion of correctly generated second-order conditionals (SOCs).
321 | ```
322 |
323 |
324 |
325 |
--------------------------------------------------------------------------------
/src/exercises/4_git_github.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title : "Exercises: Git & GitHub"
3 | subtitle : "Reproducible research workflows for psychologists"
4 | ---
5 |
6 | ```{r child = "_setup.Rmd"}
7 | ```
8 |
9 |
10 | ```{block, box.title = "Exercise 1", box.body = list(fill = "white"), box.icon = "fa-star"}
11 | Go to GitHub (or GitLab) and create a new repository for this workshop.
12 | ```
13 |
14 | ```{block, box.title = "Solution 1", box.icon = "fa-check", solution = TRUE}
15 | ### GitHub
16 |
17 | 
18 |
19 | 
20 |
21 | ---
22 |
23 | ### GitLab
24 |
25 | 
26 |
27 | 
28 | ```
29 |
--------------------------------------------------------------------------------
/src/exercises/5_git&rstudio.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title : "Exercises: Git & RStudio"
3 | subtitle : "Reproducible research workflows for psychologists"
4 | ---
5 |
6 | ```{r child = "_setup.Rmd"}
7 | ```
8 |
9 |
10 | In this set of exercises, we clone and work on the *GitHub* or *GitLab* repository you have created in the previous session.
11 |
12 | In order to do the following exercises, you should have gone through the steps described in the setup information for the workshop. Specifically, you should...
13 |
14 | - make sure that we can use `Git` via *RStudio*
15 | - have created and stored a PAT for authentication via `HTTPS` for *GitHub*
16 |
17 | For using *GitLab* you should also have enabled `SSH` authentication through creating a RSA key in the Git/SVN options in *RStudio*.
18 |
19 | ```{block, box.title = "Exercise 1", box.body = list(fill = "white"), box.icon = "fa-star"}
20 | After we've made sure that everything works, we can now clone and work on the repository we have created on *GitHub* or *GitLab* in the previous session. When doing this, you should also create a new *RStudio* project.
21 | ```
22 |
23 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
24 | You can create a new version-controlled project that is connected to an existing *GitHub* or *GitLab* repository via the *RStudio* menu. If you need some further information, you can check out the [New project, GitHub first](https://happygitwithr.com/new-github-first.html) section in *Happy Git and GitHub for the useR*.
25 | ```
26 |
27 | ```{block, , box.title = "Solution 1", solution = TRUE, box.icon = "fa-check"}
28 | You can create a new version-controlled project and associate it with a repository cloned from *GitHub* via *File* -> *New Project* -> *Version Control*. Then choose `Git`, enter the URL of the *GitHub*/*GitLab* repository (remember that the URL looks different depending on whether you use `HTTPS` or `SSH` for authentication), and choose a location where to store the project on your local machine.
29 | As we will start working on the project right away, also check "Open in new session".
30 | ```
31 |
32 | ```{block, box.title = "Exercise 2", box.body = list(fill = "white"), box.icon = "fa-star"}
33 | If everything has worked, a new instance of *RStudio* should have opened with the working directory set to the location of your new project, the files included in the project folder visible in the *Files* tab, and an active `Git` tab. To make extra sure that everything worked, let's check the `Git` status of our project via the `Terminal` in *RStudio*.
34 | ```
35 |
36 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
37 | You may want to check which shell the `Terminal` in *RStudio* uses via *Tools* -> *Global Options* -> *Terminal*. If you use Windows, you should choose `Git Bash` (which you should have installed with `Git` for Windows).
38 | ```
39 |
40 | ```{bash, , box.title = "Solution 2", solution = TRUE, box.icon = "fa-check", eval=FALSE}
41 | git status
42 | ```
43 |
44 | ```{block, box.title = "Exercise 3", box.body = list(fill = "white"), box.icon = "fa-star"}
45 | Now that the project is set up and in sync with the remote repository, we can start working on it. Modify the README file (just add, remove or edit a few words). If you want to, you can also edit the `R Markdown` file(s) in your repository/project.
46 |
47 | After modifying the file(s), save the changes (via the *Save* icon in the *RStudio* menu or the keyboard shortcut your OS uses for saving files) and stage them in `Git`.
48 | ```
49 |
50 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
51 | You can use the *RStudio* GUI for staging changes (for modified or added files). As a reminder: When you modify existing files and/or create new ones and save the changes, these should be displayed in the `Git` tab in *RStudio* and their status will be indicated as *modified* or *untracked*.
52 | ```
53 |
54 | ```{block, , box.title = "Solution 3", solution = TRUE, box.icon = "fa-check"}
55 | You can stage changed files in the *RStudio* GUI by checking the boxes in the *Staged* column in the `Git` tab.
56 | ```
57 |
58 | ```{block, box.title = "Exercise 4", box.body = list(fill = "white"), box.icon = "fa-star"}
59 | After staging your changes, let's create a commit and push that to the remote repository.
60 | ```
61 |
62 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
63 | You can do both (committing and pushing) via the *RStudio* GUI. Remember to write a meaningful commit message.
64 | ```
65 |
66 | ```{block, , box.title = "Solution 4", solution = TRUE, box.icon = "fa-check"}
67 | After staging the changes, simply click on the *Commit* button in the `Git` tab in *RStudio*, write a commit message in the menu that opens up, and then click the *Push* button in the same menu.
68 | ```
69 |
70 | ```{block, box.title = "Exercise 5", box.body = list(fill = "white"), box.icon = "fa-star"}
71 | As a final exercise for this session, let's do the opposite of pushing and pull changes from the remote repository to your local project. Before we can do this, we first need to make some edits in the remote repository. Go to the website of your remote *GitHub*/*GitLab* repository (while being logged in) and edit the README file in the browser (again, just add, remove, or edit a few words). How you edit a file depends on the platform:
72 |
73 | On *GitHub*:
74 | You can edit the README via the small pen icon next displayed above the content of your README file.
75 |
76 | On *GitLab*:
77 | Click on the name of the file you want to edit (in this case this should be `README.md`). Next, choose and click "Edit" from the blue dropdown menu shown next to the file name.
78 |
79 | Once you have edited the file (and committed the changes directly on *GitHub*/*GitLab*), you can pull the changes to your local project.
80 | ```
81 |
82 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
83 | Remember that if you edit a file directly via the *GitHub* or *GitLab* web interface, you also need to make a commit (and add a commit message). You can do the pull operation via the respective icon in the *RStudio* GUI.
84 | ```
85 |
86 | ```{block, , box.title = "Solution 5", solution = TRUE, box.icon = "fa-check"}
87 | After making and saving the edits to the README file via the *GitHub* or *GitLab* web interface, you can simply click the *Pull* button in the `Git` tab in *RStudio* to update your local project.
88 | ```
89 |
--------------------------------------------------------------------------------
/src/exercises/6_github_collaboration.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title : "Exercises: Collaborate with Git & GitHub"
3 | subtitle : "Reproducible research workflows for psychologists"
4 | ---
5 |
6 | ```{r child = "_setup.Rmd"}
7 | ```
8 |
9 | ## Adding collaborators
10 |
11 | ```{block, box.title = "Exercise 1", box.body = list(fill = "white"), box.icon = "fa-star"}
12 | Find one or two collaborators. Go to GitHub (or GitLab) and add each other as collaborators to your repositories.
13 | ```
14 |
15 | ```{block, box.title = "Solution 1", box.icon = "fa-check", solution = TRUE}
16 | GitHub: `Settings > Manage access > Add people`
17 |
18 | GitLab: `Project information > Members > Invite members`
19 | ```
20 |
21 | ## Publish changes without review
22 |
23 | ```{block, box.title = "Exercise 2", box.body = list(fill = "white"), box.icon = "fa-star"}
24 | Now, it's time to start collaborating.
25 |
26 | 1. Clone your collaborators repository into a new directory (not inside your repository!)
27 | 1. Make some constructive changes
28 | 1. Stage, commit, and push all changes to your collaborators remote repository
29 | 1. Pull and review the changes your collaborator has made to your repository
30 | 1. Comment on one of the changes to your repository on GitHub
31 | ```
32 |
33 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
34 | You may review the changes to your repository on GitHub or in RStudio. In RStudio, click the little clock icon in the Git pane to open the commit history and review the changes.
35 | ```
36 |
37 | ```{bash, box.title = "Solution 2", box.icon = "fa-check", solution = TRUE, eval = FALSE}
38 | git clone
39 | git add .
40 | git commit -m "Constructive changes"
41 | git push
42 | ```
43 |
44 |
45 | ## Open a pull request
46 |
47 | ```{block, box.title = "Exercise 3", box.body = list(fill = "white"), box.icon = "fa-star"}
48 | Open your browser and navigate to your collaborator's GitHub repository.
49 |
50 | 1. Choose a file and edit it in your browser
51 | 2. Open a pull request
52 | 3. Review the changes your collaborator has proposed to your repository, accept them, and merge the pull request
53 | ```
54 |
55 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
56 | After creating a new branch with `git branch my-branch` you have to switch over to that branch before making any edits with `git checkout my-branch`.
57 |
58 | When pushing a newly created branch for the first time, you need to specify where the branch should be pushed to (`git push origin my-branch`).
59 | ```
60 |
61 | ```{bash, box.title = "Solution 3", box.icon = "fa-check", solution = TRUE, eval = FALSE}
62 | git pull
63 | git branch revision
64 | git checkout revision
65 | git add .
66 | git commit -m "My changes"
67 | git push origin revision
68 | ```
69 |
70 |
71 | ```{block, box.title = "Exercise 4", box.body = list(fill = "white"), box.icon = "fa-star"}
72 | Start a conversation. Open your collaborator's repository in RStudio.
73 |
74 | 1. Pull the latest changes from the remote repository
75 | 2. Create a new branch
76 | 1. Edit multiple files, stage, commit, and push the changes
77 | 2. Open your collaborator's GitHub repository, find your branch, and open a pull request
78 | 2. Review the changes your collaborator has proposed to your repository and request a change
79 | 3. Make the requested changes to your PR
80 | 4. After reviewing the updated pull requests to your repository, accept and merge it
81 | ```
82 |
83 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
84 | You can revise your pull request simply by editing the branch in RStudio and pushing the committed changes to GitHub as usual. The pull request will be updated automatically.
85 | ```
86 |
87 |
88 | ## Merge conflicts
89 |
90 | ```{block, box.title = "Bonus", box.body = list(fill = "white"), box.icon = "fa-medal"}
91 | Together with your collaborator, create a merge conflicts on each others repositories.
92 |
93 | 1. Pull the latest changes from the remote repository
94 | 2. Choose a file and edit the same line in that file in your RStudio and commit the change (do not push, yet).
95 | 3. Let your collaborator push the change to your repository and then try pushing yourself.
96 | 4. Pull the latest changes from the remote repository
97 | 5. Resolve the merge conflict
98 | 6. Push your changes to your repository
99 | ```
100 |
101 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
102 | When resolving a merge conflict, you can do so in any way you see fit. You can keep your changes or those of your collaborator. You may also combine the changes or discard both and come up with something new.
103 | ```
104 |
105 | ```{block, box.title = "Bonus solution", box.icon = "fa-check", solution = TRUE}
106 | The file containing the merge conflict might look something like the following.
107 |
108 |
109 | <<<<<<<< HEAD
110 | Your changes
111 | ========
112 | Your collaborator's changes
113 | >>>>>>>> b8e009f666b984509b28a8dedc18e45811be94a6
114 |
115 |
116 | After resolving the conflict, the file could look as follows.
117 |
118 |
119 | Your and your collaborator's changes
120 |
121 |
122 | Then you can just stage and commit the conflict resolution as usual.
123 | ```
124 |
--------------------------------------------------------------------------------
/src/exercises/_output.yaml:
--------------------------------------------------------------------------------
1 | unilur::tutorial_html_solution: default
2 | unilur::tutorial_html: default
3 |
--------------------------------------------------------------------------------
/src/exercises/_setup.Rmd:
--------------------------------------------------------------------------------
1 |
2 | ```{r custom-boxes, include = FALSE}
3 | knitr::opts_template$set(
4 | clues = list(
5 | box.title = "Clues"
6 | , box.body = list(fill = "#fff9dc", colour = "black")
7 | , box.header = list(fill = "#ffec8b", colour = "black")
8 | , box.icon = "fa-search"
9 | , box.collapse = TRUE
10 | )
11 | )
12 | ```
13 |
14 | ```{r klippy, echo = FALSE}
15 | klippy::klippy(position = c("top", "right"))
16 | ```
17 |
18 | ```{css, echo = FALSE}
19 | .highlight {
20 | background-color: rgb(255, 150, 79, 0.75); /*#ffcc66;*/
21 | }
22 |
23 | a:not([href^="#"]):not([href^="/"])::after {
24 | font-family: 'FontAwesome';
25 | content: " \f08e";
26 | font-size: 1rem;
27 | vertical-align: top;
28 | }
29 |
30 | a[target="_blank"]:after {
31 | font-family: 'FontAwesome';
32 | content: " \f08e";
33 | font-size: 1rem;
34 | vertical-align: top;
35 | }
36 |
37 | pre {
38 | white-space: pre-wrap; /* Since CSS 2.1 */
39 | white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
40 | white-space: -pre-wrap; /* Opera 4-6 */
41 | white-space: -o-pre-wrap; /* Opera 7 */
42 | word-wrap: break-word; /*Internet Explorer 5.5+ */
43 | word-break: break-word; /*Internet Explorer 5.5+ */
44 | }
45 | ```
46 |
--------------------------------------------------------------------------------
/src/exercises/template.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title : "Exercises: "
3 | subtitle : "Reproducible research workflows for psychologists"
4 | ---
5 |
6 | ```{r child = "_setup.Rmd"}
7 | ```
8 |
9 |
10 | ```{block, box.title = "Exercise 1", box.body = list(fill = "white"), box.icon = "fa-star"}
11 | This is exercise 1.
12 | ```
13 |
14 | ```{block, opts.label = "clues", box.icon = "fa-lightbulb"}
15 | Not really a lot to do here.
16 | ```
17 |
18 | ```{block, box.title = "Solution 1", box.icon = "fa-check", solution = TRUE}
19 | Well done!
20 | ```
21 |
--------------------------------------------------------------------------------
/src/outline.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title: "`r gsub('.+:', '', params$title)`"
3 | subtitle: "Workshop outline"
4 | author : "`r params$author`"
5 |
6 | date : "`r params$date`"
7 | location: "`r params$location`"
8 |
9 | abstract: |
10 | For several years, psychological science has been facing a crisis of confidence fueled by concerns about low rates of successful replications of empirical findings.
11 | Different solutions have been proposed to address this issue.
12 | A key factor in these efforts is increasing transparency and computational reproducibility of psychological research.
13 | While transparent and computationally reproducible research is not necessarily more replicable, it facilitates replication attempts and helps to foster trust in empirical findings.
14 | The evolving open science ecosystem provides a variety of tools and services that can be used to implement reproducible research practices.
15 | Navigating the growing space of tools and practices, however, can be a daunting task.
16 |
17 | Hence, the purpose of this 2 days workshop is to introduce researchers to the essential components of tailored reproducible research workflows as well as the tools for implementing them.
18 | Combining lectures with practical hands-on sessions, the workshop will focus on data analysis, reporting of results, and sharing data and materials.
19 | Regarding the tool stack, the workshop will cover version control with Git and writing reports with RMarkdown as key components of a reproducible research workflow, but will also introduce other tools, such as the Open Science Framework (OSF), Docker, and Binder.
20 |
21 | output:
22 | html_document:
23 | keep_md : true
24 | theme : "spacelab"
25 | df_print : "kable"
26 | toc : true
27 | toc_float : true
28 | ---
29 |
30 | ```{r setup, include = FALSE}
31 | library("rmarkdown")
32 | ```
33 |
34 | ---
35 |
36 | ## Learning objectives
37 |
38 | Upon course completion, participants should
39 |
40 | 1. be familiar with key concepts of reproducible research
41 | 2. be able to choose the appropriate tools to implement a tailored workflow
42 | 3. have gained basic proficiency of Git, LaTeX, R Markdown, and `papaja`
43 | 4. be able to manage projects and collaborate using Git and GitHub
44 |
45 | ## Prerequisites
46 |
47 | Participants should have some basic knowledge of R have used R Studio before.
48 |
49 | ---
50 |
51 | # Preparations
52 |
53 | To make the most of our time, we recommend that you prepare for the workshop by installing the following software ahead of time.
54 |
55 | *Please note that these preparations will require some time to complete. Please do not delay them to the last moment before the workshop.*
56 |
57 | ### R and RStudio
58 |
59 | Please ensure that you are using a recent version of R ($\geq$ 4.0.0) and RStudio.
60 |
61 | ### LaTeX
62 |
63 | To enable `papaja`'s full set of features you need a [TeX](http://de.wikipedia.org/wiki/TeX) distribution.
64 | We recommend that you use [TinyTex](https://yihui.name/tinytex/), a LaTeX distribution designed for use with R Markdown.
65 | TinyTex can be installed from within R as follows.
66 |
67 | ```{r eval = FALSE}
68 | # If necessary, install tinytex R package
69 | if(!requireNamespace("tinytex", quietly = TRUE)) install.packages("tinytex")
70 |
71 | # Install TinyTex distribution
72 | tinytex::install_tinytex()
73 | ```
74 |
75 | If you prefer, you may also use [MikTeX](http://miktex.org/) for Windows, [MacTeX](https://tug.org/mactex/) for Mac, or [TeX Live](http://www.tug.org/texlive/) for Linux.
76 | Refer to the [`papaja` manual](https://crsh.github.io/papaja_man/introduction.html#getting-started) for instructions.
77 |
78 |
79 | #### `papaja`
80 |
81 | `papaja` is not yet available on CRAN but you can install it from this repository:
82 |
83 | ```{r install_papapja, eval = FALSE}
84 | # Install remotes package if necessary
85 | if(!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")
86 |
87 | # Install the latest development snapshot from GitHub
88 | remotes::install_github("crsh/papaja")
89 | ```
90 |
91 |
92 |
93 | ### Git and GitHub
94 |
95 | We will use Git for version control (change tracking) and as a tool for collaboration.
96 | The following steps may be daunting at first, but the linked-to instructions are excellent and should get you set up in no time.
97 | You can do it! :)
98 |
99 | In preparation, please
100 |
101 | 1. create a [GitHub](https://github.com) account
102 | 2. install Git (see [instructions](https://happygitwithr.com/install-git.html))
103 | - During installation of Git, add `git bash` to the Windows context menu by selecting its option (this should be the default)
104 | 3. configure Git (see [ instructions](https://happygitwithr.com/hello-git.html))
105 | 2. create a personal access token for HTTPS (see [instructions](https://happygitwithr.com/https-pat.html))
106 | 4. confirm that you can connect to GitHub (see [instructions](https://happygitwithr.com/push-pull-github.html))
107 |
--------------------------------------------------------------------------------
/src/slides/1_introduction.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title : "Reproducible research workflows for psychologists"
3 | subtitle : "Introduction"
4 |
5 | author : " `r paste(params$author, collapse = ' & ')`"
6 | date : "`r paste0(params$location, ', ', params$date)`"
7 | ---
8 | exclude: true
9 |
10 |
11 | ```{r child = "_setup.Rmd"}
12 |
13 | ```
14 |
15 | ---
16 |
17 | # About us
18 |
19 | [Frederik Aust](http://frederikaust.com/) ([f.aust@uva.nl](mailto:f.aust@uva.nl), [@frederikaust](http://twitter.com/frederikaust))
20 |
21 | - PostDoc with Prof. Dr. Eric-Jan Wagenmakers at the University of Amsterdam
22 |
23 | --
24 | - Mathematical models of learning and memory
25 | - Bayesian statistics
26 | - Computational reproducibility
27 | --
28 | - Author and contributor to several R packages (e.g., [`afex`](https://cran.r-project.org/web/packages/afex/index.html), [`citr`](https://cran.r-project.org/web/packages/citr/index.html), [`papaja`](https://github.com/crsh/papaja))
29 |
30 | ---
31 |
32 |
33 |
34 | # About us
35 |
36 | [Johannes Breuer](https://www.johannesbreuer.com/) ([johannes.breuer@gesis.org](mailto:johannes.breuer@gesis.org), [@MattEagle09](https://twitter.com/MattEagle09))
37 |
38 | - Senior researcher at [*GESIS - Leibniz Institute for the Social Sciences*](https://www.gesis.org/home) (Department Survey Data Curation) & (co-) leader of the team *Research Data & Methods* at the [*Center for Advanced Internet Studies*](https://www.cais.nrw/) (CAIS)
39 |
40 | --
41 | - Uses and effects of digital media
42 | - Computational methods
43 | - Data management & Open science
44 |
45 | ---
46 |
47 | # About you
48 |
49 | - What's your name?
50 | - What is your research area?
51 | - What are your experiences with reproducible research (and the tools we cover in this course)?
52 | - What are your expectations for this course?
53 |
54 | ---
55 |
56 | # Preliminaries
57 |
58 | Slides and material are available at
59 |
60 | .center[
61 | http://frederikaust.com/reproducible-research-practices-workshop
62 | ]
63 |
64 | - The workshop consists of a combination of lectures and hands-on exercises
65 | - Feel free to ask questions anytime
66 | - We will have frequent breaks (please remind us if necessary)
67 |
68 | ---
69 |
70 | # Preliminaries
71 |
72 | Did you have any trouble with the setup for this workshop?
73 |
74 | Installing...
75 |
76 | - [`git`](https://git-scm.com/)
77 | - [`R`](https://www.r-project.org/) & [*RStudio*](https://www.rstudio.com/products/rstudio/)
78 | - a `TeX` distribution (e.g., [TinyTeX](https://yihui.name/tinytex/))
79 | - [`papaja`](https://github.com/crsh/papaja)
80 |
81 | ---
82 |
83 | # Preliminaries
84 |
85 | Did you have any trouble with the setup for this workshop?
86 |
87 | Creating...
88 |
89 | - a [*GitHub*](https://github.com/) account
90 | - an account for the [KU Leuven *GitLab*](https://gitlab.kuleuven.be/)
91 | - access credentials for *GitHub* (HTTPS, PAT) and *GitLab* (SSH)
92 |
93 | ---
94 |
95 | ## Course schedule
96 |
97 | .center[**Wednesday, April 27th, 2022**]
98 |
99 | ```{r schedule Wed, echo = F}
100 | schedule <- data.frame(
101 | "When?" = c("10:00 - 12:00", "12:00 - 13:00", "13:00 - 15:00", "15:00 - 15:30", "15:30 - 17:30")
102 | , " " = " "
103 | , "What?" = c("Introduction: Reproducible Workflows", "Lunch break", "Introduction to R Markdown", "Coffee break", "papaja")
104 | , check.names = FALSE
105 | )
106 | knitr::kable(
107 | schedule
108 | , format = "html"
109 | , align = "ll"
110 | , escape = FALSE
111 | )
112 | ```
113 |
114 | ---
115 |
116 | ## Course schedule
117 |
118 | .center[**Thursday, April 28th, 2022**]
119 |
120 | ```{r schedule Thur-1, echo = F}
121 | sharing_options <- data.frame(
122 | "When?" = c("09:00 - 10:15", "10:15 - 10:30", "10:30 - 11:30", "11:30 - 12:30")
123 | , " " = " "
124 | , "What?" = c("Introduction to Git & GitHub", "Coffee break", "Git in RStudio", "Git & GitHub for collaboration - Part 1")
125 | , check.names = FALSE
126 | )
127 | knitr::kable(
128 | sharing_options
129 | , format = "html"
130 | , align = "ll"
131 | , escape = FALSE
132 | )
133 | ```
134 |
135 | ---
136 |
137 | ## Course schedule
138 |
139 | .center[**Thursday, April 28th, 2022**]
140 | ```{r schedule Thur-2, echo = F}
141 | sharing_options <- data.frame(
142 | "When?" = c("12:30 - 13:30", "13:30 - 14:00", "14:00 - 14:15", "14:15 - 15:30", "15:30 - 16:00")
143 | , " " = " "
144 | , "What?" = c("Lunch break", "Git & GitHub for collaboration - Part 2", "Coffee break", "Other tools & workflows", "Wrap-Up")
145 | , check.names = FALSE
146 | )
147 | knitr::kable(
148 | sharing_options
149 | , format = "html"
150 | , align = "ll"
151 | , escape = FALSE
152 | )
153 | ```
154 |
155 | ---
156 |
157 | # What is reproducibility?
158 |
159 | .center[
160 | ```{r repro-tweet, echo=FALSE}
161 | tweetrmd::tweet_embed("https://twitter.com/jakevdp/status/519563939177197571")
162 | ```
163 | ]
164 |
165 | ---
166 |
167 | # Why reproducibility matters
168 |
169 |
170 | .center[
171 | ```{r repro-lazy, echo=FALSE}
172 | tweetrmd::tweet_embed("https://twitter.com/hadleywickham/status/598532170160873472")
173 | ```
174 | ]
175 |
176 | ---
177 |
178 | # Defining reproducibility
179 |
180 | As with (almost) everything in science, there are different definitions of reproducibility.
181 | We will discuss some of them in the following.
182 |
183 | ---
184 |
185 | # Defining dimensions
186 |
187 | 3-dimensional concept space
188 |
189 | ```{r, three-dims, out.width = "50%", echo = F}
190 | include_graphics("./img/trr-cube.jpg")
191 | ```
192 | By Christof Schöch. Source: https://dh-trier.github.io/trr/#/2/1
193 |
194 | ---
195 |
196 | # Defining dimensions
197 |
198 | ```{r, turing-dims, out.width = "75%", echo = F}
199 | include_graphics("./img/turing_way_parts.jpg")
200 | ```
201 | [*The Turing Way Project*](https://the-turing-way.netlify.app/welcome.html) illustration by Scriberia. DOI: [10.5281/zenodo.3332807](https://doi.org/10.5281/zenodo.3332807)
202 |
203 | ---
204 |
205 | # *The Turing Way* definition
206 |
207 | ```{r, turing-def, out.width = "80%", echo = F}
208 | include_graphics("./img/reproducible-matrix.jpg")
209 | ```
210 | Source: https://the-turing-way.netlify.app/reproducible-research/overview/overview-definitions.html
211 |
212 | ---
213 |
214 | # Replication or reproduction?
215 |
216 | ```{r, other-def, out.width = "50%", echo = F}
217 | include_graphics("./img/replication-typology-a.jpg")
218 | ```
219 | By Christof Schöch. Source: https://dh-trier.github.io/trr/#/2/2
220 |
221 | ---
222 | exclude: true
223 |
224 |
225 | # Zooming in
226 |
227 | ```{r zoomable-plot, out.height = "95%", out.extra='id="zoom-margin"'}
228 | knitr::include_graphics("img/reproducibility-schema-1.png")
229 | ```
230 |
231 | ---
232 |
233 | # Reproducible research workflows
234 |
235 | > being an open scientist means .highlight[adopting a few straightforward research management practices, which lead to less error-prone, reproducible research workflows] ([Klein et al., 2018](https://doi.org/10.1525/collabra.158), p. 11)
236 |
237 | ---
238 |
239 | # Research management practices
240 |
241 | There are quite a few practices that researchers can adopt to increase the reproducibility of their work.
242 |
243 | - [Project-oriented workflow](https://www.tidyverse.org/blog/2017/12/workflow-vs-script/)
244 | - [Folder structures](https://psych-transparency-guide.uni-koeln.de/folder-structure.html)
245 | - [Naming things](https://betterprogramming.pub/string-case-styles-camel-pascal-snake-and-kebab-case-981407998841?gi=3295916e039)
246 | - ...
247 |
248 |
249 |
250 | ---
251 |
252 | # Exercise: Folder structures
253 |
254 | If you feel comfortable with that, feel free to share screenshots of some of your project folders. You can choose examples that you think are particularly well-organized as well as negative examples from your "dark past" as someone whose research might have been difficult to reproduce.
255 |
256 | ---
257 |
258 |
259 |
260 | # Sharing is caring
261 |
262 | .small[
263 | One prerequisite for research being reproducible (by others) is sharing research materials. There are many parts of their work that researchers can share to increase the reproducibility as well as the (potential) replicability of their work (see Klein et al., 2018). Four main types of output are:
264 |
265 | 1. Data
266 | 2. Code & scripts (for data collection, processing, and analysis)
267 | 3. Other study materials (e.g., questionnaires or stimulus materials)
268 | 4. (Detailed) Information about the study procedure
269 |
270 | Notably, all of these outputs should be well-documented (e.g., via README files, metadata or comments in code).
271 | ]
272 |
273 | ---
274 |
275 | # Sharing for reproducibility
276 |
277 | While sharing study materials and information about the procedure are important for replicability, for reproducibility, the most important things to share are the data and code.
278 |
279 | ---
280 |
281 | # Sharing data & code
282 |
283 | There are many different ways in which researchers can share their data and code/scripts (see Klein et al., 2018). Keeping only local copies of things and sharing upon personal request is not a very sustainable or scalable solution. The better option is sharing via institutional or public archives and repositories.
284 |
285 | ---
286 |
287 | # Fantastic repositories and where to find them `r ji("dragon")`
288 |
289 | The paper by [Klein et al. (2018)](https://doi.org/10.1525/collabra.158) provides an overview of public repositories that hold psychological data.1
290 | A good tool for finding suitable repositories is the [*Registry of Research Data Repositories*](https://www.re3data.org/).
291 |
292 | [1] However, parts of this overview have inevitably become somewhat outdated since the paper was published.
293 |
294 |
295 | ---
296 |
297 | # How to choose a repository
298 |
299 | In general, research data (and code) that are publicly archived should follow the so-called [FAIR principles](https://www.go-fair.org/fair-principles/) ([Wilkinson et al., 2016](https://doi.org/10.1038/sdata.2016.18)), meaning that the shared materials should be...
300 |
301 | - **F**indable: Persistent identifiers; metadata; indexed
302 | - **A**ccessible: Retrievable by identifier; controlled access where necessary
303 | - **I**nteroperable: Standardized metadata; open, lightweight, and interoperable file formats (e.g., CSV, TSV, JSON, ODS)
304 | - **R**eusable: Documented; clear usage license
305 |
306 | ---
307 |
308 | # How to choose a repository
309 |
310 | Some more specific key criteria for choosing a repository are that it should...
311 |
312 | - use persistent and unique identifiers (such as DOIs)
313 | - accommodate licensing
314 | - feature access controls (e.g., allowing the restriction of
315 | access to a particular set of users)
316 | - have persistence guarantees for long-term access
317 | - store data in accordance with local legislation (e.g. the [GDPR](https://gdpr.eu/) in Europe)
318 |
319 | .small[See [Klein et al., (2018)](https://doi.org/10.1525/collabra.158) for further details
320 | ]
321 |
322 | ---
323 |
324 | # Public archiving options
325 |
326 | Two archiving options that are quite popular among researchers (esp. also in psychology) are the [*Open Science Framework*](https://osf.io/) (OSF) and [*Zenodo*](https://zenodo.org/).
327 |
328 | --
329 |
330 | While these two archives are not curated, which somewhat reduces findability, they are quite flexible and easy to use. They can be used to share different types of content, including data and code, and also offer some degree of access control. A nice feature of the *OSF* and *Zenodo*, especially for sharing code, is that they offer integration with *GitHub* (which facilitates version control).
331 |
332 | ---
333 |
334 | # Tools & tool stacks
335 |
336 | As you probably already know, there are lots of different tools and workflows that can be used to increase the reproducibility of research. These tools can then be combined into different tool stacks. We will introduce you to some of those in this workshop, but there are many more, and, in the end, it depends on your personal preferences and needs what tools/tool stacks and workflows you (should) employ.1
337 |
338 | [1] As you will see, the two of us also have different preferences in our workflows and tool use.
339 |
340 | ---
341 |
342 | # Tools in this workshop
343 |
344 | As stated before, we will focus on the following tools for reproducible research in this workshop:
345 |
346 | - Git & *GitHub*/*GitLab*
347 | - R Markdown
348 |
349 | We will focus on using them via *RStudio*.
350 |
351 | .small[
352 | *Note:* In the outlook part, we will also briefly introduce some other/additional tools.
353 | ]
354 |
355 | ---
356 |
357 | class: center, middle
358 |
359 | # Any questions so far?
360 |
--------------------------------------------------------------------------------
/src/slides/4_git_github.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title : "Reproducible research workflows for psychologists"
3 | subtitle : "Git & GitHub"
4 |
5 | author : " `r paste(params$author, collapse = ' & ')`"
6 | date : "`r paste0(params$location, ', ', params$date)`"
7 | ---
8 | exclude: true
9 |
10 | ```{r child = "_setup.Rmd"}
11 |
12 | ```
13 |
14 | ---
15 | layout: true
16 | name: git
17 |
18 | # Git
19 |
20 | ---
21 | name: vc
22 |
23 | Command line tool
24 |
25 | 1. Version control
26 | - Track changes to *text files*
27 | - Retain version history of snapshot (*commits*)
28 | - Track provenance (who, what, when)
29 |
30 | ---
31 |
32 | ```{r out.width = "85%", out.extra='id="zoom-margin"'}
33 | include_graphics("img/git-history.png")
34 | ```
35 |
36 | ---
37 | template: vc
38 |
39 | 2. Branching
40 | - Alternative versions of files
41 | - Simultaneous asynchronous collaboration
42 |
43 | --
44 | (Vuorre & Curley, 2018)
45 |
46 |
47 | ---
48 |
49 | ```{r}
50 | include_graphics("img/git-branching.jpg")
51 | ```
52 |
53 |
54 | ---
55 |
56 | Why use Git?
57 |
58 | - Avoid mistakes, e.g.
59 | - Working on wrong version
60 | - Inadvertently deleting or editing files
61 | --
62 | - Track and merge changes of multiple collaborators across multiple files
63 |
64 | --
65 | - (Offsite backups)
66 |
67 |
68 | ---
69 | layout: false
70 | class: center, middle
71 |
72 | ```{r out.height = "450px", out.width = "", echo = FALSE}
73 | knitr::include_graphics("img/git-fire.png")
74 | ```
75 |
76 |
77 | ---
78 | layout: false
79 | name: git-system
80 |
81 | # Git
82 |
83 | ```{r out.height="", out.width="550px", echo = FALSE}
84 | knitr::include_graphics("img/git-system.png")
85 | ```
86 |
87 |
88 | ---
89 |
90 | ```{r out.extra = "style='float:right;'", out.width = "150px"}
91 | include_graphics("img/github-logo.png")
92 | ```
93 |
94 | # GitHub
95 |
96 | - Proprietary plattform
97 | - Free to use for academics
98 | - Host remote Git repositories
99 | --
100 |
101 | - Provides slick web interface
102 | - Offers project management tools
103 | --
104 |
105 | - Repositories can receive a DOI with [Zenodo](https://guides.github.com/activities/citable-code/)
106 | --
107 |
108 | - Servers located in the USA (GDPR)
109 |
110 |
111 | ---
112 |
113 | # GitHub
114 |
115 |
116 |
117 | ```{r out.height="450px", out.width="", echo = FALSE}
118 | knitr::include_graphics("img/github-home.png")
119 | ```
120 |
121 |
122 | ---
123 | layout:false
124 |
125 | ```{r out.height="600px", out.width="", echo = FALSE}
126 | knitr::include_graphics("img/github-new-repo.png")
127 | ```
128 |
129 |
130 | ---
131 |
132 | ```{r out.extra = "style='float:right;'", out.width = "150px"}
133 | include_graphics("img/gitlab-logo.png")
134 | ```
135 |
136 | # GitLab
137 |
138 | - .highlight[Open source plattform]
139 | - .highlight[Can be hosted by your institution]
140 | --
141 |
142 | - Host remote Git repositories
143 | - Provides slick web interface
144 | - Offers project management tools
145 | --
146 |
147 | - .highlight[Servers can be located in your country] (GDPR)
148 |
149 | ---
150 |
151 | # GitLab
152 |
153 |
154 |
155 | ```{r echo = FALSE}
156 | knitr::include_graphics("img/gitlab-home.png")
157 | ```
158 |
159 |
160 | ---
161 | layout: false
162 |
163 | ```{r out.height="600px", out.width="", echo = FALSE}
164 | knitr::include_graphics("img/gitlab-new-repo.png")
165 | ```
166 |
167 |
168 | ---
169 | layout: true
170 | template: git
171 |
172 | ---
173 |
174 | Clone your GitHub repository to your computer
175 |
176 | ~~~bash
177 | git clone git@github.com:crsh/my-first-repository.git`
178 | ~~~
179 |
180 | .pull-left-45[
181 |
182 | ```{r out.height="", out.width="450px", echo = FALSE}
183 | knitr::include_graphics("img/github-clone.png")
184 | ```
185 |
186 | ]
187 |
188 | .pull-right-45[
189 |
190 | ```{r out.height="", out.width="450px", echo = FALSE}
191 | knitr::include_graphics("img/rstudio-new-git.png")
192 | ```
193 |
194 | ]
195 |
196 |
197 | ---
198 |
199 | .pull-left-50[
200 |
201 | `.gitignore`
202 |
203 | - Files to ignore (do not track)
204 | - Each line specifies a [pattern](https://git-scm.com/docs/gitignore)
205 | - I typically add R Markdown cache files (e.g., `.rdb`, `.rdx`)
206 | - `usethis:::git_ignore_lines`
207 |
208 | ]
209 |
210 | .pull-right-40[
211 |
212 | 
213 |
214 | ]
215 |
216 |
217 | ---
218 | **Adding files**
219 |
220 | ~~~bash
221 | git status # What has changed?
222 | git add . # Stage all changes
223 | git commit -m "My very first commit! :)"
224 | ~~~
225 |
226 | .pull-left-45[
227 |
228 | - New files are "untracked", not watched for changes
229 | - To start tracking "stage" and "commit" files
230 |
231 | ]
232 |
233 | .pull-right-55[
234 |
235 | ```{r out.height="", out.width="80%", echo = FALSE}
236 | knitr::include_graphics("img/rstudio-git-commit.png")
237 | ```
238 |
239 | ]
240 |
241 | ???
242 | Amend a previous commit if you forgot to add a change
243 |
244 | ---
245 | template: git-system
246 |
247 |
248 | ---
249 |
250 | Now we can push changes to our remote repository
251 |
252 | ~~~bash
253 | git push
254 | ~~~
255 |
256 | ```{r out.height="", out.width="700px", echo = FALSE}
257 | knitr::include_graphics("img/rstudio-git-pushed.png")
258 | ```
259 |
260 | --
261 |
262 | ~~~bash
263 | git pull
264 | ~~~
265 |
266 |
267 | ---
268 |
269 | ~~~bash
270 | git log
271 | ~~~
272 |
273 | ```{r out.height="450px", out.width="", echo = FALSE}
274 | knitr::include_graphics("img/rstudio-git-history.png")
275 | ```
276 |
277 |
278 | ---
279 | **Standard Git workflow**
280 |
281 |
282 | ~~~bash
283 | git pull
284 | git status
285 | git add .
286 | git commit -m "Such exciting changes! :)"
287 | git log
288 | git push
289 | ~~~
290 |
291 | ---
292 |
293 | GitHub provides a web interface for your repository
294 |
295 | - List of files
296 | - Overview of commit history
297 |
298 | ```{r out.height="", out.width="700px", echo = FALSE}
299 | knitr::include_graphics("img/github-commit.png")
300 | ```
301 |
302 |
303 | ---
304 | layout: false
305 | class: middle, center
306 |
307 | # Exercise time
308 |
309 | .center[[Exercise](http://frederikaust.com/reproducible-research-practices-workshop/exercises/4_git_github_question.html)]
310 |
311 | .center[[Solutions](http://frederikaust.com/reproducible-research-practices-workshop/exercises/4_git_github_solution.html)]
312 |
--------------------------------------------------------------------------------
/src/slides/5_Git&RStudio.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title : "Reproducible research workflows for psychologists"
3 | subtitle : "Git & RStudio"
4 |
5 | author : " `r paste(params$author, collapse = ' & ')`"
6 | date : "`r paste0(params$location, ', ', params$date)`"
7 | ---
8 | exclude: true
9 |
10 | ```{r child = "_setup.Rmd"}
11 |
12 | ```
13 |
14 | ---
15 |
16 | # Interacting with `Git`
17 |
18 | There are various tools that we can use for interacting with `Git`. Besides command line interfaces (CLI), such as [*git bash*](https://gitforwindows.org/) for *Windows* or the Terminal on *MacOS*, there also are Graphical User Interfaces (GUI), such as [*GitHub Desktop*](https://desktop.github.com/) or [*GitKraken*](https://www.gitkraken.com/) (for an overview of `Git` clients with a GUI, see https://git-scm.com/downloads/guis).
19 |
20 | ---
21 |
22 | # A note on tool stacks
23 |
24 | While we introduce you to different tools for reproducible research in this workshop and it is always possible to "mix and match", it is usually advisable to try to minimize the number of different tools in your workflow.
25 |
26 | ---
27 |
28 | # VC in your favorite IDE
29 |
30 | Lucky for us, the most popular Integrated Development Interfaces (IDE) for `R`, *RStudio*, also offers functionalities for using `Git`.1
31 |
32 |
33 | [1] Another popular IDE that works nicely with `R` and `Git` is [*Visual Studio Code*](https://code.visualstudio.com/) - or VSCode for short - by *Microsoft*.
34 |
35 | ---
36 |
37 | # All set?
38 |
39 | If you have correctly set up `Git`, *RStudio* should be able to detect it. The easiest way to check this is via the *RStudio* options: *Tools* -> *Global Options* -> *Git/SVN*
40 |
41 | ```{r git-menu, out.width = "45%", echo=FALSE}
42 | include_graphics("./img/git_menu.png")
43 | ```
44 |
45 | ---
46 |
47 | # Finding `Git`
48 |
49 | If you have properly installed `Git` and *RStudio* cannot detect your local `Git` executable, you need to tell it where to find it via the *Browse* button in the menu shown on the previous slide.
50 |
51 | On macOS and Linux, a common path for the `Git` installation is (something like) `/usr/bin/git`, while on Windows it is (something like) `C:/Program Files/Git/bin/git.exe`.
52 |
53 | *Note*: You should restart *RStudio* after making changes in this menu.
54 |
55 | ---
56 |
57 | # How to use `Git` in *RStudio*
58 |
59 | There are essentially two options for using `Git` via *RStudio*
60 |
61 | 1. Through the GUI
62 |
63 | 2. Via the Terminal
64 |
65 | ---
66 |
67 | # Other options for using `Git` with `R`
68 |
69 | .small[
70 | While we won't cover those in any detail in this session, there are also *R* packages for `Git` operations:
71 | - [`usethis`](https://usethis.r-lib.org/) can, e.g., be used to initialize a `Git` repository or for managing credentials
72 | - [`gert`](https://docs.ropensci.org/gert/) is a simple `Git` client for `R` that can be used to perform basic `Git` commands, such as staging, adding, and committing files, or creating, merging, and deleting branches
73 | - [`ghstudio`](https://github.com/moodymudskipper/ghstudio) is a novel in-development package that provides "experimental tools to use git/github with RStudio, e.g see issues and diffs in the viewer"
74 | ]
75 |
76 | ---
77 |
78 | # Are you legit to `Git`?
79 |
80 | As a reminder, there are two protocols for securely communicating with remote `Git` servers, such as *GitHub*: `HTTPS` and `SSH`.
81 |
82 | For our *GitHub* examples, we will use `HTTPS` with a Personal Access Token (PAT). For the *KU Leuven GitLab*, we will use `SSH`.
83 |
84 | ---
85 |
86 | # Creating a PAT
87 |
88 | You should have created a PAT in preparation for this course (via the *GitHub* web interface. If you have not yet done so, you can also use a function from the `usethis` package.
89 |
90 | ```{r create-gh-token, eval = FALSE}
91 | library(usethis)
92 |
93 | create_github_token()
94 | ```
95 |
96 | **NB**: Do not close the browser window/tab with the PAT until you have stored it somewhere. You should treat the PAT like a password.
97 |
98 | ---
99 |
100 | # Storing a PAT
101 |
102 | Once you have created a PAT, the simplest way to store it for use with `R` and *RStudio* is the `gitcreds_set()` function from the [`gitcreds` package](https://gitcreds.r-lib.org/).
103 |
104 | ```{r store-pat, eval = FALSE}
105 | library(gitcreds)
106 |
107 | gitcreds_set()
108 | ```
109 |
110 | *Note*: Of course, you can also (or additionally) store your PAT in another (safe) place, such as your password manager.
111 |
112 | ---
113 |
114 | # SSH
115 |
116 | SSH stands for Secure Shell and is another option for secure interaction with remote `Git` servers, such as *GitHub* or *GitLab* instances. As for the PAT, you should have set up SSH in preparation for the workshop. If you have done so, the location of your RSA key should be displayed in the *RStudio* `Git` menu (*Tools* -> *Global Options* -> *Git/SVN*).
117 |
118 | ---
119 |
120 | # SSH
121 |
122 | ```{r rstudio-ssh, out.width = "70%", echo=FALSE}
123 | include_graphics("./img/git_menu_rstudio.png")
124 | ```
125 |
126 | ---
127 |
128 | # SSH
129 |
130 | If you have not done so before, you first need to create an RSA key via the `Git` menu in *RStudio*. After that, you have to need to copy the public key into the key field in the SSH Keys page on *GitLab*.
131 |
132 | ```{r gitlab-ssh, out.width = "85%", echo=FALSE}
133 | include_graphics("./img/ssh_key_gitlab.png")
134 | ```
135 |
136 | ---
137 |
138 | # `Git` + *RStudio* = `r ji("heart")`
139 |
140 | Now you should hopefully be all set to use `Git` as well *GitHub* and *GitLab* via *RStudio*.
141 |
142 | In order to get the best out of the combination of `R`, `R Markdown`, *RStudio*, and `Git`, it is recommendable to adopt a ["project-oriented workflow"](https://rstats.wtf/project-oriented-workflow.html).
143 |
144 | ---
145 |
146 | # Excursus: *RStudio* projects
147 |
148 | *RStudio* projects are associated with `.Rproj` files that contain some specific settings for the project. If you double-click on a `.Rproj` file, this opens a new instance of *RStudio* with the working directory and file browser set to the location of that file.
149 |
150 | *Note*: The repository/folder for this workshop contains an `.Rproj` file, if you want to try this out.
151 |
152 | ---
153 |
154 | # Excursus: *RStudio* projects
155 |
156 | Using *RStudio* projects can facilitate several things: the organization of files, the use of (relative) file paths, but also the integration of `R` and `R Markdown` with `Git`.
157 |
158 | --
159 |
160 | Explaining *RStudio* projects in detail would be too much of a detour at this point, but if your interested in that, you can check out the [*RStudio* support site](https://support.rstudio.com/hc/en-us/articles/200526207-Using-Projects) or the [respective chapter in *What They Forgot to Teach You About R*](https://rstats.wtf/project-oriented-workflow.html#rstudio-projectsl).
161 |
162 | ---
163 |
164 | # What comes first? `r ji("chicken")` `r ji("egg")`
165 |
166 | In your everyday work, you quite likely need different workflows depending on the temporal order in which things are created or set up: your local project/files, version control with `Git`, and the remote *GitHub* repository.
167 |
168 | - [New project, GitHub first](https://happygitwithr.com/new-github-first.html)
169 | - [Existing project, GitHub first](https://happygitwithr.com/existing-github-first.html)
170 | - [Existing project, GitHub last](https://happygitwithr.com/existing-github-last.html)
171 |
172 | --
173 |
174 | In this session, we will focus on the *New project, GitHub first* approach (which works the same for *GitLab*).
175 |
176 | ---
177 |
178 | # `Git` through the GUI
179 |
180 | You can perform quite a few `Git` operations via the *RStudio* GUI: You can, e.g., create a new `Git` repository, clone an existing repository, stage and commit changes and push them to a remote repository, or pull changes from there, and merge those with your local changes.
181 |
182 | We'll go through a few of these common steps in the following.
183 |
184 | ---
185 |
186 | # New `Git` project connected to existing remote repo
187 |
188 | You can create a new version-controlled project that is connected to a remote repository that already exists on *GitHub* or *GitLab* via *File* -> *New Project* -> *Version Control* in the *RStudio* menu.
189 |
190 | ```{r vc-proj, out.width = "45%", echo=FALSE}
191 | include_graphics("./img/vc_project.png")
192 | ```
193 |
194 | ---
195 |
196 | # New `Git` project connected to existing remote repo
197 |
198 | Next, choose `Git`...
199 |
200 | ```{r git-proj, out.width = "65%", echo=FALSE}
201 | include_graphics("./img/choose_git.png")
202 | ```
203 |
204 | ---
205 |
206 | # Associate remote repo: `HTTPS`
207 |
208 | In the menu that opens after that, enter the URL of the remote repository, give the local repository a name, and tell *RStudio* where it should be stored. It usually makes sense to check "Open in new session".
209 |
210 | --
211 |
212 | **NB**: Which URL you should enter depends on the authentication method you use. If you use `HTTPS`, you can simply copy the URL from the address bar of your browser.
213 |
214 | ---
215 |
216 | # Associate remote repo: `HTTPS`
217 |
218 | ```{r gh-clone-https, out.width = "75%", echo=FALSE}
219 | include_graphics("./img/git_clone_https.png")
220 | ```
221 |
222 | ---
223 |
224 | # URL for `SSH`
225 |
226 | In case you use `SSH`, you can get the right URL from *GitLab* via the blue *Clone* button on the website of the repository.
227 |
228 | ```{r gl-ssh, out.width = "95%", echo=FALSE}
229 | include_graphics("./img/gl_ssh.png")
230 | ```
231 |
232 | ---
233 |
234 | # Associate remote repo: `SSH`
235 |
236 | ```{r gl-clone-ssh, out.width = "75%", echo=FALSE}
237 | include_graphics("./img/git_clone_ssh.png")
238 | ```
239 |
240 | ---
241 |
242 | # Modifying & creating files within the project
243 |
244 | Once you have successfully created the project, you can start editing files or creating new ones. When you have modified existing files and/or created new ones and saved the changes, these will be displayed in the `Git` tab in *RStudio* and their status will be indicated as *modified* or *untracked*.
245 |
246 | *Note*: The `Git` tab also displays in which branch you are currently working.
247 |
248 | ---
249 |
250 | # Modifying & creating files within the project
251 |
252 | ```{r files-changed, out.width = "75%", echo=FALSE}
253 | include_graphics("./img/git_pane_files_changed.png")
254 | ```
255 |
256 | ---
257 |
258 | # Staging changes
259 |
260 | Once you have reached a point at which you want to commit (and possibly also push) your changes, you can stage them by checking the boxes in the *Staged* column in the `Git` tab. This the *RStudio* GUI equivalent of `git add`. The status of previously untracked files will then change to *added*.
261 |
262 | ```{r staged, out.width = "65%", echo=FALSE}
263 | include_graphics("./img/git_staged.png")
264 | ```
265 |
266 | ---
267 |
268 | # Committing & pushing changes
269 |
270 | After staging your changes you can commit them via the *Commit* button in the `Git` tab. In the commit menu that opens you should enter a meaningful commit message. Once that is done you can click the *Commit* button. If you want to, you can also directly push your changes to the remote repository on *GitHub* via the *Push* button. You can, of course, also do this at a later point (directly via the `Git` tab).
271 |
272 |
273 | ---
274 |
275 | # Committing & pushing changes
276 |
277 | ```{r commit, out.width = "85%", echo=FALSE}
278 | include_graphics("./img/git_commit.png")
279 | ```
280 |
281 | ---
282 |
283 | # Pulling changes from the remote repository
284 |
285 | You can also pull changes from the remote repository via the *Pull* button in the `Git` tab.
286 |
287 | As a general workflow recommendation (especially if you're just getting started with `Git` and *GitHub*/*GitLab*) it is usually advisable to first pull from the remote repository before making (and then staging, committing, and pushing) any local changes. This is even more relevant when you collaborate with others on the same repository (more on that later).
288 |
289 | ---
290 |
291 | # Pulling changes from the remote repository
292 |
293 | **Important technical note**: If you click the *Pull* button in *RStudio* this will perform a [pull with rebase](http://gitready.com/advanced/2009/02/11/pull-with-rebase.html). Put briefly, pulling with rebase means that local changes are reapplied on top of remote changes. This is [different from pull with merge](https://sdqweb.ipd.kit.edu/wiki/Git_pull_--rebase_vs._--merge). In many scenarios, this is generally the preferable method and nothing you need to worry about. However, in some cases, this can cause issues, and it is good to be aware of this.
294 |
295 | ---
296 |
297 | # Limitations of the GUI
298 |
299 | While the *RStudio* GUI can be used for quite a few basic `Git` operations, it has a set of limitations. The first one is the use of specific defaults as is the case with pulling (with rebase). Another one is that it can become quite tedious to stage a large number of files through the GUI.
300 |
301 | ---
302 |
303 | # Limitations of the GUI
304 |
305 | Another downside of interacting with `Git` through the *RStudio* GUI is that there is a risk of *RStudio* becoming really slow or even crashing if you add/commit a lot of files at the same time and/or very large files. If the overall size of added or altered files is large, the Commit menu in *RStudio* usually also gives a warning about this.
306 |
307 | The *RStudio* GUI is also not the best tool for [handling merge conflicts](https://happygitwithr.com/git-branches.html?q=merge%20conflict#dealing-with-conflicts) (we will discuss those in more detail when we talk about *Git* & collaboration).
308 |
309 |
310 | ---
311 |
312 | # Destination `Terminal`
313 |
314 | If you want to add/commit a lot of files or large files, want more control over the `Git` commands, or need to use more advanced `Git` operations, the *RStudio* GUI is not the right choice. Instead, you should use a command line interface (CLI).
315 |
316 | ---
317 |
318 | # Destination `Terminal`
319 |
320 | Lucky for us, if you need a CLI for using `Git`, you don't need to leave *RStudio*. As of version 1.3.1056-1, *RStudio* provides a `Terminal` tab in the console pane. Through this, *RStudio* provides access to the [system shell](https://happygitwithr.com/shell.html). If you have properly installed `Git` you can use this to execute the full range of `Git` commands.
321 |
322 | ---
323 |
324 | # Picking shells `r ji("shell")`
325 |
326 | Depending on your OS as well as your installation of `Git`, you can pick different shells to be run in the *RStudio* Terminal tab. You can choose those via the the *Terminal* menu in the *RStudio* Global Options.
327 |
328 | ```{r terminal-menu, out.width = "45%", echo=FALSE}
329 | include_graphics("./img/terminal_menu.png")
330 | ```
331 |
332 | ---
333 |
334 | # Picking shells `r ji("shell")`
335 |
336 | If you use *Windows* and have installed `Git` for *Windows*, you should use `Git Bash` as the shell that is run in the *RStudio* terminal (shown in the picture below). On *MacOS*, you should be able to simply use its own `Terminal` in *RStudio*.
337 |
338 | ```{r terminal, out.width = "80%", echo=FALSE}
339 | include_graphics("./img/terminal.png")
340 | ```
341 |
342 | ---
343 |
344 | # Terminal and Shell in *RStudio*
345 |
346 | For some more information on choosing and using the shell in *RStudio*, you can check out the [chapter on this in *Happy Git and GitHub for the useR*](https://happygitwithr.com/shell.html) or the *RStudio* How To Article on [*Using the RStudio Terminal in the RStudio IDE*](https://support.rstudio.com/hc/en-us/articles/115010737148-Using-the-RStudio-Terminal-in-the-RStudio-IDE).
347 |
348 | ---
349 |
350 | # Using the `Terminal` in *RStudio*
351 |
352 | You can use the `Terminal` in *RStudio* to run all available `Git` commands, such as `git status`.
353 |
354 | ```{r git-status, out.width = "80%", echo=FALSE}
355 | include_graphics("./img/git-status.png")
356 | ```
357 |
358 | ---
359 |
360 | # Using the `Terminal` in *RStudio*
361 |
362 | You can also use the full range of arguments to customize your `Git` commands. For example, to stage and commit all changes, you could run the following command in the `Terminal`: `git add -A && git commit -m "Your Message"`
363 |
364 | ---
365 |
366 | class: center, middle
367 |
368 | # [Exercise](https://crsh.github.io/reproducible-research-practices-workshop/exercises/5_git-rstudio_question.html) time `r ji("weight_lifting_woman")``r ji("muscle")``r ji("running_man")``r ji("biking_man")`
369 |
370 | ## [Solutions](https://crsh.github.io/reproducible-research-practices-workshop/exercises/5_git-rstudio_solution.html)
371 |
372 | ---
373 |
374 | # Resources
375 |
376 | A really great resource on using `Git` (and *GitHub*) in combination with `R` and *RStudio* is the website [*Happy Git and GitHub for the useR*](https://happygitwithr.com/) by [Jennifer Bryan](https://jennybryan.org/). Much of the content in this session is based on this resource and it offers a lot of additional helpful information and advice (including some help with troubleshooting commonly encountered issues).
377 |
378 | Another good introductory resource is the *RStudio* How-To Article on [*Version Control with Git and SVN*](https://support.rstudio.com/hc/en-us/articles/200532077?version=2021.09.0%2B351&mode=desktop).
379 |
380 |
--------------------------------------------------------------------------------
/src/slides/6_github_collaboration.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title : "Reproducible research workflows for psychologists"
3 | subtitle : "Collaborate with Git & GitHub"
4 |
5 | author : " `r paste(params$author, collapse = ' & ')`"
6 | date : "`r paste0(params$location, ', ', params$date)`"
7 | ---
8 | exclude: true
9 |
10 | ```{r child = "_setup.Rmd"}
11 |
12 | ```
13 |
14 |
15 | ---
16 | layout: false
17 | name: git-system
18 |
19 | # Git
20 |
21 | ```{r out.height="", out.width="550px", echo = FALSE}
22 | knitr::include_graphics("img/git-system.png")
23 | ```
24 |
25 | ---
26 | layout: true
27 | name: collabo
28 |
29 | # Collaboration
30 |
31 | ---
32 |
33 | **Add collaborators**
34 |
35 | .center[
36 | `Settings > Manage access > Add people`
37 | ]
38 |
39 | ```{r out.height="", out.width="700px", echo = FALSE}
40 | knitr::include_graphics("img/github-add-collaborator.png")
41 | ```
42 |
43 | ---
44 |
45 | **Add collaborators**
46 |
47 | .center[
48 | `Project information > Members > Invite members`
49 | ]
50 |
51 | ```{r out.height="", out.width="600px", echo = FALSE}
52 | knitr::include_graphics("img/gitlab-add-collaborator.png")
53 | ```
54 |
55 | ---
56 |
57 | GitHub provides a lot of collaboration features
58 |
59 | - Edit files in browser
60 | - Change highlighting and commenting
61 | - Interactive revise-and-resubmit workflow
62 | - [See example](https://github.com/crsh/papaja/pull/443)
63 | - Issue tracker (to-do list and discussion)
64 | - ...
65 |
66 |
67 | ???
68 | - Rich change view
69 | - Comments on commits
70 | - GitHub workflow is used by JOSS
71 |
72 | Show git blame ;)
73 |
74 | ---
75 |
76 | Workflows for collaboration
77 |
78 | 1. "Publishing" changes without prior review
79 | - Push directly to `main` branch on GitHub
80 | --
81 | 2. Suggest changes with review (*pull request*)
82 | - Create a new *branch* ("parallel universe" of repository)
83 | --
84 |
85 | Edit on GitHub or in RStudio on your computer
86 |
87 | ---
88 | layout: false
89 |
90 | # Pull requests
91 |
92 | ```{r out.height="", out.width="500px", echo = FALSE}
93 | knitr::include_graphics("img/github-workflow.png")
94 | ```
95 |
96 | 1. Pull current state of repository
97 | 2. Create new _branch_ ("parallel universe")
98 | 3. Make changes, stage, commit, & push
99 | 4. Discuss and revise changes
100 | 5. Merge changes
101 |
102 |
103 | ---
104 | layout: true
105 |
106 | # Editing on GitHub
107 |
108 | ---
109 |
110 | Small changes (to one file) in the browser on GitHub
111 |
112 | ```{r out.height="", out.width="700px", echo = FALSE}
113 | knitr::include_graphics("img/github-edit.png")
114 | ```
115 |
116 | ---
117 |
118 | ```{r out.height="", out.width="700px", echo = FALSE}
119 | knitr::include_graphics("img/github-edit-pr.png")
120 | ```
121 |
122 |
123 | ---
124 |
125 | ```{r out.height="", out.width="700px", echo = FALSE}
126 | knitr::include_graphics("img/github-open-pr.png")
127 | ```
128 |
129 |
130 | ???
131 | - Request reviewer
132 |
133 |
134 | ---
135 | name: review
136 |
137 | Reviewers can provide
138 |
139 | - comments on specific changes
140 |
141 | ---
142 | template: review
143 |
144 | ```{r out.height="", out.width="700px", echo = FALSE}
145 | knitr::include_graphics("img/github-inline-comment.png")
146 | ```
147 |
148 | ---
149 | template: review
150 |
151 | - higher level comments on the entire pull request
152 |
153 | ```{r out.height="", out.width="650px", echo = FALSE}
154 | knitr::include_graphics("img/github-pr-review.png")
155 | ```
156 |
157 |
158 | ???
159 | Show how to make additional changes after review
160 |
161 | https://github.com/crsh/my-first-repository/pull/1
162 |
163 |
164 | ---
165 | layout: true
166 | template: footer
167 |
168 | # Editing on your computer
169 |
170 | ---
171 |
172 | Larger changes across multiple files in RStudio
173 |
174 | 1. Pull current state of remote repository
175 | 2. Switch to new _branch_ ("parallel universe")
176 | 3. Make changes, stage, commit, & push
177 |
178 | .pull-left-45[
179 |
180 | ~~~bash
181 | git pull
182 | *git branch revision
183 | *git checkout revision
184 | git status
185 | git add .
186 | git commit -m "My changes"
187 | ...
188 | *git push origin revision
189 | ~~~
190 |
191 | ]
192 |
193 | .pull-right-45[
194 |
195 | ```{r out.height="", out.width="100%", echo = FALSE}
196 | knitr::include_graphics("img/rstudio-branches.png")
197 | ```
198 |
199 | ]
200 |
201 | ---
202 |
203 | ```{r out.height="", out.width="100%", echo = FALSE}
204 | knitr::include_graphics("img/github-pr-branch.png")
205 | ```
206 |
207 |
208 | ---
209 |
210 | ```{r out.height="", out.width="100%", echo = FALSE}
211 | knitr::include_graphics("img/github-pr-branch2.png")
212 | ```
213 |
214 | ---
215 | layout: true
216 |
217 | # Merge conflicts `r ji("scream")`
218 |
219 | ---
220 |
221 | Competing changes to *the same line of text*
222 |
223 | ```{r out.height="", out.width="100%", echo = FALSE}
224 | knitr::include_graphics("img/github-merge-conflict.png")
225 | ```
226 |
227 | ---
228 |
229 | Review competing changes marked by `<<<<<<<<` and `>>>>>>>>`
230 |
231 | ```{r out.height="", out.width="100%", echo = FALSE}
232 | knitr::include_graphics("img/github-merge-conflict-edit.png")
233 | ```
234 |
235 | --
236 |
237 | Again, this can be done on GitHub or in RStudio
238 |
239 | ---
240 |
241 | Stage and commit conflict resolution
242 |
243 | ```{r out.height="", out.width="100%", echo = FALSE}
244 | knitr::include_graphics("img/github-merge-conflict-resolve.png")
245 | ```
246 |
247 | ~~~bash
248 | git add .
249 | git commit -m "Resolved merge conflict by doing something"
250 |
251 | ~~~
252 |
253 | ---
254 | layout: false
255 | class: middle, center
256 |
257 | # Exercise time
258 |
259 | .center[[Exercise](http://frederikaust.com/reproducible-research-practices-workshop/exercises/6_github_collaboration_question.html)]
260 |
261 | .center[[Solutions](http://frederikaust.com/reproducible-research-practices-workshop/exercises/6_github_collaboration_solution.html)]
262 |
--------------------------------------------------------------------------------
/src/slides/7_Other_Topics.Rmd:
--------------------------------------------------------------------------------
1 | ---
2 | title : "Reproducible research workflows for psychologists"
3 | subtitle : "Other topics in reproducible research"
4 |
5 | author : " `r paste(params$author, collapse = ' & ')`"
6 | date : "`r paste0(params$location, ', ', params$date)`"
7 | ---
8 | exclude: true
9 |
10 | ```{r child = "_setup.Rmd"}
11 | ```
12 |
13 | ---
14 |
15 | # Other topics in reproducible research
16 |
17 | .small[
18 | As we said in the introduction, we cannot cover all tools and topics related to reproducible research in this workshop. However, we want to use this session to cover some additional tools as well as other topics in reproducible research:
19 |
20 | - Collaborating with others who do not use `R Markdown` and/or `Git`
21 | - R package dependency management
22 | - Preventing code rot
23 | - Publishing reproducible research environments and "one-click reproducibility"
24 | ]
25 |
26 | ---
27 |
28 | # Other approaches to collaboration
29 |
30 | There also are `R` packages that you can use for collaborating on `R Markdown` documents with people who do not (want to) use `R Markdown` (and `Git`):
31 |
32 | - [`trackdown`](https://claudiozandonella.github.io/trackdown/) uses *Google Drive* for this
33 |
34 | - [`redoc`](https://noamross.github.io/redoc/) "is a package to enable a two-way R Markdown-Microsoft Word workflow" (*note*: development currently suspended)
35 |
36 | ---
37 |
38 | # `trackdown`
39 |
40 | The basic workflow for `trackdown` is that you upload the content of an `.Rmd` file to *Google Drive* where you can collaboratively edit the text parts. You can then download the document again (e.g., to edit the code in the `R Markdown` document in *RStudio*), and also update the file on *Google Drive* after changing the `.Rmd` locally. The [`trackdown` documentation](https://claudiozandonella.github.io/trackdown/) provides further details.
41 |
42 | ---
43 |
44 | # Advanced use of `trackdown` with `Git`
45 |
46 | To combine `R Markdown` with collaborative text editing via `trackdown` and version control (and to avoid potential issues caused by - possibly unintended - changes to the code parts on *Google Drive*), the author of the `trackdown` package, [Claudio Zandonella Callegher](https://github.com/ClaudioZandonella), proposes a solution in an [issue in the *GitHub* repository for the package](https://github.com/ClaudioZandonella/trackdown/issues/31).
47 |
48 | Essentially, the idea here is to create a `trackdown` branch in the `Git` repository and merge it with the `main` branch which is (mainly) used to edit the code.
49 |
50 |
51 |
52 |
53 | ---
54 | layout: true
55 | template: footer
56 |
57 | # Dependency management
58 |
59 |
60 | ---
61 |
62 | ```{r zoomable-plot, out.width = "75%", out.extra='id="zoom-margin"'}
63 | include_graphics("img/dependendy-graph.png")
64 | ```
65 |
66 | ---
67 |
68 | - Our projects may use/require different package versions
69 | - Manually managing dependencies is a nightmare
70 | - Keeping track of the dependencies and their changes
71 | - Restore the R environment
72 |
73 | ---
74 |
75 | 1. [`checkpoint`](https://github.com/RevolutionAnalytics/checkpoint/) by Microsoft
76 | - Requires a project-based workflow
77 | - Package database will gradually grow
78 | --
79 |
80 | 2. [`groundhog`](https://groundhogr.com/)
81 | - Package database will gradually grow
82 | --
83 |
84 | 3. [`renv`](https://rstudio.github.io/renv/articles/renv.html) by RStudio
85 | - Most flexible and powerful
86 | - Least straight forward to use
87 | - No "forensic" applications
88 |
89 | ---
90 |
91 | ```{r}
92 | include_graphics("img/checkpoint-pkg.png")
93 | ```
94 |
95 |
96 | ---
97 |
98 | Dependencies are detected automatically
99 |
100 | ```{r echo = TRUE, eval = FALSE}
101 | library("checkpoint")
102 | checkpoint("2022-04-27")
103 |
104 | library("ggplot2")
105 | ```
106 |
107 | --
108 |
109 | Uses a date-specific directory outside of usual library
110 |
111 | ```bash
112 | ~/.checkpoint/...
113 | ```
114 |
115 | ---
116 | layout: true
117 | template: footer
118 |
119 | # Code rot
120 |
121 | ---
122 | name: toppling
123 |
124 | .pull-left-75[
125 |
126 | ```{r echo = FALSE, fig.align = "center", out.height = "475px", out.width = ""}
127 | knitr::include_graphics("img/toppling-tower.jpg")
128 | ```
129 |
130 | ]
131 |
132 | ---
133 | template: toppling
134 |
135 | .pull-right-25[
136 |
137 | `r ji("white_check_mark")`
138 | ]
139 |
140 |
141 | ---
142 | - We need to archive the computing environment
143 |
144 | --
145 | - But how?
146 |
147 | --
148 | - Lock away computer used to run the analysis?
149 | - Trade-off between robustness and feasibility
150 |
151 | --
152 |
153 |
154 |
155 | ```{r echo = TRUE, eval = FALSE}
156 | checkpoint("2020-01-01", r_version = "3.6.2")
157 | ```
158 |
159 | ---
160 | template: toppling
161 |
162 | .pull-right-25[
163 |
205 | `r ji("white_check_mark")`
206 | ]
207 |
208 |
209 | ---
210 | layout: false
211 |
212 | # Docker
213 |
214 | ```{r echo = FALSE, fig.align = "center", out.height = "", out.width = "450px"}
215 | knitr::include_graphics("img/docker-logo.png")
216 | ```
217 |
218 |
219 | ---
220 | layout: true
221 |
222 | # Docker: Kind of like Hermann
223 |
224 |
225 | > Herman cake (often called Herman) is a 'friendship cake'. [...] the starter is passed from person to person (like a chain letter) and continues to grow as it contains yeast and lactic acid bacteria. One starter can, in theory, last indefinitely. ([Wikipedia](https://en.wikipedia.org/wiki/Herman_cake))
226 |
227 |
228 | ---
229 |
230 | ```{r echo = FALSE, fig.align = "center", out.height = "", out.width = "700px"}
231 | knitr::include_graphics("img/hermann.png")
232 | ```
233 |
234 |
235 | ---
236 |
237 | ```{r echo = FALSE, fig.align = "center", out.height = "", out.width = "700px"}
238 | knitr::include_graphics("img/hermann-docker.png")
239 | ```
240 |
241 |
242 | ---
243 | layout: true
244 |
245 | # Docker
246 |
247 | ---
248 |
249 | Built on a prepackaged base images from DockerHub (["rocker"](https://github.com/rocker-org/rocker#versioned-stack-builds-on-r-ver))
250 |
251 | ```{r echo = FALSE, fig.align = "center", out.height = "", out.width = "450px"}
252 | knitr::include_graphics("img/rocker-images.png")
253 | ```
254 |
255 | ---
256 |
257 | **Simplified Docker example**
258 |
259 | --
260 |
261 | ~~~Dockerfile
262 | # Select base image
263 | FROM rocker/rstudio:4.1.2
264 | ~~~
265 |
266 | - Latest Debian version
267 | - R 4.1.2
268 | - Latest RStudio version
269 | - Pandoc
270 | - Git
271 |
272 |
273 | ---
274 |
275 | Add system-level requirements
276 |
277 | ~~~Dockerfile
278 | # System libraries
279 | RUN apt-get update \
280 | && apt-get install -y --no-install-recommends \
281 | * libgsl0-dev \
282 | * libnlopt-dev \
283 | * libxt6 \
284 | * ssh
285 | ~~~
286 |
287 |
288 | ---
289 |
290 | Install TeX Live 2021 and required LaTeX packages
291 |
292 | ~~~Dockerfile
293 | # TeX Live
294 | ENV CTAN_REPO=http://mirror.ctan.org/systems/texlive/tlnet
295 | RUN /rocker_scripts/install_texlive.sh
296 | ENV PATH=$PATH:/usr/local/texlive/bin/x86_64-linux
297 |
298 | RUN tlmgr install \
299 | * apa6 apa7 booktabs caption csquotes \
300 | * ...
301 | ~~~
302 |
303 |
304 | ---
305 |
306 | Install `papaja` and required R packages
307 |
308 | ~~~Dockerfile
309 | # Setup R packages for papaja
310 | RUN install2.r --error \
311 | --skipinstalled \
312 | * tinytex \
313 | * remotes \
314 | * markdown \
315 | * mime
316 |
317 | ## Latest papaja development version
318 | RUN Rscript -e "remotes::install_github('crsh/papaja')"
319 | ~~~
320 |
321 | ---
322 |
323 | Our image bundles (among other things)
324 |
325 | - Latest Debian version
326 | - R 4.1.2
327 | - Latest RStudio version
328 | - Pandoc
329 | - Git
330 |
331 | --
332 | - .highlight[TeX Live 2021]
333 | - .highlight[Latest `papaja` version]
334 |
335 |
336 | ---
337 | exclude: true
338 |
339 | Online services (e.g. CodeOcean, Clyburne-Sherin, Fei, & Green, 2019)
340 |
341 | ```{r out.width = "600px"}
342 | include_graphics("img/codeocean.png")
343 | ```
344 |
345 | Limited computational resources
346 |
347 |
348 | ---
349 |
350 | [A minimally obtrusive Docker workflow to work reproducibly with papaja](https://github.com/crsh/papaja_docker)
351 |
352 | ```{r out.width = "700px"}
353 | include_graphics("img/papaja-docker-repo.png")
354 | ```
355 |
356 |
357 | ---
358 | layout: false
359 | class: middle, center
360 |
361 | # A quick demonstration!
362 |
363 |
364 | ---
365 |
366 |
367 |
368 | # Publishing reproducible research environments
369 |
370 | If you want to publicly share your fully reproducible research environment and allow others to interact with it without having to install any software on their own machines, you can use services like [*Code Ocean*](https://codeocean.com/) or [*RStudio Cloud*](https://rstudio.cloud/). A good free and open source alternative is [*BinderHub*](https://binderhub.readthedocs.io/en/latest/).
371 |
372 | ---
373 |
374 | # What is *BinderHub*?
375 |
376 | From the [*BinderHub GitHub* repository](https://github.com/jupyterhub/binderhub):
377 |
378 | *BinderHub* allows you to `BUILD` and `REGISTER` a `Docker` image from a `Git` repository, then `CONNECT` with *JupyterHub*, allowing you to create a public IP address that allows users to interact with the code and environment within a live *JupyterHub* instance. You can select a specific branch name, commit, or tag to serve.
379 |
380 | ---
381 |
382 | # What is *BinderHub*?
383 |
384 | From the [*BinderHub GitHub* repository](https://github.com/jupyterhub/binderhub):
385 |
386 | *BinderHub* ties together:
387 |
388 | - [*JupyterHub*](https://github.com/jupyterhub/jupyterhub) to provide a scalable system for authenticating users and spawning single user [`Jupyter Notebook`](https://jupyter.org/) servers, and
389 | - [*Repo2Docker*](https://github.com/jupyter/repo2docker) which generates a `Docker` image using a `Git` repository hosted online.
390 |
391 | ---
392 |
393 | # What is *BinderHub*?
394 |
395 | ```{r binger-img, out.width = "125%", echo=FALSE}
396 | include_graphics("./img/binderhub.png")
397 | ```
398 |
399 | ---
400 |
401 | # How to use *BinderHub*
402 |
403 | Using a *BinderHub* deployment like [*mybinder.org*](https://mybinder.org/) or [*GESIS Notebooks*](https://notebooks.gesis.org/binder/) you can turn an existing public `Git` repository into a publicly accessible executable environment.
404 |
405 | In order for this to work, you just need to add a few *Binder*-specific files to your repo (i.e., "Binderize" it).
406 |
407 | --
408 |
409 | .small[
410 | A platform that works in similar ways is [*PsychNotebook*](https://www.psychnotebook.org/)
411 | by the [Leibniz Institute for Psychology (ZPID)](https://leibniz-psychology.org/en/).
412 | ]
413 |
414 | ---
415 |
416 | # Binderizing your `Git` repository
417 |
418 | The minimum requirements are the following:
419 |
420 | 1. Add a `binder` folder to your repo
421 | 2. In that folder, create two files: `runtime.txt` & `install.R`
422 |
423 | .small[
424 | *Note*: It would also be ok to add those files to the root folder of your project.
425 | ]
426 |
427 | ---
428 |
429 | # Binderizing your `Git` repository
430 |
431 | In the `runtime.txt` file, you need to specify a version number and date, indicating which [snapshot](https://packagemanager.rstudio.com/client/#/repos/1/overview) to use from the [*R Studio Package Manager*](https://packagemanager.rstudio.com/client/#/). Example: `r-4.1-2022-04-22`).
432 |
433 | ---
434 |
435 | # Binderizing your `Git` repository
436 |
437 | In the `install.R` file, you need to specify which `R` packages to install as you normally would in an `.R` file (e.g., `install.packages(c("gapminder", "tinytex"))`). *CRAN* packages are installed through the [*R Studio Package Manager*](https://packagemanager.rstudio.com/client/#/).
438 |
439 | ---
440 |
441 | # Binderizing your `Git` repository
442 |
443 | There are many more options for changing or extending the executable environment. Two good resources to learn more are the [*Turing Way* guide *Zero-to-Binder*](https://the-turing-way.netlify.app/communication/binder/zero-to-binder.html) or the [*Binder* example for `R`](https://github.com/binder-examples/r).
444 |
445 | ---
446 |
447 | # Deploying your executable environment
448 |
449 | Once you have "Binderized" your repository, you can use [*mybinder.org*](https://mybinder.org/) to create the executable environment. You can set a few additional parameters in the process (such as the branch). *NB*: Creating the executable environment can take some time (esp. if you install many and/or large `R` packages).
450 |
451 | --
452 |
453 | .small[
454 | *Note*: You can also use the [`holepunch` package](https://karthik.github.io/holepunch/) to Binderize your `R` project hosted on *GitHub*.
455 | ]
456 |
457 | ---
458 |
459 | # Deploying your executable environment
460 |
461 | Once the executable environment has been created, anyone who has the link to it can use it. The easiest way to share it and enable "1-click reproducibility" for others is by adding a *Launch Binder* button to the `README` for your associated *GitHub* (or *GitLab*) repository. The `Markdown` code for this will be displayed on the *mybinder* site.
462 |
463 | ---
464 |
465 | # Things to note when using *Binder*
466 |
467 | .smaller[
468 | 1. The *BinderHub* deployments are hosted on free-to-use servers (sometimes by academic institutions), so you might experience some "hiccups" in deploying and using the executable environments (e.g., if the service is heavily used at the time).
469 | 2. Related to that, the amount of RAM is limited for the executable environment.
470 | 3. One thing you need to consider is how to share your data when using *Binder*. The [*Turing Way* guide *Zero-to-Binder*](https://the-turing-way.netlify.app/communication/binder/zero-to-binder.html) has some suggestions for that.
471 | 4. By default, the link to the executable environment will open an instance of [*Jupyter Notebook*](https://jupyter.org/), but it is also possible to run [*Jupyter Lab*](https://jupyterlab.readthedocs.io/en/stable/#), or *RStudio* (this can be done by adding parameters at the end of the URL, such as `$urlpath=rstudio`).
472 | ]
473 |
474 | ---
475 |
476 | # Test drive `r ji("racing_car")`
477 |
478 | We have prepared a Binderized repo for you that you can test, clone, fork or whatever else you would like to to: https://github.com/jobreu/binder-r-demo
479 |
480 | ---
481 |
482 | # Exercise
483 |
484 | Try out and explore one or more of the tools we have just presented:
485 |
486 | - `trackdown`
487 | - one of the `R` packages for dependency management (such as `renv`, `checkpoint`, or `groundhog`)
488 | - `Docker`
489 | - `Binder`
490 |
491 | ---
492 |
493 | # Exercise
494 |
495 | What did you do?
496 |
497 | What were your experiences?
498 |
499 | Do you think you are going to use the tool(s)? Why/why not? If yes, for what purposes?
500 |
501 | ---
502 |
503 | # Project setup and templates
504 |
505 | In this workshop, we have shown you how to manually set up a reproducible research workflows. However, there are some tools that you can use to automate parts of this process. These can range from very simple to very elaborate solutions. We will show you two examples in the following.
506 |
507 | ---
508 |
509 | # Project setup and templates
510 |
511 | `create-project.sh`: small shell script for initializing a basic project folder structure (which can be easily adapted and extended using any text editor)
512 |
513 | To run the file, open a shell/command line interface (and navigate to) where the `create-project.sh` file is located. To execute it, you need to provide a valid path for the new project folder that should be created as an argument.
514 |
515 | ---
516 |
517 | # Project setup and templates
518 |
519 | ```{r eval=FALSE, echo=TRUE}
520 | sh create-project.sh "./my-project"
521 | ```
522 |
523 | ---
524 |
525 |
526 |
527 | # Project setup and templates
528 |
529 | Frederik's `R` package for initializing new projects: https://github.com/crsh/template
530 |
531 | ---
532 |
533 |
534 |
535 | # Workflow tools
536 |
537 | There also several `R` other packages for facilitating the creation and maintenance of reproducible research workflows, such as...
538 |
539 | - [`WORCS`](https://cjvanlissa.github.io/worcs/index.html) - *Workflow for Open Reproducible Code in Science*
540 | - [`workflowr`](https://workflowr.github.io/workflowr/)
541 | - [`starter`](https://www.danieldsjoberg.com/starter/)
542 | - [`rrtools`](https://github.com/benmarwick/rrtools) - Tools for Writing Reproducible Research in R
543 |
544 | [*start your lab*](https://www.startyourlab.com/) also provides an [`R` Project Template](https://github.com/startyourlab/r-project-template).
545 |
546 | ---
547 |
548 | # Choosing the right tools `r ji("hammer")``r ji("wrench")`
549 |
550 | There are a few things to consider for choosing the right tools:
551 |
552 | - Your **habits, knowledge, and preferences** (as well as those of your collaborators)
553 | - Your **goals** and their relative importance: E.g., computational reproducibility, reusability, replicability
554 | - Your **audience**: Future you, collaborators, the academic community, the general public
555 |
556 | ---
557 |
558 | # Shoulders of giants... but sometimes also clay feet
559 |
560 | .small[
561 | As you may have already experienced, not all tools always play together nicely. Keep in mind, that most tools that we have covered in this workshop are free and open source software (FOSS). Also, tool stacks can have break points and many tools themselves depend on other tools/tool stacks. Hence, things may not always work perfectly.
562 |
563 | But don't despair! There usually are solutions ([*Stack Overflow*](https://stackoverflow.com/) and issues in associated *GitHub* repositories are good places to find them) and the advantage of FOSS is that there usually is an active development community that you can also get involved in.
564 | ]
565 |
566 | ---
567 |
568 | # Showing appreciation `r ji("clapping_hands")`
569 |
570 | The creation and maintenance of FOSS takes a lot of time and this is rarely recognized as much as it should be. One thing we can do to change this is to at least give credit where credit is due and cite the tools and resources that we use.
571 |
572 | ---
573 |
574 | # Showing appreciation `r ji("clapping_hands")`
575 |
576 | ```{r cite, echo=TRUE}
577 | citation("papaja")
578 | ```
579 |
580 | ---
581 |
582 | # Showing appreciation `r ji("clapping_hands")`
583 |
584 | When working with `R Markdown`, you can create a `packages.bib` file to cite the packages you have used, either manually, using `papaja::r_refs()`, or the [`grateful` package](https://pakillo.github.io/grateful/).
585 |
586 | ---
587 |
588 | # Share the `r ji("heart")` for reproducible research tools
589 |
590 | In addition to properly citing the tools and resources you use, you can make sure that they get the recognition they deserve by talking about them (e.g., on social media) and convincing your collaborators to use them as well.
591 |
592 | ---
593 |
594 | # Looking back
595 |
596 | You created a *GitHub*/*GitLab* repository containing materials for a fully reproducible research pipeline! `r ji("popper")`
597 |
598 | If you created a public *GitHub* repository: Head over to http://starlogs.net/ and paste the URL of the repository to recap your heroic journey into the universe of reproducible research! `r ji("milky_way")`
599 |
600 | ---
601 |
602 | # Looking forward
603 |
604 | We hope that we could get you started or help you with with making your research (more) reproducible.
605 | Of course, as always, there is much more to explore and learn. The only way to really get familiar with the tools and workflows is if you use them for your own research.
606 |
607 | --
608 |
609 | Keep calm and stay reproducible! `r ji("smiling_face_with_smiling_eyes")`
610 |
611 | ---
612 |
613 | class: center, middle
614 |
615 | # Thank you very much for participating in this workshop! `r ji("bowing_man")`
616 |
617 | We hope that you learned something and also had some fun (at least a little bit...)
618 |
--------------------------------------------------------------------------------
/src/slides/_output.yaml:
--------------------------------------------------------------------------------
1 | xaringan::moon_reader:
2 | lib_dir: libs
3 | chakra: libs/remark-latest.min.js
4 | css: ["src/xaringan-themer.css", "src/slides.css"]
5 | nature:
6 | countIncrementalSlides: false
7 | highlightLines: true
8 | slideNumberFormat: |
9 |