yjh051108/mmkit/paper-analysis

echo "=== 产出验证（必须全部 ✅，否则继续补全）==="
PASS=true
[ -f RESULTS.md ] && SZ=$(wc -c < RESULTS.md) || SZ=0
if [ "$SZ" -ge 1024 ]; then echo "✅ RESULTS.md ($SZ bytes)"; else echo "❌ RESULTS.md 缺失或过小 ($SZ bytes)"; PASS=false; fi
 
JSON_COUNT=$(ls figures/*.json 2>/dev/null | wc -l)
if [ "$JSON_COUNT" -ge 1 ]; then echo "✅ figures/*.json ($JSON_COUNT 个)"; else echo "❌ figures/*.json 缺失"; PASS=false; fi
 
if [ "$PASS" != true ]; then
    echo ""
    echo "⛔ 产出验证失败 — 必须立刻补全后重新跑验证。不要结束本步骤。"
    echo "   正确做法: 用 Edit/Write 工具补全 RESULTS.md, 或重跑代码生成 figures/*.json"
fi

echo "=== 工作区扫描 ==="
HAS_CODE=$(ls code/*.py 2>/dev/null | wc -l)
HAS_JSON=$(ls figures/*.json 2>/dev/null | wc -l)
HAS_RESULTS=$([ -f RESULTS.md ] && wc -c < RESULTS.md || echo 0)
echo "  code/*.py: $HAS_CODE 个"
echo "  figures/*.json: $HAS_JSON 个"
echo "  RESULTS.md: $HAS_RESULTS 字节"

ANALYSIS CHECKLIST (from PAPER_PLAN.md):
[ ] 数据准备: [数据来源], [变量列表], [样本量]
[ ] 描述性统计: 均值/标准差/分布
[ ] 分析任务1: [方法名] — 输入: [xxx], 输出: [yyy]
[ ] 分析任务2: [方法名] — 输入: [xxx], 输出: [yyy]
[ ] 稳健性检验: [方法]

echo "=== 图表预规划 ==="
for plan in PAPER_PLAN.md TOPIC_PLAN.md; do
    [ -f "$plan" ] || continue
    echo "--- $plan ---"
    grep -i 'fig_\|图表\|TABLE_\|figure\|预规划\|配方' "$plan" | head -30
done

echo "=== 数据来源检查 ==="
DATA_SOURCE="simulate"
for dir in user_data data; do
    if [ -d "$dir" ] && [ "$(ls -A $dir 2>/dev/null)" ]; then
        echo "✅ 发现用户数据: $dir/"
        ls -la $dir/
        DATA_SOURCE="real"
    fi
done
echo "数据来源: $DATA_SOURCE"

code/
  main.py              # 主程序（串联所有分析）
  data_preparation.py   # 数据准备（读取/模拟 + 清洗）
  analysis_1.py         # 分析任务 1
  analysis_2.py         # 分析任务 2
  robustness.py         # 稳健性检验
  utils.py              # 公共工具
  requirements.txt

# ⛔ 自举模块路径（让 sibling import 不依赖调用方式）
import os, sys
_HERE = os.path.dirname(os.path.abspath(__file__))
if _HERE not in sys.path:
    sys.path.insert(0, _HERE)
# 之后才能写其它 import
import numpy as np
import utils as u

# ✅ 正确
cd code && python main.py && cd ..
 
# ❌ 错误：sibling import 必报 ModuleNotFoundError
python code/main.py
python -m code.main

# code/sanity_check.py — 检测不合理数值
import json, os, sys, math
results = {}
for f in sorted(os.listdir('figures')):
    if f.endswith('_results.json') or f == 'all_results.json':
        try:
            with open(f'figures/{f}', 'r') as fh:
                results[f] = json.load(fh)
        except: pass
errors, warnings, suspicious = [], [], []
def check_unrealistic(name, val):
    if not isinstance(val, (int, float)) or isinstance(val, bool): return
    key = name.lower()
    # 归一化指标：R²/accuracy/precision/recall/f1/auc（>0.99 标记）
    if any(w in key for w in ['r2', 'r_squared', 'accuracy', 'acc', 'precision', 'recall', 'f1', 'auc']):
        if val > 0.99:
            suspicious.append(f"🚩 {name} = {val:.4f}（>0.99），请在审查中确认是否过拟合")
        elif val < 0:
            errors.append(f"❌ {name} = {val} 负值（模型比均值预测还差，必须换模型）")
        elif val < 0.5 and any(w in key for w in ['r2', 'r_squared']):
            errors.append(f"❌ {name} = {val:.4f}（R² < 0.5，模型解释力极弱，必须改进模型或检查数据预处理）")
    # 误差类：RMSE/MAE/MSE/Loss
    if any(w in key for w in ['rmse', 'mae', 'mse', 'loss']):
        if val == 0:
            suspicious.append(f"🚩 {name} = 0 完美误差，请确认训练/测试是否分开")
        elif val < 0:
            errors.append(f"❌ {name} = {val} 误差不应为负")
    # 提升百分比（>100% 标记）
    if any(w in key for w in ['improvement', 'speedup', 'gain', '提升', '改进']):
        if val > 1:  # >100%
            suspicious.append(f"🚩 {name} = {val:.2f}（提升 {val*100:.0f}%），请结合研究背景确认")
    # p-value
    if 'p_value' in key or 'pvalue' in key or 'p值' in key:
        if val == 0:
            suspicious.append(f"🚩 {name} = 0 完美显著（应 > 1e-16），请确认")
        elif val > 1:
            errors.append(f"❌ {name} = {val} p 值 > 1 不可能")
def walk(obj, path=""):
    if isinstance(obj, dict):
        for k, v in obj.items(): walk(v, f"{path}.{k}")
    elif isinstance(obj, list):
        for i, v in enumerate(obj): walk(v, f"{path}[{i}]")
    elif isinstance(obj, (int, float)):
        if isinstance(obj, float):
            if math.isnan(obj): errors.append(f"❌ {path} 为 NaN")
            elif math.isinf(obj): errors.append(f"❌ {path} 为 Inf")
        check_unrealistic(path, obj)
for fname, data in results.items():
    walk(data, fname)
for e in errors: print(e)
for s in suspicious: print(s)
if errors:
    print(f"\n❌ {len(errors)} 个硬错误 — 必须修复"); sys.exit(1)
if suspicious:
    print(f"\n🚩 {len(suspicious)} 个可疑的'完美'结果 — 逐条确认：")
    print("  1. 训练/测试是否真的分开了？（数据泄漏最常见的原因）")
    print("  2. 样本量是否足够？（<100 时 R²>0.95 通常是过拟合）")
    print("  3. 自变量是否含因变量函数？（回归中最易犯的错）")
    print("  4. 如果确实合理（物理仿真/确定性问题），在 RESULTS.md 中明确说明")
elif not errors:
    print("✅ 所有数值通过 sanity check")

echo "=== 结合研究背景的合理性审查 ==="
 
# 1. 完整读取选题与研究设计
echo "--- 选题与研究设计 ---"
for src in PAPER_PLAN.md TOPIC_PLAN.md FINAL_PROPOSAL.md; do
    [ -f "$src" ] && echo "=== $src ===" && cat "$src" | head -150
done
 
echo "--- 用户上传的数据概况 ---"
for src in user_data/*.csv user_data/*.xlsx; do
    [ -f "$src" ] && echo "文件: $src ($(wc -l < "$src" 2>/dev/null) 行)"
done
 
# 2. 列出所有计算结果
echo "--- 所有结果数值 ---"
python3 -c "
import json, os
for f in sorted(os.listdir('figures')):
    if not (f.endswith('_results.json') or f == 'all_results.json'): continue
    try:
        data = json.load(open(f'figures/{f}', 'r', encoding='utf-8'))
        print(f'=== {f} ===')
        print(json.dumps(data, ensure_ascii=False, indent=2)[:3000])
    except: pass
" 2>/dev/null

=== 合理性审查（结合研究背景）===
 
Q1. [数值量级] 每个关键指标的数值量级是否符合研究场景？
   举例：
   - 社会科学：回归系数绝对值一般 < 10（标准化后一般 < 1）
   - 经济学：GDP 增长率一般 0-20%，通货膨胀率一般 0-50%
   - 机器学习：准确率 0-1，训练时间 < 100 小时（中等规模）
   - 医学：OR 值一般 0.1-10，RR 值一般 0.5-5
   - 你的研究领域：[自行判断]
   逐条列出每个关键结果的数值，判断量级是否合理。
 
Q2. [符号方向] 结果的正负/大小方向是否符合先验假设和文献？
   举例：
   - 已知文献显示 X 对 Y 有正向影响，我的系数也应该是正的
   - 理论预期：教育投入越多，收入越高 → 系数应为正
   - 如果结果方向与主流文献相反，要么是重大发现（极罕见），
     要么是代码 bug（更常见），必须深入检查
   逐条检查结果方向是否与文献/理论一致。
 
Q3. [统计显著性分布] p 值分布是否合理？
   - 所有变量的 p 值都 < 0.001？（太完美，可能过度拟合或数据泄漏）
   - 所有 p 值都 > 0.05？（研究设计可能有问题）
   - 正常应该：关键变量显著，控制变量部分显著，一些不显著
   如果 p 值分布异常，说明数据或模型有问题。
 
Q4. [效应大小] 效应大小是否在文献报告范围内？
   - 同类研究的效应大小一般 [a, b] 区间
   - 我的效应大小是否与该区间一致？
   - 如果效应特别大（比同类研究大 10 倍），要么是真正的重大发现，
     要么是我的模型/数据处理有问题
   查阅文献比较，在 RESULTS.md 中引用 2-3 篇同类研究作为对照。
 
Q5. [R² / 拟合优度] 拟合优度是否在合理范围？
   **⛔ 关键：R² 的合理范围取决于任务类型，不能一刀切！**
   - 截面数据经济学/社科研究：R² 一般 0.2-0.6（因为噪声大、变量多）
   - 时间序列（含趋势）：R² 一般 0.7-0.95
   - **物理/工程曲线拟合（如光谱拟合、信号拟合、传递函数拟合）：R² 应 > 0.8**
     - 如果 R² < 0.5 → 模型形式错误（如缺少基线项、频率估计错误），必须换模型
     - 如果 R² 在 0.5-0.8 → 模型可能遗漏了重要物理效应，需要检查
   - 机器学习测试集：accuracy 一般 0.7-0.95（视任务难度）
   - 物理仿真/确定性问题：R² 可能接近 1.0（正常）
   
   **⛔ R² < 0.5 的拟合结果绝对不能直接写入论文。** 必须先诊断原因：
   1. 模型形式是否正确？（是否遗漏了基线漂移、非线性项、相位偏移等）
   2. 数据预处理是否正确？（是否需要去趋势、归一化、截取有效区间）
   3. 初始参数是否合理？（非线性拟合对初值敏感）
   修复后 R² 应显著提升，否则说明模型假设与数据不匹配。
   
   如果 R² > 0.99 而任务又不是确定性问题，极大概率过拟合或数据泄漏。
 
Q6. [样本量与自由度] 样本量是否支撑所用方法？
   - OLS 回归：每个参数至少 10-20 个样本
   - Logistic 回归：每个事件至少 10 个（EPV 原则）
   - 面板：截面 × 时间 至少 > 3 × 参数数量
   - 机器学习：训练集至少 > 10 × 特征数（防维度灾难）
   如果样本量不足，结果可能不稳定。
 
Q7. [变量间关系] 关键变量间的相关性是否合理？
   - 互斥变量不应正相关（如 A 组 vs B 组）
   - 同一概念的不同度量应正相关（如学历水平和毕业年限）
   - 如果出现违反常识的相关性，检查数据处理是否出错
 
Q8. [稳健性] 稳健性检验结果是否与主模型一致？
   - 替换变量/子样本/不同方法后，系数方向应基本一致
   - 如果稳健性检验结果方向相反或差异巨大，主模型可能不可靠
   至少做 2 种稳健性检验，并在 RESULTS.md 中对比报告。
 
Q9. [与研究设计一致] 实际结果是否与 PAPER_PLAN.md 中的研究设计预期一致？
   逐条对照：
   - 论文大纲说用 XX 方法 → 代码里确实用了 XX 方法？（不是偷换成更简单的）
   - 论文大纲的研究假设 → 结果支持还是拒绝？（都支持太完美，都拒绝说明设计有问题）
   - 论文大纲规划的分析任务 → 全部完成了？有遗漏的吗？
   - 论文大纲预期的效应方向 → 实际方向一致？
   - 如果结果与研究设计严重不符 → 要么代码有 bug（回去查），
     要么研究设计需要调整（回去改 PAPER_PLAN.md 再重跑）
   - 如果假设被拒绝 → 这是正常的科研结果，诚实报告，不要篡改

=== 通用自检 ===
1. [研究覆盖] 论文大纲中规划的分析任务是否全部完成？缺了哪个？
2. [数值合理] 结果数值是否符合领域常识？（回归系数方向、效应大小）
3. [NaN/Inf] JSON 结果中是否有 NaN、Inf、null？
4. [统计规范] 是否报告了所有必要的统计量？（系数、标准误、p值、R²、样本量）
5. [数据一致] 描述性统计的样本量是否与回归分析一致？