Skip to main content

Modern Workflows

Overview

Summary: This week you set up the computational environment you will use for the rest of the course. By the end, the technology should fade into the background so you can focus on health data science, not installation errors. We adopt a “Zero to AI Co-Pilot” approach: you do not need to install R, Python, or Git on your personal laptop. Everything runs in a cloud-native environment called GitHub Codespaces.

You can complete the course using VS Code in your web browser through GitHub Codespaces. You do not need to install the desktop version of VS Code unless you choose to.

NoteKey Terms This Week
  • Repository (repo): your project folder stored on GitHub — the “cloud drive.”
  • Codespace: a cloud computer that opens in your browser — the “public computer.”
  • IDE: the editor you work in. Here it is VS Code, running inside the Codespace.
  • Quarto (.qmd): a document format that mixes text and runnable code; rendering it produces a finished HTML report.

Each term gets a full section further down this page.

Learning Objectives:

  • Understand the “public computer vs cloud drive” analogy for cloud computing.
  • Create a GitHub account, fork the course template repository, and work from your personal fork.
  • Launch a Codespace and identify the three key areas of the VS Code interface.
  • Distinguish between an IDE, a notebook, and a script, and explain why this course uses Quarto notebooks.
  • Explain the concept of literate programming and why it matters for reproducible health research.
  • Edit and render a Quarto (.qmd) document: YAML header, Markdown text, and code chunks.
  • Maintain a reproducible project structure using the data/ and output/ folder convention.
  • Stage, commit, and sync changes using the VS Code Source Control panel.
  • Stop your Codespace to conserve your free monthly hours.

Connection

Week 1 focused on whether a dataset is trustworthy enough to use. This week focuses on where that dataset lives in a project and how relative paths make the same work portable across machines. Next week you will start inspecting the data with R.

Case Study Data Spine

What to do with this code: Read only — you do not need to run, modify, or submit it this week. The code block below shows how the case-study data is loaded with a relative path. You will start running code like this yourself in Week 3.

The NHANES Health Equity data spine is the recurring dataset thread for this course. In the early weeks, use it only as a documented public-health data artifact: provenance, ethics, file organization, and reproducible paths.

  • Cached RDS: examples/nhanes-equity/data/nhanes_equity_v6.rds
  • CSV snapshot: examples/nhanes-equity/data/nhanes_equity_v6.csv
  • Case-study README: examples/nhanes-equity/README.md

The cached files are provided so early work can happen without internet access.

What to do here: read the code below as an example of documented data provenance — you are not required to run or modify it on this page (each week’s page states its own expectations). 

library(tidyverse)  # AI-EDIT(2026-06-23): tidyverse-default — consolidated core library() calls into library(tidyverse)

candidate_paths <- c(
  "examples/nhanes-equity/data/nhanes_equity_v6.csv",
  "../../examples/nhanes-equity/data/nhanes_equity_v6.csv"
)

nhanes_path <- candidate_paths[file.exists(candidate_paths)][1]
if (is.na(nhanes_path)) {
  stop("Could not find examples/nhanes-equity/data/nhanes_equity_v6.csv")
}

nhanes_spine <- read_csv(nhanes_path, show_col_types = FALSE)

dim(nhanes_spine)
#> [1] 105626     18
glimpse(nhanes_spine)
#> Rows: 105,626
#> Columns: 18
#> $ Cycle          <chr> "1999-2000", "1999-2000", "1999-2000", "1999-2000", "19…
#> $ BMI            <dbl> 14.90, 24.90, 17.63, NA, 29.10, 22.56, 29.39, 15.51, 18…
#> $ Weight         <dbl> 12.5, 75.4, 32.9, 13.3, 92.5, 59.2, 78.0, 40.7, 45.5, 1…
#> $ Height         <dbl> 91.6, 174.0, 136.6, NA, 178.3, 162.0, 162.9, 162.0, 156…
#> $ Waist          <dbl> 45.7, 98.0, 64.7, NA, 99.9, 81.6, 90.7, 64.1, 64.6, 108…
#> $ WeightMEC      <dbl> 10982.899, 28325.385, 46192.257, 10251.260, 99445.066, …
#> $ Strata         <dbl> 5, 1, 7, 2, 8, 2, 4, 6, 9, 7, 1, 6, 13, 12, 11, 11, 5, …
#> $ PSU            <dbl> 1, 3, 2, 1, 2, 2, 2, 1, 2, 1, 2, 2, 2, 1, 2, 1, 1, 1, 2…
#> $ Gender         <chr> "Female", "Male", "Female", "Male", "Male", "Female", "…
#> $ Race           <chr> "Non-Hispanic Black", "Non-Hispanic White", "Non-Hispan…
#> $ Education      <chr> NA, "College Grad", NA, NA, "College Grad", NA, "HS or …
#> $ Marital        <chr> NA, NA, NA, NA, "Married/Partner", "Never Married", "Ma…
#> $ Age            <dbl> 2, 77, 10, 1, 49, 19, 59, 13, 11, 43, 15, 37, 70, 81, 3…
#> $ PIR            <dbl> 0.86, 5.00, 1.47, 0.57, 5.00, 1.21, NA, 0.53, NA, NA, 1…
#> $ EducationClean <chr> NA, "College Grad", NA, NA, "College Grad", NA, "HS or …
#> $ MaritalClean   <chr> NA, NA, NA, NA, "Married/Partner", "Never Married", "Ma…
#> $ IncomeGroup    <chr> "Low Income (<1.3)", "High Income (>3.5)", "Middle Inco…
#> $ WHtR           <dbl> 0.4989083, 0.5632184, 0.4736457, NA, 0.5602916, 0.50370…

In-Class Activity

  • Locate the case-study data, README, and snippet folders in the Explorer.
  • Explain why the data example uses relative paths instead of machine-specific paths.
  • Check that the weekly page includes the shared snippet rather than duplicating instructions.
  • Render the book from the repository root and check that this page updates in the rendered output.

Student output: a rendered Quarto page and one commit showing a small, reproducible edit. Assignment link: Assignment 1.

workflows1.qmd The Analogy: Public Computer and Cloud Drive

Deeper Dive: The Analogy: Public Computer vs Cloud Drive.

To understand how we work in this course, forget about “servers” and “clients.” Imagine you are working in a university computer lab.

The Repository (Your Cloud Drive)

Think of GitHub as your personal Google Drive or Dropbox.

  • It is where your files live permanently.
  • If your laptop crashes, the files are still here.
  • Key concept: This is your “Master Copy.”

The Codespace (The Public Computer)

Think of a Codespace as a public computer in the library.

  • It is a temporary machine you borrow to do your work.
  • It comes pre-installed with all the software you need (R, Python, Quarto), so you don’t have to install anything on your own laptop.
  • Crucial difference: Saved changes remain in that Codespace when it stops, but they are not in your GitHub repository until you commit and sync them. A Codespace can later be deleted, so GitHub—not the Codespace—is the safe home for finished work.

The Workflow

  1. Log in: Launch your Codespace (open the public computer).
  2. Work: Edit files using the computer’s software.
  3. Save to the cloud: Commit and push your work back to your Cloud Drive (GitHub).
  4. Log off: Stop the Codespace to save your free hours.

This cycle — launch, work, commit, stop — is the rhythm of every week in this course.

workflows2.qmd Getting Started: GitHub Account and Fork

Deeper Dive: Tour of the Repository.

Step 1: Check Your GitHub Account

You should already have a GitHub account from Week 0: Asynchronous Onboarding, which walks through account creation step by step. If you skipped Week 0, go back and complete the account setup there first.

If login goes wrong:

  • Forgot which email you used? Try your UBC email first — that is what Week 0 recommended.
  • Forgot your password? Use Forgot password? on the GitHub sign-in page; the reset email arrives within a few minutes.
  • Account exists but you cannot access it? Ask for help in class rather than creating a second account — two accounts cause confusion later.
Tip

Portfolio thinking: Your GitHub profile will become part of your professional presence. Pick a username you would be comfortable putting on a CV (e.g., jchen-epi rather than xXcoolcoder99Xx).

Step 2: Fork the Course Template

  1. Open the course starter repository: https://github.com/ehsanx/HDSx-workspace (also linked from Canvas).
  2. Click Fork in the upper-right corner of the GitHub page.
  3. Create the fork under your own GitHub account.
  4. Keep the default repository name unless Canvas gives a specific naming rule.
  5. After the fork is created, look at the web address at the top of your browser. It should include your GitHub username. This confirms that you are working in your own copy, not the original course repository.

Step 3: Verify Your Repository

Navigate to your forked repository. You should see:

  • A file list including practice_report.qmd, README.md, and a data/ folder.
  • A formatted README below the file list explaining the project.

If you see these in your fork, you are ready to launch your Codespace.

If you do not see these, stop and ask for help before continuing. You may be in the wrong repository, the wrong branch, or the starter files may not have loaded correctly.

workflows3.qmd Launching Your Codespace

Deeper Dive: Opening Your First Codespace and Reopening a Codespace.

  1. On your repository page, click the green <> Code button.
  2. Select the Codespaces tab.
  3. Click Create codespace on main.

The first launch takes 2–3 minutes while the environment builds. Subsequent launches are faster.

Note

Reopening an existing Codespace: After you stop or close your Codespace, do not create a new one each time. Go to github.com/codespaces, find your existing Codespace, and click its name to restart it. Creating multiple Codespaces wastes your hours and causes confusion.

workflows4.qmd Tour of VS Code: The “Big Three” Zones

Deeper Dive: VS Code Orientation.

The VS Code interface can look intimidating — it is designed for professional software engineers. You only need to know three areas. Safely ignore 90% of the buttons.

1. The Explorer (Left Sidebar)

Your file cabinet. It shows folders and files in your project. You will use this to open .qmd files, navigate the data/ folder, and create new files.

2. The Editor (Center)

Your work area. This is where you read and write code and text. You can have multiple files open in tabs.

3. The Terminal (Bottom Panel)

The engine room where R and Python actually run. You will not type commands here often — most of your work happens in the Editor — but this is where output and error messages appear.

Tip

Lost a panel? Use the top menu: View → Explorer or View → Terminal to bring them back. You can also press Ctrl+` (backtick) to toggle the Terminal.

workflows5.qmd Concepts: IDE, Notebook, Script

The syllabus mentions three ways to write code. Understanding the difference helps you choose the right tool throughout the course.

IDE (Integrated Development Environment)

VS Code is an IDE — a text editor with superpowers: file browsing, syntax highlighting, built-in terminal, extensions, and version control. It is the container that holds everything else.

Script

A plain text file containing only code (e.g., .R or .py). Runs top-to-bottom. Best for reusable utilities and automation. You will write your first script in Week 5.

Notebook

A document that interleaves code and narrative. You run code in chunks and see results inline. Examples include Jupyter notebooks (.ipynb, Week 5) and Quarto documents (.qmd, which you use starting today).

This course primarily uses Quarto notebooks because they combine the strengths of notebooks (interactivity, narrative) with the ability to produce publication-quality reports, slides, and websites — all from a single file.

workflows6.qmd Concepts: Literate Programming

The Big Idea

Traditional workflows separate code from writing: you run an analysis in one program, copy results into a Word document, and hope nothing changes. Literate programming weaves code, results, and interpretation into a single document. When the data changes, you re-render and the entire report updates automatically.

This is not just convenient — it is a scientific obligation. In health research, reviewers and regulators need to see exactly how you went from raw data to conclusions. A literate document is a transparent, auditable record of your reasoning.

How Quarto Implements This

A .qmd file has three ingredients:

  1. YAML header (metadata at the top, between --- lines)
  2. Markdown text (human-readable prose)
  3. Code chunks (executable R or Python code in fenced blocks)

When you Render, Quarto runs every code chunk, captures the output (tables, figures, numbers), and weaves everything into a finished HTML, PDF, or Word document.

You will use literate programming in every subsequent week of this course: your assignments, your EDA (Week 7), your reports (Week 10), and your final portfolio are all Quarto documents.

workflows7.qmd Project Structure: Files and Folders

Deeper Dive: Files vs Folders.

A reproducible project needs a consistent folder structure. This course uses the following convention:

my-project/
├── data/           ← Raw data. Never edit files here directly.
├── output/         ← Cleaned data, figures, and tables generated by your code.
├── practice_report.qmd   ← Your Quarto notebook.
├── README.md       ← Explains what this project is.
└── .gitignore      ← Tells Git which files to ignore (more in Week 4).

Rules

  • data/ is read-only. Import from it; never save into it.
  • output/ is generated. Your code writes cleaned data and figures here. In Week 3, you will export output/summary_table.csv.
  • Use relative paths. Always refer to files relative to the project root (e.g., "data/patients.csv"), never absolute paths (e.g., "/home/user/Documents/patients.csv"). This ensures your code runs on any machine.

Activity: In the Explorer pane, click the New Folder icon and create the output/ folder if it does not already exist.

workflows8.qmd Tutorial: Your First Quarto Document

Deeper Dive: The Magic Moment: Render Quarto.

Step 1: Open the Starter File

In the Explorer, click practice_report.qmd. It lives in the top level (root) of your forked workspace repository, alongside README.md and the data/ folder. It opens in the Editor.

Step 2: Understand the YAML Header

At the very top, between --- lines, you will see something like:

---
title: "My First Report"
author: "Your Name"
format:
  html:
    embed-resources: true
---

Change author: to your actual name. The YAML header controls metadata and output format. The embed-resources: true line bundles every figure and style into a single self-contained HTML file, so the report still shows your plots when you download it or open it on another computer.

Step 3: Read the Markdown

Below the YAML, you will see plain text with formatting:

  • # Heading creates a section title.
  • **bold** makes text bold.
  • - item creates a bullet point.

This is Markdown — a lightweight way to format text without a word processor.

Step 4: Read the Code Chunks

Look for grey blocks that start with ```{r} and end with ```. These are code chunks. Everything inside them is R code that will execute when you render.

```{r}
# This is a code chunk
2 + 2
```

Step 5: Edit a Code Chunk

Find a code chunk in the starter file. Make a small change — for example, change a number or add a comment. This is your first edit.

Step 6: Render

Before you render: save the file with Ctrl+S (Cmd+S on macOS). Rendering runs the code chunks from the start and captures their results, so you do not need to run every chunk first. Running chunks interactively is still useful for finding errors before a full render.

To render, open the Command Palette — press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS), or use View → Command Palette — and run Quarto: Render Document. If you are asked which output format to produce, choose HTML. The detailed steps and an always-works terminal fallback are below.

TipHow to render: the course default

  1. Open the .qmd file you want to render, then open the Command Palette (View → Command Palette, or press Ctrl+Shift+P on Windows/Linux / Cmd+Shift+P on Mac) and run Quarto: Render Document. The Quarto extension renders the file and opens a preview pane.

  2. Always-works fallback (terminal): type the render command with the file’s path as shown in the Explorer, for example:

    quarto render practice_report.qmd

    Always name the file — a bare quarto render rebuilds the whole project and takes much longer.

  3. If you see a Render (or Preview) button in the editor toolbar, it does the same thing as step 1.

Where did the output go? Watch the render log for the Output created: line — it names the exact .html file created. By default the file appears next to your .qmd; in projects that set an output directory (like this book’s docs/ folder), it appears there instead. If no preview opened automatically, find that .html file in the Explorer, right-click it, and choose Download to open it in your browser (or Open Preview if available).

A preview pane appears showing your formatted report with code output embedded.

NoteWhere is my HTML file?

In your personal workspace, practice_report.html is saved beside practice_report.qmd at the repository root. Watch the render log for the Output created: line, then right-click the HTML file and choose Open Preview or Download. The course book uses a separate docs/ output directory; your personal workspace does not.

NoteSeeing a TeX warning?

If you see a warning that no TeX installation was found, you can ignore it as long as your HTML file was created successfully. TinyTeX is only needed for PDF output — do not install anything.

Tip

What just happened: Quarto ran every code chunk, captured the results, combined them with your Markdown text, and produced an HTML document. This is literate programming in action.

workflows9.qmd Tutorial: Stage, Commit, and Sync

Deeper Dive: Commit Your Work.

Your work currently exists only on the public computer (Codespace). To save it permanently to your Cloud Drive (GitHub), you need to commit.

Think of this as a three-step save process:

  1. Stage = choose which changed files to include.
  2. Commit = save a snapshot with a message.
  3. Sync = upload that snapshot to GitHub so it is safely stored online.

Step 1: Open Source Control

Click the Source Control icon on the left sidebar (it looks like a branching graph). You will see a list of files that have changed since your last commit.

Step 2: Stage Your Changes

Hover over a changed file name. Click the + icon that appears. This stages the file — it tells Git “I want to include this change in my next snapshot.”

Note

Staging vs committing: Staging selects which changes to include. Committing takes the snapshot. Think of staging as putting items on the conveyor belt; committing is pressing the “scan” button at checkout.

Step 3: Write a Commit Message

In the text box at the top of the Source Control panel, type a short, descriptive message:

Updated author name and edited first code chunk in practice report

A good commit message answers: what did I change and why?

Step 4: Commit

Click the ✔ Commit button (checkmark). Your changes are now saved as a snapshot in your local history.

Step 5: Sync with GitHub

Click Sync Changes (in the Source Control panel or the status bar at the bottom). This pushes your commit to GitHub — your Cloud Drive.

Verify: Go to your repository on github.com and check that your changes appear. You should see your commit message next to the updated file.

Warning

If you skip the Sync step, your commit exists only on the Codespace. If the Codespace is deleted, the commit goes with it. Always Sync.

workflows10.qmd Stopping Your Codespace (Saving Credits)

Deeper Dive: Stop Your Codespace.

GitHub Free personal accounts currently include 120 core-hours per month. On the course’s default 2-core machine, that is about 60 hours of active runtime. If you leave the browser tab open, the meter keeps running until the Codespace reaches its idle timeout, even if you are not actively working.

The Right Way to Stop

  1. Go to github.com/codespaces.
  2. Find your active Codespace.
  3. Click the three dots (…) → Stop codespace.

What Happens If You Just Close the Tab?

The Codespace runs for another 30 minutes before it times out automatically. That is 30 minutes of wasted credits every time.

Warning

Policy: It is your responsibility to manage your compute hours. If you run out before the month resets, you will need to wait or pay out of pocket. Get in the habit of stopping your Codespace at the end of every session.

workflows11.qmd Troubleshooting

Deeper Dive: Troubleshooting: Rebuild Container.

Sometimes things break. Here is a graduated approach — try the simplest fix first.

Level 1: Reload the Window

Press F1 (or Ctrl+Shift+P / Cmd+Shift+P) to open the Command Palette. Type Reload Window and select it. This restarts VS Code without rebuilding the entire environment.

Level 2: Restart the R or Python Session

If R or Python is frozen, open the Command Palette → type R: Restart R Session (or the equivalent for Python). This clears the session without touching your files.

Level 3: Rebuild the Container (Nuclear Option)

If nothing else works:

  1. Open the Command Palette.
  2. Type Rebuild Container.
  3. Select Codespaces: Rebuild Container.

This shuts down and rebuilds the entire environment from scratch. It solves nearly all technical glitches but takes a few minutes.

Warning

Before rebuilding: Make sure you have committed and synced your work. Uncommitted changes may survive a rebuild, but there is no guarantee.

workflows12.qmd Knowledge Check

  1. In the analogy, what is the “Cloud Drive” and what is the “Public Computer”?
  2. Why don’t you need to install R or Python on your laptop for this course?
  3. Name the “Big Three” zones of the VS Code interface and what each is for.
  4. What is the difference between an IDE, a notebook, and a script?
  5. What is literate programming, and why does it matter for health research?
  6. What are the three ingredients of a .qmd file?
  7. What is the difference between staging and committing?
  8. Why must you click Sync Changes after committing?
  9. How do you properly stop a Codespace to save your free hours?

workflows13.qmd Assignment 1: Your First Quarto Report

Due Monday after the Week 2 class at 4 PM. Submit via Canvas.

Task

Edit and render the supplied root-level practice_report.qmd, demonstrating that you can navigate your personal workspace Codespace, edit Quarto, and commit your work. This is the same authoritative workflow as the Assignment 1 brief; there is no separate nested A1 submission.

Step-by-Step Workflow

  1. Launch your Codespace from your forked repository.
  2. Edit the YAML: Change author: to your name.
  3. Add a Markdown section: Below the existing content, add a new heading (## My Notes) and write 2–3 sentences about what you learned this week. Use at least one Markdown feature (bold, italics, or a bullet list).
  4. Edit a code chunk: Modify an existing code chunk or add a new one. For example:
```{r}
# My first R calculation
2 + 2
```
  1. Render the document. Check that the output looks correct.
  2. Commit and Sync:
    • Open Source Control.
    • Stage your changed files (+).
    • Write a commit message: e.g., "Complete Week 2 assignment: edit YAML, add notes, render report".
    • Click ✔ Commit, then Sync Changes.
  3. Stop your Codespace.
  4. Verify on github.com that your commit appears in the repository.
  5. Submit your personal workspace repository link on Canvas. The synced commit must include the root-level practice_report.qmd and practice_report.html; no extra reflection or commit-evidence file is required.

workflows14.qmd Quick Reference

Action How
Launch Codespace Repository → green <> Code → Codespaces → Create codespace on main
Reopen Codespace github.com/codespaces → click Codespace name
Stop Codespace github.com/codespaces → … → Stop codespace
Open Explorer View → Explorer or click file icon (left sidebar)
Open Terminal View → Terminal or Ctrl+`
Render Quarto Command Palette (F1) → Quarto: Render Document, or terminal: quarto render practice_report.qmd
Stage a file Source Control → hover file → click +
Commit Type message → click ✔
Sync to GitHub Click Sync Changes
Reload window Command Palette (F1) → Reload Window
Rebuild container Command Palette (F1) → Codespaces: Rebuild Container