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、Microsoft 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 < 计数 < 值的单元格	询问 / 协议	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、电子邮件、姓名、令牌、引用者 URL、如非必要则精确时间戳）并说明你已这样做。
2. 构建一个编码手册：变量、问题文本、类型（单选题、多选题、李克特 k 点题、数值题、开放题、矩阵行题、元数据题）、值标签、量表方向与极性、反向题、缺失/“不知道”代码、筛选条件（谁看到了该问题）。
3. 根据标签确定量表方向和反向题，切勿根据假设。如果标签缺失，请询问。
4. 重新编码为分析文件；在日志中保留映射关系。

阶段 2 - 数据清洗

标记、记录，然后才决定。切勿静默删除。

• 完成问卷与部分完成问卷；定义分析样本（默认：完成问卷；部分完成问卷仅针对其回答的题目，如果用户同意）。按页面划分中途中止情况。
• 重复项（相同令牌，或具有几乎相同时间戳的相同回答向量）。
• 速度过快者：总时长 < ratio x 中位数。矩阵题（>= min_items 个项目）中的直线作答者。只有在向用户展示计数和模式后才排除；当 n 较小时，切勿仅凭一个标志排除。
• 每个项目的项目无应答；标记 > 10% 的项。
• 超出范围的值、筛选违规、不可能的组合。

输出：数据清洗日志（检查项、计数、决定、原因）。

阶段 3 - 推断框架与加权

阅读 references/methods.md 的第 1 节和第 7 节。设计决定了哪些不确定性陈述是合理的：

情况	报告内容
已知小总体的普查或接近普查（n/N > 5%）	含有限总体校正（FPC）的置信区间 加上 关键指标的最坏情况无应答边界。将结果表述为“在受访者中”，除非无应答检查支持概化。
概率样本	标准置信区间（如果 n/N > 5% 则使用 FPC）；如果设计有不平等的选择概率，则使用设计权重。
自选择 / 开放链接 / 便利样本	无法进行总体推断。描述性描述份额；如果显示置信区间，则仅作为“统计精度”，并附上明确警告。

加权仅遵循 weighting.mode（基本原则 2）。如果使用了权重：并排报告加权和未加权的关键指标、Kish 设计效应和有效 n（kish_deff、effective_n），并对置信区间和检验使用有效 n。

阶段 4 - 所有答案的分布

• 每个项目，每个数字都附有其基数（n），该基数是经过筛选和排除后的。
• 单选题：计数和份额；关键指标的置信区间（Wilson 法，如适用则使用 FPC）。
• 李克特题：先展示完整分布，然后是顶端项 / 底端项及其置信区间、中位数。均值 +/- 标准差仅作为补充，且仅针对 >= 5 点的项目或多项目量表。
• 多选题：每个选项的受访者份额；总计超过 100%。
• 数值题：先展示中位数和四分位距，然后是均值/标准差；检查异常值。
• 舍入：当 n < 200 时，使用整数百分比。总计可能不等于 100%——请说明一次。
• 关键指标与 50%（或其他参考值）的比较仅在使用 mdd_one_proportion 时进行：如果份额落在 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 节）：分类变量使用卡方 / Fisher 精确检验，有序变量使用 Mann-Whitney / Kruskal-Wallis 检验，度量尺度得分使用 Welch 检验。始终附带效应量及其标签；单独的 p 值永远不能作为发现。
4. 横幅表（crosstabs.mode: banner）：对每个项目 x 允许的变量使用 banner_table() / format_banner()——列百分比、基数行、显著性字母（字母表示该列的份额显著高于带有该字母的另一列），这些字母基于在行内调整后的 p 值。横幅带是探索性的：在将差异写入文本之前，需使用 Benjamini-Hochberg 方法对横幅带内的所有 p 值进行整体调整（对返回的 tests 使用 p_adjust）。横幅表放入附录；只有稳健的差异（经过带内整体调整后仍显著 且 至少具有小效应）才写入文本。
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 项短量表，alpha >= .60 且附有说明）。

阶段 8 - 开放题

参见 references/methods.md，第 6 节。阅读每一个答案，构建归纳编码框架，允许多重编码进行编码，将主题报告为“n 名受访者中的 x 人提到了……”。对 >= 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）：仅根据统计标准对项目或主题进行排名——不赞成答案的份额、在最坏情况边界下的稳健性

…

[为翻译截断]