Best-Worst Scaling

MaxDiff annotation where annotators select the best and worst items from a set for relative comparison.

⚖️

comparison annotation

Configuration Fileconfig.yaml

# Best-Worst Scaling (MaxDiff) Configuration
# Annotators select the best and worst items from a set

annotation_task_name: "Best-Worst Scaling"

data_files:
  - "data/comparison_sets.json"

item_properties:
  id_key: "id"
  text_display_key: "prompt"
  list_display_key: "options"

user_config:
  allow_all_users: true

annotation_schemes:
  - annotation_type: "best-worst"
    name: "quality_comparison"
    description: "Select the BEST and WORST response to the given prompt"
    best_label: "Best Response"
    worst_label: "Worst Response"
    use_colors: true
    best_color: "#22c55e"
    worst_color: "#ef4444"

  - annotation_type: "text"
    name: "reasoning"
    description: "Briefly explain your choices (optional)"
    required: false

  - annotation_type: "radio"
    name: "difficulty"
    description: "How difficult was this comparison?"
    labels:
      - name: "Easy"
        tooltip: "Clear difference between options"
      - name: "Moderate"
        tooltip: "Some thought required"
      - name: "Hard"
        tooltip: "Very similar quality, difficult to choose"

output: "annotation_output/"

Sample Datasample-data.json

[
  {
    "id": "bws_001",
    "prompt": "Write a haiku about spring",
    "options": [
      "Cherry blossoms fall / Gentle breeze carries petals / Nature awakens",
      "Spring is here now / Flowers bloom in the garden / Birds sing songs today",
      "Pink flowers bloom / The sun is warm and nice / I like spring a lot",
      "Melting snow reveals / Hidden crocuses emerge / Life begins anew"
    ]
  },
  {
    "id": "bws_002",
    "prompt": "Explain photosynthesis to a 10-year-old",
    "options": [
      "Plants eat sunlight and make food from it.",
      "Photosynthesis is like cooking for plants! They use sunlight as their stove, water and air as ingredients, and make their own food called glucose. The bonus? They release oxygen for us to breathe!",
      "Plants absorb light energy through chlorophyll in their leaves, converting carbon dioxide and water into glucose and oxygen through a complex biochemical process.",
      "Plants are green because they have chlorophyll. This helps them make food from the sun."
    ]
  }
]

// ... and 1 more items

Get This Design

View on GitHub

Clone or download from the repository

Quick start:

git clone https://github.com/davidjurgens/potato-showcase.git
cd potato-showcase/best-worst-scaling
potato start config.yaml

Details

Annotation Types

best-worst

Domain

nlpevaluation

Use Cases

preference-learningrankingquality-assessment

Related Designs

Ranking Task

Drag-and-drop ranking interface to order items from best to worst.

ranking

Dialogue Act Labeling

Classify utterances in conversations by their communicative function (question, statement, request, etc.).

radio

Fact Verification

Verify claims as supported, refuted, or not enough information based on provided evidence.

radiotext