Collaboration: Technical Checklists

This page is under active development. If anything is unclear for any reason, talk to Zhenya about it. If you don't know how to do something and there is no link to isntructions, talk to Zhenya about it. If there is a link but the instructions it points too are unclear or insufficient, talk to Zhenya.

We want collaboration to be as smooth as possible and we want everyone to spend their time on research and not troubleshooting technical problems.

This document was written mainly with projects that are centered around a single R Markdown document in mind. However, if your aren't using R Markdown, most of the guidelines will still apply. Simply skip things that are specific to R Markdown.

For projects that are centered around R Markdown documents, the minimal goal is for Elika to be able to knit that document after she pulls updates from GitHub. We aren't, however, doing it just for Elika's time's sake, this is a good way to test of the computational reproducibility of your project - something that.

You don't have to follow all the rules/checklist in this document. As long as all collaborators (which could be just you and Elika) agree, feel free to change any given item to your liking or to skip it entirely. However, if you do so, please leave a note about it in README.md.

Setup

These two checklists are designed for setting the project up. Items in them aren't as much things to do as they are states to be reached once and to be maintained after that.

Organization checklist

• One folder. All project files that are on your computer should be in one folder. Having exceptions is normal, just make sure to document them in README.md and/or on the project GitBook page.

• README.md. At the very minimum, it should contain a short project description, project lead's name, description of files in the project folder and, importantly, location of all the files that aren't.

• Git + GitHub. A git repo should exist in the project folder and it should be linked to a GitHub repo. You should be able to run git status and git fetch in the project root.

• RStudio project. There should be an RStudio project (*.Rproj) file in the root of the folder.

• renv. (skip if you don't have any R code) The project should use a renv virtual environment. See renv - reproducible R environments

• Rmd-to-pdf GitHub workflow. (skip if you don't have an R Markdown document) Test with gh workflow run rmd-to-pdf

Extra:

• If you use Python, use a virtual environment and commit requirements.txt/environment.yml.

R/R-Markdown Checklists

Both R and R Markdown

• File paths. Use Working with file paths

Specific to R Markdown

When you knit an R Markdown document, it produces several output files. Some will be deleted once knitting is done, some will be retained; some are useful to have versioned under git, some - not so much.

• .tex and .md files. Set keep_texand keep_md to yes and commit .tex and .md files in the header of your .Rmd.

• .png plot files. Commit them if you have any plots.

• .pdf files. Don't commit them, gitignore them. This applies to both the manuscript pdf and the images.

Before passing to collaborators

This checklist is a process checklist - the items are in the intended order of execution.

1. Wrap up locally. You might need a couple of rounds of these substeps:

   1. Update renv. See Keep the `renv` environment in sync

   2. Get git status to say "nothing to commit, working tree clean".

   3. Test-run in a fresh RStudio session.

2. Push to GitHub.

3. Run an independent test, either

   • using the Rmd-to-pdf GitHub workflow or

   • making a fresh clone in a different location than your project folder with VPN turned off.

4. Message your collaborators, attach the pdf.

Creating reproducible .Rmd and .pdf

1. (only relevant if you commit the pdf output) To prevent metadata from unnecessarily updating pdf when no actual changes are recorded

create a file called disable-metadata.tex in the same folder as the .Rmd, write the following lines:

\pdfinfo{
  /CreationDate ()
  /ModDate ()
}
\pdftrailerid{}

Then in the beginning of the .Rmd (before the setup code chunk), include some lines like the following:

output:
  papaja::apa6_pdf:
    includes:
      in_header: disable-metadata.tex

1. To ensure figures turn out the same: use "ragg_png" and ensure the setup chunk includes something like below:

   knitr::opts_chunk$set(
     dev = "ragg_png",
     fig.align = "center", 
     out.width = '80%',
     dpi = 300,
     fig.width = 8,
     fig.height = 6
   )

The exact settings don't matter - feel free to adapt. The point is to set them in the same way for all users/machines.

1. (not tested) If the difference are due to fonts used for various labels in the figures, then you can try this:

   knitr::opts_chunk$set(
     fig.showtext = TRUE
   )
   
   showtext::font_add_google("Crimson Text", "free_times_new_roman")
   showtext::showtext_auto()
   
   # Has to come after setting the theme
   ggplot2::theme_update(text = element_text(family = "free_times_new_roman", size = 12))

After receiving from collaborators

If there is an R Markdown to knit:

1. git pull

2. renv::restore(clean = TRUE)

3. Open R Studio, hit "knit".

---

Status: Zhenya should update this page by 28 Feb 2024.

TODO:

• Explanations + alternative options.

• README.md writing instructions.