A codebook is a list of questions, each with its own instructions.
A named list of questions. Each with its own instructions.
· · ·
Input documents · Purpose for extraction · anything else true of the whole corpus
##analyzing_data
Question
Is this manuscript actively analyzing empirical data?
Description
Answer "Yes" if authors gathered or analyzed data. "No" for protocols, editorials, commentaries.
Examples
"Yes" — The abstract reports results from 500 patients.
Default
"Yes"
##patient_level_health_outcomes
Question
Does the analysis involve individual patient-level data to evaluate health outcomes?
Description
Isolates clinical research from economic modeling. "No" for HEOR or cluster-level.
Examples
"Yes" — Patients assessed for depressive symptoms via PHQ-9.
Default
"Yes"
##intervention_randomized
Question
Was the intervention individually randomised? Answer "Yes", "No", or "Unclear".
Description
"Yes" if individual participants were randomly assigned. "No" for cluster, single-arm, or pseudo-randomisation.
Default
"Unclear"
· · · more fields below · · ·
A codebook is a list of fields. Each field has a name like ##intervention_type and its own slots: Question, Description, Examples, Default. Descriptions grow as needed — rules, edge cases, references to other fields. The block above the first field is part of it too.
The AI reader reads the whole thing, top to bottom.
@karlrohe
A codebook is a plain text file. I write mine in markdown. The card above shows one with the formatting turned on. Here is a real screening codebook with the formatting off, trimmed to its first field:
# MetaCIH Title/Abstract Screening
**Input documents:** Rows from a screening spreadsheet, each containing a study's
title, authors, abstract, journal, year, and bibliographic metadata. …
**Purpose for extraction:** Determine whether each study should advance to
full-text review based on its title and abstract. …
---
## language
**Question:** What language are the title and abstract written in?
**Description:** If the title/abstract are only in a language other than English,
exclude. Be sure to look carefully, because sometimes the title and abstract are
present in two languages. …
**Examples:**
- "English"
- "Chinese only — title and abstract in Chinese, no English"
- "Bilingual — title in Spanish and English, abstract in English"
**Default if missing:** Not specified
**Answer Type:** text
---
## language_meets_criteria
**Question:** Are the title and abstract available in English?
…
Two hash marks name a column in your spreadsheet.## language becomes the column language. Everything under it is instruction for that one question. Question asks it at a high level. Description holds the rules. Examples shows what a right answer looks like. Default if missing says what to write when the document does not say.
Any tag you invent is passed straight through to the reader. Data Mint's parser keeps no list of allowed tag names. Write **Reviewer's note:** or **Why this matters:** or **Watch for:** and the reader sees it, in your words, in the prompt for that question. Nothing is dropped for being unrecognized.
Data Mint writes your first codebook for you, in a conversation. You bring what you have. It asks a few questions, proposes a skeleton, and writes the draft. How that conversation goes, and what it may and may not read into your instructions, is the next card.
The first codebook is where you start. Edge cases and ambiguities come out later, when several readers read the same document and disagree. That is what the refinement loop is for. This conversation only gets you to a codebook you can run.