benno-mueller/survey-analysis

調查分析

將原始問卷匯出結果轉化為專業調查研究人員會認可的發現： 每個數字都有其樣本基礎，不確定性被誠實陳述，差異僅在其成立時才被聲稱，且沒有任何受訪者可以被識別。

此技能與工具和主題無關。針對特定調查的一切皆為參數（第0階段），而非硬編碼的假設。

基本規則（適用於每項調查，並凌駕於任何其他對於「洞見」的要求）

1. 僅限統計解讀。 描述數據顯示的內容：規模、精確度、穩健性、差異、一致性。切勿提供關於結果為何如此的解釋、原因、動機或假設——即使有所保留（例如「可能是因為……」、「這可能表示……」）。受訪者自己陳述的理由（開放式答案）可以作為受訪者的說法來報告。
2. 預設為等權。 每份回應計算一次。僅在調查設計要求（例如抽樣比例不均、數據中包含加權變數）或參數指定時，才使用加權。切勿自行加權；應將不平衡視為限制條件來報告。
3. 僅在允許的情況下進行交叉表和子群體報告。 結果是否可以被細分、由哪些變數細分、以及在何種限制下進行，均由調查擁有者決定（crosstabs、subgroup_reports、anonymity 參數）。若未獲得許可：僅提供總計。
4. 所有計算均在程式碼中進行（使用 Python 搭配 pandas/scipy，或 R）。切勿以文字描述估計數字。針對數據副本進行操作；切勿修改使用者的原始數據。

捆綁檔案

檔案	使用於
references/methods.md	第3-9階段：公式、檢定選擇、加權、揭露控制、完整範例
references/reporting.md	第10階段：管理摘要、行動領域、結構、措辭、圖表
references/data-sources.md	第1階段：匯出格式（LimeSurvey, MS Forms, Google Forms, SurveyMonkey, SPSS/R）
scripts/survey_stats.py	所有階段：經過測試的輔助工具——含有限母體校正的信賴區間、最壞情況無回應邊界、檢定與效果量、p值調整、帶有顯著性字母的旗標表、最小可檢測差異、反覆加權與設計效果、群組揭露計畫、細胞抑制、Cronbach's alpha、品質標誌
assets/survey-config.template.yaml	第0階段：參數檔案

如果僅安裝了此 SKILL.md，則末尾的核心規則部分是最低需求；請自行在程式碼中實現公式。

---

第0階段 - 參數

尋找已填寫的 survey-config.yaml（模板在 assets/ 中）。否則收集以下參數。可以從數據或檔案中讀取的事實，請自行讀取；決策屬於使用者。 在一輪中提出未確定的決策問題（最多4個問題），每個問題附上你建議的預設值。如果無人回答，則使用預設值並在報告的「假設」下列出。預設值刻意設為限制性：不允許細分，不加權。

參數	含義	來源	預設值
population.definition	調查對象是誰	詢問	- (必填)
population.size_N	目標母體大小	詢問	null = 未知/非常大
population.design	census、simple_random、stratified、quota、self_selected	詢問	self_selected (最保守)
population.known_margins	已知每個特性的母體計數	詢問 / 檔案	無
fieldwork.invited / completes / partials / ineligible	結果計數	數據 + 詢問	completes = 有提交日期的記錄
purpose	describe、compare_groups、test_hypotheses、track_waves、benchmark	詢問	describe
hypotheses	預先指定的統計比較（驗證性）	詢問	無 -> 所有比較皆為探索性
crosstabs.mode	none、specified（列出變數）、banner（完整表格列）	詢問	none
crosstabs.variables	可以使用的細分變數	詢問	[]
crosstabs.forbidden_combinations	禁止交叉的變數對	詢問	所有人口統計變數的兩兩組合
subgroup_reports.enabled	每個單位（站點、部門等）的獨立報告	詢問	false
subgroup_reports.unit_variable / min_n / min_response_rate / compare_to_total	單位報告的限制	詢問	- / anonymity.min_group_n / 無 / true
anonymity.min_group_n	任何報告群體的最低受訪者數	詢問 / 協議	5
anonymity.min_cell_n	抑制計數在 0 < count < 此值的儲存格	詢問 / 協議	null (關閉)
weighting.mode	none、design（數據中的加權變數）、raking	調查設計 / 參數	none
weighting.variable / margins / trim	design / raking 的細節	參數	- / - / [0.3, 3]
analysis.confidence_level / alpha / power		預設值	0.95 / 0.05 / 0.80
analysis.multiple_testing	holm、bh、none	預設值	holm 用於驗證性，bh 用於旗標/探索性
analysis.dont_know / dont_know_codes	處理「不知道 / 未回答」	預設值	從樣本基礎中排除，分別報告
analysis.likert_top_box	被計為同意的類別數	預設值	4-6點量表為2，7點以上量表為3
analysis.item_polarity	每個項目的有利極性	編碼簿 + 詢問	根據標籤
analysis.quality_rules	快速作答比例，直線作答最少題項數	預設值	0.4 x 中位數；5題
open_text.quotes	none、paraphrase、anonymized_verbatim	詢問	paraphrase
recommendations.mode	none、action_fields、action_fields_with_measures	詢問	action_fields
recommendations.measures	使用者提供的、要對應到發現項目的措施	詢問	[]
benchmarks	早期波次 / 具有完全相同措辭的外部研究	詢問	無
output.audience / format / language		詢問 / 對話	lay / 環境預設 / 使用者語言

第0階段以一個簡短的參數摘要結束，供使用者修正。

第1階段 - 數據攝入與編碼簿

閱讀 references/data-sources.md 以了解目前要處理的匯出格式。然後：

1. 載入數據；立即刪除直接識別符（IP、電子郵件、姓名、令牌、參照網址、不必要的精確時間戳），並說明你已這麼做。
2. 建立編碼簿：變數、問題文字、類型（單選、複選、李克特k點量表、數值、開放式文字、矩陣列、後設資料）、數值標籤、量表方向與極性、反向題項、缺失值 /「不知道」代碼、篩選條件（誰被顯示了該問題）。
3. 根據標籤決定量表方向和反向題項，切勿根據假設。如果缺少標籤，請詢問。
4. 重新編碼為分析檔案；在日誌中保留對應關係。

第2階段 - 數據清理

標記、記錄，然後再決定。切勿無聲刪除。

• 完成數 vs. 部分完成數；定義分析樣本（預設：完成數；僅針對已完成題項的部分完成數，如果使用者同意）。按頁面檢查中斷點。
• 重複項（相同的令牌，或近乎相同的時間戳且答案向量相同）。
• 快速作答者：總填答時間 < ratio x 中位數。反向矩陣中存在 >= min_items 個題項的直線作答者。僅在向使用者展示計數和模式後才排除；當 n 很小時，切勿僅根據一個標記就排除。
• 每個題項的項目無回應；標記 > 10 % 的題項。
• 超出範圍的值、篩選條件違規、不可能的組合。

輸出：一個數據清理日誌（檢查、計數、決定、原因）。

第3階段 - 推論框架與加權

閱讀 references/methods.md 的第1和第7節。研究設計決定了哪些不確定性陳述是合理的：

情況	應報告的內容
已知、小型母體的普查或近乎普查 (n/N > 5 %)	使用有限母體校正（FPC）的信賴區間，以及關鍵數字的最壞情況無回應邊界。除非無回應檢查支持推論，否則將結果表述為「在受訪者中」。
機率樣本	標準信賴區間（若 n/N > 5 % 則使用 FPC）；若設計有不等的選擇機率，則使用設計加權。
自選 / 開放連結 / 方便樣本	不做母體推論。僅描述性分享；如果顯示信賴區間，僅作為「統計精確度」，並附上明確的警告。

僅根據 weighting.mode 進行加權（基本規則2）。如果使用了加權：並排報告加權和未加權的關鍵數字、Kish 設計效果和有效樣本數（kish_deff、effective_n），並對信賴區間和檢定使用有效樣本數。

第4階段 - 所有答案的分佈

• 每個題項、每個數字都應附上其樣本基礎（n），考慮過濾和排除之後。
• 單選：計數和比例；對關鍵數字使用信賴區間（Wilson 方法，若適用則加上 FPC）。
• 李克特量表：先提供完整分佈，然後提供頂盒 / 底盒及其信賴區間、中位數。僅在 >= 5點量表或多題項量表的情況下，才補充平均值 +/- 標準差。
• 多選：每個選項的受訪者比例；總和超過 100 %。
• 數值：先提供中位數和四分位距，然後是平均值/標準差；檢查異常值。
• 四捨五入：當 n < 200 時，使用整數百分比。總和可能不等於 100 % —— 說明一次。
• 僅在考慮 mdd_one_proportion 後，才將關鍵數字與 50%（或其他參考值）進行比較：比例在 50% 的信賴區間內即視為「大約一半」。

第5階段 - 交叉表與顯著性檢定

由 crosstabs.mode 控制。若為 none，則完全跳過此階段，並在方法框中說明。

1. 先進行揭露控制。 僅使用 crosstabs.variables；切勿交叉 forbidden_combinations。對每個細分變數執行 reportable_groups()：低於 anonymity.min_group_n 的群組將被刪除，當刪除的其餘部分可以從總計推導出來時，則進行二次抑制。如果設定了 anonymity.min_cell_n，則套用。
2. 檢定力。 對每個細分計算最小可檢測差異（mdd_two_proportions，80% 檢定力）。報告它，以便正確解讀「無顯著差異」（「低於 x 個百分點的差異無法被檢測到」）。
3. 檢定。 根據數據類型選擇（references/methods.md，第3節）：類別數據使用卡方檢定 / 費雪精確檢定，順序數據使用曼-惠特尼 U 檢定 / 克-瓦二氏檢定，量尺分數使用 Welch t 檢定。務必附上效果量及其標籤；僅 p 值本身永遠不是一個發現。
4. 旗標表（crosstabs.mode: banner）：對每個題項 x 允許的變數使用 banner_table() / format_banner()——欄位百分比、樣本基礎列、顯著性字母（字母表示該欄位的比例顯著高於帶有該字母的其他欄位），字母基於在該列內調整過的 p 值。該旗標是探索性的：在將一個差異寫入文字之前，請先對整個旗標的所有 p 值進行 Benjamini-Hochberg 調整（p_adjust 應用於返回的 tests）。旗標表放入附錄；只有穩健的差異（在整個旗標調整後仍顯著且至少具有小的效果量）才放入正文。
5. 區分驗證性結果（預先指定的 hypotheses）和探索性結果。
6. 不顯著的差異是「沒有可靠的差異」，絕非趨勢。

第6階段 - 子群體報告

僅在 subgroup_reports.enabled 時執行。對於 unit_variable 的每個單位：

1. reportable_groups(sizes, min_n, total_published=True, invited, min_response_rate) 決定哪些單位獲得報告。其餘規則很重要：如果一個小單位被隱藏，但所有其他單位和總計都被發布，則其結果可以透過減法計算出來——該函數會進一步隱藏單位，直到被隱藏的其餘部分本身 >= min_n。列出被隱藏的單位及其原因（不含其數據）給調查擁有者，而非在已發布的報告中。
2. 每個單位報告使用與主報告相同的結構、該單位自己的樣本基礎和信賴區間（使用該單位的邀請數作為 N 進行 FPC），以及——如果 compare_to_total 為真——則使用總計作為參考。除非 crosstabs 允許該變數，否則不要將單位彼此進行比較。
3. 在單位報告內部，不得進一步細分，除非明確允許且所有群組都通過了門檻。

第7階段 - 量表與指標

僅針對設計為量表（或經過驗證的工具）的題項集。重新編碼反向題項，計算 Cronbach's alpha（如果因子分析套件可用，則計算 McDonald's omega）、項目-總分相關、刪除項目後的 alpha。僅當 alpha >= .70（對於3題項短量表，>= .60，並附上警告）時才構建量表分數。

第8階段 - 開放式答案

請參閱 references/methods.md 第6節。閱讀每個答案，建立歸納式編碼架構，允許對同一個答案進行多重編碼，將主題報告為「x 位受訪者中有 n 位提到了……」。對 >= 20% 的答案進行第二次編碼，報告一致性。說明編碼是由 AI 作為單一編碼員完成的。引用僅根據 open_text.quotes 的允許，並移除任何可識別身份的資訊。報告受訪者所寫的內容；不要添加你自己的解釋。

第9階段 - 無回應與代表性

• 回覆率（RR1 / RR2，response_rates()），整體及按已知群組劃分。
• 將受訪者組成與 known_margins 進行比較（適配度檢定）。群組間回覆率差異超過 15 個百分點，應作為限制條件報告（如果允許子群體報告，則按群組報告關鍵數字）。除非 weighting.mode 指定，否則不加權。
• 項目無回應模式；如果有時間戳，比較早期與後期受訪者。
• 明確總結結果適用於誰以及有哪些限制。

第10階段 - 解讀、管理摘要與報告

閱讀 references/reporting.md。

• 解讀 = 僅限統計解讀（基本規則1）：有多大、多精確、多穩健（信賴區間、最壞情況邊界）、在允許的群體間一致性如何、與相同措辭的基準比較如何。
• 管理摘要（第一頁）：3-7 個關鍵發現，附上 n 值和不確定性，然後是行動領域。
• 行動領域（recommendations.mode）：僅根據統計標準對事項或主題進行排序——不滿意答案的比例、在最壞情況邊界下的穩健性。

…

[翻譯截斷]