A good, scientific workflow

Quant Camp

Juan Tellez

UC Davis

September 17, 2026

Plan for today

  • Quarto: prose and code in one document
  • Zotero: your papers and your citations
  • Managing AI agents
  • Agents for reading and writing
  • The pipeline: from raw data to a paper

One idea all day

Everything you make should have inputs and outputs

When an input changes, you rerun. You never redo

Input Output
prose + code a Quarto file a document with tables, figures, numbers
your Zotero library a .bib file every citation, formatted
raw data cleaning + analysis scripts clean data, figures, tables

Quarto

Writing while coding

If you work with data, you will be writing text and code at the same time, all the time:

  • Notes for your methods classes
  • Problem sets
  • Research papers

The copy-paste paper

Some people start like this:

  1. Run the analysis in R
  2. Copy the number into Word. Save the plot, drag it into Word
  3. Get new data, or find a bug
  4. Redo steps 1 and 2 for every number and figure. Miss one

The paper and the analysis are two separate things, and nothing keeps them in sync. This is redo, not rerun

Quarto

Quarto is a way to write regular text (prose) and code in the same document. The code runs inside the document

  • Write prose using a simple syntax called markdown
  • Put R code in chunks. The output (a table, a figure) appears right below
  • Click Render and the whole thing becomes html, pdf, Word, or slides (these slides are Quarto)

Let’s make one…

Three parts of a .qmd

---
title: "Coups around the world"
author: "Juan Tellez"
format: html
---

## What I found

Most coup attempts **fail**.

```{r}
coups |>
  count(realized) |>
  knitr::kable()
```
  1. Header (between the ---): title, author, output format
  2. Prose, written in markdown: ## is a heading, **bold**, *italic*
  3. Chunks: R code, same as in a script. You can add options at the top of a chunk, on lines that start with #|: for example, #| echo: false hides the code and keeps the output

Never type a number

You can run R inside a sentence. This text:

The data has `r nrow(coups)` coup attempts. Of those,
`r round(mean(coups$realized) * 100, 1)` percent succeeded.

renders as:

The data has 981 coup attempts. Of those, 45 percent succeeded.

A number you type by hand is wrong the moment the data changes. A number R writes updates itself. Rerun, never redo

One file, many formats

Change one line in the header and render again:

Header You get
format: html a web page (the default; always works)
format: docx a Word document, for coauthors who live in Word
format: pdf a PDF (one-time setup: quarto install tinytex in the Terminal)
format: revealjs slides

Same prose, same code, same numbers. You never rebuild the document for a new format

Two things that trip people up

A render starts from a fresh R session. It cannot see your Environment. Every package and object the document needs must be loaded or made inside the document

It is the same rule as all week: restart R, run top to bottom

Use here() for every file. Quarto runs from the folder the .qmd sits in, which may not be your project folder. here("data", "clean", "co2.rds") works from anywhere

Zotero

Bad citation management

  • Save PDFs in random folders, or (god forbid) the Downloads folder, with names like paper1.pdf, paper2.pdf, etc.
  • Write a paper, typing out the references by hand at the end
  • Need to find an old paper? Good luck!

  • Writing a new paper? You’ll have to type all the references again

Zotero: a citation manager and a library

  • Every paper you have ever saved, in one searchable place, with the PDF attached
  • One click in your browser (the Zotero Connector) saves the citation and the paper
  • Free, open source, and it syncs across your computers
  • Great setup guide, ignore the “migration” part

Let me show you mine…

Read where your citations live

Zotero has a PDF reader built in. Read the paper inside Zotero:

  • Highlight and comment as you read
  • Every highlight keeps its page number and stays tied to the citation

Then get your highlights out, as notes you can search and write from:

  • Zotero can turn them into a note by itself (Add Note from Annotations)
  • Or send them to a notes app. I use Obsidian; there are others

In three years, “where did I read that?” takes ten seconds

From Zotero to Quarto: the .bib file

Zotero exports your library as a plain-text .bib file. Each paper is one entry:

camp.bib
@article{fearon2003,
  title = {Ethnicity, Insurgency, and Civil War},
  author = {Fearon, James D. and Laitin, David D.},
  year = {2003},
  journal = {American Political Science Review},
  volume = {97},
  number = {1},
  pages = {75--90}
}

You never write these by hand. The part you use is the key on the first line: fearon2003

The Better BibTeX add-on keeps the .bib file up to date as your library grows

Citing in Quarto

Point the header at your .bib file with bibliography: camp.bib. Then cite with @ and the key:

You write You get
@fearon2003 argue that... Fearon and Laitin (2003) argue that…
...is common [@fearon2003]. …is common (Fearon and Laitin 2003).
[@fearon2003; @wickham2014] (Fearon and Laitin 2003; Wickham 2014)

Quarto builds the reference list for you, with only the works you cited, formatted the same way every time

Let’s cite the dataset from this morning’s notebook. Datasets get cited too

🚨 Your turn: a report that updates itself 🚨

Download 05_report.qmd and camp.bib. Put both at the top level of your camp project (next to the .Rproj file)

  1. Open 05_report.qmd and click Render. Find the three parts: header, prose, chunks

  2. Change my_country to a different country and render again. What changed in the text? Did you type any of it?

  3. Add a sentence that cites Healy’s book (the key is in camp.bib). Render. Look at the reference list

  4. Ask your agent to add a short section to the report that compares your country to the average for its continent. Render. Read the chunk it wrote

Managing AI agents

The agent forgets. The project remembers

Every new session starts from zero. The agent knows only:

  • what is in CLAUDE.md
  • the files it opens in your project
  • what you type

So anything worth keeping goes in a file: a rule in CLAUDE.md, a comment in the script, a note about where the data came from

Write those notes in markdown (.md) files. It’s the same plain text you just used in Quarto: easy for you to read, easy for the agent to read, and it opens on any computer

If it only lives in the chat, it is gone tomorrow

Grow your CLAUDE.md

CLAUDE.md is a living file. When you catch the agent making the same mistake twice, add a rule:

CLAUDE.md
## Checking

- After every filter or merge, tell me how many rows went in and how many came out.
- Never use `na.rm = TRUE` or `drop_na()` without telling me how many rows were missing.
- For every percent, say in a comment what it is a percent of.

These are Wednesday’s and Thursday’s lessons, written as instructions

Keep a session log in the project

CLAUDE.md holds the rules. A session log holds the history: dated summaries of what was done, what was decided, and what comes next

session_log.md
# Session log

## 2026-09-16
- Cleaned the CCES survey: party collapsed to 3 groups, wall question recoded to 0/1
- Dropped 185 respondents with no party or no wall answer (5000 -> 4815)
- Saved data/clean/clean_data.csv
- NEXT: table of wall support by party

## 2026-09-18
- Made the party table and the education figure (code/analysis.qmd)
- DECIDED: drop pure Independents, the study is about partisans (4815 -> 4083)
- OPEN QUESTION: should "leaners" count as partisans? Ask my advisor

End of a session: “Add today’s entry to session_log.md.” Start of the next: “Read session_log.md first.”

Make the agent show its work

Ask a question in the chat and you get an answer you can’t check: a number, a confident paragraph, and nothing behind it

Ask the agent to put its work in your notebook instead:

Add a section to coups.qmd that shows whether military coups succeed more often than other coups. Put the code in chunks with comments, show a table, and write two sentences on what it shows. Use inline code for every number. Then render it.

Now the analysis is a thing you can read, run, and rerun: the code, its output, and the claim, side by side

What the agent can see

The agent reads the files in your project folder, and what it reads is sent to the company’s servers

Keep out of any folder you run an agent in:

  • data with names, addresses, or anything that identifies a person
  • anything your IRB protocol or a data-use agreement says must stay private
  • passwords and API keys

Workaround: give the agent a fake or de-identified sample with the same columns. It writes the code; you run it on the real data

Not sure? Ask your advisor and the IRB before, not after

The adversarial agent

The agent that wrote the code is the worst one to check it: it shares its own blind spots. Start a fresh session (/clear, or a new terminal) whose only job is to find what’s wrong:

You are reviewing coups.qmd. Do not change anything. Look for mistakes: rows dropped without saying so, percents with the wrong denominator, numbers in the text that don’t match the code, anything that would mislead a reader. For each one, tell me how I can check it myself.

I’m going to break my notebook on purpose. Let’s see if it notices…

Its report is a list of leads, not a verdict. The reviewer can be wrong too. You check each lead yourself

🚨 Your turn: find the bugs 🚨

Download 05_check_me.R into your code/ folder. An agent wrote it. It runs with no errors

  1. Within one region, what should the percents add up to? Do they?

  2. Find a county you know (Yolo? your hometown?). Did Democrats gain there, according to the raw columns? According to dem_gain?

  3. Open a fresh agent session and ask for an adversarial review (don’t let it change the file). Did it find what you found? Did it flag anything that turned out to be fine?

Agents for reading and writing

How can we make these useful?

Agents can search the literature, summarize papers, and draft text. Two ways this goes wrong:

1. It makes up a citation. A paper that doesn’t exist, or a real paper that doesn’t say that

2. It misreads a text. The paper is real, the summary is confident, and the summary is wrong

These are not equally hard to fix

Made-up citations: mostly solved

Agents can search the web now. Demand that they check:

Before you suggest any paper, verify that it exists: find the journal page or DOI and give me the link. If you can’t find it, don’t mention it.

Then you still go get it yourself: open the link, save it with the Zotero Connector, read it

If it’s not in your Zotero, it’s not in your paper

Misreading: much harder

The paper exists. The agent says it “finds that aid reduces conflict.” Does it?

Maybe it finds that in one region. Maybe it’s the hypothesis, and the result was null. Maybe it’s what the paper argues against

There is no prompt that fixes this. The only way to verify what a text says is to read it yourself

If you cite it, you read it

The pipeline

From raw data to results

Every project, no matter how big, is this:

raw data → cleaning → clean data → analysis → figures + tables

Two rules:

  • Raw data stays raw. You never open it and edit it. Cleaning happens in a script, and the script is the record of what you did

  • Figures and tables are ALWAYS made by a script. Never by hand, never by copy-paste, never touched up afterwards

A project folder

pipeline_example/
├── data/
│   ├── raw/cces_2020_sample.csv    <- raw survey data: never edited
│   └── clean/clean_data.csv        <- made by clean_data.qmd
├── code/
│   ├── clean_data.qmd              <- reads raw, cleans, says why in plain English
│   └── analysis.qmd                <- reads clean, makes every table and figure
├── figures/                        <- made by analysis.qmd
└── tables/                         <- made by analysis.qmd

Download it: pipeline_example.zip. Let’s open it up…

“You need to drop those respondents”

Months in, you realize (or a reviewer tells you) that some respondents should be excluded

With a copy-paste paper: redo every number, every table, every figure. Hope you got them all

With a pipeline:

  1. Make one edit, in clean_data.qmd, and write down why
  2. Rerun the pipeline: render clean_data.qmd, then analysis.qmd
  3. Every count, table, and figure downstream updates

Rerun, never redo

This afternoon

Problem set 5

Go out into the wild: pick a dataset from Data Is Plural and write a short Quarto report on it, inside your camp project

It needs: a figure, numbers written with inline code (none typed by hand), and a citation for the data

Before you call it done: open a fresh agent session and ask for an adversarial review of your report. Check what it flags

Then, one last time: restart R and render top to bottom. If it works then, it works