Getting Started Guide

This guide walks you through setting up your first annotation project with Potato.

Installation

pip install potato-annotation

Or install from source:

git clone https://github.com/davidjurgens/potato.git
cd potato && pip install -r requirements.txt

For full installation details, see Installation & Usage.

Your First Annotation Task

The fastest way to get started:

pip install potato-annotation
potato start examples/classification/single-choice/config.yaml -p 8000

Open http://localhost:8000 and you're ready to annotate. Browse the examples/ directory for ready-to-use templates.

For the step-by-step walkthrough, see Quick Start.

Understanding Configuration

Every Potato project is defined by a YAML configuration file. Key sections:

Section Purpose
data_files Input data paths
annotation_schemes Define annotation types and labels
item_properties Map data fields (id_key, text_key)
task_dir Output directory for annotations

See Configuration Reference for all options, and Data Format for input/output specifications.

Choosing an Annotation Type

Potato supports 30+ annotation types. Start with the decision guide:

Common starting points: - Radio buttons for single-choice classification - Checkboxes for multi-label tasks - Likert scales for rating tasks - Span annotation for NER and text highlighting

Setting Up Workflows

Potato supports multi-phase workflows: consent, instructions, training, annotation, and post-study surveys.

Exporting Results

After annotation, export in multiple formats:

Next Steps