# Collaboration: Technical Checklists

{% hint style="info" %}
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.
{% endhint %}

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](/programming-info/computing-programming-guides/virtual-environments/renv-reproducible-r-environments.md)
* [ ] [Rmd-to-pdf GitHub workflow](/programming-info/quick-programming-computing-how-tos/knit-.rmd-to-pdf-with-github-actions.md). (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](/programming-info/computing-programming-guides/virtual-environments.md#python-venv) and commit `requirements.txt`/`environment.yml`.

### R/R-Markdown Checklists

#### Both R and R Markdown

* [ ] **File paths.** Use [/pages/I8PGKoWCxwxCJus3Yy6g#here-and-file.path](https://gitbook.bergelsonlab.com/data-and-code/pages/I8PGKoWCxwxCJus3Yy6g#here-and-file.path "mention")

#### 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_tex`and `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 [renv - reproducible R environments](/programming-info/computing-programming-guides/virtual-environments/renv-reproducible-r-environments.md#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](/programming-info/quick-programming-computing-how-tos/knit-.rmd-to-pdf-with-github-actions.md) 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:

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

2. To ensure figures turn out the same:\
   use `"ragg_png"` and ensure the setup chunk includes something like below:<br>

   ```r
   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.

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

   ```r
   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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.bergelsonlab.com/data-and-code/collaboration-technical-checklists.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.