lab 2 · portfolio book (Qmd) — source
A. Stamm 
This page shows the source file of the lab below. Use the button to download it as a plain file and run it in your own workspace.
---
title: "Lab 2: set up your portfolio book"
subtitle: "Reproducible Workflows · Session 2"
author: "Your Name"
format: html
editor: source
---
> ~35 min. Turn your Lab-1 EDA into **Chapter 1 of a real Quarto book**, the
> seed of the portfolio you'll version (Session 3) and publish. Work from the
> starter scaffold in `common/portfolio-book/`.
>
> **Tools in this lab:** Quarto (books) and `{pins}` (data pinning).
## Step 0: copy the scaffold
Don't edit the scaffold in place; copy it to your own workspace so you always
have a pristine original to re-copy:
```bash
cp -r reproducible-workflows/common/portfolio-book ~/my-portfolio
```
Open `~/my-portfolio` in Positron.
## Step 1: render the starter book
Render the empty book and confirm it builds before touching any content:
```bash
cd ~/my-portfolio && quarto preview
```
(or press *Preview* in Positron on `index.qmd`). You should see a working book
with a welcome page, placeholder chapters and a bibliography page.
## Step 2: make it yours
Edit `_quarto.yml` and `index.qmd`:
- put your **name** in the `author:` field (both places);
- change the **title** if you like;
- in `index.qmd`, replace the greeting with a sentence or two introducing your
portfolio, and describe the chapter you're about to add.
Re-render and confirm your changes appear.
## Step 3: drop in Chapter 1
Open `chapters/01-EDA.qmd`. It's a template with `TODO` markers. Replace them
with your Lab-1 content:
- **The question**: your one-sentence motivation.
- **Getting the data**: your sourcing code from Lab 1 (`download.file`, with
`{rdatagouv}` only if you chose it), so the chapter *downloads its own data*
on render (this is Chapter 1's reproducibility superpower). Optionally wrap
the fetch in `{pins}` so the chapter reads from a versioned local board
instead of hitting the network every render.
- **A first look**: `skim()`, `vis_miss()`.
- **Cleaning decisions**: your paragraph from Lab 1.
- **Plotting the story**: your captioned figure.
- **Findings**: a short, honest conclusion.
Add `#| message: false` to library-loading chunks so the chapter reads cleanly.
> **Note on `setup`.** Keep package loading in the chapter's first `setup`
> chunk (the template already has one). A single, predictable setup chunk is
> what lets later instructors extend your book confidently.
## Step 4: pin the data with `{pins}`
Now version the dataset you fetched in Chapter 1. Pinning snapshots the *exact
data* to a local board, with a version + hash; so re-renders get the same data
you analysed, even if the portal changes or the URL breaks later.
```cjs
#| label: pins
#| eval: false
library(pins)
board <- board_folder("pins/", versioned = TRUE) # a versioned local board
pin_write(board, dat, "my-data") # snapshot dat with a version
```
After writing, confirm the versions are recorded:
```r
pin_list(board) # what's on the board?
pin_versions(board, "my-data") # every snapshot, with hashes + dates
```
Then update the `Getting the data` section of `chapters/01-EDA.qmd` to read
from the pinned copy instead of re-downloading:
```r
dat <- pin_read(board, "my-data") # the exact snapshot you pinned
```
> **Where do the versions live?** In the `pins/` folder beside your book. You'll
> commit it alongside your code in Session 3, so the *data* your analysis used
> is reproducible forever. Add `pins/` is **not** ignored by the scaffold
> `.gitignore` (only `_book/`, `*_files/` and `renv/library/` are), so it is
> versioned intentionally.
## Step 5: render the whole book
```bash
cd ~/my-portfolio && quarto render
```
Walk the sidebar in the output:
- Does **Chapter 1** appear where you expect?
- Are **cross-references** (`@fig-…`) and the **bibliography** resolving?
- Does `index.qmd` link to the chapter's main figure?
## Step 6: make it look like yours
Your portfolio's *look* is yours to define, don't match the course materials,
find what you like. The scaffold ships two theming files that give you two
levels of control (both beside `_quarto.yml`):
1. **`_brand.yml`**: the quick win. Open it, change a couple of `"#hex"`
colours, re-render (`quarto preview`), and the whole book restyles. This is
the zero-CSS on-ramp: edit → preview → iterate.
2. **`styles.scss`**: structural CSS for anything the palette can't do
(spacing, layout, custom components). It ships fully commented-out, so it's
inert until you uncomment. To find a selector, right-click an element in the
rendered book → *Inspect*.
Try at least one change to `_brand.yml` now: pick an accent you like. The goal
isn't polish yet, just to confirm the pipeline: *change a value → restyle
appears*.
## Step 7: a provenance sentence
In `~/my-portfolio` create (or confirm) a short `README.md` line recording
your dataset's **name, publisher, URL, and license**: the provenance of your
whole portfolio. This is the document you'll commit to git next session.
## Done: check yourself
- The book builds with `quarto render` (no errors).
- Chapter 1 sources its data **by code** and shows your EDA with captions.
- The data is **pinned** with `{pins}` and you read it back with `pin_read()`.
- Your name is on the book; `index.qmd` reads like an introduction.
- You changed at least one colour in `_brand.yml` and it took effect.
- There is a written **provenance** for the dataset.
> **Stretch.** Add a *second* figure that speaks to a sub-question of your
> EDA, and cross-reference both figures in your Findings. Then preview the
> book with `quarto preview` to feel the difference between a report and a
> *navigable book*.
>
> **Stretch (theming).** Go beyond the palette: add a font in
> `_brand.yml` (`typography:` is commented in the file), or uncomment a rule
> in `styles.scss` (e.g. rounded figure frames, a tinted code background).
> Re-render and confirm the change is visible everywhere in the book.
>
> **Stretch (models).** If your EDA fits a model, pin the *model* too with
> [`{vetiver}`](https://rstudio.github.io/vetiver-r/), it records the trained
> model plus the package versions that made it, so it re-deploys anywhere.
> Everything has a Python twin when you get there: `renv`↔`uv`/`venv`, [`pins`](https://rstudio.github.io/pins-python/), [`vetiver`](https://rstudio.github.io/vetiver-python/).