정성 코딩을 위한 공유 코드북

Potato의 코드북은 프로젝트의 코더가 적용하는 코드의 목록입니다. Potato는 코드북을 YAML 구성이 아니라 프로젝트 데이터베이스에 보관합니다. 스킴은 codebook: true로 참여하며, 그러면 스킴의 옵션이 코드북에서 나옵니다. 코더는 구성을 편집하거나 서버를 다시 시작할 필요 없이 세션 도중에 코드를 추가할 수 있습니다. 코드는 상위 코드 아래에 둘 수 있고, 각 코드의 항목에는 정의, 포함 및 제외 규칙, 예시를 포함한 유형이 있는 필드가 있습니다. Potato는 저장되는 모든 어노테이션에 저장 시점에 적용 중이던 코드북 수정본을 찍습니다. 코드북은 Potato 2.6.0에서 QDA 모드와 함께 도입되었으며 표준 어노테이션, 솔로 모드, QDA 모드에서 작동합니다.

질적 연구에서 코드북은 팀이 적용하는 코드를 나열하고 각 코드를 언제 적용하는지 말합니다. MacQueen et al. (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 목록은 구조적 변경만 추적합니다.

Potato는 저장된 코드 이름에 대해 일치도를 계산하고 라운드 도중에 이름이 바뀐 코드는 두 개의 코드가 되므로, 신뢰도 라운드에는 codebook_mode: fixed를 설정하세요. 어노테이터 간 일치도는 계수를 다룹니다. /admin/iaa의 일치도 타임라인은 시간에 따른 일치도에 대해 각 코드북 수정본을 표시합니다. 일치도 드리프트는 타임라인을 읽는 방법을 설명합니다.

각 코드 항목의 유형 필드

각 코드의 항목은 유형이 있는 필드의 목록입니다. /codebook은 모든 코드에 대한 버전 이력, 버전 사이의 diff, 이전 버전을 새 버전으로 저장하는 복원 기능을 갖춘 전체 페이지 편집기입니다. "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는 프로젝트 이름, 상위 코드, 코드 이름에서 각 ID를 계산하므로, CLI가 만든 코드는 모든 머신에서 같은 ID를 갖습니다. 프로젝트 사본 사이에 ID가 일치해야 한다면 서버가 시드한 코드는 무작위 ID를 받으므로 서버를 처음 시작하기 전에 CLI를 실행하세요. 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

구현 세부 사항은 소스 문서를 참조하세요.