GitHub 开发者贡献分析系统

🚀 快速开始（3步）

步骤1：创建目录结构

Windows:

# 双击运行或在命令行执行
setup_data_folder.bat

# 或手动创建
mkdir data\raw
mkdir data\intermediate
mkdir data\output
mkdir data\raw\平衡&非平衡

Linux/Mac:

mkdir -p data/raw
mkdir -p data/intermediate
mkdir -p data/output
mkdir -p "data/raw/平衡&非平衡"

步骤2：放置数据文件

将所有原始数据文件复制到 data/raw/ 目录：

data/raw/
├── uid.csv                                 ⭐ 必需
├── userid.csv                             ⭐ 必需
├── pull_request_history.csv               ⭐ 必需
├── projects.csv                           ⭐ 必需
├── commits_match.csv                      ⭐ 必需
├── projects_match.csv                     ⭐ 必需
├── fork_match.csv                         ⭐ 必需
├── pull_request_match.csv                 ⭐ 必需
├── pull_requests_history_match.csv        ⭐ 必需
└── 平衡&非平衡/平衡面板.csv               ⭐ 必需

步骤3：运行

python pipeline.py

最终结果： data/output/final_merged_panel.csv ⭐

---

📁 项目结构

GitHub-Panel-Data/
│
├── pipeline.py                    # ⭐ 主脚本（运行这个）
├── setup_data_folder.bat          # ⭐ 自动创建目录
│
├── data/                          # 数据目录
│   ├── raw/                       # 原始数据（你放文件的地方）
│   ├── intermediate/              # 中间文件（自动生成，可删除）
│   └── output/                    # 最终结果（自动生成）
│
├── src/                           # 原有独立脚本（保留，可忽略）
│
├── README.md                      # 本文件
├── 使用指南.md                    # 详细说明
└── 算法说明.md                    # 核心算法解释

---

🎯 系统特点

• ✅ 一键运行 - 单条命令完成所有处理
• ✅ 智能配置 - 自动创建目录结构
• ✅ 算法保留 - 100%保留原有双轨扫描算法
• ✅ 进度显示 - 清晰的处理进度反馈
• ✅ 模块化设计 - 代码清晰，易于维护

---

⚙️ 配置说明

在 pipeline.py 中修改 Config 类：

class Config:
    # 使用 data 文件夹（推荐）
    USE_DATA_FOLDER = True

    # 分块大小（根据内存调整，建议100000）
    CHUNK_SIZE = 100000

    # 时间窗口
    START_DATE = "2011-01-01"
    END_DATE = "2021-03-06"

切换到根目录模式： 将 USE_DATA_FOLDER 改为 False，文件直接放在项目根目录

---

🔧 常用命令

# 运行完整流程
python pipeline.py

# 仅运行数据过滤
python pipeline.py filter

# 仅运行PR分析
python pipeline.py analyze

# 仅运行数据合并
python pipeline.py merge

---

📊 处理流程

系统采用三阶段流水线架构：

原始数据 → 数据过滤 → 时序分析 → 维度统计 → 数据合并 → 最终结果
   ↓           ↓          ↓          ↓          ↓          ↓
data/raw/  阶段一    阶段二    阶段三    阶段四   data/output/

核心算法： 双轨扫描-延迟匹配算法（解决PR时序非同步问题）

详见：算法说明.md

---

📖 详细文档

• 使用指南.md - 详细的使用说明和常见问题
• 算法说明.md - 核心算法和系统架构详解
• 代码处理流程与逻辑说明.md - 原有说明文档

---

💡 提示

1. 首次使用：先运行 setup_data_folder.bat 创建目录
2. 数据准备：确保所有必需的CSV文件都在 data/raw/
3. 磁盘空间：建议预留10GB以上空间
4. 内存要求：建议8GB以上内存
5. 中间文件：data/intermediate/ 中的文件可以安全删除

---

🆘 常见问题

Q: 文件应该放在哪里？ A: 将所有原始数据文件放入 data/raw/ 目录

Q: 如何修改配置？ A: 编辑 pipeline.py 文件的 Config 类（第20-64行）

Q: 中间文件可以删除吗？ A: 可以！data/intermediate/ 中的文件都可以安全删除，重新运行会重新生成

Q: 如何只运行某个阶段？ A: 使用命令：python pipeline.py filter 或 analyze 或 merge

Q: 处理需要多长时间？ A: 根据数据量，完整流程通常需要2-6小时

---

📝 输出文件说明

中间文件（data/intermediate/）

• filtered_history.csv - 过滤后的PR历史
• daily_opened_merged_stats.csv - PR合并统计
• daily_commits_count.csv - 每日提交统计
• daily_projects_count.csv - 每日项目统计
• daily_forks_count.csv - 每日Fork统计
• daily_pull_requests_count.csv - 每日PR统计
• merged_daily_activity_with_weekend.csv - 合并后的活动数据

最终结果（data/output/）

• final_merged_panel.csv ⭐⭐⭐ - 最终分析结果，包含用户在每一天的各种活动指标

---

🎓 系统架构

三阶段流水线

阶段一：数据过滤 (filter_by_uid)

• 使用HashSet索引进行O(1)快速查找
• 分块读取处理大文件
• 从海量数据中提取目标开发者记录

阶段二：PR时序分析 (analyze_future_merges)

• 双轨扫描-延迟匹配算法（核心创新）
• 单次遍历同时收集merged状态和opened事件
• 内存中O(1)查找验证

阶段三：数据整合 (merge, merge_panel)

• 左连接确保数据完整性
• 零值填充处理稀疏数据
• 生成统一的面板数据

---

📧 技术支持

如有问题：

1. 查看 使用指南.md
2. 检查 pipeline.py 中的注释
3. 验证数据文件格式是否正确

---

祝使用愉快！ 🎉