Skip to content

データ形式

サポートされるデータ形式とアノテーションデータの構造化方法。

Potatoは複数のデータ形式をそのままサポートしています。このガイドでは、アノテーション用のデータ構造化方法を説明します。

How data flows through Potato: input files become instances with an id and text plus metadata, get annotated, and are exported to many formatsFrom input file to exported labels

サポートされる形式

形式拡張子説明
JSON.jsonオブジェクトの配列
JSON Lines.jsonl1行に1つのJSONオブジェクト
CSV.csvカンマ区切り値
TSV.tsvタブ区切り値

JSON形式

最も一般的な形式です。データはオブジェクトの配列として構成します：

json
[
  {
    "id": "doc_001",
    "text": "This is the first document to annotate.",
    "source": "twitter",
    "date": "2024-01-15"
  },
  {
    "id": "doc_002",
    "text": "This is the second document.",
    "source": "reddit",
    "date": "2024-01-16"
  }
]

JSON Lines形式

各行が独立したJSONオブジェクトです。大規模データセットに適しています：

jsonl
{"id": "doc_001", "text": "First document"}
{"id": "doc_002", "text": "Second document"}
{"id": "doc_003", "text": "Third document"}

CSV/TSV形式

ヘッダー付きの表形式データ：

csv
id,text,source
doc_001,"This is the first document",twitter
doc_002,"This is the second document",reddit

設定

基本セットアップ

YAMLでデータファイルとフィールドマッピングを設定：

yaml
data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id      # Field name for unique ID
  text_key: text  # Field name for content to annotate

複数のデータファイル

複数のデータソースを組み合わせる：

yaml
data_files:
  - "data/batch_1.json"
  - "data/batch_2.json"
  - "data/batch_3.jsonl"

ファイルは順番に処理され、結合されます。

データタイプ

プレーンテキスト

シンプルなテキストコンテンツ：

json
{
  "id": "1",
  "text": "The product arrived quickly and works great!"
}

メディアファイル

画像、ビデオ、またはオーディオの参照：

json
{
  "id": "1",
  "image_path": "images/photo_001.jpg"
}
yaml
item_properties:
  id_key: id
  image_key: image_path

対話/リスト

リストは自動的に横並びで表示されます：

json
{
  "id": "1",
  "text": "Option A,Option B,Option C"
}

テキストペア

比較タスク用：

json
{
  "id": "pair_001",
  "text": {
    "A": "Response from Model A",
    "B": "Response from Model B"
  }
}

HTMLファイル

フォルダに保存されたHTMLファイルの参照：

json
{
  "id": "1",
  "html_file": "html/document_001.html"
}

コンテキスト付きアノテーション

メインテキストとともにコンテキストを含める：

json
{
  "id": "1",
  "text": "This is great!",
  "context": "Previous message: How do you like the new feature?"
}
yaml
item_properties:
  id_key: id
  text_key: text
  context_key: context

表示設定

リスト表示オプション

リストと辞書の表示方法を制御：

yaml
list_as_text:
  # Add prefixes to items
  text_prefix: "A"  # A., B., C. (or "1" for 1., 2., 3.)
 
  # Display orientation
  horizontal: true  # Side-by-side (false for vertical)
 
  # Randomization
  randomize_values: true   # Shuffle list items
  randomize_keys: true     # Shuffle dictionary keys

HTMLコンテンツ

テキスト内のHTMLレンダリングを有効にする：

yaml
html_content: true
json
{
  "id": "1",
  "text": "<p>This is <strong>formatted</strong> text.</p>"
}

出力設定

出力ディレクトリ

アノテーションの保存先を指定：

yaml
output_annotation_dir: "output/"

出力形式

出力形式を選択：

yaml
output_annotation_format: "json"  # json, jsonl, csv, or tsv

出力構造

アノテーションにはドキュメントIDと回答が含まれます：

json
{
  "id": "doc_001",
  "user": "annotator_1",
  "annotations": {
    "sentiment": "Positive",
    "confidence": 4
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

特殊データタイプ

ベスト・ワーストスケーリング

ランキングタスクでは、カンマ区切りのアイテムを使用：

json
{
  "id": "1",
  "text": "Item A,Item B,Item C,Item D"
}

カスタム引数

表示やフィルタリング用の追加フィールドを含める：

json
{
  "id": "1",
  "text": "Document content",
  "category": "news",
  "priority": "high",
  "custom_field": "any value"
}

データベースバックエンド

大規模データセットにはMySQLを使用：

yaml
database:
  type: mysql
  host: localhost
  database: potato_db
  user: ${DB_USER}
  password: ${DB_PASSWORD}

Potatoは初回起動時に必要なテーブルを自動的に作成します。

データ検証

Potatoは起動時にデータを検証します：

  • IDフィールドの欠落 - すべてのアイテムに一意の識別子が必要
  • テキストフィールドの欠落 - アイテムにはアノテーション対象のコンテンツが必要
  • 重複ID - すべてのIDが一意である必要がある
  • ファイルが見つからない - データファイルのパスを確認

完全な例

yaml
task_name: "Document Classification"
task_dir: "."
port: 8000
 
# Data configuration
data_files:
  - "data/documents.json"
 
item_properties:
  id_key: id
  text_key: text
  context_key: metadata
 
# Display settings
list_as_text:
  text_prefix: "1"
  horizontal: false
 
# Output
output_annotation_dir: "output/"
output_annotation_format: "json"
 
# Annotation scheme
annotation_schemes:
  - annotation_type: radio
    name: category
    description: "Select the document category"
    labels:
      - News
      - Opinion
      - Tutorial
      - Other
 
allow_all_users: true

ベストプラクティス

1. 意味のあるIDを使用

追跡とデバッグを容易にします：

json
{"id": "twitter_2024_001", "text": "..."}

2. テキストを簡潔に

長いテキストはアノテーションを遅くします。検討事項：

  • 重要な部分に切り詰める
  • 要約を提供する
  • スクロールコンテナを使用する

3. メタデータを含める

フィルタリングと分析に役立ちます：

json
{
  "id": "1",
  "text": "Content",
  "source": "twitter",
  "date": "2024-01-15",
  "language": "en"
}

4. 読み込み前に検証

オフラインでデータを確認：

python
import json
 
with open('data.json') as f:
    data = json.load(f)
 
# Check for required fields
for item in data:
    assert 'id' in item, f"Missing id: {item}"
    assert 'text' in item, f"Missing text: {item}"
 
# Check for duplicates
ids = [item['id'] for item in data]
assert len(ids) == len(set(ids)), "Duplicate IDs found"
 
print(f"Validated {len(data)} items")

5. 元データをバックアップ

再現性のために、生データをアノテーションとは別に保管してください。

6. 大きなファイルにはJSON Linesを使用

JSON配列よりメモリ効率が良い：

bash
# Convert JSON array to JSON Lines
cat data.json | jq -c '.[]' > data.jsonl

関連資料

実装の詳細については、ソースドキュメントを参照してください。