-
Notifications
You must be signed in to change notification settings - Fork 0
/
comp_reproducible.qmd
106 lines (64 loc) · 7.95 KB
/
comp_reproducible.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
---
title: "Reproducibility"
fig-cap-location: bottom
bibliography: references.bib
---
In this tutorial, we focus on the practical aspects of making sure that the code we write can be run on other machines, by other people, and in the future. In other words, we want to make sure that our code is portable and future-proof by ensuring the software originally used in creating our code is the same software used by others. Let’s look at this in more detail.
# What is Reproducibility?
## A Brief Definition
> I propose to consider the question "What is reproducibility?" As reproducibility is such a central concept in science, one would think that it would be clearly defined. However, this is not the case. Reproducibility is an elusive concept. It has no single commonly agreed upon definition. Rather, it has many different, and each of these captures central, but different properties of it...
>
> -- <cite>Odd Erik Gundersen</cite> [-@erikgundersen2021]
Gundersen explores many definitions put forward for "reproducibility", but, for the purposes of this tutorial, his exploration of reproducibility is best summarized as "the ability of independent investigators to draw the same conclusions from an experiment by following the documentation shared by the original investigators" [@erikgundersen2021].
In principle, this sounds simple enough--provide others with enough information, and they should be able to reproduce your work! Achieving this in practice is, of course, a vastly complex endeavor that requires careful planning and execution. Above all, opinions on what constitutes sufficient "documentation" or how much documentation is necessary to achieve reproducibility can vary widely.
One might assume that academic publications provide all of the information required for an independent researcher to reproduce a publication; the requisite background on the topic, the data cleaning choices, and the exact statistical methods employed to arrive at a conclusion are theoretically included in a paper.[^1] In practice, a written publication generally cannot capture all of the nuances of data cleaning, exploration, and analysis employed by the original researchers. As a result, reproducing an analysis result only from a written description is, at best, incredibly time-consuming, and, at worst, an impossible endeavor.
[^1]: Assuming, of course, that the data for the analysis can also be accessed either because it is publicly available or by way of contacting the original researcher.
To address the shortcomings of written descriptions, **researchers must also strive to publish their code, data, and ideally both code and data together such that the *complete* documentation of the project is available to others.** This tutorial specifically covers how to document the R version and R packages used in a project to ensure that the code can be run on other machines.
## Reproducible Code
Why should we concern ourselves with making reproducible *code* specifically? From a scientific perspective, reproducible code is essential in allowing other researchers to verify findings, to build upon existing work, and to ensure that the scientific process is transparent and trustworthy. From a practical perspective, reproducible code can save time and effort in the long run by making it easier to revisit and understand one's own work, to make debugging and troubleshooting easier, and to collaborate with others.
In the context of this tutorial, we will focus on the practical aspects of making code reproducible. This mainly means taking steps to ensure that the code we write can be run on other machines, by other people, and in the future. In other words, we want to make sure that our code is **portable** and **future-proof** by ensuring the software originally used in creating our code is the same software used by others. Let's look at this in more detail.
# The \~Machines\~
## Your Computer
Getting code to work on your own machine is, in principle, not too difficult. You can install the necessary software specific to your hardware and software, set up your environment, and run your code! Simple, right? (Writing code that actually works is another story, of course 😉.)
However, this is only half the battle. When you run your code on your machine, you are running it in an environment that you have set up and configured to your liking. You have installed the software *you* need, perhaps have set up specific paths, and configured various settings to your preferences.
::: center
```{r, out.width="85%", echo=FALSE}
knitr::include_graphics("assets/img/works_on_my_machine.jpg")
```
:::
## Someone Else's Computer
When you share your code with others, you are effectively asking them to run *your* code on *their* machine, and it is unlikely that their computer is set up exactly like yours given how many degrees of freedom there are in operating systems, programming languages, software, and the different versions of these. A non-exhaustive list of examples where there might be software discrepancies are detailed below.
### Major Machine & Software Differences
<br>
::: panel-tabset
## Operating systems
It's already well-known that different operating systems can have different software requirements. For example, some software might only be available on Windows, while others might only be available on MacOS or Linux.
However, it is also important to consider that different versions of the same operating system can have different software requirements. For example, some software might only be compatible with Windows 10 and not Windows 11.
::: center
:::
## Programming languages
Another obvious difference is the programming language used in a project. For example, a project written in R will not run (correctly) in a Python, MATLAB, or Julia environment.
Less obvious, however, and more common as a pain-point, are the differences in versions of programming languages. For example, a project written in Python 3.8 might not run in Python 3.9 due to changes in the language, and most R packages are only tested for compatibility back to the 5 most recent minor releases of R (e.g. 4.4, 4.3, 4.2, 4.1, 4.0).
Fortunately, most modern programming languages are cross-compatible across recent, major operating systems without issue.
::: center
:::
## Packages/Libraries (Add-Ons)
The most likely pain point for reproducibility is the software add-ons, or packages/libraries, that are used in a project. For example, in R, there are over 20,000 packages available on CRAN, and in Python, there are over 200,000 packages available on PyPI.
Keeping track of which packages are used and the specific versions of those packages is a major challenge in reproducibility.
In the context of the R programming language, most packages are likewise compatible across operating systems.
::: center
:::
:::
<br>
## All of the Machines
::: callout-important
## Expect No One to Already Have the Required Software
1. Don't expect others to have the software you rely on.
2. Even if others have the software, don't expect them to have the **same version**.
:::
In summary, the software environment of a project can be incredibly complex, with many degrees of freedom. If you have ever tried to run someone else's code and it didn't work, it was likely due to one of these reasons. Moreover, it's not practical to manage most of these differences manually. For example, requesting that someone *manually* install Python v3.8.2, R v4.0.3, and specific versions of dozens of packages is technically possible, but exceptionally tedious and a poor use of time. So this brings us to our core question: how do we set up a project to work on everybody's machines?[^2] **By managing our software dependencies**, described in the next chapter.
[^2]: Within reason; many software and hardware configurations just simply were not meant to be, but most modern programming languages are cross-compatible across recent, major operating systems without issue.
<!-- footnotes -->