Quarto and Git on VS Code (Optional)

Objectives

By the end of this lab, you should be able to:

  • Set up your working environment (WSL for Windows users, VS Code, R or Python, Quarto, Git)
  • Clone a GitHub repository and open it in VS Code
  • Render a Quarto document to HTML

Introduction

This course is about computational statistics and simulation. That means we are not only writing code — we are designing reproducible experiments and communicating results clearly.

To support this, we will use a structured workflow.

R or Python
   ↓
Quarto (.qmd document)
   ↓
VS Code (where you write and edit)
   ↓
Git (tracks changes)
   ↓
GitHub (collaboration + backup)
   ↓
Rendered HTML Report

Why This Setup?

We are using:

  • R or Python — to implement simulations and statistical models
  • Quarto — to combine code, output, and interpretation in one document
  • VS Code — to manage and edit our project
  • Git & GitHub — to collaborate and track changes

Together, these tools allow us to:

  • Write simulations
  • Generate results and figures automatically
  • Keep analysis and explanation together
  • Work safely in teams
  • Reproduce results later

This reflects modern practice in computational statistics.

Why WSL2? (Windows Users Only)

Windows users will use WSL2 to run a Linux environment inside Windows.

This helps ensure that:

  • R and Python packages install and behave consistently.
  • Command-line tools behave as expected.
  • Everyone works in a similar computational environment.

You will still use VS Code on Windows, but your code will run inside the Linux environment.

Mac users do not need WSL2.

Why Git and GitHub?

In this unit, you will work in pairs and manage your work using Git and GitHub. Git is not just for software developers. It is increasingly standard practice in academic research, data science teams, industry and analytics projects.

Using Git and GitHub will help you:

  • Avoid overwriting each other’s work
  • Work on different parts of the report simultaneously
  • See exactly what changes were made
  • Revert mistakes safely

Instead of emailing files back and forth, you will manage everything in a structured and reliable way.

System Architecture Diagram (with WSL)

When using Windows + WSL + VS Code + Quarto (R or Python), you are working across two operating systems.

The diagram below explains how and where your code actually runs.

Windows (GUI layer)
└── VS Code
      └── Remote - WSL Extension
            └── Ubuntu (Linux inside WSL2)
                  └── R  OR  Python
                        └── Quarto (renders and executes code)
                              └── HTML Output

What is Actually Happening

  • In this setup, Windows is not running your R or Python code. It is only hosting the editor (VS Code).
  • WSL2 is a lightweight virtual machine running a Linux kernel.
  • Ubuntu is your Linux environment. This is where: apt install, git, quarto, R, python, venv, renv are actually running.

Where Does R or Python Run

Inside Ubuntu,

  • If you use Python, you may create a virtual environment (.venv).
  • If you use R, packages are installed in your R library (or managed with renv).

This is where your actual runtime lives.

What Happens When You Click “Render”?

When you render a Quarto document:

Windows GUI
   ↓
VS Code (connected to WSL)
   ↓
Quarto (running inside Ubuntu)
   ↓
R  or  Python executes your code
   ↓
HTML document is generated

So execution happens inside Linux. The final result is an HTML file.

Takeaway:

  • Always keep your project inside: /home/<user>/.... NOT: C:\Users\... Because crossing the boundary slows things down and causes path confusion.

Setup Guide

This guide will help you set up the working environment for your lab exercises and project.

Important: Please find a lab partner before continuing. (Working alone is allowed if necessary.)

Step 1: (Windows Users Only) Enable WSL2 and Install Ubuntu

Mac users: Skip to Step 2.

Open PowerShell as Administrator, then run:

wsl --install -d Ubuntu
wsl --update
  • Reboot if prompted.
  • Launch Ubuntu from the Start Menu and create your Linux user. Remember your password!
  • Update Ubuntu and install other essentials:
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential curl git zip unzip wget gdebi-core
  • To verify, run: uname -a. You should see Linux information.

Step 2: Install and Setup VS Code

Download and install the latest version of VS Code at https://code.visualstudio.com/Download. If VS Code is previously installed, upgrade via CMD / PowerShell:

winget upgrade --id Microsoft.VisualStudioCode

In VS Code:

  • Install Remote - WSL extension from the Extensions tab.
  • Connect to WSL by pressing F1 → WSL: Connect to WSL. Ensure the bottom-left corner shows “WSL: Ubuntu”.

Step 3: Configure Git and GitHub Repository

3.1 Create a Repository (one per group)

  • Create GitHub account at https://github.com, if not already

  • Create a repository (one per group):

    • name: <repo-name>
    • visibility: Private
    • README: on
    • Add .gitignore: No .gitignore
    • Add license: optional

  • Add your group mate to the repo: Settings → Collaborators → Add people

3.2 Clone the Repository

  • Copy the HTTPS code from your GitHub repository page.
  • To configure Git and clone repository, run the following commands….
    • Windows users: inside Ubuntu (WSL)
    • Mac users: inside Terminal
git config --global user.name "Your Full Name"
git config --global user.email "your_email@example.com"
cd ~
mkdir -p code
cd code
git clone <HTTPS that you copied>
cd <repo-name>
code .
  • You only need to configure Git once per computer.
  • If prompted for authentication, log in using your GitHub credentials.
  • The code . command will open VS Code.

3.3 Add the Lab File

  • Only one group member needs to perform the initial commit and push.
  • Download ws01.zip from Week 1 on BB.
  • Extract and move the lab file into your repository folder.
  • Make an initial commit:
git status
git add ws01.qmd
git commit -m "Workshop 1 initial commit"
git push
  • Refresh your GitHub repository page and confirm that ws01.qmd appears online.

3.4 Sync with Your Partner

The other group member should:

  1. Follow Step 3.2 to clone the repository.
  2. Navigate into the project folder.
  3. Run:
git pull

Now both group members have the same project files. (Although technically fresh clone doesn’t need pull, it reinforces standard workflow.)

Step 4: Install Quarto

  • Mac: Download and install the latest version of Quarto from https://quarto.org/docs/download/index.html
  • Windows (inside WSL): Check the latest version of Linux .deb from the website above. The current version (Feb 2026) is v1.8.27. Run:
wget https://github.com/quarto-dev/quarto-cli/releases/download/v1.8.27/quarto-1.8.27-linux-amd64.deb
sudo gdebi -n quarto-1.8.27-linux-amd64.deb
  • Verify: quarto --version
  • Then, install Quarto extension in VS Code.

Step 5: Install R or Python (inside WSL)

  • For R:
sudo apt install -y r-base
R # to open R on console
install.packages("languageserver")
q() # to exit R workspace

Then, install R extension in VS Code.

  • For Python:
sudo apt install -y python3 python3-pip python3-venv
python3 -m venv .venv 
source .venv/bin/activate
pip install -U pip
pip install pandas numpy matplotlib

Then, install Python extension.

Note: source .venv/bin/activate activates the Python virtual environment. Once activated, your terminal prompt will change, showing the name of the virtual environment (e.g., (.venv)). This process ensures that all Python packages installed via pip are isolated to your project, avoiding conflicts with global installations.

Step 6: Render

Check the VS Code terminal and make sure that:

  • You are inside your repository folder
  • Python: .venv is activated

Run:

quarto render ws01-index.qmd

If this generates an HTML file without errors, your setup is successful.

Working Together using Git and GitHub

When working in pairs, Git helps you collaborate safely and avoid overwriting each other’s work.

In this course, you will follow a simple workflow.

The Golden Rules

  1. Never work directly on main.
  2. Always pull before starting new work.
  3. Use a branch for new changes.
  4. Push your branch and open a Pull Request (PR).

%%{init: { 'theme': 'base' } }%%
gitGraph
    commit tag: "v0"
    branch part1
    checkout main
    commit
    branch part2
    commit
    checkout part1
    commit id: "finish part 1"
    checkout main
    merge part1
    commit tag: "v1"
    checkout part2
    commit id: "finish part 2"
    checkout main
    merge part2
    commit tag: "v2"

Step 1: Always Pull Before You start

Before doing any new work:

git pull

This ensures your local copy is up to date with GitHub.

Step 2: Create a New Branch

Create a branch for your task:

git branch <branch-name>  # create a new branch.
git checkout <branch-name> # switch to an existing branch.
git checkout -b <new-branch-name> # combine creation and switching.
git branch -d <branch-name> # delete branch after merging.
git branch -D <branch-name> # delete a branch forcefully when necessary.

Examples:

git checkout -b feature/simulation-study
git checkout -b feature/analysis-plots
git checkout -b write/discussion-section

Step 3: Make Changes and Commit

After making changes:

git status # display summary of changes
git add <file> # add a specific file for commit
git add . # add all changes
git commit -m "Add random walk simulation"

Write clear commit messages that describe what you changed.

Step 4: Push Your Branch

git push -u origin feature/short-description

This uploads your branch to GitHub.

Step 5: Open a Pull Request (PR)

On GitHub:

  1. Click Compare & pull request
  2. Add a short description
  3. Click Create pull request

Your partner should review your changes before merging.

Step 6: Merge and Update

After the PR is approved:

  1. Click Merge pull request
  2. Delete the branch (optional but recommended)

Then both partners run:

git checkout main
git pull

Now main contains the latest version.

Minimal Daily Workflow Summary

git pull
git checkout -b feature/my-task
# make changes
git add -A
git commit -m "Describe your change"
git push -u origin feature/my-task

Working Alone using Git and GitHub

Everytime you make significant changes to the file, it’s a good practice to commit the change to Git for source control and push to GitHub for cloud storage. To do that, run:

git status # check status
git add -A # add all changes
git commit -m "Initial Quarto test document" # commit with message
git push # push to Remote (GitHub)

Reproducibility (Optional)

Reproducibility means someone else (or future you) can set up the same R/Python environment and run the project without “it works on my other machine” problems. The most common approach is to freeze your dependencies so others can install exactly what you used.

Why it matters

  • Consistent results: Same library versions → fewer surprises.
  • Easier onboarding: Teammates can set up fast.
  • Recoverability: You can rebuild your environment later.
  • Deployment-friendly: Many servers and CI pipelines expect a requirements file.

R

R environments can be managed using the renv package. renv creates a lockfile that records the exact versions of packages used in your project.

Initialise renv

Inside your project folder, open R and run:

install.packages("renv")   # run once if not installed
renv::init()

This creates renv.lock.

Commit it:

git add renv.lock
git commit -m "Add renv lockfile"
git push

Restore the Environment

On a new machine (or for your partner):

renv::restore()

R will install the exact package versions recorded in renv.lock.

Python

Generate requirements.txt

If you are using venv + pip

Make sure your virtual environment is activated:

cd ~/code/stat2005
source .venv/bin/activate
pip freeze > requirements.txt

This creates a file listing pinned versions, e.g. pandas==....

Commit it:

git add requirements.txt
git commit -m "Add requirements.txt file"
git push

Install dependencies from requirements.txt

On a fresh machine (or a new venv), run:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

To confirm you’re installing into (and running from) your venv:

which python
python -V
pip -V

Important Notes

  • Do not manually edit requirements.txt or renv.lock.
  • Regenerate them if you add or remove packages.
  • Always commit these files to GitHub.