Skip to content
ガイド10分で読めます

Prolificでのアノテーション研究の実施

URL直接ログイン、完了コード、アテンションチェック、API経由の提出状況モニタリングを使って、PotatoのアノテーションスタディをProlificで実施します。

Potato Team

ProlificのスタディURLを?PROLIFIC_PID={{%PROLIFIC_PID%}}付きでPotatoサーバーに向け、login.type: url_directと、スタディ側のコードと一致するcompletion_codeを設定すれば、各参加者は自分のProlific IDでログインし、作業を終えるとProlificに戻されます。

Prolificは学術研究向けに作られた参加者プールで、Potatoが最も幅広くサポートしているクラウドソーシングプラットフォームです。本ガイドでは、Potatoに必要な設定、Prolific側のスタディ設定、そして費用をかける前に用意しておくべき品質管理を扱います。

研究者がアノテーションにProlificを使う理由

Prolificは参加者を審査し、報酬もプラットフォーム経由で支払うため、クラウドソーシングで通常スタディの予算を食う部分はあなたのサーバーの外で処理されます。最低時給を強制し、人口統計や言語の条件で参加者を絞り込み、同意を記録するので、ラベリング研究のIRB書類が短くて済みます。よく比較されるMechanical Turkは2026年9月30日に終了しました。そこで実施していたスタディについては、MTurkからスタディを移すで移行の方法を説明しています。

始める前に必要なもの

  1. Prolificの研究者アカウント。
  2. 公開HTTPS URLを持つサーバー上で動作しているPotato。この手順はサーバーデプロイガイドで扱っています。
  3. データファイル、item_properties、少なくとも1つのアノテーションスキームを含む設定。

Potatoに必要な設定

4つの設定で、通常のPotatoプロジェクトをProlificから動かせるプロジェクトにできます。login.url_argumentは参加者のProlific IDを運ぶURLパラメータ名を指定し、completion_codeはProlificのスタディに設定したコードと一致させる必要があります。2つのリダイレクト用キーは、参加者を完了ページに残さずProlificへ戻します。その下の割り当て用キーは1人の参加者に渡す作業量の上限を決めるもので、これがスタディのコストを予測可能に保ちます。

yaml
annotation_task_name: "Sentiment Annotation Study"
task_description: "Classify the sentiment of short text snippets. This task takes about five minutes."
 
# Participants are logged in from the PROLIFIC_PID URL parameter
login:
  type: url_direct
  url_argument: PROLIFIC_PID
 
# Must match a completion code configured on the Prolific study
completion_code: "C1ABCDEF"
auto_redirect_on_completion: true
auto_redirect_delay: 5000
 
# Keep participants on task
hide_navbar: true
jumping_to_id_disabled: true
 
# Each participant labels 20 items; each item is labeled by 3 participants
assignment_strategy: random
max_annotations_per_user: 20
num_annotators_per_item: 3
 
data_files:
  - data/texts.json
 
item_properties:
  id_key: id
  text_key: text
 
output_annotation_dir: annotation_output/prolific-study/
export_annotation_format: jsonl
 
user_config:
  allow_all_users: true
  users: []
 
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the sentiment expressed in this text?"
    labels:
      - name: positive
      - name: neutral
      - name: negative
    sequential_key_binding: true
    label_requirement:
      required: true

num_annotators_per_itemは、データを何に使うかで決めてください。一致率を報告したり多数決ラベルを取ったりするなら3が一般的で、パイロットでタスクが明確に定義されていると確認できた後なら1で十分です。結果の読み方はアノテーター間一致率ガイドで解説しています。

Prolificでスタディを設定する

Prolificのスタディフォームで、外部スタディURLにPotatoサーバーを指定し、クエリ文字列にProlificのプレースホルダーを入れます：

text
https://your-server.com/?PROLIFIC_PID={{%PROLIFIC_PID%}}&STUDY_ID={{%STUDY_ID%}}&SESSION_ID={{%SESSION_ID%}}

Prolific IDの記録方法を問う質問では"I'll use URL parameters"を選び、続いて設定ファイルのcompletion_codeと一致する完了コードをスタディに設定します。STUDY_IDとSESSION_IDは、後で追跡できるよう参加者のセッションに保存されます。

リンクをクリックした参加者は、URLに自分のIDを載せた状態でPotatoに到着します。PotatoはそのIDでパスワードなしのアカウントを作成し、設定したフェーズを順に進ませ、作業が終わると完了コードと、https://app.prolific.com/submissions/complete?cc=<code>へリンクするReturn to Prolificボタンを表示します。auto_redirect_on_completionを設定していれば、auto_redirect_delayミリ秒後に自動でリダイレクトされます。

ドメインはapp.prolific.comと書いてください。古いapp.prolific.coドメインはもうHTTPSを提供していないため、古いガイドからコピーした完了URLでは、参加者は作業を終えた後に使えないページへ送られてしまいます。

同意、説明、終了時アンケート

クラウドソーシングのスタディの多くは、アノテーションページだけでは足りません。Potatoのphasesブロックは、同意、事前スクリーニング、説明、スタディ後アンケートをアノテーションフェーズの前後に配置し、参加者は列挙した順にそれらを進みます：

yaml
phases:
  order: [consent, prestudy, instructions, annotation, poststudy]
 
  consent:
    type: consent
    file: surveyflow/consent.json
 
  prestudy:
    type: prestudy
    file: surveyflow/prescreening.json
 
  instructions:
    type: instructions
    file: surveyflow/instructions.html
 
  poststudy:
    type: poststudy
    file: surveyflow/demographics.json

このブロックを上の設定に追加します。必須なのはannotationフェーズだけなので、同意フォームが不要なスタディは他の項目をすべて省略できます。古いプロジェクトは同じことをsurveyflowで設定しています。Potatoは今もこれを読み込みますが、新しいプロジェクトには推奨していません。

アテンションチェック

アテンションチェックとは、正解が分かっているアイテムをキューに混ぜておき、注意を払っていない参加者が検出可能な誤答をするようにしたものです。Potatoはこれをデータではなく専用のファイルから読み込むため、チェック項目はデータセットに入りません：

yaml
attention_checks:
  enabled: true
  items_file: "data/attention_checks.json"
  frequency: 10
  min_response_time: 3.0
  failure_handling:
    warn_threshold: 2
    block_threshold: 5

このブロックを上の設定に追加します。frequency: 10は10アイテムごとにチェックを1つ挿入し、min_response_timeは、誰もアイテムを読めないほど速く届いた回答を、内容にかかわらず不合格にします。時間はサーバー側で計測され、アイテムを送信した時点から保存を受け取った時点までを数えます。

各チェックアイテムには、id、参加者に表示されるテキスト、スキーム名ごとの期待される回答を含めます：

json
[
  {
    "id": "attn_001",
    "text": "Please select 'positive' for this item to verify you are reading carefully.",
    "expected_answer": {"sentiment": "positive"}
  }
]

block_thresholdはスタディの長さに合わせて設定してください。20アイテムのタスクで5回チェックに失敗する参加者は、そもそもアノテーションをしていません。一方、300アイテムを通して5回失敗する参加者は一時的に疲れていただけかもしれず、ブロックすると残りの作業を失います。

実施中のスタディをモニタリングする

login.type: prolificを設定してprolificブロックを追加すると、Potatoは既に行っているURL直接ログインに加えて、Prolific APIに提出状況を定期的に問い合わせます：

yaml
login:
  type: prolific
  url_argument: PROLIFIC_PID
 
prolific:
  config_file_path: configs/prolific_config.yaml
 
completion_code: "C1ABCDEF"

このブロックを上の設定に追加します。参照先のファイルにはAPIトークンが入るので、バージョン管理の対象から外してください：

yaml
# configs/prolific_config.yaml
token: "your-prolific-api-token"
study_id: "your-study-id"
workload_checker: true
max_concurrent_sessions: 30
workload_checker_period: 300

トークンを設定すると、管理ダッシュボードにProlificパネルが加わります。このパネルからスタディの公開、一時停止、停止、提出の承認や却下、ボーナスの支払い、枠を追加した場合のコストのプレビューができます。ワークロードモニターは、アクティブな参加者がmax_concurrent_sessionsに達するとスタディを一時停止し、その数が上限の20%を下回ると再開します。再開するのは自分で一時停止したスタディだけなので、Prolific上で手動で一時停止したスタディは停止したままです。

途中で離脱する参加者

参加者が完了せずに離脱すると、Prolificはその提出をRETURNED、TIMED-OUT、REJECTEDのいずれかとして報告します。Potatoはその参加者に割り当てたアイテムを解放して他の人が取れるようにし、既に完了していたアノテーションは保持します。離脱の理由によって完了済みの作業の扱いを変えたい場合は、instance_reclaimを使います：

yaml
instance_reclaim:
  enabled: true
  prolific:
    preserve_completed_annotations: true
    status_policies:
      TIMED-OUT:
        preserve_completed_annotations: true
      REJECTED:
        preserve_completed_annotations: false

このブロックを上の設定に追加します。この区別は意図して設定する価値があります。タイムアウトした参加者は、たいてい何かに中断されるまでは誠実にアノテーションしていました。一方、却下された参加者の作業は支払わないと決めたものであり、それをデータセットに残すと却下の意味が損なわれます。

出力の内容

Potatoはoutput_annotation_dirの下にアノテーターごとのファイルを書き出し、export_annotation_formatが設定されていれば<output_annotation_dir>/exports/<format>/の下に定期的なエクスポートも書き出します。エクスポートされた各レコードには、インスタンス、アノテーター、スキーム名ごとのラベルが含まれます：

json
{"instance_id": "t_014", "user_id": "5f2c9a1b3d4e5f6a7b8c9d0e", "labels": {"sentiment": {"positive": "positive"}}, "spans": {}, "links": {}}

user_idは参加者のProlific IDです。Potatoがそのユーザー名でアカウントを作成したためで、これにより各行をProlificの提出と照合して承認やボーナスの支払いができます。データセットを公開するときは、この列を個人を識別できるデータとして扱ってください。

まずパイロットを実施する

本番のスタディを始める前に5〜10人の参加者で試し、完了率だけでなく出力そのものを読んでください。後から見つかると高くつく失敗が2つあります。1つ目は、タスクを自分で書いたために気づけない形で曖昧になっている説明、2つ目はアイテムあたりの所要時間が見積もりから大きく外れていることで、これは報酬単価がどちらかの方向に間違っていることを意味します。

スタディの報酬は、自分の所要時間ではなくパイロットの所要時間の中央値から決めてください。スタディの説明に何を書いても一部の参加者はスマートフォンで参加するので、インターフェースはスマートフォンの幅でも使えるようにしておきます。提出は速やかに承認してください。参加者は支払いを待っていますし、あなたの承認までの時間は、スタディを受けるか判断する将来の参加者にも見えています。

次のステップ

完全なリファレンスは本サイトのクラウドソーシング統合にあり、PotatoリポジトリのProlific統合ドキュメントでは、ダッシュボードパネルの背後にある管理APIエンドポイントを解説しています。スタディの作成、参加資格（qualification）の同期、有償のスクリーンアウトを自分のコードから操作したい場合は、そこから始めてください。