# Wildfire Research Lab: a small Codex starter

Copy this folder into a **new folder for your team's project**. Open that copy in Codex and run commands from its root. Keep the course repository and the instructor's research system separate from your team's work. Each student uses their own account. This starter requires R for the example and uses only base R; it requires no API key, package installation, custom agents, or additional service.

Begin by filling in `project-plan.md`. Read `AGENTS.md`, then ask Codex for one concrete task with specified inputs and outputs. Keep decisions and actual checks in `lab-notebook.md`. Students choose the research question, exposure definitions, and interpretation, and explain the resulting code and figures.

## First lab: an intentionally failing data audit

The files in `data/raw/` are **entirely synthetic teaching data**. Their county identifiers and dates provide practice with joins. Their numbers are invented and support no claim about actual wildfire smoke or weather. The intended observation unit is **county-day**.

1. Inspect both CSV files before running code. Read their definitions in `data/README.md`.
2. From the project root, run `Rscript R/01_audit.R`.
3. Read `output/checks/audit.txt`. The script deliberately stops when it detects a duplicated weather key. An intentional failure is a useful finding to explain.
4. Ask Codex to propose a derived transformation that removes only the exact duplicate weather record. Check the records yourself and record why this decision is appropriate for this synthetic exercise. Preserve both raw files. An identical-looking record in a real dataset still requires investigation of the source's observation unit.
5. Save the transformed weather data separately in `data/derived/`. Preserve missing precipitation and the negative smoke estimate. Do not replace missing values with zero or clip negative values simply to make a plot look plausible.
6. Check that the derived weather file has one row per county-day. Then propose and implement a left join with smoke as the left table. Verify the expected row count, unique keys, and unmatched keys. Save the join checks in `output/checks/`.
7. Explain the checks and the decision to a classmate. Update `lab-notebook.md` with the exact command run, result, remaining uncertainty, and next task.

Example starting prompt:

> Read AGENTS.md, project-plan.md, and data/README.md. Inspect the raw CSV files and run the supplied audit. Explain its failure using the actual records. Propose a transformation and the checks needed for a six-row county-day left join. Preserve raw data, missing precipitation, negative smoke estimates, and leading zeros in county identifiers. Wait for my substantive decision about the duplicate before implementing that transformation.

`AGENTS.md` supplies project instructions. It does not configure the app's permissions. Use the permissions available in your own Codex setup. This lab only needs local project files.

## Instructor notes: expected audit and join results

These expectations describe the supplied **synthetic** fixture, not environmental findings. There is intentionally no completed cleaning or joining solution script.

| Check | Expected result |
|---|---|
| Smoke rows / unique county-day keys | 6 / 6 |
| Weather rows / unique county-day keys | 7 / 6 |
| Exact duplicated weather record | `06037`, `2023-06-07`, `temperature_c = 22`, `precipitation_mm = 0` appears twice |
| Weather rows beyond the first occurrence of each key | 1 |
| Weather rows belonging to repeated keys | 2 |
| Missing precipitation in raw weather | 1, for `01001` on `2023-06-08` |
| Missing values in other supplied fields | 0 |
| Negative smoke estimates | 1: `06037` on `2023-06-07`, value `-0.4` |
| Leading-zero county identifier | `01001` remains a five-character string |
| Left join against uncorrected weather | 7 rows: the repeated weather key multiplies a smoke row |
| Exact-duplicate removal in derived weather | 6 weather rows and 6 unique keys |
| Left join against derived weather | 6 rows, 6 unique county-day keys, 0 unmatched smoke keys |
| Missing precipitation after corrected join | 1; it remains missing |
| Negative smoke after corrected join | 1; the value remains `-0.4` |

The audit validates `GEOID` and ISO calendar dates, rejects missing or malformed key values and duplicated smoke keys, and saves its report **before** stopping on the supplied weather duplicate with a nonzero exit status. The student's final join should meet explicit checks rather than merely complete without an error. Generated audit output is ignored by Git and can be regenerated.

## Later project work

Replace the toy exercise with approved public data and complete the source table before analysis. Record the original observation unit, temporal coverage, spatial definition, exposure units, and missing-value codes. Keep smoke plumes, modeled smoke PM2.5 estimates, and total measured PM2.5 distinct. Begin with descriptive questions and figures. Mortality outcomes are outside this course's project scope. Use a supported identification strategy before making causal claims.

Do not place account credentials or API keys in this folder. Share code, documented decisions, and permitted data through the team's normal course workflow.