Reproducibility 3:
File Organization and RStudio Projects

File-related recommendations to improve the reproducibility of you research

reproducibility
Author

Jelmer Poelstra

Published

September 22, 2025

Artwork by @allison_horst


1 Introduction: Reproducibility

After covering Quarto in the first two sessions, today is the third of a series of Code Club sessions covering several topics under the umbrella of “reproducibility”.

I would like to start by taking a step back to talk about reproducibility in general. What do we mean by reproducibility? Your research is reproducible when third parties are able to perform the same analysis on your data, and produce the same results.

Reproducibility is perhaps a low bar compared to the related concept of replicability, which is the ability to produce the same (qualitative) results when applying the same analysis to different data. Here is a helpful table showing these two and two other related concepts:

From The Turing Way

For example:

  • Say that you’ve written a paper in which you present the results of one of your research projects. When this research is fully reproducible, it means that someone else should be able to be able to run the exact same analysis and produce all the results and figures using your paper and its associated documentation.

  • Relatedly, when you work in a reproducible manner and you abandon an analysis for say two years, you will be able to pick up from where you left off without much trouble.

1.1 Using R is already a big step in the right direction!

It is inherently more reproducible to write code, such as in R, as opposed to clicking around in a program with a Graphical User Interface (GUI). This is because it would generally be necessary but very tedious to record every single click that you make in a GUI, whereas it is easy to save your code.1

In addition, R is open source and freely available. If you use a proprietary program that requires an expensive license, your work may be reproducible in principle, but won’t be in practice for many people.

1.2 Additional aspects & the plan for this series

Research that is fully reproducible should use a set of tools and best-practice related to:

  • File organization (this session)
  • Code style and organization (next two sessions)
  • File version management (Git at the end of the semester)
  • Data and code sharing (In part: Git at the end of the semester)
  • Software management (Within R with renv - may cover this later?)
  • Project documentation

1.3 Today

Today, we’ll go over the following four recommendations related to file organization that improve your research projects’ reproducibility.

  1. Use a self-contained folder for each project
  2. Separate files using a consistent subfolder structure
  3. Use relative paths
  4. Use RStudio Projects

And at the bottom of the page, there is some reading material for fifth recommendation:

  1. Use good file names

2 Use a self-contained folder for each project

Using one folder, or really a hierarchy of folders, for one project means that you:

  • Don’t mix files for multiple distinct projects inside one folder.
  • Don’t keep files for one project in multiple places.

For example:

Two project folder hierarchies, nicely separated and self-contained.
The gray $HOME folder is a Home folder which exists for Mac and Linux users.
For Windows users, you can think of this e.g. as your Documents or Desktop folder.

When you have a single folder hierarchy for each project, it is:

  • Easier to find files and to share your project, harder to accidentally throw away stuff, etc.
  • Possible to use relative paths within a project’s scripts, which improves reproducibility (see below).

3 Separate files using a consistent subfolder structure

Within your project’s directory hierarchy, you should:

  • Separate code from data.
  • Separate raw data from processed data and from results.

For example, here is one good way of organizing a (bioinformatics) research project:

An example research project folder structure.
Folders are shown in blue and the README Markdown (.md) file is shown in black.

Also:

  • Treat raw data as read-only and as highly valuable.
  • Treat generated output as somewhat disposable and as possible to regenerate.

4 Use relative paths

A next reproducibility-related recommendation is to use relative paths in your R code. To understand this recommendation, we’ll go over the following key terms:

  1. “Directory” (“dir” for short) is just another word for folder commonly used in coding contexts.

  2. Your “working directory” is the directory where you are currently located. When you open R (or Python, or a Terminal, etc.), it will always have a starting point at a specific location in your computer2.

There are functions to change your working dir as well as ways to refer to any location on the computer regardless of whether you are there. That brings us to the third term:

  1. A path specifies the location of a file or folder on the computer.

4.1 Absolute and relative paths

In paths, folders are separated by slashes – forward slashes in Mac and Linux:

/Users/John Doe/Desktop/cats.png

…and backward slashes in Windows:

C:\Users\John Doe\Desktop\cats.png

There are two types of paths:

  • Absolute paths (AKA full paths) start from a root (top-level) directory, and correctly point to a file or folder regardless of what your working dir is. If you think of a path as a way to point to a geographic location, then absolute paths are like GPS coordinates. The two paths above are examples of absolute paths.

  • Relative paths start from a specific working dir, and won’t work if you’re located elsewhere. Again thinking of a path as a way to point to a geographic location, then relative paths are like directions like “Take the second left”. For example:

    results/summary.tsv
my_script.R

4.2 Why prefer relative paths

Don’t absolute paths sound better? What could be a disadvantage of them?

Absolute paths:

  • Don’t generally work across computers
  • Break when your move a project folder hierarchy to a a different place on your computer

On the other hand, relative paths that use the root of the project folder hierarchy as the working dir, also work when moving the folder within and between computers.

Two project dir hierarchies, and the absolute and relative path to a (FASTQ) file.

Now everything was moved into Dropbox.
The absolute path has changed, but the relative path remains the same.

5 Use RStudio Projects

5.1 Getting and setting the working directory in R

In R, you can see what your working directory is with the function getwd() (short for “get working dir”):

getwd()
[1] "/Users/poelstra.1/Library/CloudStorage/Dropbox/mcic/teach/codeclub/codeclub-site/posts/S10E03_reprod_03"

You can see that the output path is my working directory – yours will be different as the set up of your computer organization structure is different from mine (and recall that you will see backslashes if you have Windows).

You can change your working directory using the function setwd()…

setwd("/this/should/be/your/working-directory/path")
We recommend always using forward slashes, even on Windows!

This may seem strange given what I explained above — but even though Windows natively uses backslashes, you can use backslashes in R as it will take care of the conversion.

Specifically, using forward slashes even on Windows is better for two reasons:

  1. It makes the path specification universal (independent of the operating system).
  2. Backslashes have a separate purpose in R. Therefore, you would actually need to use two backslashes inside setwd() (e.g. setwd("C:\\Users\\John Doe")) and in other contexts where you use paths. This gets confusing and error-prone!

Exercise: Change your working dir

Find a location on your computer that you would like to move to (it doesn’t matter where or what that is, this is just for practice). Then, move to that directory using setwd().

5.2 RStudio Projects

Instead of changing working directories whenever you fire up R, you can (and should!) use an RStudio Project instead. RStudio Projects are an RStudio-specific concept that create a special file (.Rproj), primarily to designate a directory as the working directory for everything within it, and to make it easy to switch between projects.

Let’s create an RStudio Project for Code Club:

  1. You may already have a folder on your computer for all things Code Club. If not, please create one now.

  2. Click File > New Project, and then select Existing Directory. Select your folder for Code Club.

After RStudio automatically reloads, the R working directory will be set to the place where your RStudio Project file is located. Therefore, you should see the file ending in .Rproj in the RStudio Files tab in the lower right pane. Also, you can check your working dir:

getwd()

5.3 Why RStudio Projects are useful

In brief, RStudio Projects help you to organize your work and make it more reproducible:

  • When using Projects, you can avoid manually setting your working directory altogether. To refer to files within the project, you can use relative file paths. This way, even if you move the project directory, or copy it to a different computer, the same paths will still work.

  • Projects encourage you to organize research projects inside self-contained folder hierarchies exactly as recommended above.

  • When you switch between Projects, R will restart — and this is a good thing, since you don’t want to randomly carry over objects and loaded packages across research projects.

  • Convenience in RStudio:

    • Projects record which scripts (and R Markdown files) are open in RStudio, and will reopen all of those when you reopen the project. This becomes quite handy, say, when you work on three different projects, each of which uses a number of different scripts.
    • Files pane in sync with your working dir

5.4 Using relative paths to refer to files within the project

As mentioned above, a main function of RStudio Projects is that you should not have to use setwd() at all. But of course, not all files will be -nor should they be!- in the very same top-level project folder that your RStudio Project will set your working dir to.

So, to refer to files you will (still) be using paths, and you should prefer relative paths – for example:

# [Don't run - fictional examples]
read_tsv("data/experiment1.tsv")
ggsave("results/figures/barplot.png")
Accessing files that aren’t in the project dir

Occasionally, you may need to access a file that is outside of your project dir (but the less that happens, the better!). In that case, you can either use an absolute path, or a relative path that starts by going “up” one or more levels. You can do the latter with the .. notation, for example:

# [Don't run - fictional examples]
# The file is located in the dir:
read_tsv("../myfile.tsv")

# The file is located in the dir Downloads, which is two levels up:
read_tsv("../../Downloads/myfile.tsv")

Exercise: Create an RStudio Project for a research project folder

Then, practice with finding files: open quotes (") and press Tab!


6 Bonus: Use good file names

Here are three principles for good file names (from Jenny Bryan) — good file names:

  • Are machine-readable
  • Are human-readable
  • Play well with default file ordering

6.1 Machine-readable

Consistent and informative naming helps you to programmatically find and process files.

  • Avoid spaces in file names. More generally, only use the following in file names:
    • Alphanumeric characters A-Z, a-z, 0-9
    • Underscores _ and hyphens (dashes) -
    • Periods (dots) .
  • In file names, you may provide metadata like Sample ID and date – (allowing you to easily select samples from e.g. a certain month): sample032_2016-05-03.txt

6.2 Human-readable

One good way to combine machine- and human-readable (opinionated recommendations):

  • Use underscores (_) to delimit units you may later want to separate on: sampleID, treatment, date.
  • Within such units, use dashes (-) to delimit words: grass-samples.
  • Limit the use of periods (.) to indicate file extensions.
  • Generally avoid capitals.

For example:

mmus001_treatmentA_filtered.tsv
mmus002_treatmentA_filtered.tsv
.
.
mmus086_treatmentA_filtered.tsv

6.3 Play well with default file ordering

  • Use leading zeros for lexicographic sorting: sample005.
  • Dates should always be written as YYYY-MM-DD: 2020-10-11.
  • Group similar files together by starting with same phrase, and number scripts by execution order:
DE-01_normalize.R
DE-02_test.R
DE-03_process-significant.R

7 Further resources

Back to top

Footnotes

  1. Though this is not without caveats. For example, some programs with GUIs may be able to report the exact procedure that was used along with the results.

    Conversely, if you also save say alternative R code that gives different results, and do so without annotation, you may not know what produced the results that you ended up writing down in your manuscripts.↩︎

  2. You can think of this along the lines of opening a file browser (Finder / File Explorer etc.) – it will always have a starting point, and you can move around to go to other locations.↩︎