Drafting a reproducible paper

1 Recap of Day 1

Let’s recap what we covered yesterday:

  • Session 1: Setting up a reproducible environment with R, RStudio, and Git/GitHub
  • Session 2: Sharing code and data with GitHub
  • Session 3: Writing reproducible papers with Quarto
  • Session 4: Cross-references and citations with Quarto

1.1 Syncing your fork

You’ve forked a repo, now what?

You can sync your fork with the… “Sync fork” button.

Click “Update branch”.

After syncing:

This branch is 2 commits ahead of, 3 commits behind tdscience/course:main.

How to do this with the gh cli: use gh repo sync.

Example usage from this morning showing how to deal with merge conflicts:

robin@robin-Apollo:~/github/robinlovelace$ gh repo clone course
fatal: destination path 'course' already exists and is not an empty directory.
failed to run git: exit status 128
robin@robin-Apollo:~/github/robinlovelace$ cd course/
robin@robin-Apollo:~/github/robinlovelace/course$ git log -n 2
commit c4b203b33714390e1d7d380ddc8d8ef1d4aeb131 (HEAD -> main, origin/main, origin/HEAD)
Author: robinlovelace <rob00x@gmail.com>
Date:   Mon Sep 8 14:22:47 2025 +0100

    Update people.csv

commit 32b3c1dd0acae412eefc051abb67c723725c0caa (upstream/main, upstream/HEAD)
Merge: ae4354e c561743
Author: Robin Lovelace <Robinlovelace@users.noreply.github.com>
Date:   Mon Sep 8 14:07:26 2025 +0100

    Merge pull request #42 from tdscience/Robinlovelace-patch-1
    
    Fix capitalization of 'Red kite' in people.csv
robin@robin-Apollo:~/github/robinlovelace/course$ gh repo sync
can't sync because there are diverging changes; use `--force` to overwrite the destination branch
robin@robin-Apollo:~/github/robinlovelace/course$ 
robin@robin-Apollo:~/github/robinlovelace/course$ 
robin@robin-Apollo:~/github/robinlovelace/course$ gh repo sync --force
✓ Synced the "main" branch from "tdscience/course" to local repository
robin@robin-Apollo:~/github/robinlovelace/course$ git pull
hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint:
hint:   git config pull.rebase false  # merge
hint:   git config pull.rebase true   # rebase
hint:   git config pull.ff only       # fast-forward only
hint:
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --no-rebase,
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches.
robin@robin-Apollo:~/github/robinlovelace/course$ git config pull.rebase false
robin@robin-Apollo:~/github/robinlovelace/course$ git pull
Auto-merging data/people.csv
Merge made by the 'ort' strategy.
 data/people.csv | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

See docs.github.com for more info and search the site.

2 Topic selection

Mind-mapping tools including pen and paper and online tools such as excalidraw.

An advantage with Excalidraw is that you can instantly share your mindmap and collaborate with others.

See https://excalidraw.com/#room=cf5501f9193c8345ee2d,h6D4Ddxni6JBK0dg0m2aZQ for an example mindmap.

3 Exercises

3.1 Using official documentation

  • Search either docs.github.com or cli.github.com/manual for a topic that interests you

  • Take a look at the equivalent Quarto official documentation site

    • Navigate to the Figures documentation section

  • Bookmark pages that interest you

3.2 Generate a ‘mind map’ of a topic of interest to you

  • Go to excalidraw and start sketching an idea, including inputs and outputs
  • Bonus: discuss with a partner and get feedback

3.3 Create a reproducible paper skeleton

Add content to your paper draft or create a new file, e.g. called paper.qmd, and edit it e.g. to include the following content (add more advanced content if you already have this):

---
title: "Your title here"
author: "Your name here"
format: html
---

Add headings with the following structure:

# Introduction {#sec-intro}

<!-- TODO: add content -->

# Methods {#sec-methods}

# Results {#sec-results}

# Discussion {#sec-discussion}

# References

3.4 Add your mindmap to the paper as Figure 1

  • Export your mindmap from excalidraw as a PNG or JPG file or take a screenshot
  • Save the image in a folder called images in your project folder, or paste it into the paper while in visual mode
  • Add it to your paper under the Introduction section, with a caption

3.5 Push your changes to GitHub

  • Use Git/GitHub to push your changes to your GitHub repo

e.g. with:

git add paper.qmd images/mindmap.png  # Add any other changed files too
git commit -m "Add initial paper draft and mindmap figure"
git push # or git push origin main if you want to be explicit

Reuse