Claude Code数据科学入门：从数据分析到ML预测全流程实战

# 检查 Node.js 版本
node --version   # 需要 v18+

# 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

Claude Code v2.x.x

# 启动认证流程（浏览器自动打开）
claude

# 或使用 API Key 方式
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
claude

# 创建项目目录
mkdir house-price-predictor && cd house-price-predictor

# 初始化 Python 环境（推荐 uv）
uv init
uv add pandas scikit-learn matplotlib seaborn jupyter

# 创建标准数据科学目录结构
mkdir -p data/raw data/processed src notebooks outputs/models outputs/figures

house-price-predictor/
├── CLAUDE.md              # 项目上下文配置
├── pyproject.toml          # Python 依赖管理
├── data/
│   ├── raw/               # 原始数据（不可修改）
│   └── processed/         # 清洗后数据
├── src/
│   ├── __init__.py
│   ├── data_loader.py     # 数据加载模块
│   ├── features.py        # 特征工程模块
│   ├── model.py           # 模型定义
│   └── evaluate.py        # 模型评估
├── notebooks/
│   └── 01_eda.ipynb       # 探索性分析
└── outputs/
    ├── models/            # 保存的模型
    └── figures/           # 可视化图表

# House Price Predictor

## 项目概述
房价预测机器学习项目，使用 Scikit-learn 构建回归模型。

## 技术栈
- Python 3.12, uv 包管理
- pandas, scikit-learn, matplotlib, seaborn
- 运行命令: `uv run python src/main.py`

## 代码规范
- 使用 type hints
- 函数有 docstring
- 数据路径使用 pathlib.Path
- 图表保存到 outputs/figures/，不弹出窗口（matplotlib.use('Agg')）
- 模型用 joblib 保存到 outputs/models/

## 数据说明
- 原始数据放在 data/raw/，不可修改
- 处理后数据保存到 data/processed/
- 目标变量: SalePrice（房屋售价）

## 测试
- 运行: `uv run pytest tests/ -v`
- 测试覆盖率目标: >80%

# 下载经典房价数据集（Ames Housing Dataset 的精简版）
curl -L -o data/raw/housing.csv \
  "https://raw.githubusercontent.com/house-price-prediction/sample-data/main/housing.csv"

# 如果网络不通，让 Claude Code 帮你生成模拟数据
claude "生成一个包含1000条记录的模拟房价数据集CSV，包含字段：
LotArea, OverallQual, YearBuilt, TotalBsmtSF, GrLivArea, FullBath,
GarageCars, Neighborhood, SalePrice。保存到 data/raw/housing.csv"

# 在项目根目录启动
cd house-price-predictor
claude

请帮我编写 src/data_loader.py，完成以下功能：
1. 使用 pandas 读取 data/raw/housing.csv
2. 打印数据形状、列名、数据类型
3. 显示缺失值统计
4. 显示数值列的描述性统计
然后运行它，把结果展示给我

数据形状: (1000, 9)
列名: ['LotArea', 'OverallQual', 'YearBuilt', 'TotalBsmtSF', 'GrLivArea', 'FullBath', 'GarageCars', 'Neighborhood', 'SalePrice']

缺失值统计:
LotArea        0
OverallQual    0
YearBuilt      5
TotalBsmtSF    3
GrLivArea      0
FullBath       0
GarageCars     8
Neighborhood   0
SalePrice      0

数值列描述性统计:
         LotArea  OverallQual   YearBuilt  TotalBsmtSF  ...
count   1000.00      1000.00     995.00      997.00  ...
mean   10516.83         6.10    1984.32     1057.43  ...

数据中有 YearBuilt 缺失5条、TotalBsmtSF 缺失3条、GarageCars 缺失8条。
请帮我处理：
1. YearBuilt 用中位数填充
2. TotalBsmtSF 用0填充（可能没有地下室）
3. GarageCars 用0填充（可能没有车库）
4. 检查并删除 GrLivArea > 4000 的异常值
5. 保存清洗后数据到 data/processed/housing_clean.csv
然后更新 src/data_loader.py 并运行验证

请帮我完成 src/eda.py，生成以下图表并保存到 outputs/figures/：
1. SalePrice 的分布直方图（带KDE曲线）
2. OverallQual 与 SalePrice 的箱线图
3. GrLivArea 与 SalePrice 的散点图（带回归线）
4. 数值变量的相关系数热力图
5. 各 Neighborhood 的房价中位数条形图（降序排列）

要求：图表风格用 seaborn 的 whitegrid 主题，中文字体不报错，
     所有图表 dpi=150，figsize=(10, 6)

import matplotlib
matplotlib.use('Agg')  # 关键：非交互式后端
import matplotlib.pyplot as plt
import seaborn as sns
import pandas as pd
from pathlib import Path

def plot_target_distribution(df: pd.DataFrame, save_path: Path) -> None:
    """绘制目标变量 SalePrice 的分布图。"""
    fig, ax = plt.subplots(figsize=(10, 6))
    sns.histplot(df['SalePrice'], kde=True, ax=ax, color='#2196F3')
    ax.set_title('SalePrice Distribution', fontsize=14)
    ax.set_xlabel('Sale Price ($)', fontsize=12)
    ax.set_ylabel('Count', fontsize=12)
    fig.savefig(save_path / '01_target_distribution.png', dpi=150, bbox_inches='tight')
    plt.close(fig)

def plot_correlation_heatmap(df: pd.DataFrame, save_path: Path) -> None:
    """绘制数值变量相关系数热力图。"""
    numeric_cols = df.select_dtypes(include='number').columns
    corr = df[numeric_cols].corr()
    fig, ax = plt.subplots(figsize=(12, 10))
    sns.heatmap(corr, annot=True, fmt='.2f', cmap='RdBu_r',
                center=0, ax=ax, square=True)
    ax.set_title('Feature Correlation Heatmap', fontsize=14)
    fig.savefig(save_path / '04_correlation_heatmap.png', dpi=150, bbox_inches='tight')
    plt.close(fig)

# ... 其余图表函数

请运行 src/eda.py，然后根据生成的图表告诉我：
1. SalePrice 的分布是否偏斜？是否需要对数变换？
2. 哪些特征与 SalePrice 的相关性最强（相关系数 > 0.5）？
3. 有没有明显的异常值模式？
4. 你建议选择哪些特征进入模型？

请生成一个 SalePrice 的对数变换前后对比图，
如果 log1p 变换后更接近正态分布，就把变换应用到清洗数据中

请编写 src/features.py，完成以下特征工程：
1. 对 SalePrice 做 log1p 变换
2. 对 Neighborhood 做 Target Encoding（用训练集均值）
3. 创建新特征：HouseAge = YrSold - YearBuilt（假设当前年份2026）
4. 创建新特征：TotalSF = TotalBsmtSF + GrLivArea
5. 对数值特征做 StandardScaler 标准化
6. 使用 train_test_split 划分数据（test_size=0.2, random_state=42）

注意：拟合（fit）只在训练集上做，测试集用 transform
保存特征名称列表供后续使用

请编写 src/model.py，训练以下4个回归模型并比较性能：
1. LinearRegression（基线）
2. Ridge（alpha=1.0）
3. RandomForestRegressor（n_estimators=100, random_state=42）
4. GradientBoostingRegressor（n_estimators=200, learning_rate=0.1）

评估指标：RMSE, MAE, R²（注意：指标要在反变换后的原始价格上计算）
用 matplotlib 画一个模型对比条形图，保存到 outputs/figures/
将最佳模型保存到 outputs/models/best_model.joblib

from sklearn.linear_model import LinearRegression, Ridge
from sklearn.ensemble import RandomForestRegressor, GradientBoostingRegressor
from sklearn.metrics import mean_squared_error, mean_absolute_error, r2_score
import numpy as np
import joblib

MODELS = {
    "LinearRegression": LinearRegression(),
    "Ridge": Ridge(alpha=1.0),
    "RandomForest": RandomForestRegressor(n_estimators=100, random_state=42),
    "GradientBoosting": GradientBoostingRegressor(
        n_estimators=200, learning_rate=0.1, random_state=42
    ),
}

def train_and_evaluate(X_train, X_test, y_train, y_test):
    """训练多个模型，返回评估结果和最佳模型。"""
    results = {}
    for name, model in MODELS.items():
        model.fit(X_train, y_train)
        y_pred_log = model.predict(X_test)
        # 反变换：从 log1p 空间回到原始价格
        y_pred = np.expm1(y_pred_log)
        y_true = np.expm1(y_test)
        results[name] = {
            "RMSE": np.sqrt(mean_squared_error(y_true, y_pred)),
            "MAE": mean_absolute_error(y_true, y_pred),
            "R2": r2_score(y_true, y_pred),
            "model": model,
        }
    return results

请按顺序运行完整的模型训练流水线：
1. 加载清洗后数据 data/processed/housing_clean.csv
2. 执行特征工程 src/features.py
3. 训练和评估模型 src/model.py
4. 输出各模型的 RMSE、MAE、R² 对比表
5. 保存最佳模型和对比图

╔═════════════════════╦══════════╦═════════╦═══════╗
║ Model               ║ RMSE ($) ║ MAE ($) ║  R²   ║
╠═════════════════════╬══════════╬═════════╬═══════╣
║ LinearRegression    ║ 38,421   ║ 26,153  ║ 0.762 ║
║ Ridge               ║ 37,892   ║ 25,831  ║ 0.769 ║
║ RandomForest        ║ 31,256   ║ 20,417  ║ 0.843 ║
║ GradientBoosting    ║ 28,734   ║ 18,692  ║ 0.867 ║ ← Best
╚═════════════════════╩══════════╩═════════╩═══════╝

最佳模型: GradientBoosting (R²=0.867)
已保存到 outputs/models/best_model.joblib

请编写 src/evaluate.py，对最佳模型做深入评估：
1. 预测值 vs 实际值的散点图（对角线参考线）
2. 残差分布图（直方图 + QQ图）
3. 特征重要性排序条形图
4. 使用 5-fold 交叉验证计算 R² 的均值和标准差
5. 生成评估报告保存到 outputs/evaluation_report.txt

对 GradientBoosting 模型做超参数调优，使用 GridSearchCV：
- n_estimators: [100, 200, 300]
- learning_rate: [0.05, 0.1, 0.15]
- max_depth: [3, 5, 7]
- min_samples_split: [2, 5]

5-fold CV，评分用 neg_mean_squared_error
报告最佳参数和对应的 CV 分数
保存调优后的模型为 outputs/models/tuned_model.joblib

请检查调优后的模型是否存在过拟合：
1. 比较训练集和测试集上的 R² 差值
2. 如果差值 > 0.1，说明存在过拟合，请：
   - 减小 max_depth
   - 增加 min_samples_leaf
   - 添加 subsample=0.8
3. 重新训练并比较

"""房价预测项目主程序 - 从数据加载到模型评估的完整流水线。"""

from pathlib import Path
import pandas as pd
import numpy as np
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
from sklearn.ensemble import GradientBoostingRegressor
from sklearn.metrics import mean_squared_error, mean_absolute_error, r2_score
import joblib

# 路径常量
ROOT = Path(__file__).resolve().parent.parent
DATA_RAW = ROOT / "data" / "raw"
DATA_PROCESSED = ROOT / "data" / "processed"
FIGURES = ROOT / "outputs" / "figures"
MODELS = ROOT / "outputs" / "models"


def load_data(filepath: Path) -> pd.DataFrame:
    """加载原始数据。"""
    df = pd.read_csv(filepath)
    print(f"数据形状: {df.shape}")
    print(f"缺失值:\n{df.isnull().sum()[df.isnull().sum() > 0]}")
    return df


def clean_data(df: pd.DataFrame) -> pd.DataFrame:
    """清洗数据：填充缺失值、移除异常值。"""
    df = df.copy()
    df["YearBuilt"] = df["YearBuilt"].fillna(df["YearBuilt"].median())
    df["TotalBsmtSF"] = df["TotalBsmtSF"].fillna(0)
    df["GarageCars"] = df["GarageCars"].fillna(0)
    df = df[df["GrLivArea"] <= 4000]
    return df


def engineer_features(df: pd.DataFrame) -> tuple:
    """特征工程：创建新特征、编码、标准化。"""
    df = df.copy()
    df["SalePrice"] = np.log1p(df["SalePrice"])
    df["HouseAge"] = 2026 - df["YearBuilt"]
    df["TotalSF"] = df["TotalBsmtSF"] + df["GrLivArea"]

    feature_cols = [
        "LotArea", "OverallQual", "YearBuilt", "TotalBsmtSF",
        "GrLivArea", "FullBath", "GarageCars", "HouseAge", "TotalSF",
    ]
    X = df[feature_cols]
    y = df["SalePrice"]

    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.2, random_state=42
    )

    scaler = StandardScaler()
    X_train_scaled = scaler.fit_transform(X_train)
    X_test_scaled = scaler.transform(X_test)

    return X_train_scaled, X_test_scaled, y_train, y_test, scaler, feature_cols


def train_model(X_train, y_train) -> GradientBoostingRegressor:
    """训练梯度提升回归模型。"""
    model = GradientBoostingRegressor(
        n_estimators=200, learning_rate=0.1,
        max_depth=5, random_state=42
    )
    model.fit(X_train, y_train)
    return model


def evaluate_model(model, X_test, y_test) -> dict:
    """评估模型性能（反变换回原始价格）。"""
    y_pred = np.expm1(model.predict(X_test))
    y_true = np.expm1(y_test)
    return {
        "RMSE": np.sqrt(mean_squared_error(y_true, y_pred)),
        "MAE": mean_absolute_error(y_true, y_pred),
        "R2": r2_score(y_true, y_pred),
    }


def main():
    """运行完整流水线。"""
    # 确保输出目录存在
    FIGURES.mkdir(parents=True, exist_ok=True)
    MODELS.mkdir(parents=True, exist_ok=True)

    # 1. 加载
    print("=" * 50)
    print("Step 1: 加载数据")
    df = load_data(DATA_RAW / "housing.csv")

    # 2. 清洗
    print("=" * 50)
    print("Step 2: 清洗数据")
    df_clean = clean_data(df)
    df_clean.to_csv(DATA_PROCESSED / "housing_clean.csv", index=False)
    print(f"清洗后数据形状: {df_clean.shape}")

    # 3. 特征工程
    print("=" * 50)
    print("Step 3: 特征工程")
    X_train, X_test, y_train, y_test, scaler, features = engineer_features(df_clean)
    print(f"训练集: {X_train.shape}, 测试集: {X_test.shape}")

    # 4. 训练
    print("=" * 50)
    print("Step 4: 训练模型")
    model = train_model(X_train, y_train)

    # 5. 评估
    print("=" * 50)
    print("Step 5: 评估模型")
    metrics = evaluate_model(model, X_test, y_test)
    print(f"RMSE: ${metrics['RMSE']:,.0f}")
    print(f"MAE:  ${metrics['MAE']:,.0f}")
    print(f"R²:   {metrics['R2']:.4f}")

    # 6. 保存
    joblib.dump(model, MODELS / "best_model.joblib")
    print(f"\n模型已保存到 {MODELS / 'best_model.joblib'}")


if __name__ == "__main__":
    main()

uv run python src/main.py

flowchart TB
    subgraph 准备阶段
        A[安装 Claude Code CLI] --> B[创建项目结构]
        B --> C[编写 CLAUDE.md]
        C --> D[安装 Python 依赖]
    end

    subgraph 数据阶段
        D --> E[加载原始数据]
        E --> F[检查缺失值/异常值]
        F --> G[数据清洗与填充]
        G --> H[保存清洗后数据]
    end

    subgraph 分析阶段
        H --> I[EDA: 分布/相关性/箱线图]
        I --> J[Claude Code 解读图表]
        J --> K{分布偏斜?}
        K -- 是 --> L[log1p 变换]
        K -- 否 --> M[保持原样]
        L --> N[特征工程]
        M --> N
    end

    subgraph 建模阶段
        N --> O[划分训练/测试集]
        O --> P[训练多个候选模型]
        P --> Q[交叉验证评估]
        Q --> R[选择最佳模型]
        R --> S[超参数调优]
        S --> T[过拟合检查]
    end

    subgraph 交付阶段
        T --> U[保存最终模型]
        U --> V[生成评估报告]
        V --> W[输出预测结果]
    end

    style 准备阶段 fill:#e3f2fd
    style 数据阶段 fill:#f3e5f5
    style 分析阶段 fill:#e8f5e9
    style 建模阶段 fill:#fff3e0
    style 交付阶段 fill:#fce4ec

# 不要一次性要求所有分析，分步骤进行
# 第1步：只做数据加载
> 请帮我加载 housing.csv 并显示基本信息

# 第2步：确认无误后再做清洗
> 基于以上信息，请执行数据清洗

# 第3步：清洗完成后再做EDA
> 数据清洗完成，请生成EDA图表

# 当对话变长时，压缩历史上下文
> /compact

# 或带提示的压缩
> /compact 保留特征工程和数据清洗的关键决策，删除中间输出

# 进入建模阶段时清空上下文
> /clear

# 重新加载项目上下文
> 请阅读 CLAUDE.md 和 src/ 目录下的文件，准备开始建模

> /plan

# Plan Mode 下，Claude Code 会分析而非执行
# 请帮我设计一个完整的特征工程方案：
# - 考虑类别变量的编码方式（OneHot vs Target Encoding）
# - 考虑是否需要多项式特征
# - 考虑特征选择策略
# - 给出理由和预期效果

请为 src/features.py 编写单元测试 tests/test_features.py：
1. 测试缺失值填充是否正确（填充前后数量对比）
2. 测试异常值过滤是否正确（GrLivArea > 4000 被移除）
3. 测试新特征 HouseAge 计算是否正确
4. 测试标准化后均值为0、标准差为1
5. 测试 train/test 划分比例是否正确

使用 pytest，运行命令: uv run pytest tests/ -v

# 错误：在整个数据集上做标准化
scaler.fit(X)  # ← 测试集信息泄漏到训练过程

# 正确：只在训练集上 fit
scaler.fit(X_train)
X_train_scaled = scaler.transform(X_train)
X_test_scaled = scaler.transform(X_test)

请检查 src/features.py 中是否存在数据泄漏：
- 所有 fit/fit_transform 是否只在训练集上
- Target Encoding 是否用了测试集的目标值
- 特征选择是否在划分前执行
如果有问题请修复并解释

# 错误：在 log 变换空间计算 RMSE
rmse = np.sqrt(mean_squared_error(y_test, y_pred_log))

# 正确：在原始价格空间计算
y_pred = np.expm1(y_pred_log)
y_true = np.expm1(y_test)
rmse = np.sqrt(mean_squared_error(y_true, y_pred))

import matplotlib
matplotlib.use('Agg')  # 必须在 import pyplot 之前
import matplotlib.pyplot as plt

# 非交互模式：自动生成 EDA 报告
claude -p "运行 src/eda.py 并总结关键发现" \
  --output-format json > outputs/eda_summary.json

# 批量处理多个数据集
for dataset in data/raw/*.csv; do
  claude -p "分析 $dataset 的数据质量，生成缺失值报告和分布图"
done

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd $PROJECT_DIR && uv run pytest tests/ -v --tb=short 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}

# 完全自动化的每日数据质量报告
claude -p "加载数据/raw/daily_data.csv，检查数据质量，生成报告，如果有异常则发送邮件通知" \
  --allowedTools "Bash,Read,Write" \
  --model claude-sonnet-4-6

sequenceDiagram
    participant U as 用户
    participant CC as Claude Code
    participant FS as 文件系统
    participant PY as Python 运行时

    U->>CC: 启动 claude
    CC->>FS: 读取 CLAUDE.md
    CC-->>U: 准备就绪

    Note over U,PY: 数据加载与清洗阶段
    U->>CC: "加载 housing.csv 并清洗"
    CC->>FS: 写入 src/data_loader.py
    CC->>PY: uv run python src/data_loader.py
    PY-->>CC: 数据统计输出
    CC->>FS: 保存 housing_clean.csv
    CC-->>U: 清洗结果摘要

    Note over U,PY: EDA 阶段
    U->>CC: "生成 EDA 图表"
    CC->>FS: 写入 src/eda.py
    CC->>PY: uv run python src/eda.py
    PY-->>CC: 图表已保存
    CC-->>U: 分析解读

    Note over U,PY: 建模阶段
    U->>CC: "训练模型并评估"
    CC->>FS: 写入 src/model.py
    CC->>PY: uv run python src/model.py
    PY-->>CC: 评估指标
    CC->>FS: 保存 best_model.joblib
    CC-->>U: 模型性能报告

    Note over U,PY: 优化阶段
    U->>CC: "调优超参数"
    CC->>FS: 更新 src/model.py
    CC->>PY: 运行 GridSearchCV
    PY-->>CC: 最佳参数
    CC-->>U: 调优结果