定性コーディングのための共有コードブック

Potato のコードブックは、プロジェクトのコーダーが適用するコードのリストです。Potato は、コードブックを YAML 設定ではなく、プロジェクトのデータベースに保持します。スキームは codebook: true でオプトインし、スキームの選択肢はコードブックから得られるようになります。コーダーは、誰も設定を編集せず、サーバーを再起動しなくても、セッションの途中でコードを追加できます。コードは親コードの下に置け、各コードの項目には、定義、包含と除外のルール、例を含む型付きフィールドがあります。Potato は、保存されたすべてのアノテーションに、保存の時点で有効だったコードブックの改訂を刻印します。コードブックは、Potato 2.6.0 で QDA モードとともに登場し、標準のアノテーション、ソロモード、QDA モードで動作します。

質的研究におけるコードブックは、チームが適用するコードを一覧し、各コードがいつ適用されるかを述べます。MacQueen ら（1998）は、すべてのコードに同じ固定構造を持つコードブックは、コーダーのチームに安定した枠組みを与え、コーダー間一致度を高めると主張しています。Potato は、すべてのコードに、短い定義から反例までの、同じ型付きフィールドの集合を与えます。コードブック開発ガイドは、チームが項目をどのように書き、改訂するかを扱います。

コードブックの保存と初期化

• 保存。 コードは <task_dir>/project.sqlite にあります。メモとケースは、同じプロジェクトデータベースを共有します。YAML には、開始時のラベルだけが入っています。
• 初期化。 最初のサーバー起動時に、Potato は codebook: true と印の付いたすべてのスキームの labels を、空のコードブックにコピーします。それ以降はデータベースが信頼できる情報源となり、サーバーは YAML のラベルへのその後の編集を無視します。
• プロジェクトごとに一つのコードブック。 codebook: true と印の付いたすべてのスキームは、同じコードを表示します。themes スキームと quotes スキームを持つプロジェクトは、両方を一つのリストから取ります。
• スキームタイプ。 radio、multiselect、select、span が codebook: true を受け付けます。
• 改訂。 コードの追加、名前変更、色の変更、移動、削除、統合、分割は、プロジェクトのコードブックの改訂を一つ上げます。Potato は、その後に保存されるすべてのアノテーションに、改訂を記録します。
• コーダーがコードブックを見る場所。 アノテーションページの右端にある Codebook のトグルは、各コードをその短い定義とともに一覧するトレイを開きます。/codebook ページは、すべてのコードのすべてのフィールドを含む、完全なコードブックを表示します。

設定

以下の設定は、extensible モードのチームのためにインタビューのコーディングを設定します。コーダーは読みながらコードを追加でき、コードの名前変更や削除ができるのは裁定者のみです。二つの初期ラベルはオブジェクト形式を使い、オブジェクト形式のラベルは、色と短い定義を持つコードとして始まります。

annotation_task_name: Clinic Access Interviews
task_dir: .
output_annotation_dir: annotation_output/
data_files:
- data/interviews.json
item_properties:
  id_key: id
  text_key: text
user_config:
  allow_all_users: true
 
codebook_mode: extensible
 
annotation_schemes:
- annotation_type: span
  name: codes
  description: Highlight a passage and apply a code
  codebook: true
  labels:
  - name: access barriers
    color: "#4682b4"
    description: Anything the speaker names as standing between them and care they wanted.
  - name: cost concerns
    color: "#b44682"
    description: Money, insurance, or the fear of a bill.

qda_mode.codebook.mode は検証に合格します。Potato 2.13.1 は、誰が編集できるかを決める際に、このキーを読みません。QDA モードの下で open というデフォルトを変えるには、codebook_mode を設定してください。

誰がコードを変更できるか

ログイン済みのコーダーが何をできるかは、モードによって決まります。裁定者は、extensible と open モードで、すべての構造上の変更を行えます。fixed モードでは、コーダーも裁定者も、コードの追加、名前変更、色の変更、移動、削除ができません。管理者と裁定者は、それでもトレイの Curate セクションから、コードの統合と分割を行えます。

Potato は、クラウドソーシングの設定ではモードを fixed にロックし、設定がそれ以上を求めている場合は警告をログに記録します。Potato は、募集されたアノテーターが共有のコードブックを作り変えるのを防ぐために、このロックを適用します。このロックは、expert 以外の値を持つ crowdsourcing.provider、トップレベルの prolific: または mturk: ブロック、login.type: prolific または mturk をカバーします。認識されないプロバイダー名と、空のプロバイダー値も、モードをロックします。

crowdsourcing.provider: expert は、エキスパートが名前で招待されるため、要求されたモードを保ちます。login.type: url_direct だけの場合は、要求されたモードを保ち、警告をログに記録します。そのような調査のリンクを知っている人は誰でも、登録して、オープンなコードブックを編集できます。

2.13.1 では、変更の種類ごとに別々の経路があります。

トレイの追加ボックスは、トップレベルのコードを作成します。コードを親の下に置くには、POST または PATCH の parent_id フィールドを使います。

テキスト選択からのインビボ・コーディング

codebook: true と印の付いた span スキームでは、コーダーが一節を選択し、インビボのキーを押します。選択された語から取った名前（60 文字まで）で小さなコンポーザーが開き、「Create & code」がコードを追加し、その一節を新しいコードで一度にハイライトします。コーダーが名前を入力している間、似た名前の既存のコードがチップとして表示されます。チップを選んだコーダーは、cost concerns の隣に cost のようなほぼ重複したコードを作る代わりに、既存のコードを適用します。

モデルが提案する変更

モデルが共有のコードブックを直接変更することはありません。エージェントまたはソロモードのモデルは、POST /api/codebook/proposals と actor_kind: "model" で変更をステージングします。その変更は、「Merge «cost» into «cost concerns»」のような文として、Curate セクションで待機します。管理者または裁定者が、提案を確認または却下します。確認された提案は、人間の編集と同じ経路で実行され、変更ログではモデル由来としてマークされます。

コードの入れ子

parent_id を持つコードはその親の下に置かれ、親は別の親の下に置けます。コードを、そのコード自身の子孫の下に置くことになる移動は、エラーで失敗します。一つの親の下に同じ名前の二つ目のコードを追加することも、同じように失敗します。親を削除すると、その親の下のすべてのコードが削除されます。

トレイと /codebook は、ツリーを表示します。アノテーションフォームは、コードを、親が子より前に来るツリー順の一つのフラットなリストとして表示します。フォームの選択肢と保存されたアノテーションは、どちらもコードの名前だけを保持します。そのため、二つの親の下にある同じ名前は、フォーム上で二回現れ、後からその二つのコードを区別できません。コードの名前は、コードブック全体で一意に保ってください。

codebook の CSV エクスポートと .qdpx エクスポートは、どちらも 2.13.1 では、コードブックに基づくスキームのコードをフラットなリストとして書き出します。それらのコードでは、CSV の parent 列と color 列は空です。別のプログラムで必要なコードの階層は、そこで再構築するか、コードの名前に記録しなければなりません。

コードの変更が保存済みのコーディングに与える影響

Potato は、各コーディングを、コードの名前をラベルとして、コーダーの user_state.json に保存します。統合や分割によって、データベースから行が削除されることはありません。Potato は、各コードブックの変更をコードブックだけに適用し、保存済みのアノテーションを書き換えることはありません。

• コードの追加は、保存済みのコーディングを変えません。
• コードの名前変更は、その後のフォームを変えます。古い名前で保存されたコーディングは古い名前を保ち、エクスポートと一致度の統計は、それらのコーディングを古い名前の下に数えます。コーディングのラウンドが始まる前に名前を変更するか、影響を受ける抜粋を再コーディングしてください。
• コードの削除は、そのコードと、そのコードの下のすべてのコードをフォームから取り除きます。保存済みのコーディングは名前を保ち、変更ログは削除されたコードの名前を保持します。
• 統合は、元のコードをアーカイブします。アーカイブされたコードはフォームから外れ、そのコードの行と履歴はデータベースに残ります。元のコードで保存されたコーディングは、元のコードの名前を保ちます。
• コーダーによる分割は、一人のコーダーと、新規または既存の対象コードを指定します。この分割は、一つのコード名を別々のことに使った二人のコーダーのためのもので、指名されたコーダーの使用分だけを移すように設計されています。2.13.1 では、アノテーションフォームは、分割が移すコーダーごとのリンクを記録しません。そのため分割は、元のコードに子コードがない場合は常に、対象コードを作成し、すべてのコーダーについて元のコードをアーカイブします。保存済みのコーディングは、各コーダーが選んだ名前を保ちます。

Potato は、二つの方法でコーダーに変更を知らせます。第一に、新しいコードが追加される前に保存された抜粋のバナーが、新しいコードを示します。第二に、トレイの Review リストには、コーダーが、あらゆる種類の最新の変更より前に保存したすべての抜粋が入っています。リスト内の各抜粋には Go ボタンがあります。どちらのシグナルも閉じられ、Potato が再コーディングを強制することはありません。管理者または裁定者は、プロジェクト全体の同じリストを GET /api/codebook/admin/stale で見られます。

定義の編集には、別のカウンターがあります。コードの短い定義、定義、「Use when」、「Avoid when」のフィールドの編集は、意味上の改訂を上げ、Potato はその後に保存されるすべてのアノテーションに、意味上の改訂を記録します。アナリストは、その後、定義が変わる前と後に行われたコーディングを分けられます。/codebook のエディターで Minor edit (no re-review) にチェックを入れると、意味上の改訂を上げずに文言を保存します。2.13.1 の Review リストは、構造上の変更のみを追跡します。

信頼性のラウンドでは codebook_mode: fixed を設定してください。Potato は保存されたコードの名前に対して一致度を計算するため、ラウンドの途中で名前を変更されたコードは、二つのコードになるからです。アノテーター間一致度は、係数を扱います。/admin/iaa の一致度のタイムラインは、時間にわたる一致度に対して、各コードブックの改訂に印を付けます。一致度のドリフトは、タイムラインの読み方を説明します。

各コードの項目の型付きフィールド

各コードの項目は、型付きフィールドのリストです。/codebook は、すべてのコードのバージョン履歴、バージョン間の差分、古いバージョンを新しいバージョンとして保存する復元を備えた、全ページのエディターです。「Paste markdown」ボタンは、貼り付けられたコードブックの文章を見出しごとにフィールドに変換し、パーサーが認識しないセクションについては、ユーザーに型を選ぶよう求めます。同じコードを二人が同時に保存しても、互いを上書きしません。二番目の保存は失敗し、突き合わせるための現在のテキストを返します。

コードブック全体には、コードの外側に、Preamble、General instructions、Background、How codes are used downstream という題名の四つのセクションがあります。トレイは、各コードの短い定義を、二行に収めて表示します。コードに短い定義がない場合、トレイは代わりに完全な定義を表示します。

ディスティラーは、選ばれたフィールドを、Potato が ICL ラベリングのプロンプトに追加するテキストに変換し、コードブックの変更のたびにそのテキストを再構築します。GET /api/codebook/distilled は、モデルが現在受け取っているテキストを返します。フィールドを選ぶには、上の設定に codebook.distiller ブロックを追加します。

codebook:
  distiller:
    include: [definition, use_when, avoid_when, example]
    procedure: concat

CLI による初期化と移行

potato codebook は、codebook: true のすべてのスキームの各ラベルのうち、コードブックにまだないもののコードを追加し、既存のコードには手を触れません。

potato codebook config.yaml

このコマンドは、作成されたコードの数と、すでに存在していたコードの数を表示します。CLI が作成したコードは、CLI がプロジェクト名、親、コード名から各 ID を計算するため、どのマシンでも同じ ID になります。プロジェクトのコピー間で ID を一致させる必要がある場合は、最初のサーバー起動の前に CLI を実行してください。サーバーが初期化したコードには、ランダムな ID が付くためです。CLI は名前のみをコピーします。オブジェクト形式のラベルの色と定義は、サーバーの最初の起動時の初期化を通じてのみ、コードブックに届きます。

サーバーは空のコードブックしか初期化しないため、すでにコードを持つコードブックに新しい YAML のラベルを追加するには、CLI を使います。書き込まずにプレビューするには、モジュールを直接実行します。2.13.1 では、potato codebook --dry-run はフラグを無視して、コードを書き込みます。

python -m potato.codebook_cli config.yaml --dry-run

API

すべてのルートは /api/codebook の下にあり、ログイン済みのセッションが必要です。管理ルートは、管理者または裁定者を受け付けます。

定義のエディターは、GET /api/codebook/document、GET と PUT /api/codebook/blocks、POST /api/codebook/parse、GET /api/codebook/history、GET /api/codebook/history/<id>、POST /api/codebook/restore、GET /api/codebook/distilled を使います。QDA モードの下では、/qda/codebook がコードブックの読み取り専用ビューを返します。

コードブックのエクスポートと変更履歴

codebook エクスポートは、コードブックスキームごとにコードごとに一行を持ち、列が schema、annotation_type、code、parent、description、color、n_uses である codebook.csv を書き出します。このエクスポートは、コードブックのデータベースを読み取ります。コーディング中に追加されたコードは含まれ、統合されたコードは除かれます。description には、コードの短い定義、またはコードに短い定義がない場合は完全な定義が入ります。n_uses は、保存されたコーディングを名前で数えます。コードブックにもう存在しない名前で保存されたコーディングは、どの行にも数えられません。

python -m potato.export -c config.yaml --format codebook -o ./export/

quotation_report エクスポートは、コーディングされたすべての箇所を、その箇所のコードとともに一覧します。qdpx エクスポートは、コードとコーディングを別の QDA プログラムに渡します。QDA モードは両方のエクスポートを扱い、エクスポート形式は列を一覧します。

履歴は project.sqlite に残ります。codebook_change テーブルは、すべての名前変更、色の変更、移動、削除、統合、分割、そして確認または却下された提案を、古い値と新しい値、行為者、行為者が人間かモデルか、改訂とともに記録します。2.13.1 では、PATCH や DELETE を通じて行われた名前変更、色の変更、移動、削除は、行為者 system でログに記録され、コードの追加は、ログではなく、作成者のユーザー名とともに codes テーブルに現れます。GET /api/codebook/admin/changes は、変更ログを JSON として返します。

codebook_snapshot は、すべての定義のすべての保存されたバージョンを保持し、codebook_revision_history は、各改訂がいつ行われたかを記録します。プロジェクトのスナップショットと、potato deploy pull のアーカイブは、どちらも project.sqlite を含みます。どちらのバンドルも、方法のセクションのための、コードブックの監査証跡です。

同梱の例を、Potato のチェックアウトから実行します。

python potato/flask_server.py start examples/advanced/codebook-example/config.yaml -p 8000

この例は、診療所へのアクセスに関する五つの患者のコメントを、四つのテーマのオープンな multiselect コードブックでコーディングします。examples/advanced/codebook-document-example/ は、ディスティラーのブロックを追加します。その例で /codebook を開くと、定義のエディターを見られます。

関連資料

• QDA モード。メモ、ケース、検索とともにコードブックを扱います
• メモ。コードの隣の分析ノートについて
• 定性コードブックの開発。定義の書き方と、チームでのコードの改訂について
• 質的研究におけるコーダー間信頼性。一致度をいつ報告するかと、どの係数を使うかについて
• 一致度のドリフト。コードブックの改訂に対する、時間にわたる一致度について

参考文献

MacQueen, K. M., McLellan, E., Kay, K., & Milstein, B. (1998). Codebook Development for Team-Based Qualitative Analysis. CAM Journal, 10(2), 31-36. https://doi.org/10.1177/1525822X980100020301

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