# QeDataSimulater **Repository Path**: StarsPython/qe-data-simulater ## Basic Information - **Project Name**: QeDataSimulater - **Description**: 根据调查数据文本和相关配置生成随机模拟样本数据 - **Primary Language**: Python - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-30 - **Last Updated**: 2026-02-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # QeDataSimulater **问卷模拟数据生成与检验工具** —— 根据问卷结构与研究提纲中的预期统计结论，生成符合设定特征的初中生英语学习焦虑与策略量表模拟数据，并可自动检验数据是否满足预期。 --- ## 一、项目简介 本项目面向教育测量与实证研究场景，主要完成： 1. **解析问卷结构**：从《初中生英语课堂学习焦虑量表》与《初中生英语学习策略使用量表》的文本中提取维度、题项、选项与计分方式，并以结构化 JSON 保存。 2. **配置驱动生成**：基于研究提纲中的“预期统计结论”（如焦虑/策略总分均值与标准差、焦虑与策略的负相关、高/低焦虑组在策略使用上的差异、信度等），在 `config/` 中维护一份 YAML 配置；程序根据该配置生成指定样本量的模拟数据。 3. **数据生成**：使用多元正态与总分分配算法，生成同一批被试在焦虑量表（33 题）与策略量表（50 题）上的作答，保证总分与维度得分满足预设均值、标准差及焦虑–策略相关系数，并可引入少量缺失值以贴近真实问卷；**分别输出两份问卷的数据文件**，文件名采用中文（与量表名称一致），每份同时支持 CSV 与 xlsx。 4. **数据检验**：对生成结果进行描述统计、Pearson 相关、高/低焦虑组独立样本 t 检验、Cronbach's α 等分析，并与配置中的预期及容差对比，输出是否通过，用于**确认模拟数据是否符合预期结论与数据特征**。 5. **数据分析报告**：在已生成数据基础上实现初级数据分析，按《提纲》第四部分「研究结果与分析」模板计算全部 [X] 占位符，并生成图表，输出 **模拟问卷数据分析报告**（Markdown，含 6 张图）。 适用于：开题/答辩前需要“与预期结论一致”的示例数据、方法学演示、统计分析流程验证等。 --- ## 二、功能概览 | 功能 | 说明 | |--------------|------| | 问卷结构管理 | `data/` 下 JSON 定义焦虑量表（4 维度、33 题）与策略量表（3 维度、50 题）、选项与计分。 | | 模拟参数配置 | `config/simulation_config.yaml` 中配置样本量、男女比例、各维度/总分均值与标准差、相关、组间差异、信度及检验容差。 | | 一键生成 | 运行 `main.py` 或 `src.generate_simulated_data`，分别输出两份问卷的中文命名 CSV/Excel 至 `results/`。 | | 自动检验 | 生成后自动（或单独）运行 `src.validate_simulated_data`，对照配置做均值、标准差、相关、t 检验、α 等检验并打印报告。 | | 数据分析报告 | 运行 `src.questionnaire_data_analysis`，计算提纲第四部分所有统计量，填补 [X]，生成含图表的 Markdown 报告至 `reports/`。 | | 可扩展性 | 调整样本量、分布参数、容差等只需改配置文件，无需改代码。 | --- ## 三、项目结构 ``` qe-data-simulater/ ├── README.md # 本说明 ├── LICENSE ├── pyproject.toml # 项目与依赖（uv / pip 通用） ├── requirements.txt # pip 安装时的依赖列表 ├── main.py # 入口：生成 + 检验 + 数据分析报告 ├── run_gui.py # GUI 启动入口（供打包 exe 使用） ├── questionnaire_gui.spec # PyInstaller 打包配置 ├── build_exe.bat # Windows 打包脚本 ├── build_exe.ps1 # PowerShell 打包脚本 │ ├── config/ # 配置目录（与数据、源码分离） │ └── simulation_config.yaml # 样本、量表预期、相关、组间差异、信度、检验容差 │ ├── data/ # 问卷结构及静态数据 │ ├── questionnaire_anxiety_structure.json # 焦虑量表：维度、题号、题目、选项、计分 │ └── questionnaire_strategy_structure.json # 策略量表：同上 │ ├── src/ # 源码 │ ├── __init__.py │ ├── generate_simulated_data.py # 读取 config + data，生成模拟数据并写入 results │ ├── validate_simulated_data.py # 读取 config + results 中 CSV，做统计检验并报告 │ ├── questionnaire_data_analysis.py # 基于 results 数据计算统计量，生成提纲第四部分分析报告 │ ├── gui.py # Tkinter 图形界面：编辑配置、保存/另存为、一键运行、打开结果/报告目录 │ └── paths.py # 路径解析：开发时用项目根，打包 exe 后用 exe 所在目录 │ ├── results/ # 生成结果（规范输出目录，中文文件名） │ ├── README.txt # 结果目录说明 │ ├── 初中生英语课堂学习焦虑量表.csv / .xlsx │ └── 初中生英语学习策略使用量表.csv / .xlsx │ ├── reports/ # 数据分析报告 │ ├── 模拟问卷数据分析报告.md # 提纲第四部分完整分析报告（含统计量与 [X] 填空） │ └── figures/ # 报告附图 │ ├── 01_焦虑水平分布.png │ ├── 02_焦虑各维度均分.png │ ├── 03_策略使用水平分布.png │ ├── 04_策略各维度均分.png │ ├── 05_焦虑与策略相关性.png │ └── 06_高低焦虑组策略对比.png │ └── docs/ # 文档与原始问卷/提纲 ├── 初中生英语课堂学习焦虑量表.md ├── 初中生英语学习策略使用量表.md └── 提纲.md # 研究提纲与预期结论来源 ``` **目录约定**： - **config/**：所有“可调参数”与“预期结论、检验容差”，仅 YAML，便于版本管理与协作。 - **data/**：问卷结构（题号、维度、题干等）及只读数据，与配置分离。 - **results/**：程序生成的 CSV/Excel，不提交大文件时可被 .gitignore。 - **src/**：业务逻辑，仅依赖 config 与 data 路径，不写死数值。 --- ## 四、环境要求 - **Python**：3.10+（推荐 3.12；`pyproject.toml` 中为 `>=3.14` 时以本地解释器为准）。 - **依赖**：numpy、pandas、scipy、pyyaml、openpyxl、matplotlib（见 `pyproject.toml` / `requirements.txt`）。 --- ## 五、安装 ### 方式一：使用 uv（推荐） 1. 安装 [uv](https://docs.astral.sh/uv/)。 2. 在项目根目录执行： ```bash uv sync ``` 将根据 `pyproject.toml` 创建虚拟环境并安装全部依赖。 ### 方式二：使用 pip ```bash pip install -r requirements.txt ``` ### 打包为 exe（可选） 需先安装 PyInstaller（开发依赖），再在项目根目录执行打包： ```bash # 使用 uv 安装打包依赖 uv sync --extra dev # 执行打包（Windows） pyinstaller questionnaire_gui.spec # 或直接运行脚本 build_exe.bat # 或 PowerShell: .\build_exe.ps1 ``` 打包完成后，在 `dist/` 下生成 **问卷模拟数据生成.exe**（单文件）。将 exe 放到任意目录运行即可；首次运行会在 exe 同目录自动生成 `config/`（内含默认配置）、`results/`、`reports/`，数据与报告均保存在该目录，便于携带与分发。 --- ## 六、配置说明 ### 6.1 模拟与预期结论：`config/simulation_config.yaml` 该文件决定“生成什么样的数据”以及“检验时预期与容差”： - **sample**：样本量 `N`、男生比例 `male_ratio`、缺失率 `missing_rate`。 - **anxiety_scale**：焦虑量表总分均值/标准差、四个维度（课堂表达、考试、交际、学习压力）的均值/标准差、高/低焦虑划分分数线、性别差异预期等。 - **strategy_scale**：策略量表总分与三个维度（认知、元认知、社交情感）的均值/标准差。 - **correlation**：焦虑总分与策略总分的预期相关系数及 p 值；可选维度间相关。 - **group_difference**：高焦虑组与低焦虑组在策略使用上的预期均分及 t 检验 p 值。 - **reliability**：焦虑量表与策略量表的 Cronbach's α 预期。 - **validation**：检验阶段使用的容差（如总分均值允许误差、相关系数允许误差、α 下限等）。 修改该文件即可改变生成目标与检验松紧，无需改代码。 ### 6.2 问卷结构：`data/*.json` - **questionnaire_anxiety_structure.json**：焦虑量表名称、总题数、维度与题号映射、每题题干（Q1–Q33）、选项、计分、反向题列表。 - **questionnaire_strategy_structure.json**：策略量表同上（Q1–Q50），维度为认知、元认知、社交情感。 生成与检验模块均通过读取这些 JSON 确定题数、维度名与列名，保证一致。 --- ## 七、使用方法 ### 7.1 图形界面（推荐：调参与运行） 使用 Tkinter 图形界面编辑配置、保存/另存为 YAML、一键运行生成+检验+报告，并打开结果/报告目录： ```bash python main.py --gui # 或 python main.py -g # 或直接 python -m src.gui ``` 界面包含标签页：**样本**、**焦虑量表**、**策略量表**、**相关**、**组间差异**、**信度**、**检验容差**、**运行选项**（随机种子、是否检验、是否生成报告）。启动时自动加载 `config/simulation_config.yaml`；可修改后“保存”或“另存为”，点击“运行”会先保存当前配置再执行生成→检验→报告，运行日志显示在下方文本框，结束后可点击“打开结果目录”“打开报告目录”。 ### 7.2 一键生成并检验（命令行） ```bash python main.py ``` 将依次： 1. 读取 `config/simulation_config.yaml` 与 `data/` 下两份问卷结构。 2. 按配置生成 300 名被试的焦虑与策略作答，**分别**写入两份中文命名的文件（每份同时生成 CSV 与 xlsx）： - `results/初中生英语课堂学习焦虑量表.csv`、`results/初中生英语课堂学习焦虑量表.xlsx` - `results/初中生英语学习策略使用量表.csv`、`results/初中生英语学习策略使用量表.xlsx` 3. 自动对生成结果运行检验模块（会读取上述两份 CSV 并按 学生ID 合并），在控制台打印**检验报告**（各项预期 vs 观测、是否通过）。 4. 自动运行数据分析模块，基于生成数据计算提纲第四部分「研究结果与分析」中的全部统计量（焦虑/策略总分及维度、高/中/低焦虑人数与占比、性别 t 检验、Cronbach α、KMO、Bartlett、Pearson 相关、高/低焦虑组策略差异等），填补所有 [X] 占位符，生成 6 张图表，输出 `reports/模拟问卷数据分析报告.md`。 ### 7.3 仅生成数据 ```bash python -m src.generate_simulated_data ``` 只执行数据生成，不运行检验。输出仍为 `results/` 下两份问卷的中文命名 CSV 与 xlsx。 ### 7.4 仅生成数据分析报告 对已有 `results/` 下两份问卷 CSV 做初级数据分析，生成提纲第四部分完整报告： ```bash python -m src.questionnaire_data_analysis ``` 将输出 `reports/模拟问卷数据分析报告.md` 及 `reports/figures/` 下 6 张 PNG 图。 ### 7.5 仅运行检验 对已有 `results/初中生英语课堂学习焦虑量表.csv` 与 `results/初中生英语学习策略使用量表.csv` 做检验（检验模块会按 学生ID 合并后计算相关、组间差异等）： ```bash python -m src.validate_simulated_data ``` 检验模块会： - 从 `results/` 加载两份中文命名的问卷 CSV，按 学生ID 合并。 - 加载 `config/simulation_config.yaml` 中的预期与 `validation` 容差。 - 计算样本量、性别比例、焦虑/策略总分均值与标准差、焦虑–策略 Pearson 相关及 p 值、各维度均值、高/低焦虑组策略均分及独立样本 t 检验、Cronbach's α。 - 逐项与配置对比，标记 ✓/✗ 并汇总“总体是否通过”。 --- ## 八、输出说明 ### 8.1 生成文件（中文命名，每份问卷各一份 CSV + 一份 xlsx） | 文件 | 格式 | 内容概要 | |------|------|----------| | `results/初中生英语课堂学习焦虑量表.csv` | CSV（UTF-8-BOM） | 焦虑量表：学生ID、性别、焦虑_Q1…Q33、四维度、焦虑_总分。 | | `results/初中生英语课堂学习焦虑量表.xlsx` | Excel | 同上。 | | `results/初中生英语学习策略使用量表.csv` | CSV（UTF-8-BOM） | 策略量表：学生ID、性别、策略_Q1…Q50、三维度、策略_总分。 | | `results/初中生英语学习策略使用量表.xlsx` | Excel | 同上。 | ### 8.2 数据列结构 **焦虑量表文件**：学生ID、性别、焦虑_Q1 … 焦虑_Q33、课堂表达焦虑、考试焦虑、交际焦虑、学习压力焦虑、焦虑_总分。 **策略量表文件**：学生ID、性别、策略_Q1 … 策略_Q50、认知策略、元认知策略、社交情感策略、策略_总分。 两表为同一批被试（学生ID 一一对应），性别由配置中 `male_ratio` 控制。缺失值按配置 `missing_rate` 在题项上随机引入（约 5%），以模拟真实问卷中的漏答。 --- ## 九、如何确认数据符合预期 本项目通过**检验模块**系统性地回答“随机生成的模拟数据是否满足预期结论和数据特征”： 1. **预期与容差均来自配置**：`config/simulation_config.yaml` 中既有“研究结论”的数值（均值、相关、t、α），也有 `validation` 段中的容差（如均值允许误差、r 允许误差、α 下限）。检验时用“观测值 vs 预期值 + 容差”判断通过与否。 2. **检验内容覆盖提纲要点**： 描述统计（总分与维度均值/标准差）、焦虑–策略相关及显著性、高/低焦虑组在策略使用上的差异（t 检验）、两个量表的 Cronbach's α 等，与常见研究提纲中的“结果与分析”一一对应。 3. **运行即得报告**：执行 `python main.py` 或 `python -m src.validate_simulated_data` 后，控制台会打印每一项的“预期 / 观测 / 是否通过”，以及总体结果。若某项未通过，可： - 适当放宽 `config` 中 `validation` 的容差；或 - 重新生成（换随机种子或微调生成参数）再检验。 因此，**无需手工做一遍 SPSS/Excel**，只要在项目中运行检验即可确认当前这批模拟数据是否符合预设结论与数据特征；若需更严格或更宽松，只需改配置文件中的预期与容差。 --- ## 十、问卷与预期结论背景（简要） - **焦虑量表**：33 题，四维度（课堂表达、考试、交际、学习压力），5 级李克特（1=非常不符合 … 5=非常符合），得分越高焦虑程度越高；含反向题，生成时已按焦虑方向处理。 - **策略量表**：50 题，三维度（认知 1–29、元认知 30–38、社交情感 39–50），同样 5 级李克特，得分越高策略使用越频繁。 - **预期结论**：来源于 `docs/提纲.md` 中的“研究结果与分析”，包括焦虑与策略总分水平、维度排序、焦虑与策略负相关、高/低焦虑组在策略使用上的显著差异、两量表信度等；具体数值在 `config/simulation_config.yaml` 中细化为可执行参数。 --- ## 十一、扩展与开发 - **改样本量或分布**：仅需编辑 `config/simulation_config.yaml` 中 `sample`、`anxiety_scale`、`strategy_scale`、`correlation` 等，再运行 `main.py`。 - **调整检验松紧**：修改同一文件中的 `validation` 段（如 `mean_abs_tol`、`r_tol`、`alpha_min`）。 - **新增问卷或维度**：在 `data/` 增加或修改 JSON 结构，并在 `src/generate_simulated_data.py` 中增加对应读取与生成逻辑；检验模块可仿照现有维度/总分在 `validate_simulated_data.py` 中增加对比项。 - **指定种子**：在 `main.py` 或直接调用 `run_simulate(seed=...)` 时传入固定种子，即可复现同一批数据；图形界面中可在“运行选项”标签页设置种子。 - **图形界面**：所有可调参数均可在 `src.gui` 中编辑；支持指定配置文件路径（`main(config_path=...)`），便于多套方案对比。 - **打包 exe**：使用 `questionnaire_gui.spec` 与 PyInstaller 可生成单文件 exe，运行后 config/results/reports 与 exe 同目录（见上文「打包为 exe」）。 项目规则见 `.cursor/rules/questionnaire-simulation.mdc`，约定配置与数据分离、结果输出到 `results/`、检验与配置驱动等，便于与 AI 或团队协作时保持一致。 --- ## 十二、许可证与贡献 - 许可证：见仓库内 [LICENSE](LICENSE)。 - 欢迎 Fork、提 Issue 与 Pull Request；贡献时请保持 `config/` 与 `data/` 的目录约定及检验流程可用。 --- **总结**：QeDataSimulater 通过 **config 配置 + data 问卷结构 + src 生成与检验** 的标准结构，实现“预期结论驱动”的问卷模拟数据生成，并通过内置检验模块确保生成数据符合预期，适合教育测量与实证研究中的示例数据制备与方法验证。