# Paper Mode

Source: https://www.potatoannotator.com/docs/features/paper-mode

*New in v2.7.0*

Every dataset paper ends the same way: reconstructing annotator counts, agreement statistics, label distributions, and timing from scattered output files, then hand-formatting them into LaTeX. Paper Mode does it in one command.

```bash
python -m potato.paper config.yaml -o paper_export
```

![One command turns the project into a compilable LaTeX dataset report — methods section and all.](/images/docs/paper-mode.png)

The output is fully offline. No LLM, no server, no network.

```
paper_export/
├── paper.tex        # compilable standalone; every section cut-paste-able
├── paper.bib        # citations for every metric used (+ Potato)
├── tables/*.csv     # each table as CSV, for your own styling
└── summary.json     # every computed number, machine-readable
```

`paper.tex` compiles as-is, and every paragraph and table sits between markers so you can lift sections straight into a manuscript:

```latex
%% === BLOCK: paragraph-annotation-methods ===
Annotators spent a median of 42 seconds per item (12.3 person-hours in total).
Inter-annotator agreement for \emph{politeness}, measured by Krippendorff's
$\alpha$ (nominal) \citep{krippendorff2004content} over the 214
multiply-annotated units, was $\alpha = 0.712$ (tentative agreement). ...
%% === END BLOCK: paragraph-annotation-methods ===
```

## What it generates

| Block | Content |
|-------|---------|
| `paragraph-dataset-description` | Item counts, schemes, labels, annotator and label totals — ready for a Data section |
| `paragraph-annotation-methods` | Timing, Krippendorff's α per scheme, mean pairwise Cohen's κ, all cited |
| `table-distribution-<scheme>` | A booktabs label-distribution table per scheme, with totals |
| `table-annotators` | Items, labels, and median seconds per item for each annotator |
| `table-agreement` | α, mean κ, and interpretation per scheme against Krippendorff's 0.667 and 0.8 thresholds |
| `paragraph-limitations` | Caveats with real numbers: single-annotated units, low-α schemes, small annotator pools |

## CLI options

| Flag | Default | Description |
|------|---------|-------------|
| `-o, --output-dir` | `paper_export` | Where to write the report |
| `--no-anonymize` | off | Keep real usernames; by default annotators become A1..An |

## Method notes

- Paper Mode reads `{output_annotation_dir}/<user>/user_state.json` directly, resolved relative to the config file, so it works on archived projects without starting a server.
- Krippendorff's α (nominal) is computed with `simpledorff` — the same implementation as the [admin dashboard](/docs/features/admin-dashboard) — over units with two or more annotations. Pairwise Cohen's κ is computed per annotator pair with two or more shared items.
- Categorical schemes (`radio`, `likert`, `multiselect`, `select`, `bws`) get distributions and agreement. Multiselect agreement treats each (item, label) checkbox as a binary-coded unit. Span and textbox schemes are listed as not covered.
- Timing comes from [behavioral logs](/docs/features/behavioral-tracking), using `total_time_ms` and falling back to interaction timestamp spans, ignoring gaps over an hour.

## Further reading

- [Documenting annotation datasets](/docs/guides/documenting-datasets-and-models)
- [Inter-annotator agreement](/docs/guides/inter-annotator-agreement)
- [Admin dashboard](/docs/features/admin-dashboard) — the live equivalents of these numbers
- [Source documentation](https://github.com/davidjurgens/potato/blob/main/docs/advanced/paper_mode.md)