---
# ─── YAML header · everything between the two --- lines is configuration ───
#
# `title` and `author` appear at the top of the rendered HTML.
# Change `author` to your own name; change `title` for each new notebook.
title: "Lab Notebook Template · Annotated Reference Copy"
author: "Your Name"

# `date: today` automatically fills in today's date when you render.
date: today

# `format: html:` says "render this to HTML." Everything indented under it
# customizes how the HTML looks.
format:
  html:
    toc: true              # Build a table of contents in the right margin
    toc-depth: 3           # Include H1 (`#`), H2 (`##`), and H3 (`###`) in the TOC
    theme: cosmo           # Bootstrap theme; `cosmo` is a clean default
    df-print: paged        # Data frames render as scrollable paged tables
    highlight-style: github
    embed-resources: true  # IMPORTANT · bundle CSS/JS/images into one self-contained .html.
                           # Without this, Quarto creates a sidecar folder of supporting
                           # files alongside the .html. With it, the .html is one
                           # email-able / submit-able file.

# `execute:` applies chunk options to EVERY chunk in this document.
# Per-chunk `#|` options (see below) override these for individual chunks.
execute:
  warning: false  # Hide R WARNINGS from the rendered report — but not from you.
                  # Warnings still print in the Console while you work, so you'll
                  # still see them. Unlike messages, a warning can carry real
                  # information: "Removed 12 rows containing missing values" means
                  # a chart quietly dropped data. If you want a warning to show up
                  # in the report itself while debugging, put `#| warning: true`
                  # on that one chunk (it overrides this global setting).
  message: false  # Suppress informational messages (the "Attaching tidyverse..."
                  # block, dplyr's "`summarise()` has grouped output by..." note).
                  # These are pure noise — safe to hide.
---

<!-- ─── This file is your ANNOTATED REFERENCE · NOT a working lab notebook ───

The file you're looking at is a reference copy you can return to whenever you
need a reminder about how a YAML block, a chunk option, or a standard lab
section is structured. Keep it pristine — don't edit this file directly.

There is also a stripped-down `lab_template.qmd` next to this one — the same
skeleton with the teaching comments removed. That clean copy is the one you
save-as to START a new lab notebook; this annotated copy is the one you READ
when you want a quick reminder of what each piece does.

HOW YOU START EACH LAB:

  • The first four labs (Modules 2-5): a pre-built notebook was already
    waiting in this `programs/` folder — `m02_lab.qmd`, `m03_lab.qmd`, and so
    on — with the title, packages, and TODO scaffolding filled in. You just
    opened it and worked through it.

  • From Module 6 onward: there is NO pre-built file. You build each
    week's notebook yourself. Use **File → Save As…** to copy the clean
    `lab_template.qmd` (the un-annotated sibling of this file) into
    `programs/`, rename the copy (for the Module 6 lab, that's
    `m06_lab_nsduh_probability.qmd`), and follow the lab walkthrough — you'll
    set the title, swap in the week's dataset, and add the analysis sections
    as you go. This is by design: after four weeks of practice you drive more
    of the setup yourself now, and each lab hands you a little less.

The sections below (Setup, Import Data, Glimpse) are the standard opening of
every lab notebook. `nhanes` appears only as a concrete example of the
read_rds() pattern — replace it with whatever dataset the week's lab uses.

-->

# Setup

<!-- The Setup section loads the packages this notebook needs. Putting all
     library() calls in one chunk at the top makes it obvious which packages
     an analysis depends on.

     Warnings and messages are already suppressed for EVERY chunk by the
     `execute:` block in the YAML header above, so there is nothing to add
     here. If you ever want to override that for a single chunk — say, to see
     a warning while debugging — add a `#|` option at the top of that chunk,
     e.g. `#| warning: true`.

     The `#| label: setup` line below is another such option: it names the
     chunk. Quarto then refers to it by name when something fails ("Error in
     chunk `setup`") instead of numbering it, and labelled chunks appear in
     the Outline at the top-right of the Source pane. Give every chunk you
     add a label; keep it short and hyphenated, and never reuse a name in
     the same file. -->

```{r}
#| label: setup

library(tidyverse) # data wrangling + ggplot2 + pipes
library(here) # portable file paths from the project root
library(skimr) # rich summary statistics
library(gtsummary) # publication-quality tables
```

# Import Data

<!-- Pattern: read_rds(here("data", "filename.Rds"))
     - here() builds a path relative to the project root (where the .Rproj
       file lives). Works on any machine without modification.
     - read_rds() loads R's native binary data format. The PSY 652 datasets
       all ship as .Rds files in the project's data/ folder.
     - The arrow `<-` is the assignment operator. It takes the result on the
       right and gives it a name on the left. Read it aloud as "gets":
       "nhanes gets the result of read_rds()." -->

```{r}
#| label: import-data

nhanes <- read_rds(here("data", "nhanes.Rds"))
```

# Glimpse

<!-- glimpse() prints a one-line-per-variable structural summary of the data
     frame: row count, column count, and each column's type plus the first
     several values. Always glimpse a dataset right after loading it to
     confirm the columns are what you expect. -->

```{r}
#| label: glimpse-data

nhanes |> glimpse()
```

<!-- ─── Add your own sections below this line ───

To add a new section, type a top-level heading (one `#`) followed by the
section name. For a subsection use two `##`; for a sub-subsection use three
`###`.

To insert a new code chunk, click the green +C button in the toolbar at the
top of the Source pane and choose R — or place your cursor where you want
the chunk and press Cmd+Option+I (Mac) / Ctrl+Alt+I (Windows). Either way RStudio inserts
both fences for you. (You can also type the opening fence as ```{r} on its
own line and the closing fence as ``` on a line of its own, but there is
no reason to.)

The render button (right-pointing arrow icon at the top of the Source pane) runs every
chunk in order from a fresh R session and writes the rendered HTML right next
to this file. To run a single chunk inline as you develop, click the green
arrow at the top-right of the chunk. -->
