Tools and Skills for Reproducible Transport Research

Day 2

Robin Lovelace

r.lovelace@leeds.ac.uk

University of Leeds

Juan Fonseca

University of Leeds

September 9, 2025

Introduction

Course overview (see schedule)

Day 1 (recap)

Development environments, 2) Sharing code (Git/GitHub), 3) Introduction to Quarto 4) Cross-references and citations with Quarto

Day 2

09:30-10:30 Drafting a reproducible paper
10:45-12:30 Generating reproducible publication-quality visualisations
13:30-14:30 Editing other people’s work
14:45-16:00 Working on papers -> Presentations and wrap-up

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

Decision!

Live demo of creating a repo, forking, cloning, editing, pushing, pulling, making a PR?
Web UI, gh cli, or both?
Me, you, or both?

Recap of Day 1

You’ve forked a repo, now what?

Syncing your fork

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

Click “Update branch”.

Using the (GitHub) documentation

Search on docs.github.com for “syncing a fork”.

Update branch

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(-)

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.

Exercises

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

Create a reproducible paper skeleton

Create a file called paper.qmd in your project folder, and add the following content:

---
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

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

Any questions before we move to the practical session?

Practical session: Visualising data with R and Quarto

See Section 6 for details.

Practical session: Editing other people’s work

See Section 7 for details.

Practical session: Working on papers

Feedback form

Please provide feedback with the QR code so we can improve the course.

Merging PRs

See the documentation on PRs at docs.github.com.

And specifically, the reviewing PRs section at https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests.

Pull requests in the wild

See the ROpenSci slopes PR for an example.

Example of ‘Quarto in production’

Presentation from Gonçalo Matos

See his work at https://github.com/gmatosferreira

Publishing your work

After you’ve created your paper, you have many options for publishing it.

See https://quarto.org/docs/publishing/ for details.

Presentations

Max 2 minutes to say:

What you did
What you learned

Thank you!

Feel free to get in touch with me (Robin) or Juan if you have questions via email (or of course GitHub!)
Plug: 2 courses on data science for transport planning, upcoming
Plug: Mobile Tartu Summer School in June
Thanks: the amazing people who build Quarto and the other tools we have used