江无没有月の博客

Python 官方教程综合练习手册：Oh My Pi Terminal Edition

Mon, 27 Jul 2026 04:30:00 GMT

oh-my-pi python manual · terminal edition

oh-my-pi@python:~/official-tutorial$ cat beginner-practice-manual.md

Python Official Tutorial × AI / Quant Practice

把官方教程变成能敲、能跑、能解释的 4 周终端练习。

每个练习都先讲函数怎么用，再拆代码逻辑，最后给验收问题。目标不是背语法，而是能进入 pandas、sklearn、PyTorch 和回测项目前不再被 Python 基础卡住。

start week-a week-b week-c week-d AI/Quant 总路线

Python 官方教程综合练习手册：Oh My Pi Terminal Edition

这版按“先教概念 → 再看函数怎么用 → 再拆代码逻辑 → 最后做练习”的顺序写。目标读者是：会一点 C，知道变量、函数、循环这些词，但 Python 还不系统。

0. 使用方式

不要把这份文档当成“看完就会”的文章。它是练习手册。每个练习都按同一个学习节奏来：

1. 先理解这个语法/函数解决什么问题
2. 看最小例子，确认会运行
3. 拆代码逻辑，知道每一行为什么存在
4. 再写练习，不要跳过验收
5. 把错误记录下来，下一周会用到

0.1 官方教程映射

官方教程	本手册用途
2. Using the Python Interpreter	解释器、脚本、命令行运行
3. An Informal Introduction to Python	数字、文本、列表、第一段程序
4. More Control Flow Tools	`if`、`for`、`range`、`match`、函数、参数、编码风格
5. Data Structures	list、tuple、set、dict、comprehension、循环技巧
6. Modules	模块、包、`__name__ == "__main__"`、导入规范
7. Input and Output	f-string、文件读写、JSON
8. Errors and Exceptions	语法错误、异常、`try`、`raise`、清理动作
9. Classes	对象、作用域、类、实例、迭代器、生成器
10. Brief Tour of the Standard Library	`pathlib`、`csv`、`json`、`argparse`、`statistics`、`logging`
12. Virtual Environments and Packages	虚拟环境、包管理、依赖复现
15. Floating-Point Arithmetic	浮点误差、`math.isclose`、金融/统计小数风险

0.2 最终项目结构

最终你会得到一个小项目：

python-official-practice/
├── README.md
├── pyproject.toml
├── data/
│   ├── scores.csv
│   └── prices.csv
├── src/
│   ├── basics.py
│   ├── stats_utils.py
│   ├── data_io.py
│   ├── metrics.py
│   ├── cli.py
│   ├── toy_backtest.py
│   └── experiment.py
├── reports/
│   ├── python_basics_report.md
│   ├── data_summary.md
│   ├── backtest_report.md
│   └── floating_point_notes.md
└── notes/
    └── official_tutorial_mapping.md

它不是大项目，但它覆盖进入 AI / Quant 之前真正要会的东西：

变量 → 列表 → 字符串 → 条件 → 循环 → 函数 → 数据结构
  → 模块 → 文件 → JSON → 异常 → CLI → 类 → 迭代器 → 浮点数

0.3 四周路线

周	主题	最终交付物
Week A	环境、基本类型、控制流	`src/basics.py`、`reports/python_basics_report.md`
Week B	函数、参数、数据结构、风格	`src/stats_utils.py`、`src/metrics.py`
Week C	模块、文件、JSON、异常、CLI	`src/data_io.py`、`src/cli.py`、`reports/data_summary.md`
Week D	类、迭代器、标准库、浮点数、综合项目	`src/toy_backtest.py`、`src/experiment.py`、`reports/backtest_report.md`

1. Week A：解释器、虚拟环境、基本类型、控制流

Week A 的目标不是“背 Python 语法”，而是能把一段数据放进变量，写几行逻辑处理它，然后在命令行跑起来。

1.1 先理解：解释器、脚本、虚拟环境

Python 有两种常见运行方式。

第一种是交互式解释器：

python

进去以后输入：

1 + 1

它会立刻返回结果。这个方式适合试语法。

第二种是脚本文件：

python src/basics.py

这个方式适合正式练习。你后面写的 AI / Quant 项目基本都应该放在 .py 文件里，而不是只写在 notebook 里。

虚拟环境的作用是隔离依赖。你这个项目需要的包，不应该污染整个系统 Python。

函数和命令怎么用

这里先不用自己写函数，只学会几个命令：

命令	作用
`uv init`	初始化 Python 项目
`uv venv`	创建虚拟环境
`source .venv/bin/activate.fish`	在 fish shell 里启用虚拟环境
`python --version`	查看当前 Python 版本
`python -c "..."`	直接执行一小段 Python 代码

代码逻辑

mkdir 创建目录
cd 进入目录
uv init 创建 pyproject.toml
uv venv 创建 .venv
source 激活 .venv
python --version 验证当前 Python 可用

Exercise A-00：创建练习项目

mkdir -p ~/Code/python-official-practice
cd ~/Code/python-official-practice
uv init
uv venv
source .venv/bin/activate.fish
python --version
python -c "print('hello python')"
mkdir -p src data reports notes

验收：

当前目录有 pyproject.toml。
command -v python 指向 .venv/bin/python。
python -c "print('hello python')" 能输出 hello python。

1.2 数字：先把统计量算出来

AI / Quant 会大量处理数字。先从最小统计任务开始：一组分数，求数量、均值、最小值、最大值。

你要学的函数

函数	怎么用	含义
`len(xs)`	`len([1, 2, 3])`	返回元素个数
`sum(xs)`	`sum([1, 2, 3])`	返回总和
`min(xs)`	`min([1, 2, 3])`	返回最小值
`max(xs)`	`max([1, 2, 3])`	返回最大值
`print(x)`	`print("mean", 2.0)`	把结果显示到终端

最小例子：

scores = [80, 92, 75, 88, 95]
mean_score = sum(scores) / len(scores)
print(mean_score)

代码逻辑

scores = [...]              把多个分数放进一个 list
sum(scores)                 求总分
len(scores)                 求人数
sum(scores) / len(scores)   总分除以人数，得到平均分
print(...)                  把结果显示出来

这和 C 的数组很像，但 Python 的 list 更灵活：它知道自己的长度，所以可以直接 len(scores)。

Exercise A-01：均值、最小值、最大值

文件：src/basics.py

写入：

scores = [80, 92, 75, 88, 95]

print("n =", len(scores))
print("mean =", sum(scores) / len(scores))
print("min =", min(scores))
print("max =", max(scores))

运行：

python src/basics.py

验收：你能解释这四个问题：

scores 是什么类型？
len(scores) 返回什么？
为什么均值要除以 len(scores)？
print("mean =", value) 为什么会显示两段内容？

1.3 字符串：把脏列名清洗成规范列名

真实数据里，列名经常不干净。例如：

" Final Score "
"Student ID"
"Group Name"

后续 pandas / SQL / sklearn 里，更推荐列名像这样：

final_score
student_id
group_name

你要学的方法

字符串后面可以接方法调用：

方法	怎么用	含义
`strip()`	`" A ".strip()`	去掉两边空白
`lower()`	`"ABC".lower()`	转小写
`replace(a, b)`	`"A B".replace(" ", "_")`	把 a 替换成 b

最小例子：

raw_name = " Final Score "
clean_name = raw_name.strip().lower().replace(" ", "_")
print(clean_name)

代码逻辑

raw_name.strip()             " Final Score " → "Final Score"
.lower()                     "Final Score" → "final score"
.replace(" ", "_")          "final score" → "final_score"

这叫链式调用。左边一步的结果，会传给右边下一步。

Exercise A-02：清洗字段名

输入：

columns = [" Student ID ", "Final Score", "Group Name"]

目标输出：

["student_id", "final_score", "group_name"]

推荐先用普通循环，不要一开始就写列表推导式：

columns = [" Student ID ", "Final Score", "Group Name"]
clean_columns = []

for name in columns:
    clean_name = name.strip().lower().replace(" ", "_")
    clean_columns.append(clean_name)

print(clean_columns)

验收：你能解释：

clean_columns = [] 为什么要先创建空列表？
for name in columns 每次拿到的是什么？
append 是把元素加到哪里？

1.4 列表过滤：去掉缺失值和异常值

真实数据经常有缺失值。Python 里常用 None 表示“没有值”。有些旧数据会用 -999 这种特殊数字表示异常占位。

你要学的语法

语法	含义
`x is not None`	判断 x 不是缺失值
`x != -999`	判断 x 不是异常占位值
`and`	两个条件都要满足
`append`	把合格数据放进新列表

最小例子：

values = [1.2, None, 3.4, -999, 2.8]
clean = []

for x in values:
    if x is not None and x != -999:
        clean.append(x)

print(clean)

代码逻辑

values 保存原始数据
clean 保存清洗后的数据
for x in values 逐个检查
if 条件成立，说明 x 是有效值
clean.append(x) 保存有效值

这里不要急着用“高级写法”。先把循环和条件看懂。

Exercise A-03：过滤缺失值

输入：

values = [1.2, None, 3.4, -999, 2.8, None, 5.0]

要求输出：

有效数据列表。
有效样本数量。
有效数据均值。

提示：均值仍然用 sum(clean) / len(clean)。

验收：如果 clean 为空，你能说明为什么不能直接除以 len(clean)。

1.5 条件函数：把分数变成等级

现在开始写第一个函数。函数的作用是：给一个输入，返回一个结果。

函数怎么用

你希望这样使用它：

grade = score_to_grade(95)
print(grade)

也就是说，score_to_grade 接收一个分数，返回一个等级。

函数定义长什么样

def score_to_grade(score: float) -> str:
    if score >= 90:
        return "A"
    if score >= 80:
        return "B"
    if score >= 70:
        return "C"
    return "D"

代码逻辑

def                      定义函数
score_to_grade           函数名
score: float             参数叫 score，期望是浮点数
-> str                   返回值期望是字符串
if score >= 90           如果分数至少 90
return "A"               立刻返回 A，函数结束
return "D"               前面条件都不满足，返回 D

注意：return 后函数就结束了。因此这里不一定需要 elif。

Exercise A-04：分数等级

文件：src/basics.py

实现：

def score_to_grade(score: float) -> str:
    if score >= 90:
        return "A"
    if score >= 80:
        return "B"
    if score >= 70:
        return "C"
    return "D"


print(score_to_grade(95))
print(score_to_grade(85))
print(score_to_grade(75))
print(score_to_grade(60))

然后加上自检：

assert score_to_grade(95) == "A"
assert score_to_grade(85) == "B"
assert score_to_grade(75) == "C"
assert score_to_grade(60) == "D"

验收：你能解释为什么 85 不会返回 A。

1.6 `match`：根据命令选择行为

match 类似其他语言里的 switch，适合处理“命令分发”。

函数怎么用

你希望这样调用：

message = handle_command("summary")
print(message)

最小例子

def handle_command(command: str) -> str:
    match command:
        case "summary":
            return "run data summary"
        case "metrics":
            return "run metrics"
        case "backtest":
            return "run backtest"
        case _:
            return "unknown command"

代码逻辑

match command       检查 command 的值
case "summary"      如果值等于 summary
return ...          返回对应说明
case _              兜底分支，匹配所有未知输入

case _ 很重要。没有它，用户输错命令时，你的程序可能没有清楚反馈。

Exercise A-05：实现命令分发

文件：src/basics.py

要求支持：

summary
metrics
backtest

验收：

assert handle_command("summary") == "run data summary"
assert handle_command("metrics") == "run metrics"
assert handle_command("backtest") == "run backtest"
assert handle_command("abc") == "unknown command"

2. Week B：函数、参数、数据结构、编码风格

Week B 的目标是把零散代码变成可复用函数。以后你写 pandas、sklearn、PyTorch，都离不开函数。

2.1 均值函数：从公式变成可复用函数

函数怎么用

你希望以后这样写：

from stats_utils import mean

score_mean = mean([80, 92, 75])
print(score_mean)

这样比每次写 sum(xs) / len(xs) 更清楚。

先写最小版本

def mean(xs: list[float]) -> float:
    return sum(xs) / len(xs)

这个版本有问题：如果 xs 是空列表，会发生除以 0。

加上错误处理

def mean(xs: list[float]) -> float:
    """Return arithmetic mean of a non-empty list."""
    if not xs:
        raise ValueError("xs must not be empty")
    return sum(xs) / len(xs)

代码逻辑

if not xs                         如果列表为空
raise ValueError(...)             主动报错，告诉调用者输入不合法
return sum(xs) / len(xs)          正常情况下返回均值

raise 不是程序崩溃的坏习惯。相反，它是在错误输入出现时给出明确解释。

Exercise B-01：统计函数库

文件：src/stats_utils.py

实现：

def mean(xs: list[float]) -> float:
    """Return arithmetic mean of a non-empty list."""
    if not xs:
        raise ValueError("xs must not be empty")
    return sum(xs) / len(xs)


def variance(xs: list[float]) -> float:
    """Return population variance of a non-empty list."""
    m = mean(xs)
    return mean([(x - m) ** 2 for x in xs])

然后自己补：

def std(xs: list[float]) -> float:
    ...


def covariance(xs: list[float], ys: list[float]) -> float:
    ...


def zscore(xs: list[float]) -> list[float]:
    ...

验收：

assert mean([1, 2, 3]) == 2
assert variance([1, 2, 3]) == 2 / 3

思考：variance 里为什么可以调用自己写的 mean？

2.2 默认参数：不要让多个调用共享同一个列表

Python 官方教程特别提醒：默认参数只在函数定义时创建一次。

错误函数怎么用会出问题

def add_tag_bad(tag: str, tags: list[str] = []) -> list[str]:
    tags.append(tag)
    return tags

print(add_tag_bad("ai"))
print(add_tag_bad("quant"))

你可能以为第二次输出只有 quant，但实际会把第一次的 ai 也留下。

正确函数怎么用

def add_tag(tag: str, tags: list[str] | None = None) -> list[str]:
    if tags is None:
        tags = []
    tags.append(tag)
    return tags

代码逻辑

tags 默认是 None              不共享可变列表
if tags is None               如果调用者没传列表
    tags = []                 创建一个新的空列表
tags.append(tag)              加入标签
return tags                   返回结果

Exercise B-02：安全默认参数

文件：src/stats_utils.py

实现：

def add_tag(tag: str, tags: list[str] | None = None) -> list[str]:
    if tags is None:
        tags = []
    tags.append(tag)
    return tags

验收：

assert add_tag("ai") == ["ai"]
assert add_tag("quant") == ["quant"]
assert add_tag("python", ["study"]) == ["study", "python"]

2.3 数据结构：选择合适的容器

Python 的数据结构不是装饰品。选错结构，代码会绕。

结构	适合保存	示例
`list`	有顺序、可重复的数据	收益率序列
`tuple`	固定组合结果	`(train, valid)`
`set`	去重、集合差异	用户 ID 集合
`dict`	名字到值的映射	指标字典

函数怎么用

你希望指标函数返回清楚的字典：

counts = confusion_counts([1, 0, 1], [1, 0, 0])
print(counts["tp"])

代码逻辑

二分类里：

y_true = 1, y_pred = 1 → tp
y_true = 0, y_pred = 0 → tn
y_true = 0, y_pred = 1 → fp
y_true = 1, y_pred = 0 → fn

Exercise B-03：指标字典

文件：src/metrics.py

实现：

def accuracy(y_true: list[int], y_pred: list[int]) -> float:
    if len(y_true) != len(y_pred):
        raise ValueError("length mismatch")
    if not y_true:
        raise ValueError("empty labels")

    correct = 0
    for a, b in zip(y_true, y_pred):
        if a == b:
            correct += 1
    return correct / len(y_true)


def confusion_counts(y_true: list[int], y_pred: list[int]) -> dict[str, int]:
    if len(y_true) != len(y_pred):
        raise ValueError("length mismatch")

    counts = {"tp": 0, "tn": 0, "fp": 0, "fn": 0}
    for a, b in zip(y_true, y_pred):
        if a == 1 and b == 1:
            counts["tp"] += 1
        elif a == 0 and b == 0:
            counts["tn"] += 1
        elif a == 0 and b == 1:
            counts["fp"] += 1
        elif a == 1 and b == 0:
            counts["fn"] += 1
        else:
            raise ValueError("labels must be 0 or 1")
    return counts

验收：

y_true = [1, 0, 1, 1]
y_pred = [1, 0, 0, 1]
assert accuracy(y_true, y_pred) == 0.75
assert confusion_counts(y_true, y_pred) == {"tp": 2, "tn": 1, "fp": 0, "fn": 1}

2.4 列表推导式：把循环写短，但不要写晦涩

列表推导式是 Python 常用写法。它适合“从旧列表生成新列表”。

普通循环写法

names = [" Alice ", "", "BOB", "  Carol"]
clean = []

for name in names:
    name = name.strip()
    if name:
        clean.append(name.lower())

函数怎么用

clean = [name.strip().lower() for name in names if name.strip()]

代码逻辑

name.strip().lower()      新列表里的元素长什么样
for name in names         从 names 里逐个拿元素
if name.strip()           只保留非空字符串

Exercise B-04：批量清洗字符串

输入：

names = [" Alice ", "", "BOB", "  Carol"]

输出：

["alice", "bob", "carol"]

验收：你能把列表推导式改回普通 for 循环。

3. Week C：模块、文件、JSON、异常、CLI

Week C 的目标是把“能跑的脚本”变成“能复用的小工具”。这是从学习代码走向项目代码的关键一步。

3.1 模块：把函数放进文件

当代码变长，不应该所有东西都写在一个文件里。

src/
├── stats_utils.py      统计函数
├── metrics.py          模型指标函数
├── data_io.py          文件读写函数
└── cli.py              命令行入口

模块怎么用

如果 src/stats_utils.py 里有：

def mean(xs: list[float]) -> float:
    if not xs:
        raise ValueError("xs must not be empty")
    return sum(xs) / len(xs)

那么其他文件可以导入：

from stats_utils import mean

print(mean([1, 2, 3]))

代码逻辑

from stats_utils import mean       从 stats_utils.py 里拿 mean 函数
mean([1, 2, 3])                    调用这个函数

Exercise C-01：模块拆分

要求：

mean、variance 放到 src/stats_utils.py。
accuracy、confusion_counts 放到 src/metrics.py。
src/cli.py 负责调用它们。

验收：

python src/cli.py

能看到一个最小输出，例如：

mean = 2.0
accuracy = 0.75

3.2 文件读取：从磁盘拿数据

真实项目不会永远把数据写死在代码里。你要学会从 CSV 文件读数据。

函数怎么用

你希望这样使用：

from pathlib import Path
from data_io import read_scores_csv

rows = read_scores_csv(Path("data/scores.csv"))
print(rows)

你要学的标准库

模块/对象	作用
`pathlib.Path`	表示文件路径
`csv.DictReader`	把 CSV 每一行读成字典
`with ... as f`	打开文件，并确保最后关闭

最小数据

文件：data/scores.csv

student_id,group,score
s1,A,80
s2,A,92
s3,B,75
s4,B,88

代码逻辑

import csv
from pathlib import Path


def read_scores_csv(path: Path) -> list[dict[str, str]]:
    with path.open("r", encoding="utf-8", newline="") as f:
        return list(csv.DictReader(f))

逐行解释：

import csv                         使用 Python 标准库 csv
from pathlib import Path            使用 Path 表示路径
path.open(...)                      打开文件
encoding="utf-8"                   按 UTF-8 读取文本
newline=""                         让 csv 模块正确处理换行
csv.DictReader(f)                   第一行作为列名，每行变成 dict
list(...)                           把可迭代结果转成列表

Exercise C-02：CSV 读写

文件：src/data_io.py

实现 read_scores_csv，然后写一个函数把 score 转成数字：

def parse_scores(rows: list[dict[str, str]]) -> list[float]:
    scores = []
    for row in rows:
        scores.append(float(row["score"]))
    return scores

验收：

rows = read_scores_csv(Path("data/scores.csv"))
scores = parse_scores(rows)
assert scores == [80.0, 92.0, 75.0, 88.0]

3.3 JSON：保存配置

CSV 适合表格数据。JSON 适合配置。

函数怎么用

你希望这样读取配置：

config = read_json(Path("config.json"))
print(config["input"])

最小配置

文件：config.json

{
  "input": "data/scores.csv",
  "output": "reports/data_summary.md",
  "pass_score": 60
}

代码逻辑

import json
from pathlib import Path


def read_json(path: Path) -> dict:
    text = path.read_text(encoding="utf-8")
    return json.loads(text)

逐行解释：

path.read_text(...)     把整个文件读成字符串
json.loads(text)        把 JSON 字符串转成 Python dict
return                  把 dict 返回给调用者

Exercise C-03：实验配置

文件：src/data_io.py

实现：

def read_json(path: Path) -> dict:
    text = path.read_text(encoding="utf-8")
    return json.loads(text)

验收：

config = read_json(Path("config.json"))
assert config["input"] == "data/scores.csv"
assert config["pass_score"] == 60

3.4 异常：让错误变得可理解

初学者常见错误是：程序错了，但不知道错在哪里。异常处理不是为了隐藏错误，而是为了把错误解释清楚。

函数怎么用

你希望用户给错路径时看到：

input file not found: data/missing.csv

而不是一大段看不懂的 traceback。

错误写法

try:
    rows = read_scores_csv(path)
except Exception:
    pass

这会把错误吞掉。不要这样写。

正确写法

try:
    rows = read_scores_csv(path)
except FileNotFoundError as exc:
    raise SystemExit(f"input file not found: {path}") from exc

代码逻辑

try                         尝试运行可能失败的代码
except FileNotFoundError     只捕获文件不存在这一类错误
as exc                       保存原始错误
raise SystemExit(...)        给命令行用户一个清楚提示
from exc                     保留原始错误链，方便调试

Exercise C-04：异常条件

在 src/data_io.py 或 src/cli.py 中处理：

输入文件不存在。
CSV 缺少 score 列。
score 不能转为数字。
输出目录不存在时自动创建。

验收：故意把输入路径写错，程序必须输出清楚错误，而不是静默结束。

3.5 CLI：从命令行传参数

CLI 是 command line interface。你可以不用改代码，只通过命令传不同输入输出。

命令怎么用

目标命令：

python src/cli.py summary --input data/scores.csv --output reports/data_summary.md

含义：

python src/cli.py        运行 cli.py
summary                  子任务：做数据摘要
--input ...              输入文件
--output ...             输出报告

代码逻辑

from argparse import ArgumentParser


def parse_args():
    parser = ArgumentParser(description="Summarize score CSV")
    parser.add_argument("command", choices=["summary"])
    parser.add_argument("--input", required=True)
    parser.add_argument("--output", required=True)
    return parser.parse_args()

逐行解释：

ArgumentParser(...)              创建参数解析器
add_argument("command")          读取位置参数 summary
choices=["summary"]              限制只能输入 summary
add_argument("--input")          读取输入路径
required=True                    必须提供这个参数
parse_args()                     从命令行解析参数

Exercise C-05：生成 Markdown 摘要报告

文件：src/cli.py

目标：读 data/scores.csv，输出 reports/data_summary.md。

报告至少包含：

# Data Summary

- rows: 4
- mean score: 83.75
- min score: 75.0
- max score: 92.0

验收命令：

python src/cli.py summary --input data/scores.csv --output reports/data_summary.md
cat reports/data_summary.md

4. Week D：类、迭代器、标准库、浮点数、综合项目

Week D 的目标是把前面的函数组织成更像真实项目的结构，并理解两个 AI / Quant 特别容易踩坑的东西：迭代器和浮点数。

4.1 dataclass：保存配置对象

类不是必须一开始学，但你需要读懂这种写法，因为后续 PyTorch、sklearn、Quant 回测都会有配置对象。

类怎么用

你希望这样创建配置：

config = ExperimentConfig(input_path="data/scores.csv", output_dir="reports")
print(config.input_path)

代码逻辑

from dataclasses import dataclass


@dataclass(frozen=True)
class ExperimentConfig:
    input_path: str
    output_dir: str
    seed: int = 42

逐行解释：

@dataclass(frozen=True)       自动生成初始化方法，并禁止修改字段
class ExperimentConfig        定义一个配置类型
input_path: str               输入路径字段
output_dir: str               输出目录字段
seed: int = 42                随机种子，默认是 42

Exercise D-01：实验配置类

文件：src/experiment.py

实现 ExperimentConfig，然后运行：

config = ExperimentConfig(input_path="data/scores.csv", output_dir="reports")
assert config.seed == 42

验收：你能解释 config.input_path 和字典 config["input_path"] 的区别。

4.2 迭代器和生成器：逐行处理数据

如果文件很大，不应该一次把所有内容读进内存。生成器可以一行一行地产生数据。

函数怎么用

for line in iter_non_empty_lines(Path("notes/raw.txt")):
    print(line)

代码逻辑

from pathlib import Path


def iter_non_empty_lines(path: Path):
    with path.open("r", encoding="utf-8") as f:
        for line in f:
            line = line.strip()
            if line:
                yield line

逐行解释：

for line in f          文件对象可以逐行迭代
line.strip()           去掉换行和两边空格
if line                空字符串会被当成 False
yield line             产出一行，但函数不一次性结束

return 是一次性返回。yield 是“这次先给你一个值，下次循环再继续”。

Exercise D-02：逐行读取

文件：src/data_io.py

实现 iter_non_empty_lines。

验收：输入文件中有空行时，输出里不能包含空字符串。

4.3 浮点数：不要用 `==` 比较小数

Python 官方教程第 15 章非常重要。它解释了为什么很多小数不能被二进制浮点数精确表示。

函数怎么用

错误比较：

0.1 + 0.1 + 0.1 == 0.3

推荐比较：

import math

math.isclose(0.1 + 0.1 + 0.1, 0.3)

代码逻辑

0.1 在二进制里不能精确表示
三个近似值相加，结果仍然是近似值
== 要求完全相等，所以可能失败
math.isclose 允许非常小的误差

这对 Quant 特别重要。收益率、波动率、Sharpe、loss 都是浮点数，不要随便用 == 判断。

Exercise D-03：浮点复盘报告

文件：reports/floating_point_notes.md

写清楚：

为什么 0.1 + 0.2 != 0.3。
round 是显示/近似，不是改变真实存储。
为什么金融收益率和模型 loss 不能用 == 比较小数。
什么时候用 math.isclose。

验收：报告里必须有一段你自己的解释，不要只复制代码。

4.4 收益率函数：从价格变成收益率

Quant 的最小输入通常是价格序列。最小计算是收益率。

函数怎么用

returns = pct_change([100, 101, 99])
print(returns)

期望：

[None, 0.010000000000000009, -0.01980198019801982]

第一天没有前一天价格，所以收益率是 None。

代码逻辑

def pct_change(values: list[float]) -> list[float | None]:
    returns: list[float | None] = [None]
    for prev, curr in zip(values, values[1:]):
        if prev == 0:
            returns.append(None)
        else:
            returns.append(curr / prev - 1)
    return returns

逐行解释：

returns = [None]             第一项没有前值
values[1:]                   从第二个价格开始
zip(values, values[1:])      组成相邻价格对
prev == 0                    防止除以 0
curr / prev - 1              收益率公式
returns.append(...)          保存每一天收益率

Exercise D-04：收益率计算

文件：src/toy_backtest.py

实现 pct_change，验收：

import math

returns = pct_change([100, 101, 99])
assert returns[0] is None
assert math.isclose(returns[1], 0.01)
assert math.isclose(returns[2], 99 / 101 - 1)

4.5 shift：避免未来函数

回测里最危险的错误之一是未来函数：用今天收盘后的信息，在今天就交易。

如果你根据今天收益率生成信号，那么真正能执行的仓位应该从下一天开始。

函数怎么用

signals = [1, 0, 1]
positions = shift(signals, fill=0)
print(positions)

输出：

[0, 1, 0]

含义：

第 1 天没有前一天信号，所以仓位 0
第 2 天使用第 1 天信号
第 3 天使用第 2 天信号

代码逻辑

def shift(values: list[int], fill: int = 0) -> list[int]:
    return [fill] + values[:-1]

逐行解释：

values[:-1]       去掉最后一个元素
[fill] + ...      在最前面补一个默认值

Exercise D-05：仓位滞后

文件：src/toy_backtest.py

实现 shift，验收：

assert shift([1, 0, 1], fill=0) == [0, 1, 0]
assert shift([1], fill=0) == [0]

你必须能解释：为什么不能直接 position = signal。

4.6 Toy Quant Backtest：综合练习

现在把前面学到的东西串起来。

读 CSV
  ↓
取 close 列
  ↓
计算收益率
  ↓
根据收益率生成 signal
  ↓
shift(signal) 得到 position
  ↓
计算策略收益
  ↓
输出 Markdown 报告

输入数据

文件：data/prices.csv

date,close
2024-01-01,100
2024-01-02,101
2024-01-03,99
2024-01-04,102

关键函数怎么用

rows = read_prices(Path("data/prices.csv"))
closes = [float(row["close"]) for row in rows]
returns = pct_change(closes)
signals = [1 if r is not None and r > 0 else 0 for r in returns]
positions = shift(signals, fill=0)

代码逻辑

read_prices              从 CSV 读取字典列表
float(row["close"])      把文本价格转成数字
pct_change               价格 → 收益率
signal                   收益率为正则看多，否则空仓
shift                    信号滞后一日，避免未来函数
position * return        仓位乘收益率，得到策略收益

Exercise D-06：完整 toy backtest

文件：src/toy_backtest.py

要求：

用 csv 读取数据。
用 pct_change 计算收益率。
用 signal = 1 if return > 0 else 0 生成简单信号。
用 position = shift(signal) 避免未来函数。
用 math.isclose 做浮点验收。
输出 reports/backtest_report.md。

报告至少包含：

# Toy Backtest Report

- rows: 4
- total return: ...
- max daily return: ...
- min daily return: ...
- warning: signal is shifted by one day to avoid look-ahead bias

验收命令：

python src/toy_backtest.py --input data/prices.csv --output reports/backtest_report.md
cat reports/backtest_report.md

4.7 doctest：把示例变成自检

小函数可以直接在 docstring 里写示例。doctest 会执行这些示例。

函数怎么用

python src/stats_utils.py

如果 doctest 通过，通常没有输出。如果失败，会显示哪里不一致。

代码逻辑

def mean(xs: list[float]) -> float:
    """
    Return arithmetic mean.

    >>> mean([1, 2, 3])
    2.0
    """
    if not xs:
        raise ValueError("xs must not be empty")
    return sum(xs) / len(xs)


if __name__ == "__main__":
    import doctest
    doctest.testmod()

逐行解释：

>>> mean([1, 2, 3])       docstring 里的交互式示例
2.0                       期望输出
doctest.testmod()         扫描当前模块里的 docstring 示例并执行

Exercise D-07：给统计函数加 doctest

文件：src/stats_utils.py

至少给 mean 和 variance 加 doctest。

验收：

python src/stats_utils.py

没有失败信息。

5. 最终检查清单

完成后，你应该能运行：

python src/basics.py
python src/cli.py summary --input data/scores.csv --output reports/data_summary.md
python src/toy_backtest.py --input data/prices.csv --output reports/backtest_report.md
python src/stats_utils.py

最终交付：

src/basics.py
src/stats_utils.py
src/metrics.py
src/data_io.py
src/cli.py
src/toy_backtest.py
src/experiment.py
reports/data_summary.md
reports/backtest_report.md
reports/floating_point_notes.md
notes/official_tutorial_mapping.md

6. 评分标准

项目	分值	合格标准
环境可复现	15	README 写清环境和命令，`.venv` 不入 Git
基础语法	15	能写数字、字符串、列表、控制流练习
函数质量	20	有类型提示、docstring、错误处理、assert/doctest
数据结构	10	list/dict/set/tuple 使用合适
模块化	15	`src/` 拆分清楚，导入关系明确
文件/CLI	15	能读 CSV/JSON，能输出报告，CLI 可运行
综合项目	10	toy backtest 或数据摘要项目可复现

低于 80 分：不要进入 pandas/sklearn。先补 Python。

7. 每日复盘模板

# Day X Python Official Practice

## 今天读的官方章节

## 今天学会的函数或语法

## 今天写的代码

## 每一行代码的逻辑解释

## 今天遇到的错误

## 我现在还解释不清的地方

## 明天继续

最低日任务：

读官方文档 20 分钟
跟着手册敲代码 40 分钟
运行和修错 20 分钟
写复盘 10 分钟

8. 什么时候可以进入 pandas / sklearn / PyTorch

不要用“看过 Python 教程”当作标准。用下面这些能力判断：

能解释 list / dict / set / tuple 的区别
能写带参数和返回值的函数
能处理空列表、路径不存在、类型转换失败
能把函数拆进不同模块
能从命令行传 input/output
能读 CSV 和 JSON
能输出 Markdown 报告
能解释为什么回测要 shift signal
能解释为什么浮点数不能直接 == 比较

这些都能做到，再进入 pandas / sklearn / PyTorch。否则后面遇到的错误看起来像库的问题，其实是 Python 基础问题。

Week 17：项目工程化、CLI 入口与可复现实验

Sun, 26 Jul 2026 09:00:00 GMT

Oh My Pi / weekly tutorial / week17-project-engineering

miku@cachyos:~/Code/python-learning$ omp teach week17-project-engineering --fish-first --step-by-step

source591 行教学文档

weekWeek 17

shellfish-first 命令版

backlink20 周计划

Week 17：项目工程化、CLI 入口与可复现实验

返回总计划：USTC 统计 + AI / 量化 20 周成长计划

Week 17 的目标是把前面做过的项目整理成一个干净、可运行、可复现的仓库。对 USTC 统计学生来说，这一步非常重要：老师、同学、面试官或未来的你，不会只看“我跑过一次”，而会看项目是否能被别人重新运行。

本文命令默认使用 fish shell。进入项目后激活环境：

ompfish

source .venv/bin/activate.fish

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	README、seed、依赖、运行说明、复现
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`README.md`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

mkdir -p src reports figures outputs
python src/train.py --config configs/baseline.yaml
python src/evaluate.py --model outputs/best.pt
python src/make_report.py --output reports/final_report.md

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `README.md`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周学习目标

完成本周后，你应该能把一个项目整理到以下状态：

目录结构清楚：代码、数据、报告、图片、配置分离。
没有临时代码、随手命名的 notebook、无用输出文件。
使用 uv 管理依赖，pyproject.toml 能说明项目需要什么包。
有 CLI 入口，可以用一条命令运行主流程。
README 写清楚安装、运行、输出、项目结构和复现步骤。
随机种子固定，输出结果可复查。
.gitignore 不提交 .venv、缓存、大文件和临时文件。

建议最终结构：

ompprompt

quant-backtest-mini/
├── README.md
├── pyproject.toml
├── uv.lock
├── .gitignore
├── data/
│   ├── README.md
│   └── prices.csv
├── figures/
│   ├── equity_curve.png
│   ├── drawdown.png
│   └── cost_sensitivity.png
├── reports/
│   ├── week16_metrics_by_split.csv
│   ├── week16_cost_sensitivity.csv
│   └── week16_quant_project_report.md
└── src/
    └── quant_backtest_mini/
        ├── __init__.py
        ├── __main__.py
        ├── backtest.py
        ├── cli.py
        ├── metrics.py
        └── report.py

注意：这里的 data/README.md 是项目内部数据说明，不是本博客源文档。Week 17 允许你在自己的量化项目里写 README；但本教程文档本身只放在 docs/week17-project-engineering.md。

2. 前置条件

你需要已经有一个待整理项目，例如 Week 15-16 的 quant-backtest-mini。

进入项目：

ompfish

cd ~/Code/ustc-stat-ai-quant/quant-backtest-mini
source .venv/bin/activate.fish
pwd
ls

确认你看到：

ompprompt

pyproject.toml
src
reports
figures

如果项目不在这个路径，进入你自己的项目根目录即可。判断标准：当前目录应包含 pyproject.toml，而不是只在总学习目录。

3. 先做清点，不急着重构

工程化第一步不是乱改文件，而是弄清楚现在有什么。

ompfish

find . -maxdepth 3 -type f | sort

这条命令用于人工检查项目文件。重点找：

Untitled.ipynb、test.py、tmp.py 这类临时文件。
重复保存的结果，例如 result_final_final.csv。
不该提交的缓存，例如 __pycache__。
是否有数据说明。
是否有 README。

如果你不确定某个文件是否还在用，先不要删。可以用 VS Code 搜索文件名或导入名。

4. 建立 `.gitignore`

如果项目还没有 .gitignore，创建：

ompfish

code .gitignore

写入：

ompprompt

.venv/
__pycache__/
*.pyc
.ipynb_checkpoints/
.ruff_cache/
.mypy_cache/
.pytest_cache/
.DS_Store
*.log
.env
.env.*

解释：

条目	为什么忽略
`.venv/`	虚拟环境很大，别人应自己用 uv 创建
`__pycache__/`	Python 运行缓存，不是源码
`.ipynb_checkpoints/`	Jupyter 自动缓存
`*.log`	临时日志通常不可复现
`.env`	可能包含密钥或本机路径

检查 Git 状态：

ompfish

git status --short

如果项目还没有 Git 仓库，可以初始化：

ompfish

git init

不要提交前先确认 .venv/ 没有出现在 git status --short 里。

5. 固定依赖：用 uv 管理环境

查看当前依赖：

ompfish

cat pyproject.toml

如果 Week 15-16 用到了 pandas、numpy、matplotlib、scikit-learn，确保它们在依赖中：

ompfish

uv add pandas numpy matplotlib scikit-learn

如果你没有用 scikit-learn，不要为了好看添加它。依赖越少越容易复现。

重新同步环境：

ompfish

uv sync
source .venv/bin/activate.fish

解释：

uv add：把依赖写进 pyproject.toml，并更新锁文件。
uv sync：根据项目配置创建或同步 .venv。
uv.lock：记录具体版本，帮助别人复现环境。

如果你需要导出传统 requirements：

ompfish

uv export --format requirements-txt --output-file requirements.txt

但对新项目，优先保留 pyproject.toml 和 uv.lock。

6. 整理 Python 包结构

推荐把业务代码放在 src/quant_backtest_mini/。

检查：

ompfish

ls src/quant_backtest_mini

应至少包含：

ompprompt

__init__.py
backtest.py
metrics.py
report.py

如果你现在只有一个 backtest.py 放在项目根目录，可以移动：

ompfish

mkdir -p src/quant_backtest_mini
mv backtest.py src/quant_backtest_mini/backtest.py
printf "" > src/quant_backtest_mini/__init__.py

移动后，要把导入改成包内导入。例如：

omppython

from quant_backtest_mini.metrics import summarize

而不是依赖当前工作目录碰巧能找到文件。

7. 添加 CLI 入口

CLI 的作用是让别人不用打开 Python 文件，也能运行项目。

创建 src/quant_backtest_mini/cli.py：

omppython

import argparse
from quant_backtest_mini.backtest import load_prices, plot_results, run_backtest
from quant_backtest_mini.metrics import summarize
def build_parser() -> argparse.ArgumentParser:
parser = argparse.ArgumentParser(description=“Run a mini momentum backtest.”)
parser.add_argument(“—data”, default=“data/prices.csv”, help=“Path to price CSV.”)
parser.add_argument(“—lookback”, type=int, default=20, help=“Momentum lookback days.”)
parser.add_argument(“—cost-bps”, type=float, default=5.0, help=“Transaction cost in bps.”)
return parser
def main() -> None:
parser = build_parser()
args = parser.parse_args()
plain prices = load_prices(args.data)
result = run_backtest(prices, lookback=args.lookback, cost_bps=args.cost_bps)
summary = summarize(result[“net_strategy_return”], result[“turnover”])
plain for key, value in summary.items():
print(f”{key}: {value:.4f}”)
plain plot_results(result)
result.to_csv(“reports/backtest_daily_results.csv”)
print(“saved reports/backtest_daily_results.csv and figures”)
if name == “main”:
main()

再创建 src/quant_backtest_mini/__main__.py：

omppython

from quant_backtest_mini.cli import main
if name == “main”:
main()

现在可以运行：

ompfish

python -m quant_backtest_mini --data data/prices.csv --lookback 20 --cost-bps 5

如果提示找不到模块，检查是否已用 uv sync 安装当前项目。也可以在 pyproject.toml 里确认项目包配置是否正确。

8. 在 `pyproject.toml` 中添加命令入口

打开：

ompfish

code pyproject.toml

在文件中加入脚本入口，具体位置通常在依赖列表之后：

omptoml

[project.scripts]
quant-backtest-mini = "quant_backtest_mini.cli:main"

然后同步：

ompfish

uv sync
source .venv/bin/activate.fish

运行：

ompfish

quant-backtest-mini --data data/prices.csv --lookback 20 --cost-bps 5

这就是一个项目级 CLI。以后 README 里可以直接写这条命令。

9. 固定随机种子和运行参数

如果项目里有任何随机过程，例如模拟数据、随机森林、抽样，都要固定随机种子。

示例：

omppython

RANDOM_SEED = 42

在 numpy 中：

omppython

rng = np.random.default_rng(RANDOM_SEED)

在 scikit-learn 中：

omppython

RandomForestClassifier(random_state=RANDOM_SEED)

同时，把核心运行参数写进 README：

ompprompt

默认参数：lookback=20, cost_bps=5
执行假设：t 日收盘生成信号，t+1 日持仓
随机种子：42

可复现不是“我电脑上能跑”，而是别人能知道你用了什么参数跑。

10. 写 README

打开 README：

ompfish

code README.md

推荐结构：

ompprompt

# Quant Backtest Mini
A minimal momentum backtest project for learning time-series validation and quant metrics.
What this project does

Loads daily close prices.
Computes daily returns.
Builds a simple N-day momentum signal.
Applies a one-day signal delay to avoid look-ahead bias.
Subtracts transaction costs based on turnover.
Reports annual return, annual volatility, Sharpe, max drawdown, and turnover.

Project structure
写出 data、src、reports、figures 分别放什么。
Setup
uv sync
source .venv/bin/activate.fish
Run
quant-backtest-mini —data data/prices.csv —lookback 20 —cost-bps 5
Outputs

reports/backtest_daily_results.csv
figures/equity_curve.png
figures/drawdown.png

Reproducibility

Python dependencies are managed by uv.
Lock file: uv.lock
Random seed: 42 if simulated data is regenerated.
Default parameters: lookback=20, cost_bps=5.

Limitations

Educational project only.
No slippage model.
No liquidity constraints.
No live trading.
Results do not imply future profitability.

README 要让别人能在 3 分钟内知道：这是什么、怎么装、怎么跑、会生成什么、限制是什么。

11. 数据说明

如果 data/prices.csv 是模拟数据或小样本数据，必须说明来源。可以创建：

ompfish

code data/README.md

写入：

ompprompt

# Data
prices.csv contains daily close prices used for the mini backtest.
Columns:

date: trading date
close: closing price

Source:

Simulated data generated for learning, or replace this line with the real data source.

Notes:

This data is for educational backtesting only.
Do not treat results as investment advice.

如果真实数据体积很大，不要直接提交大文件。README 中写清楚下载方式，或只提交小样本。

12. 可复现运行检查

从一个干净终端重新跑：

ompfish

cd ~/Code/ustc-stat-ai-quant/quant-backtest-mini
uv sync
source .venv/bin/activate.fish
quant-backtest-mini --data data/prices.csv --lookback 20 --cost-bps 5

检查输出文件：

ompfish

ls reports figures

用 Python 检查关键文件存在：

ompfish

python -c "from pathlib import Path; required = ['README.md', 'pyproject.toml', 'uv.lock', 'src/quant_backtest_mini/cli.py', 'src/quant_backtest_mini/__main__.py', 'reports/backtest_daily_results.csv', 'figures/equity_curve.png', 'figures/drawdown.png']; missing = [p for p in required if not Path(p).exists()]; print('missing:', missing); raise SystemExit(1 if missing else 0)"

这一步比“我觉得整理好了”可靠。

13. Git 提交前检查

查看状态：

ompfish

git status --short

你希望看到的是源码、配置、报告、图片、小数据说明，而不是虚拟环境和缓存。

常见不该提交：

ompprompt

.venv/
__pycache__/
.ipynb_checkpoints/
*.log

添加文件：

ompfish

git add README.md pyproject.toml uv.lock .gitignore data src reports figures

提交：

ompfish

git commit -m "Organize reproducible quant backtest project"

如果只是课程练习，也可以暂不推送远程仓库。但至少学会让本地历史清楚。

14. 清理临时代码

删除前先确认临时文件没有用。常见候选：

ompprompt

tmp.py
scratch.py
Untitled.ipynb
result_old.csv
result_final_final.csv

删除单个确认无用的文件：

ompfish

rm tmp.py

不要用危险的大范围删除命令。初学阶段宁愿手动删慢一点，也不要误删报告或数据。

15. 文件布局验收

执行：

ompfish

pwd
ls
ls src/quant_backtest_mini reports figures data

理想结构：

ompprompt

README.md
pyproject.toml
uv.lock
.gitignore
data/
figures/
reports/
src/

包目录至少包含：

ompprompt

__init__.py
__main__.py
backtest.py
cli.py
metrics.py
report.py

16. 练习

给 CLI 增加 --output 参数，让用户指定结果 CSV 保存路径。
给 CLI 增加 --no-plots 参数，在只想生成表格时不画图。
在 README 中加入一段“Methodology”，解释为什么 position = signal.shift(1)。
把 Week 16 的报告结论精简成 README 的 “Results summary”。
新建一个空目录，重新 clone 或复制项目，只按 README 运行，检查是否能复现。
请同学只看 README，不口头解释，让对方尝试运行；记录对方卡在哪里，再改 README。

17. 验收检查

在项目根目录执行：

ompfish

source .venv/bin/activate.fish
uv sync
quant-backtest-mini --data data/prices.csv --lookback 20 --cost-bps 5
python -c "from pathlib import Path; required = ['README.md', 'pyproject.toml', 'uv.lock', '.gitignore', 'src/quant_backtest_mini/cli.py', 'src/quant_backtest_mini/__main__.py']; missing = [p for p in required if not Path(p).exists()]; print('missing:', missing); raise SystemExit(1 if missing else 0)"

通过标准：

README 写清楚 setup、run、outputs、limitations。
uv sync 后能重新创建环境。
fish 激活命令写成 source .venv/bin/activate.fish。
CLI 可以一条命令运行主流程。
结果文件生成位置清楚。
.venv/、缓存和日志不会被提交。
随机种子、默认参数和交易假设写清楚。

18. 常见错误

错误 1：README 只有一句话

README 不是口号。至少要有项目说明、环境安装、运行命令、输出、限制。

错误 2：依赖只存在于本机环境

如果你手动 pip install 过，但没有写进 pyproject.toml，别人无法复现。用 uv add 记录依赖。

错误 3：CLI 只能在某个目录碰巧运行

使用包导入，不要依赖当前工作目录下的相对导入。推荐 python -m quant_backtest_mini 或项目脚本入口。

错误 4：提交 `.venv`

.venv 不应提交。别人应该用 uv sync 创建自己的环境。

错误 5：结果不可复现

如果数据生成和模型训练有随机性，必须固定随机种子，并在 README 写明。

错误 6：工程化时顺手改策略结论

Week 17 的重点是整理项目，不是继续调参优化策略。不要为了 README 好看而更改 Week 16 的研究结论。

19. 下一步

进入 Week 18：把项目经历整理成简历和面试叙述。你现在应该能把这个量化小项目概括成一句专业描述：实现时间序列回测框架，包含 rolling validation、交易成本、最大回撤、Sharpe、换手率等指标，并分析样本外失效风险。

plain

Week 16：量化项目报告、回撤分析与样本外解释

Sun, 26 Jul 2026 08:00:00 GMT

Oh My Pi / weekly tutorial / week16-quant-project-report

miku@cachyos:~/Code/python-learning$ omp teach week16-quant-project-report --fish-first --step-by-step

source487 行教学文档

weekWeek 16

shellfish-first 命令版

backlink20 周计划

Week 16：量化项目报告、回撤分析与样本外解释

返回总计划：USTC 统计 + AI / 量化 20 周成长计划

Week 16 的目标是把 Week 15 的 mini backtest 写成一份诚实、可复查的量化项目报告。报告不是宣传策略有多赚钱，而是回答：策略规则是什么、数据怎么来、样本怎么切、成本怎么算、风险有多大、样本外是否仍有效、局限性在哪里。

本文命令默认使用 fish shell。进入项目后激活环境：

ompfish

source .venv/bin/activate.fish

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	annual return、vol、Sharpe、max drawdown、成本敏感性
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`reports/week16_quant_report.md`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

summary = {
    "annual_return": annual_return(net_ret),
    "annual_volatility": annual_volatility(net_ret),
    "sharpe": sharpe_ratio(net_ret),
    "max_drawdown": max_drawdown(net_ret),
}
print(summary)

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `reports/week16_quant_report.md`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周学习目标

完成本周后，你应该能产出一份 reports/week16_quant_project_report.md，包含：

策略规则和交易假设。
数据来源、时间范围、频率、缺失值处理。
样本内 / 样本外切分。
annual return、annual volatility、Sharpe、max drawdown、turnover、交易成本敏感性。
净值曲线、回撤曲线、月度收益或分段收益。
对“是否样本外有效”的谨慎判断。
对过拟合、交易成本、滑点、流动性、实盘约束的限制说明。

建议文件布局：

ompprompt

quant-backtest-mini/
├── data/
│   └── prices.csv
├── figures/
│   ├── equity_curve.png
│   ├── drawdown.png
│   ├── split_equity.png
│   └── cost_sensitivity.png
├── reports/
│   ├── week15_backtest_daily_results.csv
│   ├── week15_backtest_notes.md
│   ├── week16_metrics_by_split.csv
│   ├── week16_cost_sensitivity.csv
│   └── week16_quant_project_report.md
├── src/
│   └── quant_backtest_mini/
│       ├── __init__.py
│       ├── backtest.py
│       ├── metrics.py
│       └── report.py
├── README.md
└── pyproject.toml

如果 Week 15 项目还不完整，先回去补齐回测脚本，再开始写报告。

2. 前置条件

你需要已经完成：

Week 15 的 backtest.py 和 metrics.py。
至少能生成策略日收益、benchmark 日收益、turnover。
至少能画净值曲线和回撤曲线。
理解 position.shift(1) 为什么必要。

进入 Week 15 项目继续工作：

ompfish

cd ~/Code/ustc-stat-ai-quant/quant-backtest-mini
source .venv/bin/activate.fish

如果你重新打开了终端，必须重新激活虚拟环境。检查依赖：

ompfish

python -c "import pandas as pd; import numpy as np; import matplotlib; print('report env ok')"

3. 报告不是 README

README 负责告诉别人如何运行项目；量化报告负责解释研究结果。

区别：

文件	读者关心什么
`README.md`	怎么安装、怎么运行、项目结构是什么
`reports/week16_quant_project_report.md`	策略是否可靠、结果是否可解释、风险在哪里

Week 16 先写报告；Week 17 再把整个项目工程化。

4. 创建报告分析脚本

创建 src/quant_backtest_mini/report.py，用于生成分段指标和成本敏感性表。

omppython

from pathlib import Path
import matplotlib.pyplot as plt
import pandas as pd
from quant_backtest_mini.backtest import load_prices, run_backtest
from quant_backtest_mini.metrics import drawdown, equity_curve, summarize
FIGURE_DIR = Path(“figures”)
REPORT_DIR = Path(“reports”)
FIGURE_DIR.mkdir(exist_ok=True)
REPORT_DIR.mkdir(exist_ok=True)
def split_periods(result: pd.DataFrame) -> dict[str, pd.DataFrame]:
n = len(result)
train_end = int(n * 0.6)
test_start = int(n * 0.8)
return {
“in_sample”: result.iloc[
],
“validation”: result.iloc[train_end],
“out_of_sample”: result.iloc[test_start:],
“full_period”: result,
}
def metrics_by_split(result: pd.DataFrame) -> pd.DataFrame:
rows = []
for name, part in split_periods(result).items():
strategy = summarize(part[“net_strategy_return”], part[“turnover”])
benchmark = summarize(part[“benchmark_return”], pd.Series(0, index=part.index))
rows.append({“period”: name, “portfolio”: “strategy”, **strategy})
rows.append({“period”: name, “portfolio”: “benchmark”, **benchmark})
return pd.DataFrame(rows)
def cost_sensitivity(prices: pd.DataFrame, lookback: int) -> pd.DataFrame:
rows = []
for cost_bps in [0, 5, 10, 20, 50]:
result = run_backtest(prices, lookback=lookback, cost_bps=cost_bps)
summary = summarize(result[“net_strategy_return”], result[“turnover”])
rows.append({“cost_bps”: cost_bps, **summary})
return pd.DataFrame(rows)
def plot_split_equity(result: pd.DataFrame) -> None:
fig, ax = plt.subplots(figsize=(10, 5))
for name, part in split_periods(result).items():
if name == “full_period”:
continue
equity_curve(part[“net_strategy_return”]).plot(ax=ax, label=name)
ax.set_title(“Strategy Equity by Split”)
ax.set_ylabel(“growth of 1 within split”)
ax.legend()
fig.tight_layout()
fig.savefig(FIGURE_DIR / “split_equity.png”, dpi=150)
plt.close(fig)
def plot_cost_sensitivity(table: pd.DataFrame) -> None:
fig, axes = plt.subplots(2, 1, figsize=(10, 7), sharex=True)
axes[0].plot(table[“cost_bps”], table[“annual_return”], marker=“o”)
axes[0].set_title(“Annual Return vs Transaction Cost”)
axes[0].set_ylabel(“annual return”)
plain axes[1].plot(table[“cost_bps”], table[“sharpe_ratio”], marker=“o”)
axes[1].set_title(“Sharpe vs Transaction Cost”)
axes[1].set_xlabel(“cost bps”)
axes[1].set_ylabel(“sharpe”)
plain fig.tight_layout()
fig.savefig(FIGURE_DIR / “cost_sensitivity.png”, dpi=150)
plt.close(fig)
def main() -> None:
prices = load_prices()
result = run_backtest(prices, lookback=20, cost_bps=5)
plain split_metrics = metrics_by_split(result)
split_metrics.to_csv(REPORT_DIR / “week16_metrics_by_split.csv”, index=False)
print(split_metrics)
plain cost_table = cost_sensitivity(prices, lookback=20)
cost_table.to_csv(REPORT_DIR / “week16_cost_sensitivity.csv”, index=False)
print(cost_table)
plain plot_split_equity(result)
plot_cost_sensitivity(cost_table)
print(“saved Week 16 report tables and figures”)
if name == “main”:
main()

运行：

ompfish

python -m quant_backtest_mini.report

如果模块运行失败，可以临时使用：

ompfish

PYTHONPATH=src python src/quant_backtest_mini/report.py

但最终报告中建议保留模块运行方式，便于 Week 17 工程化。

5. 指标表怎么写进报告

打开生成的指标表：

ompfish

python -c "import pandas as pd; print(pd.read_csv('reports/week16_metrics_by_split.csv').round(4))"

报告中不要只复制一堆数字，要解释数字背后的含义。

示例解释方式：

ompprompt

样本内策略 Sharpe 高于 benchmark，但样本外 Sharpe 明显下降，说明策略可能依赖前期市场结构。样本外最大回撤接近 benchmark，没有明显风险优势。因此不能认为该动量规则已经稳定有效。

如果策略表现很差，也不要美化。量化报告里诚实说明失败原因，比硬说有效更专业。

6. 最大回撤分析

最大回撤不是一个抽象数字，它代表真实持有体验。

要回答：

最大回撤发生在什么时间段？
回撤持续多久？
当时 benchmark 是否也在回撤？
策略是否比 benchmark 更早恢复？
如果是自己真实资金，是否能承受？

可以加入辅助代码：

omppython

def drawdown_details(daily_returns: pd.Series) -> dict[str, object]:
    equity = equity_curve(daily_returns)
    dd = drawdown(equity)
    trough = dd.idxmin()
    peak = equity.loc[:trough].idxmax()
    recovery_candidates = equity.loc[trough:][equity.loc[trough:] >= equity.loc[peak]]
    recovery = recovery_candidates.index[0] if not recovery_candidates.empty else None
    return {
        "peak": peak,
        "trough": trough,
        "recovery": recovery,
        "max_drawdown": float(dd.loc[trough]),
    }

在报告中写成自然语言：

ompprompt

策略最大回撤从 YYYY-MM-DD 的净值高点开始，到 YYYY-MM-DD 达到最低点。样本结束前是否恢复：是/否。这个回撤说明策略在连续震荡或趋势反转时承压明显。

7. 样本切分：不要只看全样本

报告必须包含三段：

ompprompt

in_sample：用于观察和开发策略
validation：用于比较参数或模型
out_of_sample：最终检验，不反复调参

写报告时避免这种说法：

ompprompt

全样本收益很好，所以策略有效。

更专业的说法：

ompprompt

全样本表现不能单独证明策略有效。样本外表现更接近未来未知数据，因此本文主要依据 out_of_sample 指标判断策略稳定性。

如果样本外变差，可以写：

ompprompt

样本外年化收益和 Sharpe 均下降，说明策略可能对样本内走势过拟合，或该动量规则在后期市场状态中不适用。

8. 成本敏感性

查看成本敏感性表：

ompfish

python -c "import pandas as pd; print(pd.read_csv('reports/week16_cost_sensitivity.csv').round(4))"

打开图：

ompfish

xdg-open figures/cost_sensitivity.png

报告必须回答：

0 bps 时是否有效？
5 bps 时是否仍有效？
20 bps 时是否完全失效？
策略换手率是否太高？

一个常见结论：

ompprompt

策略在无成本条件下略优于 benchmark，但随着成本从 0 bps 增加到 20 bps，年化收益和 Sharpe 快速下降，说明该策略对交易成本敏感，不适合高频换仓或高摩擦市场。

9. 报告正文模板

创建报告：

ompfish

code reports/week16_quant_project_report.md

推荐结构：

ompprompt

# Mini Quant Backtest Report 1. Research question 本文研究一个简单 N 日动量规则是否能在样本外获得稳定风险调整收益。 2. Data 标的：数据来源：日期范围：频率：日频缺失值处理： 3. Strategy rule 过去 N 日收益为正：持有否则：空仓 t 日收盘生成信号，t+1 日持仓 4. Backtest assumptions 初始资金：1 交易成本：5 bps 不考虑滑点不考虑停牌、涨跌停、成交量限制 benchmark：buy and hold 5. Sample split in_sample： validation： out_of_sample： 6. Metrics 插入 metrics_by_split 表格，并解释 annual return、volatility、Sharpe、max drawdown、turnover。 7. Equity and drawdown 引用 equity_curve、drawdown、split_equity 图，并解释最大回撤时间段。 8. Cost sensitivity 引用 cost_sensitivity 表格和图片。 9. Findings 样本内是否有效？样本外是否有效？是否优于 benchmark？是否对成本敏感？ 10. Limitations 数据样本有限策略过于简单未考虑真实交易滑点和流动性未考虑参数挖掘惩罚未进行多标的验证 11. Conclusion

用谨慎语言判断：可以继续研究、需要改进，或暂不认为有效。

10. 如何写限制，而不是找借口

限制不是失败借口，而是研究边界。

好的限制写法：

ompprompt

本回测只使用单一标的日频数据，无法证明策略在其它市场或更长周期中有效。交易成本仅用固定 bps 近似，没有考虑滑点、成交量、涨跌停和资金容量，因此实盘表现可能显著低于回测。

不好的写法：

ompprompt

如果以后优化一下，策略肯定会更好。

量化研究中，未来改进只能说“可能”，不能说“肯定”。

11. 图表引用建议

在 Markdown 报告中可以用相对路径引用图：

ompprompt

![Equity Curve](../figures/equity_curve.png)
![Drawdown](../figures/drawdown.png)
![Cost Sensitivity](../figures/cost_sensitivity.png)

如果报告渲染工具从项目根目录读取，也可以改成：

ompprompt

![Equity Curve](figures/equity_curve.png)

关键是你自己打开预览检查图片能显示。

12. 文件布局检查

执行：

ompfish

pwd
ls reports figures src/quant_backtest_mini

至少应有：

ompprompt

reports/week16_metrics_by_split.csv
reports/week16_cost_sensitivity.csv
reports/week16_quant_project_report.md
figures/split_equity.png
figures/cost_sensitivity.png
src/quant_backtest_mini/report.py

13. 练习

在报告中加入 benchmark 的最大回撤时间段，和策略进行比较。
把 lookback=20 改成 lookback=60，重新生成表格，但不要只因为结果更好就替换主结论。
增加一张月度收益表，检查收益是否集中在少数月份。
在成本敏感性中加入 100 bps，观察策略是否完全失效。
写一段“如果实盘会遇到什么问题”，至少包含滑点、流动性、心理承受、参数失效。
用三句话向非量化同学解释最大回撤。

14. 验收检查

在项目根目录执行：

ompfish

source .venv/bin/activate.fish
python -m quant_backtest_mini.report
python -c "from pathlib import Path; required = ['reports/week16_metrics_by_split.csv', 'reports/week16_cost_sensitivity.csv', 'reports/week16_quant_project_report.md', 'figures/split_equity.png', 'figures/cost_sensitivity.png']; missing = [p for p in required if not Path(p).exists()]; print('missing:', missing); raise SystemExit(1 if missing else 0)"

通过标准：

报告明确写出策略规则和执行假设。
报告包含样本内、验证集、样本外指标。
报告包含最大回撤解释，而不只是一个数字。
报告包含交易成本敏感性。
报告明确写出局限性和是否可能过拟合。
结论使用谨慎语言，不夸大收益。

15. 常见错误

错误 1：报告像广告

不要写“策略收益优秀，未来可期”。要写证据、风险、限制。

错误 2：只报告全样本

全样本结果容易掩盖样本外失效。必须拆分。

错误 3：最大回撤只写数字

最大回撤应解释发生时间、持续时间、是否恢复，以及投资者是否可能承受。

错误 4：忽略交易成本

量化策略如果没有成本敏感性分析，报告不完整。

错误 5：结论超过证据

如果只测了一个模拟数据或一个标的，就不能说“策略有效”。最多说“在当前样本和假设下表现如何”。

16. 下一步

进入 Week 17：项目工程化、CLI 入口、uv 依赖与可复现运行。下一周会把 Week 15-16 的回测项目整理成别人可以 clone、安装、运行、复查的干净仓库。

plain

Week 15：Mini 量化回测、动量规则与交易成本

Sun, 26 Jul 2026 07:00:00 GMT

Oh My Pi / weekly tutorial / week15-quant-backtest-mini

miku@cachyos:~/Code/python-learning$ omp teach week15-quant-backtest-mini --fish-first --step-by-step

source562 行教学文档

weekWeek 15

shellfish-first 命令版

backlink20 周计划

Week 15：Mini 量化回测、动量规则与交易成本

返回总计划：USTC 统计 + AI / 量化 20 周成长计划

Week 15 的目标是做一个最小可用回测：从价格数据出发，计算收益率，生成交易信号，转成持仓，加入交易成本，最后输出收益、波动、最大回撤、Sharpe、换手率等指标。

本文命令默认使用 fish shell。激活虚拟环境请使用：

ompfish

source .venv/bin/activate.fish

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	signal、position、shift(1)、成本、turnover
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`projects/quant-backtest-mini/src/backtest.py`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

df["ret"] = df["close"].pct_change()
df["signal"] = (df["close"].pct_change(20) > 0).astype(float)
df["position"] = df["signal"].shift(1).fillna(0.0)
df["turnover"] = df["position"].diff().abs().fillna(0.0)
df["net_ret"] = df["position"] * df["ret"] - df["turnover"] * 0.0005

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `projects/quant-backtest-mini/src/backtest.py`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周学习目标

完成本周后，你应该能做到：

读取价格数据并计算日收益率。
实现一个简单动量策略：过去 N 日收益为正则持有，否则空仓。
正确处理信号和持仓的时间差，避免用当天收盘信号赚当天收益。
加入按换手计算的交易成本。
计算策略净值、最大回撤、年化收益、年化波动、Sharpe、turnover。
把代码拆成 backtest.py 和 metrics.py，形成一个可复用的小项目。

本周建议文件布局：

ompprompt

quant-backtest-mini/
├── data/
│   └── prices.csv
├── figures/
│   ├── equity_curve.png
│   └── drawdown.png
├── reports/
│   └── week15_backtest_notes.md
├── src/
│   └── quant_backtest_mini/
│       ├── __init__.py
│       ├── backtest.py
│       └── metrics.py
├── README.md
└── pyproject.toml

2. 前置条件

你需要理解：

Week 13 的收益率、rolling 指标、画图。
Week 14 的时间顺序和数据泄露风险。
pandas.Series.shift() 的含义。
年化指标只是约定换算，不代表未来收益保证。

创建项目：

ompfish

mkdir -p ~/Code/ustc-stat-ai-quant
cd ~/Code/ustc-stat-ai-quant
mkdir quant-backtest-mini
cd quant-backtest-mini
uv init
uv venv
source .venv/bin/activate.fish
uv add pandas numpy matplotlib
mkdir -p data figures reports src/quant_backtest_mini
printf "" > src/quant_backtest_mini/__init__.py
code .

解释：

命令	作用
`quant-backtest-mini`	本周是一个小项目，不再只叫 week15
`src/quant_backtest_mini`	使用包结构，方便 Week 17 工程化
`printf "" > __init__.py`	创建空包标记文件
`uv add pandas numpy matplotlib`	本周只用基础数据处理和画图依赖

3. 准备价格数据

如果你有 Week 13 或 Week 14 的数据，可以复制：

ompfish

cp ../week14-time-series-validation/data/prices.csv data/prices.csv

如果没有，创建 src/make_sample_prices.py：

omppython

from pathlib import Path
import numpy as np
import pandas as pd
rng = np.random.default_rng(15)
dates = pd.bdate_range(“2020-01-02”, periods=756)
trend = np.where(np.arange(len(dates)) < 380, 0.0005, -0.0001)
noise = rng.normal(0, 0.012, size=len(dates))
log_returns = trend + noise
price = 100 * np.exp(np.cumsum(log_returns))
Path(“data”).mkdir(exist_ok=True)
pd.DataFrame({“date”: dates, “close”: price}).to_csv(“data/prices.csv”, index=False)
print(“saved data/prices.csv”)

运行：

ompfish

python src/make_sample_prices.py

检查：

ompfish

python -c "import pandas as pd; df = pd.read_csv('data/prices.csv'); print(df.head()); print(df.tail()); print(df.shape)"

真实项目中，数据可以来自指数、ETF、股票或课程提供的数据。本周重点不是数据接口，而是回测逻辑。

4. 回测里的时间顺序

假设策略规则是：

ompprompt

如果过去 N 日收益为正，则持有；否则空仓。

关键问题：什么时候知道信号，什么时候产生收益？

本教程采用保守设定：

ompprompt

t 日收盘后：计算过去 N 日收益，得到 t 日信号
t+1 日：根据信号持仓，获得 t+1 日收益

所以代码里必须做：

omppython

position = signal.shift(1)
strategy_return = position * asset_return

如果不 shift(1)，就相当于用今天收盘后才知道的信号，赚了今天从开盘到收盘的收益，这是未来函数。

5. 实现风险指标 `metrics.py`

创建 src/quant_backtest_mini/metrics.py：

omppython

import numpy as np
import pandas as pd
TRADING_DAYS = 252
def annual_return(daily_returns: pd.Series) -> float:
daily_returns = daily_returns.dropna()
if daily_returns.empty:
return 0.0
total_return = (1 + daily_returns).prod() - 1
years = len(daily_returns) / TRADING_DAYS
if years <= 0:
return 0.0
return float((1 + total_return) ** (1 / years) - 1)
def annual_volatility(daily_returns: pd.Series) -> float:
daily_returns = daily_returns.dropna()
return float(daily_returns.std(ddof=0) * np.sqrt(TRADING_DAYS))
def sharpe_ratio(daily_returns: pd.Series, risk_free_rate: float = 0.0) -> float:
daily_returns = daily_returns.dropna()
if daily_returns.empty:
return 0.0
daily_rf = risk_free_rate / TRADING_DAYS
excess = daily_returns - daily_rf
vol = excess.std(ddof=0)
if vol == 0 or np.isnan(vol):
return 0.0
return float(excess.mean() / vol * np.sqrt(TRADING_DAYS))
def equity_curve(daily_returns: pd.Series) -> pd.Series:
return (1 + daily_returns.fillna(0)).cumprod()
def drawdown(equity: pd.Series) -> pd.Series:
running_max = equity.cummax()
return equity / running_max - 1
def max_drawdown(daily_returns: pd.Series) -> float:
equity = equity_curve(daily_returns)
dd = drawdown(equity)
return float(dd.min())
def summarize(daily_returns: pd.Series, turnover: pd.Series) -> dict[str, float]:
return {
“annual_return”: annual_return(daily_returns),
“annual_volatility”: annual_volatility(daily_returns),
“sharpe_ratio”: sharpe_ratio(daily_returns),
“max_drawdown”: max_drawdown(daily_returns),
“average_daily_turnover”: float(turnover.fillna(0).mean()),
“total_turnover”: float(turnover.fillna(0).sum()),
}

解释：

年化收益：把整个期间累计收益换算成年化。
年化波动：日收益标准差乘以交易日数量平方根。
Sharpe：单位波动带来的超额收益。
最大回撤：从历史高点到之后低点的最大跌幅。
turnover：持仓变化幅度，用来估算交易频率和成本。

6. 实现回测 `backtest.py`

创建 src/quant_backtest_mini/backtest.py：

omppython

from pathlib import Path
import matplotlib.pyplot as plt
import pandas as pd
from quant_backtest_mini.metrics import drawdown, equity_curve, summarize
FIGURE_DIR = Path(“figures”)
FIGURE_DIR.mkdir(exist_ok=True)
def load_prices(path: str = “data/prices.csv”) -> pd.DataFrame:
df = pd.read_csv(path, parse_dates=[“date”])
df = df.sort_values(“date”).set_index(“date”)
return df
def make_momentum_signal(prices: pd.DataFrame, lookback: int) -> pd.Series:
momentum_return = prices[“close”].pct_change(lookback)
signal = (momentum_return > 0).astype(float)
return signal
def run_backtest(
prices: pd.DataFrame,
lookback: int = 20,
cost_bps: float = 5.0,
) -> pd.DataFrame:
result = prices.copy()
result[“asset_return”] = result[“close”].pct_change()
result[“signal”] = make_momentum_signal(result, lookback=lookback)
plain # t 日收盘后产生的 signal，只能用于 t+1 日持仓
result[“position”] = result[“signal”].shift(1).fillna(0)
plain result[“gross_strategy_return”] = result[“position”] * result[“asset_return”]
result[“turnover”] = result[“position”].diff().abs().fillna(result[“position”].abs())
plain cost_rate = cost_bps / 10_000
result[“transaction_cost”] = result[“turnover”] * cost_rate
result[“net_strategy_return”] = result[“gross_strategy_return”] - result[“transaction_cost”]
result[“benchmark_return”] = result[“asset_return”].fillna(0)
return result.dropna(subset=[&quot;asset_return&quot;])
def plot_results(result: pd.DataFrame) -> None:
strategy_equity = equity_curve(result[“net_strategy_return”])
benchmark_equity = equity_curve(result[“benchmark_return”])
plain fig, ax = plt.subplots(figsize=(10, 5))
strategy_equity.plot(ax=ax, label=“momentum strategy net”)
benchmark_equity.plot(ax=ax, label=“buy and hold”)
ax.set_title(“Equity Curve”)
ax.set_ylabel(“growth of 1”)
ax.legend()
fig.tight_layout()
fig.savefig(FIGURE_DIR / “equity_curve.png”, dpi=150)
plt.close(fig)
plain fig, ax = plt.subplots(figsize=(10, 4))
drawdown(strategy_equity).plot(ax=ax, label=“strategy drawdown”)
drawdown(benchmark_equity).plot(ax=ax, label=“benchmark drawdown”)
ax.set_title(“Drawdown”)
ax.set_ylabel(“drawdown”)
ax.legend()
fig.tight_layout()
fig.savefig(FIGURE_DIR / “drawdown.png”, dpi=150)
plt.close(fig)
def main() -> None:
prices = load_prices()
result = run_backtest(prices, lookback=20, cost_bps=5.0)
plain strategy_summary = summarize(result[“net_strategy_return”], result[“turnover”])
benchmark_summary = summarize(result[“benchmark_return”], pd.Series(0, index=result.index))
plain print(“strategy”)
for key, value in strategy_summary.items():
print(f”{key}: {value:.4f}”)
plain print(“benchmark”)
for key, value in benchmark_summary.items():
print(f”{key}: {value:.4f}”)
plot_results(result)
result.to_csv(&quot;reports/week15_backtest_daily_results.csv&quot;)
print(&quot;saved figures and reports/week15_backtest_daily_results.csv&quot;)
if name == “main”:
main()

运行：

ompfish

python -m quant_backtest_mini.backtest

如果提示找不到包，确认你在项目根目录，并且包在 src/quant_backtest_mini/ 下。uv init 通常会配置好 src 布局；如果没有，可以先用下面命令运行：

ompfish

PYTHONPATH=src python src/quant_backtest_mini/backtest.py

推荐最终使用模块方式运行，因为 Week 17 工程化会继续整理 CLI 入口。

7. 理解交易成本

本教程使用基点 bps：

ompprompt

1 bps = 0.01%
5 bps = 0.05%

交易成本计算：

omppython

cost_rate = cost_bps / 10_000
transaction_cost = turnover * cost_rate
net_return = gross_return - transaction_cost

如果持仓从 0 变成 1，turnover 为 1；如果从 1 变成 0，turnover 也为 1。频繁交易会产生更高成本。

必须比较：

ompprompt

gross_strategy_return：未扣成本
net_strategy_return：扣成本后
benchmark_return：买入并持有

如果策略只在未扣成本时有效，扣成本后失效，就不能说它有交易价值。

8. 风险指标怎么读

指标	含义	注意点
annual return	年化收益	样本短时容易夸大
annual volatility	年化波动	只看波动不看回撤不够
Sharpe ratio	单位风险收益	不稳定，受极端值影响
max drawdown	最大回撤	很贴近真实心理压力
turnover	换手率	越高越容易被成本吃掉
transaction cost	交易成本	回测必须扣除

对于初学者，最大回撤比年化收益更值得认真看。一个年化很高但回撤很深的策略，实盘中可能根本拿不住。

9. 加入样本切分

最小回测跑通后，再加入样本内和样本外对比。可以在 backtest.py 里加入：

omppython

def split_result(result: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame]:
    split_at = int(len(result) * 0.7)
    in_sample = result.iloc[:split_at]
    out_of_sample = result.iloc[split_at:]
    return in_sample, out_of_sample

在 main() 中输出：

omppython

in_sample, out_of_sample = split_result(result)
print("in sample strategy", summarize(in_sample["net_strategy_return"], in_sample["turnover"]))
print("out of sample strategy", summarize(out_of_sample["net_strategy_return"], out_of_sample["turnover"]))

报告中必须写明：样本外表现是否明显变差。如果样本内很好、样本外很差，优先怀疑过拟合。

10. 参数敏感性

不要只试一个 lookback=20。至少比较：

ompprompt

lookback = 5, 10, 20, 60
cost_bps = 0, 5, 10, 20

简单做法是在 main() 中循环：

omppython

for lookback in [5, 10, 20, 60]:
    for cost_bps in [0, 5, 10, 20]:
        result = run_backtest(prices, lookback=lookback, cost_bps=cost_bps)
        summary = summarize(result["net_strategy_return"], result["turnover"])
        print(
            f"lookback={lookback}, cost_bps={cost_bps}, "
            f"annual_return={summary['annual_return']:.4f}, "
            f"sharpe={summary['sharpe_ratio']:.4f}, "
            f"max_drawdown={summary['max_drawdown']:.4f}"
        )

如果只有某一个参数组合特别好，其它都很差，要警惕参数挖掘。

11. 报告模板

创建：

ompfish

code reports/week15_backtest_notes.md

建议结构：

ompprompt

# Week 15 Backtest Notes
Strategy

策略名称：N 日动量
规则：过去 N 日收益为正则持有，否则空仓
执行假设：t 日收盘生成信号，t+1 日持仓

Data

数据来源：
日期范围：
频率：日频

Backtest settings

lookback：
cost_bps：
benchmark：buy and hold

Metrics

annual return：
annual volatility：
Sharpe：
max drawdown：
turnover：

Cost sensitivity

0 bps：
5 bps：
10 bps：
20 bps：

Observations

是否优于 buy and hold？
收益是否来自少数时间段？
成本后是否仍有效？
最大回撤是否能接受？

Limitations

模拟数据或单一标的
没有滑点
没有停牌、涨跌停、成交量限制
没有真实资金容量约束

12. 文件布局检查

运行：

ompfish

pwd
ls
ls data figures reports src/quant_backtest_mini

至少应有：

ompprompt

data/prices.csv
src/quant_backtest_mini/__init__.py
src/quant_backtest_mini/backtest.py
src/quant_backtest_mini/metrics.py
figures/equity_curve.png
figures/drawdown.png
reports/week15_backtest_notes.md
reports/week15_backtest_daily_results.csv

13. 练习

把动量策略改成均值回复：价格低于 20 日均线一定比例则持有，否则空仓。
比较 lookback=5、20、60 的净值曲线和最大回撤。
把交易成本从 0 bps 增加到 20 bps，观察 Sharpe 和年化收益变化。
加入一个简单止损规则，并检查是否只是降低收益、没有真正降低回撤。
把结果保存为 CSV，并在报告里找出策略收益最高和最低的 5 天。
把 benchmark 从 buy and hold 改成空仓，解释为什么量化报告通常需要合理 benchmark。

14. 验收检查

在项目根目录执行：

ompfish

source .venv/bin/activate.fish
python -m quant_backtest_mini.backtest
python -c "from pathlib import Path; required = ['data/prices.csv', 'src/quant_backtest_mini/backtest.py', 'src/quant_backtest_mini/metrics.py', 'figures/equity_curve.png', 'figures/drawdown.png', 'reports/week15_backtest_daily_results.csv', 'reports/week15_backtest_notes.md']; missing = [p for p in required if not Path(p).exists()]; print('missing:', missing); raise SystemExit(1 if missing else 0)"

通过标准：

策略收益使用 position.shift(1)，没有偷看当天收益。
回测同时输出扣成本前和扣成本后逻辑，报告中重点解释扣成本后。
至少计算 annual return、annual volatility、Sharpe、max drawdown、turnover。
至少有净值曲线和回撤图。
报告中有成本敏感性和局限性。

15. 常见错误

错误 1：忘记 `shift(1)`

如果直接写：

omppython

strategy_return = signal * asset_return

很可能偷看未来。除非你严格证明信号在收益发生前已知，否则应使用：

omppython

position = signal.shift(1)

错误 2：只看累计收益

累计收益高不代表好。必须同时看回撤、波动、Sharpe、交易成本。

错误 3：交易成本写成固定每天扣

成本应主要和交易有关，而不是每天都扣同样数额。最小版本可以用 turnover * cost_rate。

错误 4：把模拟数据结果当真实策略

模拟数据只用于练代码。真实策略必须使用真实数据、严格样本外验证和更完整成本模型。

错误 5：参数调到最好就结束

如果你试了很多参数，只报告最好的一个，就是参数挖掘。报告中要写参数敏感性。

16. 下一步

进入 Week 16：量化项目报告：指标、回撤、样本切分与局限性。下一周重点是把回测结果写成能被老师、同学或未来自己读懂的报告。

plain

Week 14：时间序列验证、rolling window 与数据泄露检查

Sun, 26 Jul 2026 06:00:00 GMT

Oh My Pi / weekly tutorial / week14-time-series-validation

miku@cachyos:~/Code/python-learning$ omp teach week14-time-series-validation --fish-first --step-by-step

source622 行教学文档

weekWeek 14

shellfish-first 命令版

backlink20 周计划

Week 14：时间序列验证、rolling window 与数据泄露检查

返回总计划：USTC 统计 + AI / 量化 20 周成长计划

Week 14 的核心目标是：不要在时间序列任务里偷看未来。 预测模型不一定要复杂，但验证方式必须正确。对量化和金融时间序列来说，一个看起来很高的分数，经常只是数据泄露造成的幻觉。

本文命令默认使用 fish shell，虚拟环境激活命令为：

ompfish

source .venv/bin/activate.fish

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	rolling/expanding validation、naive baseline、防泄漏
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`src/time_series_validation.py`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

def rolling_splits(n, train_size, test_size):
    start = 0
    while start + train_size + test_size <= n:
        train = range(start, start + train_size)
        test = range(start + train_size, start + train_size + test_size)
        yield list(train), list(test)
        start += test_size

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `src/time_series_validation.py`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周学习目标

完成本周后，你应该能做到：

用时间顺序切分 train / validation / test。
解释为什么时间序列不能随机打乱。
实现 naive baseline、rolling window validation、expanding window validation。
比较线性模型、随机森林和简单基准，而不是只看一个模型。
检查标准化、rolling 特征、标签构造中的常见泄露。

本周建议交付物：

ompprompt

week14-time-series-validation/
├── data/
│   └── prices.csv
├── figures/
│   ├── split.png
│   └── rolling_validation_scores.png
├── reports/
│   └── week14_forecast_report.md
├── src/
│   └── time_series_validation.py
├── pyproject.toml
└── README.md

2. 前置条件

你需要已经完成或理解 Week 13：

价格和收益率的区别。
pct_change()、rolling()、shift() 的基本用法。
为什么收益率比价格更适合建模。
Python 项目的基本结构和 uv 虚拟环境。

进入学习目录并创建项目：

ompfish

mkdir -p ~/Code/ustc-stat-ai-quant
cd ~/Code/ustc-stat-ai-quant
mkdir week14-time-series-validation
cd week14-time-series-validation
uv init
uv venv
source .venv/bin/activate.fish
uv add pandas numpy matplotlib scikit-learn
mkdir -p data src reports figures
code .

解释：

命令	作用
`uv add scikit-learn`	本周会用线性模型、随机森林和指标
`mkdir -p data src reports figures`	保持数据、代码、报告、图片分离
`source .venv/bin/activate.fish`	使用 fish 语法激活环境

3. 准备数据

如果你已经有 Week 13 的模拟价格数据，可以复制过来：

ompfish

cp ../week13-time-series-basics/data/prices.csv data/prices.csv

如果没有，创建 src/make_sample_prices.py：

omppython

from pathlib import Path
import numpy as np
import pandas as pd
rng = np.random.default_rng(2026)
dates = pd.bdate_range(“2021-01-04”, periods=520)
market_noise = rng.normal(0.0002, 0.011, size=len(dates))
slow_cycle = 0.002 * np.sin(np.arange(len(dates)) / 30)
log_returns = market_noise + slow_cycle
price = 100 * np.exp(np.cumsum(log_returns))
Path(“data”).mkdir(exist_ok=True)
pd.DataFrame({“date”: dates, “close”: price}).to_csv(“data/prices.csv”, index=False)
print(“saved data/prices.csv”)

运行：

ompfish

python src/make_sample_prices.py

检查：

ompfish

python -c "import pandas as pd; df = pd.read_csv('data/prices.csv'); print(df.head()); print(df.tail()); print(df.shape)"

4. 明确预测任务

本周不要一上来就“预测价格”。先定义一个清楚、可验证的小任务：

ompprompt

输入：截至今天已经知道的收益率、滚动均值、滚动波动率
目标：预测明天的日收益率方向
标签：明天收益率是否大于 0

这意味着：

第 t 天的特征只能使用第 t 天及以前的数据。
第 t 天的标签是第 t+1 天的方向。
训练集必须早于验证集，验证集必须早于测试集。

创建 src/time_series_validation.py，先写读取和特征构造：

omppython

from pathlib import Path
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from sklearn.ensemble import RandomForestClassifier
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import accuracy_score, precision_score
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
FIGURE_DIR = Path(“figures”)
FIGURE_DIR.mkdir(exist_ok=True)
def load_prices(path: str = “data/prices.csv”) -> pd.DataFrame:
df = pd.read_csv(path, parse_dates=[“date”])
df = df.sort_values(“date”).set_index(“date”)
return df
def make_features(df: pd.DataFrame) -> pd.DataFrame:
out = df.copy()
out[“return_1d”] = out[“close”].pct_change()
out[“return_5d”] = out[“close”].pct_change(5)
out[“rolling_mean_5”] = out[“return_1d”].rolling(5).mean()
out[“rolling_vol_5”] = out[“return_1d”].rolling(5).std()
out[“rolling_mean_20”] = out[“return_1d”].rolling(20).mean()
out[“rolling_vol_20”] = out[“return_1d”].rolling(20).std()
plain # 预测明天方向：明天收益率大于 0 记为 1，否则 0
out[“target_up_next_day”] = (out[“return_1d”].shift(-1) > 0).astype(int)
out = out.dropna()
return out

关键点：shift(-1) 只用于构造标签，不可以把未来收益率当成特征。

5. 不要随机打乱时间序列

很多机器学习教程会写：随机划分训练集和测试集。时间序列不能这样做，因为未来样本会混入训练集。

错误思路：

ompprompt

随机抽 80% 日期训练，剩下 20% 日期测试

这会导致：

训练集中可能包含 2024 年数据。
测试集中可能包含 2022 年数据。
模型相当于在预测过去时已经见过未来市场环境。

正确思路：

ompprompt

早期数据：训练
中间数据：验证
后期数据：测试

在脚本中加入时间切分函数：

omppython

def chronological_split(data: pd.DataFrame) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
    n = len(data)
    train_end = int(n * 0.6)
    valid_end = int(n * 0.8)
    train = data.iloc[:train_end]
    valid = data.iloc[train_end:valid_end]
    test = data.iloc[valid_end:]
    return train, valid, test
def plot_split(train: pd.DataFrame, valid: pd.DataFrame, test: pd.DataFrame) -> None:
fig, ax = plt.subplots(figsize=(10, 4))
train[“close”].plot(ax=ax, label=“train”)
valid[“close”].plot(ax=ax, label=“validation”)
test[“close”].plot(ax=ax, label=“test”)
ax.set_title(“Chronological Split”)
ax.legend()
fig.tight_layout()
fig.savefig(FIGURE_DIR / “split.png”, dpi=150)
plt.close(fig)

6. 建立 naive baseline

在预测方向任务中，最简单的 baseline 可以是：明天方向等于今天方向。

omppython

def evaluate_naive(data: pd.DataFrame) -> dict[str, float]:
    y_true = data["target_up_next_day"]
    y_pred = (data["return_1d"] > 0).astype(int)
    return {
        "accuracy": accuracy_score(y_true, y_pred),
        "precision": precision_score(y_true, y_pred, zero_division=0),
    }

为什么 baseline 重要？

如果复杂模型打不过 naive baseline，说明模型暂时没价值。
如果只比 50% 高一点点，不一定有交易价值，因为交易成本会吃掉优势。
量化里“略高于随机”也可能是过拟合，需要滚动验证和样本外验证。

7. 用 Pipeline 避免标准化泄露

标准化常见泄露：先用全数据计算均值和标准差，再切分训练测试。这样测试集的信息已经进入训练流程。

正确方式：标准化器只在训练集 fit，然后对验证集或测试集 transform。

scikit-learn 的 Pipeline 可以减少误用：

omppython

FEATURE_COLUMNS = [
    "return_1d",
    "return_5d",
    "rolling_mean_5",
    "rolling_vol_5",
    "rolling_mean_20",
    "rolling_vol_20",
]
TARGET_COLUMN = "target_up_next_day"
def evaluate_model(train: pd.DataFrame, test: pd.DataFrame, model_name: str) -> dict[str, float | str]:
x_train = train[FEATURE_COLUMNS]
y_train = train[TARGET_COLUMN]
x_test = test[FEATURE_COLUMNS]
y_test = test[TARGET_COLUMN]
plain if model_name == “logistic”:
model = Pipeline(
steps=[
(“scaler”, StandardScaler()),
(“model”, LogisticRegression(max_iter=1000)),
]
)
elif model_name == “random_forest”:
model = RandomForestClassifier(
n_estimators=200,
max_depth=3,
random_state=42,
)
else:
raise ValueError(f”unknown model: {model_name}”)
plain model.fit(x_train, y_train)
pred = model.predict(x_test)
return {
“model”: model_name,
“accuracy”: accuracy_score(y_test, pred),
“precision”: precision_score(y_test, pred, zero_division=0),
}

注意：随机森林通常不需要标准化；逻辑回归需要。

8. rolling window validation

rolling window 的直觉：每次只用最近一段历史训练，然后预测之后一小段。

ompprompt

第 1 次：用 0-199 天训练，预测 200-219 天
第 2 次：用 20-219 天训练，预测 220-239 天
第 3 次：用 40-239 天训练，预测 240-259 天

加入函数：

omppython

def rolling_window_validation(
    data: pd.DataFrame,
    train_size: int,
    test_size: int,
    step_size: int,
    model_name: str,
) -> pd.DataFrame:
    rows = []
    start = 0
    while start + train_size + test_size <= len(data):
        train = data.iloc[start : start + train_size]
        test = data.iloc[start + train_size : start + train_size + test_size]
        score = evaluate_model(train, test, model_name)
        rows.append(
            {
                "train_start": train.index[0],
                "train_end": train.index[-1],
                "test_start": test.index[0],
                "test_end": test.index[-1],
                **score,
            }
        )
        start += step_size
    return pd.DataFrame(rows)

优点：更接近真实策略的滚动更新。缺点：早期历史会被丢弃，样本利用率较低。

9. expanding window validation

expanding window 的直觉：训练集从最早日期开始，随着时间不断扩大。

ompprompt

第 1 次：用 0-199 天训练，预测 200-219 天
第 2 次：用 0-219 天训练，预测 220-239 天
第 3 次：用 0-239 天训练，预测 240-259 天

加入函数：

omppython

def expanding_window_validation(
    data: pd.DataFrame,
    initial_train_size: int,
    test_size: int,
    step_size: int,
    model_name: str,
) -> pd.DataFrame:
    rows = []
    train_end = initial_train_size
    while train_end + test_size <= len(data):
        train = data.iloc[:train_end]
        test = data.iloc[train_end : train_end + test_size]
        score = evaluate_model(train, test, model_name)
        rows.append(
            {
                "train_start": train.index[0],
                "train_end": train.index[-1],
                "test_start": test.index[0],
                "test_end": test.index[-1],
                **score,
            }
        )
        train_end += step_size
    return pd.DataFrame(rows)

优点：历史数据利用更多。缺点：如果市场结构变化很大，太久远的数据可能拖累模型。

10. 主程序：比较 baseline 和模型

加入主程序：

omppython

def main() -> None:
    prices = load_prices()
    data = make_features(prices)
    train, valid, test = chronological_split(data)
    plot_split(train, valid, test)
plain print(“naive validation:”, evaluate_naive(valid))
print(“naive test:”, evaluate_naive(test))
plain for model_name in [“logistic”, “random_forest”]:
print(“single split”, evaluate_model(train, valid, model_name))
plain rolling_scores = rolling_window_validation(
data=data,
train_size=180,
test_size=20,
step_size=20,
model_name=“logistic”,
)
expanding_scores = expanding_window_validation(
data=data,
initial_train_size=180,
test_size=20,
step_size=20,
model_name=“logistic”,
)
print(&quot;rolling scores&quot;)
print(rolling_scores)
print(&quot;expanding scores&quot;)
print(expanding_scores)

fig, ax = plt.subplots(figsize=(10, 4))
rolling_scores[&quot;accuracy&quot;].plot(ax=ax, marker=&quot;o&quot;, label=&quot;rolling&quot;)
expanding_scores[&quot;accuracy&quot;].plot(ax=ax, marker=&quot;o&quot;, label=&quot;expanding&quot;)
ax.axhline(0.5, color=&quot;black&quot;, linewidth=1, linestyle=&quot;--&quot;)
ax.set_title(&quot;Validation Accuracy by Window&quot;)
ax.set_xlabel(&quot;window number&quot;)
ax.set_ylabel(&quot;accuracy&quot;)
ax.legend()
fig.tight_layout()
fig.savefig(FIGURE_DIR / &quot;rolling_validation_scores.png&quot;, dpi=150)
plt.close(fig)
if name == “main”:
main()

运行：

ompfish

python src/time_series_validation.py
xdg-open figures/split.png
xdg-open figures/rolling_validation_scores.png

如果结果不稳定，这是正常现象。金融预测本来就难。你的任务不是强行调参到高分，而是学会诚实验证。

11. 数据泄露检查清单

写报告前逐项检查。

11.1 时间切分

错误：随机打乱。

正确：

omppython

train = data.iloc[:train_end]
valid = data.iloc[train_end:valid_end]
test = data.iloc[valid_end:]

检查问题：

训练集最后一天是否早于验证集第一天？
验证集最后一天是否早于测试集第一天？
图上能否看出三段按时间顺序排列？

11.2 标签构造

预测明天方向可以使用：

omppython

out["target_up_next_day"] = (out["return_1d"].shift(-1) > 0).astype(int)

但不能把 return_1d.shift(-1) 放进特征列。

11.3 rolling 特征

当日做决策时，rolling() 默认包含当前行。是否允许取决于你的交易设定：

如果你在收盘后计算信号，明天开盘或收盘执行，可以使用当天收盘后才知道的数据。
如果你在当天收盘前就要交易，就不能使用当天收盘价。

初学时建议写清楚假设：

ompprompt

本项目假设在 t 日收盘后计算信号，并在 t+1 日持有，因此 t 日及以前的数据可用。

11.4 标准化

错误：全数据先标准化，再切分。

正确：用 Pipeline，让 scaler 在训练集上 fit。

11.5 调参

如果你反复看测试集表现再改模型，测试集也被你“污染”了。正确流程：

ompprompt

train：训练模型
validation：比较模型和调参
test：最后只评估一次

12. 报告模板

创建报告：

ompfish

code reports/week14_forecast_report.md

建议结构：

ompprompt

# Week 14 Forecast Report
Task

预测目标：明天收益率方向
特征：过去收益率、rolling mean、rolling volatility

Data split

train 日期范围：
validation 日期范围：
test 日期范围：

Baseline

naive baseline accuracy：
naive baseline precision：

Models

logistic regression：
random forest：

Rolling validation

rolling window 设置：
expanding window 设置：
哪种结果更稳定？

Leakage checks

是否随机打乱：否
标准化是否只在训练集 fit：是
特征是否使用未来收益率：否
测试集是否只最终评估：是

Conclusion

模型是否明显优于 baseline？
结果是否稳定？
下一步如果要做回测，还缺什么？

13. 文件布局检查

执行：

ompfish

pwd
ls
ls data src reports figures

至少应有：

ompprompt

data/prices.csv
src/time_series_validation.py
figures/split.png
figures/rolling_validation_scores.png
reports/week14_forecast_report.md

14. 练习

把预测目标改成“未来 5 日收益率是否大于 0”。注意标签和特征时间关系。
把 train_size 从 180 改成 120、240，观察 rolling validation 是否变化。
添加一个新特征：过去 10 日收益率 return_10d。
比较 logistic regression 和 random forest，写出哪个更稳定，而不是只写哪个最高。
故意写一个泄露特征 future_return = return_1d.shift(-1)，看分数是否异常变高，然后删掉它并在报告中解释为什么不能用。
把 random_state 改掉，观察随机森林结果是否明显变化。

15. 验收检查

在项目根目录执行：

ompfish

source .venv/bin/activate.fish
python src/time_series_validation.py
python -c "from pathlib import Path; required = ['data/prices.csv', 'src/time_series_validation.py', 'figures/split.png', 'figures/rolling_validation_scores.png', 'reports/week14_forecast_report.md']; missing = [p for p in required if not Path(p).exists()]; print('missing:', missing); raise SystemExit(1 if missing else 0)"

通过标准：

不使用随机打乱切分。
至少实现 naive baseline 和一个机器学习模型。
至少有 rolling 或 expanding window 的多窗口结果。
报告中有明确的数据泄露检查。
能解释为什么测试集不能反复用于调参。

16. 常见错误

错误 1：直接使用 `train_test_split` 默认随机划分

时间序列任务不要默认随机。你可以不用 train_test_split，直接用 iloc 按时间切。

错误 2：模型分数高得不正常

优先检查：

特征里是否有未来收益率？
是否全数据标准化后再切分？
是否把测试集用于多次调参？
标签是否和特征同一天，导致预测任务变成已知当天涨跌？

错误 3：rolling window 前面缺失太多

窗口越大，需要的历史越多。可以减少窗口，或接受前几行因信息不足而被删除。

错误 4：precision 报 warning

如果模型全预测为 0，就没有正类预测。示例代码用 zero_division=0 避免中断，但报告里要说明模型可能没有学到有效信号。

错误 5：只报告最高分

只写最高分没有意义。你需要报告窗口间稳定性、是否优于 baseline、是否可能泄露。

17. 下一步

进入 Week 15：mini quant backtest：动量规则、交易成本与风险指标。下一周会把本周的“预测/信号”变成持仓和策略收益，并加入交易成本。

plain

Week 13：时间序列基础、收益率与滚动统计

Sun, 26 Jul 2026 05:00:00 GMT

Oh My Pi / weekly tutorial / week13-time-series-basics

miku@cachyos:~/Code/python-learning$ omp teach week13-time-series-basics --fish-first --step-by-step

source520 行教学文档

weekWeek 13

shellfish-first 命令版

backlink20 周计划

Week 13：时间序列基础、收益率与滚动统计

返回总计划：USTC 统计 + AI / 量化 20 周成长计划

本周目标不是马上预测股价，而是先学会把价格序列变成可以分析的时间序列数据：收益率、滚动均值、滚动波动率、自相关、平稳性直觉，以及最基础的画图检查。

本文命令默认使用 fish shell。如果你正在 CachyOS 的终端里跟做，虚拟环境激活命令必须使用 fish 版本：

ompfish

source .venv/bin/activate.fish

不要把 Bash / Zsh 的激活脚本直接拿到 fish 里执行。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	return、rolling、autocorrelation、时间索引
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`notebooks/week13_time_series_intro.ipynb`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

df = df.sort_values("date")
df["ret"] = df["close"].pct_change()
df["log_ret"] = np.log(df["close"]).diff()
df["vol_20"] = df["ret"].rolling(20).std()
df["mom_20"] = df["close"].pct_change(20)
print(df.tail())

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `notebooks/week13_time_series_intro.ipynb`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周学习目标

完成本周后，你应该能回答这些问题：

为什么量化里通常分析收益率，而不是直接分析价格？
简单收益率和对数收益率有什么区别？
rolling mean / rolling volatility 在看什么？
什么叫“时间序列不平稳”，为什么金融价格经常不适合直接建模？
如何用图和几个简单统计量检查一条序列？

本周交付物建议为：

ompprompt

week13-time-series-basics/
├── data/
│   └── prices.csv
├── figures/
│   ├── price_and_returns.png
│   ├── rolling_stats.png
│   └── autocorrelation.png
├── notebooks/
│   └── week13_time_series_intro.ipynb
├── reports/
│   └── week13_time_series_notes.md
├── src/
│   └── week13_time_series_basics.py
├── pyproject.toml
└── README.md

如果你还不熟悉 notebook，可以先用 src/week13_time_series_basics.py 写脚本；等脚本跑通后，再把关键图和解释整理到 notebook 或报告里。

2. 前置条件

你需要已经具备：

CachyOS / Arch 系 Linux 的基本终端操作。
VS Code 能打开项目目录。
uv 已安装。
Python 虚拟环境能正常创建和激活。
已经学过 pandas、numpy、matplotlib 的基础用法。
能理解均值、方差、标准差、相关系数这些统计概念。

先进入统一学习目录：

ompfish

mkdir -p ~/Code/ustc-stat-ai-quant
cd ~/Code/ustc-stat-ai-quant

解释：

命令	含义
`mkdir -p`	创建目录；目录已存在时不报错
`~/Code/ustc-stat-ai-quant`	建议保存 20 周项目的总目录
`cd`	进入该目录，后续命令都在这里执行

3. 创建 Week 13 项目

ompfish

mkdir week13-time-series-basics
cd week13-time-series-basics
uv init
uv venv
source .venv/bin/activate.fish
uv add pandas numpy matplotlib statsmodels jupyter ipykernel
mkdir -p data src notebooks reports figures
code .

逐句解释：

命令	作用
`mkdir week13-time-series-basics`	为本周单独建项目，不和其它周混在一起
`uv init`	生成 `pyproject.toml`、`README.md` 等项目文件
`uv venv`	创建当前项目专用的 `.venv`
`source .venv/bin/activate.fish`	在 fish shell 中激活虚拟环境
`uv add ...`	安装数据分析、画图、时间序列相关依赖
`mkdir -p ...`	创建数据、代码、报告、图片目录
`code .`	用 VS Code 打开当前项目

检查 Python 是否来自当前项目：

ompfish

which python
python --version
python -c "import pandas as pd; import numpy as np; import matplotlib; print('ok')"

如果 which python 的输出包含 .venv/bin/python，说明环境正确。

4. 准备一份练习价格数据

真实市场数据可以以后再接入。本周先生成一份模拟价格数据，重点练概念和代码流程。

在 VS Code 中创建 src/make_sample_prices.py，写入下面代码：

omppython

from pathlib import Path
import numpy as np
import pandas as pd
rng = np.random.default_rng(42)
dates = pd.bdate_range(“2023-01-02”, periods=260)
模拟日对数收益：小正漂移 + 随机波动 + 少数冲击日
log_returns = rng.normal(loc=0.0004, scale=0.012, size=len(dates))
shock_idx = rng.choice(len(dates), size=6, replace=False)
log_returns[shock_idx] += rng.normal(loc=-0.025, scale=0.02, size=len(shock_idx))
price = 100 * np.exp(np.cumsum(log_returns))
out = pd.DataFrame({“date”: dates, “close”: price})
Path(“data”).mkdir(exist_ok=True)
out.to_csv(“data/prices.csv”, index=False)
print(out.head())
print(“saved to data/prices.csv”)

运行：

ompfish

python src/make_sample_prices.py

检查文件：

ompfish

python -c "import pandas as pd; df = pd.read_csv('data/prices.csv'); print(df.head()); print(df.tail())"

这里使用的是模拟数据，所以不能拿结论解释真实市场。它的作用是让你安全地练习时间序列处理。

5. 读取价格并设置时间索引

创建 src/week13_time_series_basics.py，先写入读取部分：

omppython

from pathlib import Path
import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from statsmodels.graphics.tsaplots import plot_acf
FIGURE_DIR = Path(“figures”)
FIGURE_DIR.mkdir(exist_ok=True)
prices = pd.read_csv(“data/prices.csv”, parse_dates=[“date”])
prices = prices.sort_values(“date”).set_index(“date”)
print(prices.head())
print(prices.info())

运行：

ompfish

python src/week13_time_series_basics.py

解释：

parse_dates=["date"]：把日期列解析成真正的时间类型。
sort_values("date")：时间序列必须按时间排序。
set_index("date")：把日期设为索引，后面 rolling 和画图更自然。

时间序列第一条规则：先确认时间顺序，再做任何统计。

6. 价格、简单收益率、对数收益率

在脚本中继续加入：

omppython

prices["simple_return"] = prices["close"].pct_change()
prices["log_return"] = np.log(prices["close"]).diff()
print(prices[[“close”, “simple_return”, “log_return”]].head(10))
print(prices[[“simple_return”, “log_return”]].describe())

运行：

ompfish

python src/week13_time_series_basics.py

概念解释：

名称	公式直觉	常见用途
简单收益率	今天价格相对昨天涨跌百分比	回测中计算资产组合收益很直观
对数收益率	价格取对数后做差	数学上可加，时间序列建模时常用

为什么不用价格直接建模？

价格经常有趋势，均值随时间变化。
价格尺度随时间变大，波动范围也可能变化。
很多模型默认数据围绕稳定均值波动，价格往往不满足。
收益率更接近“每天的相对变化”，通常比价格更适合做统计分析。

注意：第一天没有前一天价格，所以收益率是缺失值。这是正常现象，不要强行填 0。

7. 画价格和收益率

继续加入画图代码：

omppython

fig, axes = plt.subplots(2, 1, figsize=(10, 7), sharex=True)
prices[“close”].plot(ax=axes[0], title=“Simulated Close Price”)
axes[0].set_ylabel(“price”)
prices[“simple_return”].plot(ax=axes[1], title=“Daily Simple Return”)
axes[1].axhline(0, color=“black”, linewidth=1)
axes[1].set_ylabel(“return”)
fig.tight_layout()
fig.savefig(FIGURE_DIR / “price_and_returns.png”, dpi=150)
plt.close(fig)

运行并查看图片：

ompfish

python src/week13_time_series_basics.py
xdg-open figures/price_and_returns.png

看图时不要只问“涨了吗”，要问：

价格是否有明显趋势？
收益率是否围绕 0 上下波动？
是否有异常大的正收益或负收益？
波动是否集中在某些时间段？

金融数据经常不是“均匀随机噪声”，而是会出现波动聚集：一段时间很平静，另一段时间连续剧烈波动。

8. rolling mean 与 rolling volatility

继续加入：

omppython

window = 20
prices["rolling_mean_20"] = prices["simple_return"].rolling(window).mean()
prices["rolling_vol_20"] = prices["simple_return"].rolling(window).std()
fig, axes = plt.subplots(2, 1, figsize=(10, 7), sharex=True)
prices[“rolling_mean_20”].plot(ax=axes[0], title=“20-Day Rolling Mean of Returns”)
axes[0].axhline(0, color=“black”, linewidth=1)
axes[0].set_ylabel(“mean”)
prices[“rolling_vol_20”].plot(ax=axes[1], title=“20-Day Rolling Volatility of Returns”)
axes[1].set_ylabel(“volatility”)
fig.tight_layout()
fig.savefig(FIGURE_DIR / “rolling_stats.png”, dpi=150)
plt.close(fig)
print(prices[[“simple_return”, “rolling_mean_20”, “rolling_vol_20”]].tail())

运行：

ompfish

python src/week13_time_series_basics.py
xdg-open figures/rolling_stats.png

解释：

rolling(20).mean()：每一天都看过去 20 个交易日的平均收益。
rolling(20).std()：每一天都看过去 20 个交易日的波动率。
前 19 天没有足够窗口，所以结果是缺失值，这是合理的。

量化里 rolling 指标非常重要，因为策略在某一天做决策时，只能使用这一天之前已经发生的数据。以后做回测时，要特别检查 rolling 特征有没有偷看未来。

9. 平稳性直觉

你不需要本周就精通严谨的单位根检验，但必须先建立直觉。

粗略地说，一条平稳序列应该满足：

ompprompt

均值大致稳定
波动范围大致稳定
自相关结构大致稳定
没有明显长期趋势

价格通常不像平稳序列：

ompprompt

价格可能长期上升或下降
价格水平改变后，均值不再稳定
价格的绝对尺度会影响波动大小

收益率通常更接近平稳，但也不完美：

ompprompt

收益率均值更接近稳定
收益率仍可能有波动聚集
极端事件会破坏简单模型假设

在脚本里加入一个简单比较：

omppython

first_half = prices.iloc[: len(prices) // 2]
second_half = prices.iloc[len(prices) // 2 :]
summary = pd.DataFrame(
{
“price_first_half”: first_half[“close”].describe(),
“price_second_half”: second_half[“close”].describe(),
“return_first_half”: first_half[“simple_return”].describe(),
“return_second_half”: second_half[“simple_return”].describe(),
}
)
print(summary)

运行：

ompfish

python src/week13_time_series_basics.py

观察重点：价格两段的均值可能差很多；收益率两段的均值通常更接近，但标准差仍可能变化。

10. 自相关：今天和过去有关吗

自相关回答的是：今天的收益率是否和前几天的收益率有关系。

继续加入：

omppython

returns = prices["simple_return"].dropna()
print(“lag 1 autocorrelation:”, returns.autocorr(lag=1))
print(“lag 5 autocorrelation:”, returns.autocorr(lag=5))
print(“lag 20 autocorrelation:”, returns.autocorr(lag=20))
fig = plot_acf(returns, lags=30)
fig.set_size_inches(10, 5)
fig.tight_layout()
fig.savefig(FIGURE_DIR / “autocorrelation.png”, dpi=150)
plt.close(fig)

运行：

ompfish

python src/week13_time_series_basics.py
xdg-open figures/autocorrelation.png

解释：

如果 lag 1 自相关明显为正，可能表示短期动量。
如果 lag 1 自相关明显为负，可能表示短期反转。
如果大部分自相关接近 0，说明简单线性关系很弱。

不要看到一点点相关就兴奋。金融时间序列噪声很大，样本外稳定性比样本内漂亮图更重要。

11. 整理报告

创建 reports/week13_time_series_notes.md，建议包含：

ompprompt

# Week 13 Time Series Notes
Data

数据来源：模拟价格数据
时间范围：2023 年 260 个工作日

What I computed

close price
simple return
log return
20-day rolling mean
20-day rolling volatility
autocorrelation

Observations

价格是否有趋势？
收益率是否围绕 0 波动？
rolling volatility 是否有明显变化？
自相关是否明显？

Stationarity intuition

为什么价格更不平稳？
为什么收益率更适合建模？

Questions

如果换成真实股票或指数，结果会怎样？

用 VS Code 创建和编辑报告：

ompfish

code reports/week13_time_series_notes.md

12. 文件布局检查

运行：

ompfish

pwd
ls
ls data src reports figures

理想结果类似：

ompprompt

week13-time-series-basics/
data  figures  notebooks  pyproject.toml  README.md  reports  src

你最终至少应有：

ompprompt

data/prices.csv
src/make_sample_prices.py
src/week13_time_series_basics.py
figures/price_and_returns.png
figures/rolling_stats.png
figures/autocorrelation.png
reports/week13_time_series_notes.md

13. 练习

把 rolling window 从 20 改成 5、60，比较图像差异。
分别计算简单收益率和对数收益率的均值、标准差、最小值、最大值。
找出收益率绝对值最大的 5 天，检查这些天在价格图上是否明显。
把模拟数据的随机种子从 42 改成 7，再生成一次，观察结论是否稳定。
用 pandas.Series.skew() 和 pandas.Series.kurt() 查看收益率的偏度和峰度。
试着下载一个真实指数或 ETF 的日线数据，再重复同样分析，并在报告中说明数据来源。

14. 验收检查

在项目根目录执行：

ompfish

source .venv/bin/activate.fish
python src/make_sample_prices.py
python src/week13_time_series_basics.py
python -c "from pathlib import Path; required = ['data/prices.csv', 'figures/price_and_returns.png', 'figures/rolling_stats.png', 'figures/autocorrelation.png', 'reports/week13_time_series_notes.md']; missing = [p for p in required if not Path(p).exists()]; print('missing:', missing); raise SystemExit(1 if missing else 0)"

通过标准：

命令能顺利运行。
figures/ 下有三张图片。
报告能解释价格和收益率的差异。
你能口头说明为什么时间序列不能随便随机打乱。

15. 常见错误

错误 1：fish 中激活环境失败

错误原因通常是用了 Bash / Zsh 的激活脚本。

fish 应使用：

ompfish

source .venv/bin/activate.fish

错误 2：收益率第一行是空值

这是正常的，因为第一天没有前一天价格。不要为了“看起来整齐”把它随便改成 0。

错误 3：rolling 前几行是空值

rolling(20) 需要至少 20 个观测值。前 19 行没有完整窗口，所以是缺失值。

错误 4：图保存失败

先确认 figures/ 存在：

ompfish

mkdir -p figures

脚本里也建议写：

omppython

Path("figures").mkdir(exist_ok=True)

错误 5：把价格图看成策略收益

价格上涨不代表策略有效。策略必须明确什么时候买、什么时候卖、交易成本多少、样本外是否有效。这些将在 Week 15 和 Week 16 继续做。

16. 下一步

进入 Week 14：时间序列验证、rolling window 与数据泄露检查。下一周重点不是模型多高级，而是避免把未来信息泄露给过去。

plain

Week 12：AI 项目复盘报告——实验表、Ablation、README 与 Limitations

Sun, 26 Jul 2026 04:00:00 GMT

Oh My Pi / weekly tutorial / week12-ai-project-review-report

miku@cachyos:~/Code/python-learning$ omp teach week12-ai-project-review-report --fish-first --step-by-step

source436 行教学文档

weekWeek 12

shellfish-first 命令版

backlink20 周计划

Week 12：AI 项目复盘报告——实验表、Ablation、README 与 Limitations

回到总路线：USTC 统计 AI / 量化 20 周成长计划
本周目标对应计划中的 Week 12：让 AI 比赛或深度学习项目能被老师、面试官和未来的自己看懂。

本教程默认你使用 CachyOS + fish shell + VS Code + uv + Python + Git。所有命令默认是 fish。本周不再只是“跑模型”，而是把 Week 10 / Week 11 的项目整理成一份有证据、有对比、有局限性的复盘报告。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	ablation、failure cases、limitations、solution.md
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`projects/ai-competition-review/solution.md`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

rows = [
    {"experiment": "baseline", "f1": 0.71, "note": "logreg"},
    {"experiment": "+cleaning", "f1": 0.75, "note": "remove leakage"},
]
for row in rows:
    print(row)

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `projects/ai-competition-review/solution.md`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周目标

完成后，你应该拥有：

一份 reports/project_review.md，说明任务、数据、贡献、baseline、改进、实验、结果、失败案例和收获。
一张实验表，记录每次改动和指标。
至少一个 ablation，对比“去掉某个改动后结果如何”。
一个可读的 README.md，让别人知道如何复现。
明确的 limitations，不夸大项目结果。

本周核心能力是：用结构化证据说明你做了什么，而不是只说“我参加过 AI 比赛”。

2. 前置条件

你需要已经完成以下二者之一：

Week 10 的 PyTorch 小项目。
Week 11 的 AI 比赛整理项目。

你还需要有至少 2 到 3 条实验记录，例如：

ompprompt

baseline
baseline + feature engineering
baseline + feature engineering + tuned hyperparameters

先进入你要复盘的项目。如果还没有项目，可以新建一个复盘练习目录：

ompfish

mkdir -p ~/Code/ustc-ai/week12-ai-project-review
cd ~/Code/ustc-ai/week12-ai-project-review
uv init --name week12-ai-project-review
uv venv
source .venv/bin/activate.fish
uv add pandas matplotlib
code .

3. 文件布局

如果你接着 Week 10 / Week 11 项目做，推荐补齐这些文件：

ompfish

mkdir -p reports figures src

目标布局：

ompprompt

project-root/
├── README.md
├── solution.md
├── reports/
│   ├── experiments.csv
│   ├── experiment_table.md
│   └── project_review.md
├── figures/
│   └── accuracy_by_experiment.png
└── src/
    └── summarize_experiments.py

文件职责：

文件	作用
`reports/experiments.csv`	机器可读实验记录
`reports/experiment_table.md`	可粘贴进报告或 README 的 Markdown 表格
`figures/accuracy_by_experiment.png`	指标对比图
`reports/project_review.md`	本周核心复盘报告
`README.md`	项目入口说明
`solution.md`	技术方案说明

4. 建立实验表

创建 reports/experiments.csv。可以先在 VS Code 里手动写：

ompcsv

id,date,model,change,valid_metric,public_score,notes
exp001,2026-07-26,MLP,baseline,0.921,,first clean baseline
exp002,2026-07-26,MLP,hidden_dim 128 to 256,0.934,,larger model improved validation
exp003,2026-07-26,CNN,small cnn baseline,0.958,,cnn uses image structure
exp004,2026-07-26,CNN,remove second conv layer,0.941,,ablation: second conv helps

字段解释：

字段	含义
`id`	实验编号，永远不要复用
`date`	实验日期
`model`	模型或方法
`change`	本次实验相对上次改了什么
`valid_metric`	本地验证集指标
`public_score`	如果是比赛，可填 public leaderboard 分数
`notes`	观察和结论

注意：每行最好只对应一个主要变化。否则无法判断改动是否有效。

5. 生成 Markdown 表和图

创建 src/summarize_experiments.py：

omppython

from __future__ import annotations
from pathlib import Path
import matplotlib.pyplot as plt
import pandas as pd
EXPERIMENTS_CSV = Path(“reports/experiments.csv”)
TABLE_MD = Path(“reports/experiment_table.md”)
FIGURE_PATH = Path(“figures/accuracy_by_experiment.png”)
def main() -> None:
experiments = pd.read_csv(EXPERIMENTS_CSV)
required_columns = {“id”, “model”, “change”, “valid_metric”, “notes”}
missing_columns = required_columns - set(experiments.columns)
if missing_columns:
raise ValueError(f”missing columns: {sorted(missing_columns)}”)
plain TABLE_MD.parent.mkdir(parents=True, exist_ok=True)
FIGURE_PATH.parent.mkdir(parents=True, exist_ok=True)
plain table = experiments[[“id”, “model”, “change”, “valid_metric”, “notes”]]
TABLE_MD.write_text(table.to_markdown(index=False), encoding=“utf-8”)
plain plt.figure(figsize=(8, 4))
plt.plot(experiments[“id”], experiments[“valid_metric”], marker=“o”)
plt.xlabel(“experiment”)
plt.ylabel(“validation metric”)
plt.title(“Validation metric by experiment”)
plt.xticks(rotation=30, ha=“right”)
plt.tight_layout()
plt.savefig(FIGURE_PATH, dpi=150)
plt.close()
best = experiments.sort_values(&quot;valid_metric&quot;, ascending=False).iloc[0]
print(f&quot;best_experiment={best[&#39;id&#39;]} valid_metric={best[&#39;valid_metric&#39;]}&quot;)
print(f&quot;wrote {TABLE_MD}&quot;)
print(f&quot;wrote {FIGURE_PATH}&quot;)
if name == “main”:
main()

运行：

ompfish

source .venv/bin/activate.fish
python src/summarize_experiments.py

如果报 Missing optional dependency 'tabulate'，安装表格依赖：

ompfish

uv add tabulate
python src/summarize_experiments.py

检查产物：

ompfish

test -f reports/experiment_table.md; and test -f figures/accuracy_by_experiment.png

6. 什么是 ablation

Ablation 指“去掉某个模块或改动，观察结果变化”。它不是随便多跑几个实验，而是回答：这个改动是否真的有用？

例子：

实验	改动	指标	结论
exp003	CNN baseline with two conv layers	0.958	当前最好
exp004	remove second conv layer	0.941	第二个卷积层有帮助

写 ablation 时要避免：

同时改模型、学习率、数据增强，然后说某个改动有效。
只报告提升，不报告失败。
没有固定 seed，导致对比不公平。

7. 项目复盘报告结构

创建 reports/project_review.md，推荐结构如下：

ompmarkdown

# AI Competition / Deep Learning Project Review
Task

Problem:
Input:
Output:
Metric:

Dataset

Source:
Size:
Features / modalities:
Train / validation split:
Important preprocessing:

My Contribution

I implemented:
I cleaned:
I trained:
I analyzed:

Baseline

Model:
Why this baseline:
Baseline result:

Improvements

Improvement 1:
Improvement 2:
Improvement 3:

Experiments
Paste or link reports/experiment_table.md here.
Ablation

Removed component:
Result change:
Interpretation:

Result

Best validation score:
Public leaderboard score if any:
Final selected model:

Failure Cases

Case 1:
Case 2:
What these failures suggest:

Limitations

Dataset limitation:
Evaluation limitation:
Model limitation:
Engineering limitation:

What I Learned

Technical lesson:
Statistical lesson:
Engineering lesson:

重点不是写得华丽，而是每一段都有证据。

8. README 应该怎么写

项目根目录 README.md 是别人打开仓库最先看到的文件。它应该短、清楚、可执行。

推荐结构：

ompmarkdown

# Project Name
Summary
One paragraph explaining the task, method, and best result.
File Layout
configs/      experiment configs
src/          training and inference code
reports/      experiment table and review report
figures/      generated charts
data/raw/     local raw data, not committed
Environment
uv venv
source .venv/bin/activate.fish
uv sync
Train
python src/train.py --model mlp --epochs 20
Evaluate
python src/evaluate.py --checkpoint checkpoints/best_mlp.pt
Results




















Model Validation Metric Notes
baseline fill fill
best fill fill
Limitations

Limitation 1.
Limitation 2.
Limitation 3.

Model	Validation Metric	Notes
baseline	fill	fill
best	fill	fill

如果你的 Week 11 项目使用 python -m competition_project.train，README 里的命令就写项目真实命令，不要照抄上面的 MLP 命令。

9. 如何写 limitations

Limitations 不是自我否定，而是说明你知道项目边界。

好的 limitations：

ompprompt

- Validation uses a single random split; cross-validation was not performed.
- The dataset is small and clean, so the result may not transfer to noisy real-world data.
- Hyperparameter search was limited to three manual trials due to CPU-only training.
- Failure cases suggest the model confuses visually similar classes.

不好的 limitations：

ompprompt

- My computer was bad.
- The model could be better.
- Need more time.

好的写法要具体、可验证、能引出下一步。

10. 如何写给老师或面试官看的贡献

不要只写：

ompprompt

I participated in the competition.

改成：

ompprompt

I cleaned the tabular features, built a RandomForest baseline, fixed the train / inference feature mismatch, and wrote an ablation comparing categorical encoding strategies. The final local macro-F1 improved from 0.742 to 0.781.

结构是：

ompprompt

我做了什么 -> 解决了什么问题 -> 指标或证据是什么

11. 练习

从 reports/experiments.csv 里选出 best experiment，并在 project_review.md 中解释为什么选它。
至少写一个 ablation：去掉一个层、一个特征、一种增强或一个清洗步骤。
在 Failure Cases 中放 2 个真实错误例子。如果是图像项目，可以写错分图片编号；如果是表格项目，可以写被误判样本的特征特点。
把 README 的运行命令复制到一个新终端里执行一遍，确认没有漏步骤。
给 Limitations 写 3 条具体限制，每条都要能被事实支持。

12. 验收检查

在项目根目录执行：

ompfish

source .venv/bin/activate.fish
test -f reports/experiments.csv; and test -f reports/project_review.md; and test -f README.md
python src/summarize_experiments.py
test -f reports/experiment_table.md; and test -f figures/accuracy_by_experiment.png

通过标准：

reports/project_review.md 包含 Task、Dataset、My Contribution、Baseline、Improvements、Experiments、Result、Failure Cases、What I Learned。
实验表中至少有 baseline、best、一个 ablation。
README 里有环境、训练、评估或推理命令。
Limitations 至少 3 条，并且不夸大项目结果。
复盘报告能让没有参加项目的人看懂你做了什么。

13. 常见错误

13.1 只写结果，不写过程

错误写法：

ompprompt

We achieved 0.958 accuracy.

更好的写法：

ompprompt

The CNN baseline achieved 0.958 validation accuracy. Compared with the MLP baseline at 0.934, the CNN improved performance by using local image structure.

13.2 实验表没有对比意义

如果每次实验都同时改很多东西，就无法得出结论。实验表应该支持类似问题：

CNN 是否优于 MLP？
第二个卷积层是否有用？
某个特征工程是否提升指标？

13.3 README 命令不能运行

每次改 README 后，至少在新终端里检查环境命令。fish 项目应写：

ompfish

source .venv/bin/activate.fish

不要把 Bash / Zsh 的激活命令混进 fish 教程里。

13.4 limitations 写得太空

“模型还可以优化”不是有效 limitation。你要写清楚受什么限制、可能影响什么、下一步怎么验证。

13.5 把复盘报告写成流水账

报告不是日记。不要按“第一天我做了什么，第二天我做了什么”写；要按 Task、Dataset、Method、Experiments、Result、Limitations 组织。

14. 下一步

进入 Week 13：时间序列基础。你会从普通机器学习项目转向有时间顺序的数据，学习 ARIMA、rolling validation，并为后续量化回测打基础。

plain

Week 11：AI 比赛代码整理——从混乱 notebook 到可复现项目

Sun, 26 Jul 2026 03:00:00 GMT

Oh My Pi / weekly tutorial / week11-ai-competition-code-cleanup

miku@cachyos:~/Code/python-learning$ omp teach week11-ai-competition-code-cleanup --fish-first --step-by-step

source644 行教学文档

weekWeek 11

shellfish-first 命令版

backlink20 周计划

Week 11：AI 比赛代码整理——从混乱 notebook 到可复现项目

回到总路线：USTC 统计 AI / 量化 20 周成长计划
本周目标对应计划中的 Week 11：把 AI 比赛或课程项目整理成简历项目，沉淀数据清洗、baseline、特征工程、模型训练、调参、结果分析和文档。

本教程默认你使用 CachyOS + fish shell + VS Code + uv + Python + Git。所有命令默认是 fish。你可以整理真实比赛项目，也可以用一个课程数据集补做一个模块；重点是让项目结构、配置、随机种子、训练入口和 inference 入口清楚。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	notebook 拆分、配置、日志、实验记录
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`projects/ai-competition-review/`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

from dataclasses import dataclass
@dataclass(frozen=True)
class Config:
seed: int = 42
data_path: str = “data/train.csv”
output_dir: str = “outputs”
config = Config()
print(config)

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `projects/ai-competition-review/`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周目标

完成后，你的项目应该从：

ompprompt

notebook_final.ipynb
notebook_final_v2.ipynb
try_again.py
submit_latest.csv

整理成：

ompprompt

projects/ai-competition-review/
├── README.md
├── solution.md
├── configs/
├── data/
├── src/
├── outputs/
├── submissions/
└── reports/

你要交付的不是“更漂亮的文件夹”，而是一个别人能理解、能运行、能复现、能生成预测文件的项目。

2. 前置条件

你需要已经具备：

会创建和激活 uv 虚拟环境。
会运行 Python 脚本。
理解 train / validation split。
至少有一个比赛、课程项目或公开数据集项目可以整理。
知道不要把大数据和私密 token 提交到 Git。

先确认：

ompfish

python --version
uv --version
git --version

3. 建立整理用项目

如果你已有比赛项目，可以在原项目旁边新建一个干净版本；不要直接在混乱目录里硬改。

ompfish

mkdir -p ~/Code/ustc-ai/week11-ai-competition-review
cd ~/Code/ustc-ai/week11-ai-competition-review
uv init --name week11-ai-competition-review
uv venv
source .venv/bin/activate.fish
uv add pandas numpy scikit-learn joblib
code .

命令解释：

命令	作用
`uv init`	生成项目配置
`uv venv`	建立隔离环境
`source .venv/bin/activate.fish`	用 fish 激活环境
`uv add ...`	安装表格比赛常用依赖
`code .`	打开 VS Code 进行整理

如果你的比赛是图像或 NLP，可以额外安装 torch、torchvision、transformers 等；但本教程用表格分类 baseline 演示，因为它最适合讲清楚工程结构。

4. 目标文件布局

创建目录：

ompfish

mkdir -p configs data/raw data/processed src/competition_project outputs/models submissions reports notebooks

推荐布局：

ompprompt

week11-ai-competition-review/
├── configs/
│   └── baseline.toml
├── data/
│   ├── raw/
│   │   ├── train.csv
│   │   └── test.csv
│   └── processed/
├── src/
│   └── competition_project/
│       ├── __init__.py
│       ├── config.py
│       ├── data.py
│       ├── features.py
│       ├── model.py
│       ├── train.py
│       ├── infer.py
│       └── utils.py
├── outputs/
│   └── models/
├── submissions/
├── reports/
│   └── experiments.md
├── notebooks/
├── README.md
└── solution.md

每个目录的职责：

路径	放什么	不放什么
`configs/`	超参数、路径、随机种子	临时实验结果
`data/raw/`	原始比赛数据	手工改过的数据
`data/processed/`	可重新生成的中间数据	唯一副本
`src/competition_project/`	可复用 Python 代码	大段实验笔记
`outputs/models/`	训练出的模型文件	源代码
`submissions/`	提交文件	模型权重
`reports/`	实验表、错误分析	原始数据
`notebooks/`	探索性分析	唯一可运行训练逻辑

5. 把旧文件迁移进新结构

假设旧项目在 ~/Downloads/my-competition-messy，先只复制你需要保留的文件：

ompfish

cp ~/Downloads/my-competition-messy/train.csv data/raw/train.csv
cp ~/Downloads/my-competition-messy/test.csv data/raw/test.csv
cp ~/Downloads/my-competition-messy/best_notes.ipynb notebooks/eda_original.ipynb

如果文件名不同，就按你的实际情况改。原则是：

原始数据只进 data/raw/。
notebook 只作为分析记录，不再作为主训练入口。
最终训练逻辑要落到 src/competition_project/train.py。
最终预测逻辑要落到 src/competition_project/infer.py。

6. 写配置文件

创建 configs/baseline.toml：

omptoml

[paths]
train_csv = "data/raw/train.csv"
test_csv = "data/raw/test.csv"
model_path = "outputs/models/baseline.joblib"
submission_path = "submissions/baseline_submission.csv"
[target]
column = “target”
id_column = “id”
[train]
seed = 42
valid_size = 0.2
[model]
type = “random_forest”
n_estimators = 300
max_depth = 8

注意：上面假设你的训练集有 target 列，测试集有 id 列。真实比赛可能叫 label、SalePrice、isDefault 或其他名字，你需要改成自己的列名。

如果你复制后发现 TOML 报错，检查 section 名称。正确写法应该是：

omptoml

[target]
column = "target"
id_column = "id"

7. 配置读取：`config.py`

创建 src/competition_project/__init__.py，可以先留空。

创建 src/competition_project/config.py：

omppython

from __future__ import annotations
import tomllib
from pathlib import Path
from typing import Any
def load_config(path: str | Path) -> dict[str, Any]:
config_path = Path(path)
with config_path.open(“rb”) as file:
return tomllib.load(file)

保持简单。Week 11 不需要一上来引入复杂配置框架。

8. 可复现工具：`utils.py`

创建 src/competition_project/utils.py：

omppython

from __future__ import annotations
import os
import random
from pathlib import Path
import numpy as np
def seed_everything(seed: int) -> None:
os.environ[“PYTHONHASHSEED”] = str(seed)
random.seed(seed)
np.random.seed(seed)
def ensure_parent(path: str | Path) -> None:
Path(path).parent.mkdir(parents=True, exist_ok=True)

为什么要固定随机种子：

train / validation split 会受随机数影响。
随机森林、神经网络初始化也会受随机数影响。
复盘报告里需要说明结果来自哪个 seed。

9. 数据读取：`data.py`

创建 src/competition_project/data.py：

omppython

from __future__ import annotations
import pandas as pd
def read_train_test(train_csv: str, test_csv: str) -> tuple[pd.DataFrame, pd.DataFrame]:
train = pd.read_csv(train_csv)
test = pd.read_csv(test_csv)
return train, test
def split_features_target(
train: pd.DataFrame,
target_column: str,
) -> tuple[pd.DataFrame, pd.Series]:
y = train[target_column]
x = train.drop(columns=[target_column])
return x, y

原则：读取数据和训练模型分开。不要在 train.py 里塞满所有细节。

10. 特征工程：`features.py`

创建 src/competition_project/features.py：

omppython

from __future__ import annotations
import pandas as pd
from sklearn.compose import ColumnTransformer
from sklearn.impute import SimpleImputer
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler
def build_preprocessor(features: pd.DataFrame) -> ColumnTransformer:
numeric_columns = features.select_dtypes(include=[“number”, “bool”]).columns.tolist()
categorical_columns = [column for column in features.columns if column not in numeric_columns]
plain numeric_pipeline = Pipeline(
steps=[
(“imputer”, SimpleImputer(strategy=“median”)),
(“scaler”, StandardScaler()),
]
)
categorical_pipeline = Pipeline(
steps=[
(“imputer”, SimpleImputer(strategy=“most_frequent”)),
(“one_hot”, OneHotEncoder(handle_unknown=“ignore”)),
]
)
plain return ColumnTransformer(
transformers=[
(“numeric”, numeric_pipeline, numeric_columns),
(“categorical”, categorical_pipeline, categorical_columns),
]
)

这个版本适合表格分类 baseline：

数值列：缺失值用中位数填充，然后标准化。
类别列：缺失值用众数填充，然后 one-hot。
测试集中出现训练集没见过的类别时，handle_unknown="ignore" 不会直接崩。

11. 模型定义：`model.py`

创建 src/competition_project/model.py：

omppython

from __future__ import annotations
from sklearn.ensemble import RandomForestClassifier
from sklearn.linear_model import LogisticRegression
def build_model(config: dict):
model_type = config[“model”][“type”]
seed = config[“train”][“seed”]
plain if model_type == “random_forest”:
return RandomForestClassifier(
n_estimators=config[“model”][“n_estimators”],
max_depth=config[“model”][“max_depth”],
random_state=seed,
n_jobs=-1,
)
plain if model_type == “logistic_regression”:
return LogisticRegression(max_iter=1000, random_state=seed)
plain raise ValueError(f”unsupported model type: {model_type}”)

这里先支持两个模型，方便你做 baseline 对比。不要在 Week 11 一次性塞入十几个模型；项目清晰比模型数量更重要。

12. 训练入口：`train.py`

创建 src/competition_project/train.py：

omppython

from __future__ import annotations
import argparse
from pathlib import Path
import joblib
import pandas as pd
from sklearn.metrics import accuracy_score, f1_score
from sklearn.model_selection import train_test_split
from sklearn.pipeline import Pipeline
from competition_project.config import load_config
from competition_project.data import read_train_test, split_features_target
from competition_project.features import build_preprocessor
from competition_project.model import build_model
from competition_project.utils import ensure_parent, seed_everything
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser()
parser.add_argument(“—config”, type=Path, default=Path(“configs/baseline.toml”))
return parser.parse_args()
def main() -> None:
args = parse_args()
config = load_config(args.config)
seed_everything(config[“train”][“seed”])
plain train, _ = read_train_test(config[“paths”][“train_csv”], config[“paths”][“test_csv”])
features, target = split_features_target(train, config[“target”][“column”])
plain drop_columns = [config[“target”].get(“id_column”)]
drop_columns = [column for column in drop_columns if column and column in features.columns]
features = features.drop(columns=drop_columns)
plain x_train, x_valid, y_train, y_valid = train_test_split(
features,
target,
test_size=config[“train”][“valid_size”],
stratify=target if target.nunique() < 20 else None,
random_state=config[“train”][“seed”],
)
pipeline = Pipeline(
    steps=[
        (&quot;preprocess&quot;, build_preprocessor(x_train)),
        (&quot;model&quot;, build_model(config)),
    ]
)
pipeline.fit(x_train, y_train)
predictions = pipeline.predict(x_valid)

metrics = {
    &quot;accuracy&quot;: accuracy_score(y_valid, predictions),
    &quot;f1_macro&quot;: f1_score(y_valid, predictions, average=&quot;macro&quot;),
}
print(metrics)

model_path = Path(config[&quot;paths&quot;][&quot;model_path&quot;])
ensure_parent(model_path)
joblib.dump({&quot;pipeline&quot;: pipeline, &quot;config&quot;: config, &quot;metrics&quot;: metrics}, model_path)

report_path = Path(&quot;reports/baseline_metrics.csv&quot;)
ensure_parent(report_path)
pd.DataFrame([metrics]).to_csv(report_path, index=False)
print(f&quot;model saved to {model_path}&quot;)
print(f&quot;metrics saved to {report_path}&quot;)
if name == “main”:
main()

运行训练：

ompfish

source .venv/bin/activate.fish
set -gx PYTHONPATH src
python -m competition_project.train --config configs/baseline.toml

set -gx PYTHONPATH src 的作用是告诉 Python：模块包在 src/ 目录下。以后你也可以改成正式打包方式，但 Week 11 先保持直接。

13. 推理入口：`infer.py`

创建 src/competition_project/infer.py：

omppython

from __future__ import annotations
import argparse
from pathlib import Path
import joblib
import pandas as pd
from competition_project.utils import ensure_parent
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser()
parser.add_argument(“—model”, type=Path, default=Path(“outputs/models/baseline.joblib”))
parser.add_argument(“—test”, type=Path, default=Path(“data/raw/test.csv”))
parser.add_argument(“—output”, type=Path, default=Path(“submissions/baseline_submission.csv”))
return parser.parse_args()
def main() -> None:
args = parse_args()
artifact = joblib.load(args.model)
pipeline = artifact[“pipeline”]
config = artifact[“config”]
plain test = pd.read_csv(args.test)
id_column = config[“target”].get(“id_column”)
ids = test[id_column] if id_column in test.columns else pd.Series(range(len(test)), name=“id”)
features = test.drop(columns=[id_column]) if id_column in test.columns else test
plain predictions = pipeline.predict(features)
submission = pd.DataFrame({id_column or “id”: ids, config[“target”][“column”]: predictions})
plain ensure_parent(args.output)
submission.to_csv(args.output, index=False)
print(f”submission saved to {args.output}”)
if name == “main”:
main()

运行推理：

ompfish

source .venv/bin/activate.fish
set -gx PYTHONPATH src
python -m competition_project.infer --model outputs/models/baseline.joblib --test data/raw/test.csv --output submissions/baseline_submission.csv

这一步的意义：

比赛项目必须能生成提交文件。
infer.py 不应该重新训练模型。
训练和推理使用同一个预处理 pipeline，避免训练时和提交时特征不一致。

14. Git 忽略规则

创建或更新 .gitignore：

ompprompt

.venv/
__pycache__/
*.pyc
.ipynb_checkpoints/
data/raw/
data/processed/
outputs/models/
submissions/*.csv

解释：

虚拟环境不提交。
原始比赛数据通常不提交，尤其是有比赛协议或体积大时。
模型文件一般不提交到普通 Git 仓库。
可以提交 configs/、src/、reports/、README.md、solution.md。

15. 写 `solution.md`

solution.md 不需要很长，但要讲清楚方案：

ompmarkdown

# Solution
Task

Competition / dataset name:
Prediction target:
Metric:

Data Cleaning

Missing values:
Categorical features:
Numeric features:

Baseline

Model:
Validation split:
Metric:

Improvements

Feature engineering tried:
Model changes tried:
Hyperparameters tried:

Result

Local validation:
Public leaderboard if available:
Private leaderboard if available:

My Contribution

I implemented:
I debugged:
I analyzed:

老师或面试官最关心的是：你做了什么、为什么这样做、结果如何、失败了什么。

16. 实验记录：`reports/experiments.md`

创建 reports/experiments.md：

ompmarkdown

# Experiments





































ID Date Change Valid Metric Submission Notes
exp001 2026-07-26 random forest baseline fill baseline_submission.csv first clean run
exp002 2026-07-26 add feature group A fill compare with exp001

每次实验只记录一个主要变化。不要写“改了很多东西然后提升了”，那样无法复盘。
17. 练习

把 random_forest 改成 logistic_regression，记录指标差异。
增加一个简单特征，例如两个数值列的比值，并记录是否提升。
在 solution.md 中写清楚你负责的模块。如果原比赛中你只参与了一小部分，本周补做一个完整 baseline。
在 infer.py 里确认输出列名符合比赛提交格式。
把 notebook 中能复用的函数迁移到 src/competition_project/，notebook 只保留分析图和思路。

18. 验收检查
在项目根目录执行：
ompfish
source .venv/bin/activate.fish
set -gx PYTHONPATH src
test -f configs/baseline.toml; and test -f src/competition_project/train.py; and test -f src/competition_project/infer.py
test -f README.md; and test -f solution.md; and test -f reports/experiments.md
python -m competition_project.train --config configs/baseline.toml
python -m competition_project.infer --model outputs/models/baseline.joblib --test data/raw/test.csv --output submissions/baseline_submission.csv

通过标准：

train.py 可以训练并保存模型。
infer.py 可以读取模型并生成提交 CSV。
配置、随机种子、路径都不硬编码在 notebook 里。
solution.md 写清楚任务、方案、结果和你的贡献。
reports/experiments.md 至少有一条真实实验记录。

19. 常见错误
19.1 fish 环境没有激活
打开新终端后先执行：
ompfish
source .venv/bin/activate.fish

否则可能调用系统 Python，导致找不到 pandas 或 sklearn。
19.2 忘记设置 PYTHONPATH
如果看到 ModuleNotFoundError: No module named 'competition_project'，执行：
ompfish
set -gx PYTHONPATH src

然后重新运行 python -m competition_project.train。
19.3 配置文件 TOML 写错
TOML section 必须写成：
omptoml
[target]
column = "target"
id_column = "id"

不要漏掉左方括号。
19.4 训练和推理特征不一致
不要在 infer.py 里重新写一套预处理逻辑。正确做法是把预处理器和模型放在同一个 sklearn Pipeline 里，一起保存。
19.5 把数据和模型权重提交到 Git
先检查：
ompfish
git status --short

如果看到 data/raw/ 或 outputs/models/ 里的大文件准备提交，说明 .gitignore 没写好或文件已经被 Git 跟踪，需要先处理。
20. 下一步
进入 Week 12：把 Week 10 的深度学习项目或 Week 11 的比赛整理项目写成项目复盘报告。你会制作实验表、ablation、README、limitations，并学会用“证据”说明你的改进是否真的有效。
plain

ID	Date	Change	Valid Metric	Submission	Notes
exp001	2026-07-26	random forest baseline	fill	baseline_submission.csv	first clean run
exp002	2026-07-26	add feature group A	fill		compare with exp001

Week 10：深度学习小项目——MLP / CNN baseline、checkpoint、loss 曲线与评估

Sun, 26 Jul 2026 02:00:00 GMT

Oh My Pi / weekly tutorial / week10-deep-learning-mini-project

miku@cachyos:~/Code/python-learning$ omp teach week10-deep-learning-mini-project --fish-first --step-by-step

source658 行教学文档

weekWeek 10

shellfish-first 命令版

backlink20 周计划

Week 10：深度学习小项目——MLP / CNN baseline、checkpoint、loss 曲线与评估

回到总路线：USTC 统计 AI / 量化 20 周成长计划
本周目标对应计划中的 Week 10：在 MNIST / CIFAR10 / 表格数据上训练一个小模型，记录 loss 曲线，保存 checkpoint，做验证集评估。

本教程默认你使用 CachyOS + fish shell + VS Code + uv + Python + Git。所有终端命令默认是 fish。为了 CPU-first、可复现、无需下载大数据，本周使用 scikit-learn 自带的 digits 数据集：8×8 手写数字图片，适合练 MLP 和 CNN baseline。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	MLP/CNN、checkpoint、loss 曲线、evaluate.py
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`projects/pytorch-baseline/`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

checkpoint = {
    "model_state": model.state_dict(),
    "epoch": epoch,
    "valid_loss": valid_loss,
}
torch.save(checkpoint, "outputs/best.pt")
loaded = torch.load("outputs/best.pt", map_location="cpu")
model.load_state_dict(loaded["model_state"])

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `projects/pytorch-baseline/`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周目标

完成后你会得到一个小而完整的深度学习项目：

train.py 支持 MLP 和 CNN 两种 baseline。
训练过程保存 best checkpoint。
训练过程记录 train_loss、valid_loss、valid_acc。
自动生成 loss 曲线图。
evaluate.py 可以从 checkpoint 重新加载模型并评估。
项目结构接近以后比赛和科研项目的最小形态。

本周不追求复杂模型，重点是工程闭环：能训练、能保存、能复评、能解释。

2. 前置条件

你需要已经完成 Week 09，至少理解：

Tensor 的 shape 和 dtype。
Dataset / DataLoader。
nn.Module。
model.train() 和 model.eval() 的区别。
loss.backward() 与 optimizer.step()。

确认工具：

ompfish

python --version
uv --version
git --version

3. 建立项目

ompfish

mkdir -p ~/Code/ustc-ai/week10-deep-learning-mini-project
cd ~/Code/ustc-ai/week10-deep-learning-mini-project
uv init --name week10-deep-learning-mini-project
uv venv
source .venv/bin/activate.fish
uv add torch scikit-learn matplotlib pandas
code .

解释：

命令	作用
`uv init`	初始化 Python 项目
`uv venv`	创建隔离虚拟环境
`source .venv/bin/activate.fish`	用 fish 激活环境
`uv add torch ...`	安装 PyTorch、数据集、画图和表格依赖
`code .`	用 VS Code 打开项目

4. 文件布局

创建目录：

ompfish

mkdir -p src configs checkpoints reports figures

推荐布局：

ompprompt

week10-deep-learning-mini-project/
├── configs/
│   └── digits.toml
├── src/
│   ├── train.py
│   └── evaluate.py
├── checkpoints/
│   └── best_mlp.pt
├── reports/
│   └── metrics_mlp.csv
├── figures/
│   └── loss_curve_mlp.png
├── pyproject.toml
└── README.md

用途说明：

路径	用途
`configs/`	放实验配置，避免超参数散落在代码里
`src/train.py`	训练入口
`src/evaluate.py`	独立评估入口
`checkpoints/`	保存模型权重和必要元信息
`reports/`	保存指标 CSV
`figures/`	保存 loss 曲线
`README.md`	给别人说明如何复现

5. 写配置文件

创建 configs/digits.toml：

omptoml

[train]
epochs = 20
batch_size = 64
learning_rate = 0.001
seed = 42
valid_size = 0.2
[model]
hidden_dim = 128

为什么要有配置文件：

你以后会频繁改 epoch、学习率、batch size。
配置和代码分开，实验记录更清楚。
复现实验时，别人不需要读完整代码才能知道你怎么训练的。

6. 训练脚本：支持 MLP 和 CNN

创建 src/train.py：

omppython

from __future__ import annotations
import argparse
import csv
import random
import tomllib
from pathlib import Path
import matplotlib.pyplot as plt
import numpy as np
import torch
from sklearn.datasets import load_digits
from sklearn.model_selection import train_test_split
from torch import nn
from torch.utils.data import DataLoader, Dataset
class DigitsDataset(Dataset):
def init(self, images: np.ndarray, labels: np.ndarray, model_type: str) -> None:
images = images.astype(“float32”) / 16.0
if model_type == “mlp”:
images = images.reshape(len(images), -1)
else:
images = images[:, None, :, :]
self.images = torch.tensor(images, dtype=torch.float32)
self.labels = torch.tensor(labels, dtype=torch.long)
plain def len(self) -> int:
return len(self.labels)
plain def getitem(self, index: int) -> tuple[torch.Tensor, torch.Tensor]:
return self.images[index], self.labels[index]
class MLP(nn.Module):
def init(self, hidden_dim: int, num_classes: int = 10) -> None:
super().init()
self.net = nn.Sequential(
nn.Linear(64, hidden_dim),
nn.ReLU(),
nn.Linear(hidden_dim, hidden_dim),
nn.ReLU(),
nn.Linear(hidden_dim, num_classes),
)
plain def forward(self, x: torch.Tensor) -> torch.Tensor:
return self.net(x)
class SmallCNN(nn.Module):
def init(self, num_classes: int = 10) -> None:
super().init()
self.features = nn.Sequential(
nn.Conv2d(1, 16, kernel_size=3, padding=1),
nn.ReLU(),
nn.MaxPool2d(2),
nn.Conv2d(16, 32, kernel_size=3, padding=1),
nn.ReLU(),
nn.MaxPool2d(2),
)
self.classifier = nn.Sequential(
nn.Flatten(),
nn.Linear(32 * 2 * 2, 64),
nn.ReLU(),
nn.Linear(64, num_classes),
)
plain def forward(self, x: torch.Tensor) -> torch.Tensor:
return self.classifier(self.features(x))
def set_seed(seed: int) -> None:
random.seed(seed)
np.random.seed(seed)
torch.manual_seed(seed)
def load_config(path: Path) -> dict:
with path.open(“rb”) as file:
return tomllib.load(file)
def build_loaders(config: dict, model_type: str) -> tuple[DataLoader, DataLoader]:
digits = load_digits()
x_train, x_valid, y_train, y_valid = train_test_split(
digits.images,
digits.target,
test_size=config[“train”][“valid_size”],
stratify=digits.target,
random_state=config[“train”][“seed”],
)
train_dataset = DigitsDataset(x_train, y_train, model_type)
valid_dataset = DigitsDataset(x_valid, y_valid, model_type)
train_loader = DataLoader(
train_dataset,
batch_size=config[“train”][“batch_size”],
shuffle=True,
)
valid_loader = DataLoader(
valid_dataset,
batch_size=config[“train”][“batch_size”],
shuffle=False,
)
return train_loader, valid_loader
def build_model(config: dict, model_type: str) -> nn.Module:
if model_type == “mlp”:
return MLP(hidden_dim=config[“model”][“hidden_dim”])
if model_type == “cnn”:
return SmallCNN()
raise ValueError(f”unknown model type: {model_type}”)
def run_epoch(
model: nn.Module,
loader: DataLoader,
criterion: nn.Module,
optimizer: torch.optim.Optimizer | None,
device: torch.device,
) -> tuple[float, float]:
is_train = optimizer is not None
model.train(is_train)
total_loss = 0.0
total_correct = 0
total_examples = 0
plain context = torch.enable_grad() if is_train else torch.no_grad()
with context:
for images, labels in loader:
images = images.to(device)
labels = labels.to(device)
plain         logits = model(images)
loss = criterion(logits, labels)
plain         if is_train:
optimizer.zero_grad()
loss.backward()
optimizer.step()
        total_loss += loss.item() * len(labels)
        total_correct += (logits.argmax(dim=1) == labels).sum().item()
        total_examples += len(labels)

return total_loss / total_examples, total_correct / total_examples
def save_metrics(path: Path, rows: list[dict[str, float]]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
with path.open(“w”, newline="") as file:
writer = csv.DictWriter(file, fieldnames=list(rows[0].keys()))
writer.writeheader()
writer.writerows(rows)
def save_loss_curve(path: Path, rows: list[dict[str, float]]) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
epochs = [row[“epoch”] for row in rows]
train_loss = [row[“train_loss”] for row in rows]
valid_loss = [row[“valid_loss”] for row in rows]
plain plt.figure(figsize=(7, 4))
plt.plot(epochs, train_loss, label=“train_loss”)
plt.plot(epochs, valid_loss, label=“valid_loss”)
plt.xlabel(“epoch”)
plt.ylabel(“loss”)
plt.title(“Digits baseline loss curve”)
plt.legend()
plt.tight_layout()
plt.savefig(path, dpi=150)
plt.close()
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser()
parser.add_argument(“—config”, type=Path, default=Path(“configs/digits.toml”))
parser.add_argument(“—model”, choices=[“mlp”, “cnn”], default=“mlp”)
parser.add_argument(“—epochs”, type=int, default=None)
return parser.parse_args()
def main() -> None:
args = parse_args()
config = load_config(args.config)
if args.epochs is not None:
config[“train”][“epochs”] = args.epochs
plain set_seed(config[“train”][“seed”])
device = torch.device(“cpu”)
train_loader, valid_loader = build_loaders(config, args.model)
model = build_model(config, args.model).to(device)
criterion = nn.CrossEntropyLoss()
optimizer = torch.optim.Adam(model.parameters(), lr=config[“train”][“learning_rate”])
plain best_acc = 0.0
rows: list[dict[str, float]] = []
checkpoint_path = Path(“checkpoints”) / f”best_{args.model}.pt”
plain for epoch in range(1, config[“train”][“epochs”] + 1):
train_loss, train_acc = run_epoch(model, train_loader, criterion, optimizer, device)
valid_loss, valid_acc = run_epoch(model, valid_loader, criterion, None, device)
row = {
“epoch”: epoch,
“train_loss”: train_loss,
“train_acc”: train_acc,
“valid_loss”: valid_loss,
“valid_acc”: valid_acc,
}
rows.append(row)
print(
f”epoch={epoch
} ”
f”train_loss={train_loss:.4f} train_acc={train_acc:.3f} ”
f”valid_loss={valid_loss:.4f} valid_acc={valid_acc:.3f}”
)
    if valid_acc &gt; best_acc:
        best_acc = valid_acc
        checkpoint_path.parent.mkdir(parents=True, exist_ok=True)
        torch.save(
            {
                &quot;model_type&quot;: args.model,
                &quot;model_state_dict&quot;: model.state_dict(),
                &quot;config&quot;: config,
                &quot;best_valid_acc&quot;: best_acc,
            },
            checkpoint_path,
        )

save_metrics(Path(&quot;reports&quot;) / f&quot;metrics_{args.model}.csv&quot;, rows)
save_loss_curve(Path(&quot;figures&quot;) / f&quot;loss_curve_{args.model}.png&quot;, rows)
print(f&quot;best_valid_acc={best_acc:.3f}&quot;)
print(f&quot;checkpoint={checkpoint_path}&quot;)
if name == “main”:
main()

运行 MLP baseline：

ompfish

source .venv/bin/activate.fish
python src/train.py --model mlp --epochs 5

再运行 CNN baseline：

ompfish

source .venv/bin/activate.fish
python src/train.py --model cnn --epochs 5

MLP 和 CNN 都可以在 CPU 上很快跑完。digits 数据集很小，所以这是练工程流程的项目，不是刷榜项目。

7. 评估脚本：从 checkpoint 复现结果

训练脚本能打印验证集指标，但项目里还需要独立评估入口。这样别人拿到你的 checkpoint 后，不需要重新训练。

创建 src/evaluate.py：

omppython

from __future__ import annotations
import argparse
from pathlib import Path
import numpy as np
import torch
from sklearn.datasets import load_digits
from sklearn.metrics import accuracy_score, classification_report
from sklearn.model_selection import train_test_split
from torch import nn
from torch.utils.data import DataLoader, Dataset
class DigitsDataset(Dataset):
def init(self, images: np.ndarray, labels: np.ndarray, model_type: str) -> None:
images = images.astype(“float32”) / 16.0
if model_type == “mlp”:
images = images.reshape(len(images), -1)
else:
images = images[:, None, :, :]
self.images = torch.tensor(images, dtype=torch.float32)
self.labels = torch.tensor(labels, dtype=torch.long)
plain def len(self) -> int:
return len(self.labels)
plain def getitem(self, index: int) -> tuple[torch.Tensor, torch.Tensor]:
return self.images[index], self.labels[index]
class MLP(nn.Module):
def init(self, hidden_dim: int, num_classes: int = 10) -> None:
super().init()
self.net = nn.Sequential(
nn.Linear(64, hidden_dim),
nn.ReLU(),
nn.Linear(hidden_dim, hidden_dim),
nn.ReLU(),
nn.Linear(hidden_dim, num_classes),
)
plain def forward(self, x: torch.Tensor) -> torch.Tensor:
return self.net(x)
class SmallCNN(nn.Module):
def init(self, num_classes: int = 10) -> None:
super().init()
self.features = nn.Sequential(
nn.Conv2d(1, 16, kernel_size=3, padding=1),
nn.ReLU(),
nn.MaxPool2d(2),
nn.Conv2d(16, 32, kernel_size=3, padding=1),
nn.ReLU(),
nn.MaxPool2d(2),
)
self.classifier = nn.Sequential(
nn.Flatten(),
nn.Linear(32 * 2 * 2, 64),
nn.ReLU(),
nn.Linear(64, num_classes),
)
plain def forward(self, x: torch.Tensor) -> torch.Tensor:
return self.classifier(self.features(x))
def build_model(model_type: str, config: dict) -> nn.Module:
if model_type == “mlp”:
return MLP(hidden_dim=config[“model”][“hidden_dim”])
if model_type == “cnn”:
return SmallCNN()
raise ValueError(f”unknown model type: {model_type}”)
def build_valid_loader(config: dict, model_type: str) -> DataLoader:
digits = load_digits()
_, x_valid, _, y_valid = train_test_split(
digits.images,
digits.target,
test_size=config[“train”][“valid_size”],
stratify=digits.target,
random_state=config[“train”][“seed”],
)
dataset = DigitsDataset(x_valid, y_valid, model_type)
return DataLoader(dataset, batch_size=config[“train”][“batch_size”], shuffle=False)
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser()
parser.add_argument(“—checkpoint”, type=Path, required=True)
return parser.parse_args()
def main() -> None:
args = parse_args()
checkpoint = torch.load(args.checkpoint, map_location=“cpu”, weights_only=False)
model_type = checkpoint[“model_type”]
config = checkpoint[“config”]
plain model = build_model(model_type, config)
model.load_state_dict(checkpoint[“model_state_dict”])
model.eval()
plain loader = build_valid_loader(config, model_type)
all_predictions: list[int] = []
all_labels: list[int] = []
plain with torch.no_grad():
for images, labels in loader:
logits = model(images)
all_predictions.extend(logits.argmax(dim=1).tolist())
all_labels.extend(labels.tolist())
print(f&quot;checkpoint={args.checkpoint}&quot;)
print(f&quot;accuracy={accuracy_score(all_labels, all_predictions):.3f}&quot;)
print(classification_report(all_labels, all_predictions, digits=3))
if name == “main”:
main()

评估 MLP checkpoint：

ompfish

source .venv/bin/activate.fish
python src/evaluate.py --checkpoint checkpoints/best_mlp.pt

评估 CNN checkpoint：

ompfish

source .venv/bin/activate.fish
python src/evaluate.py --checkpoint checkpoints/best_cnn.pt

8. 看训练产物

训练后检查：

ompfish

ls checkpoints
ls reports
ls figures

应该看到类似：

ompprompt

checkpoints/best_mlp.pt
reports/metrics_mlp.csv
figures/loss_curve_mlp.png

用 VS Code 打开 figures/loss_curve_mlp.png。你要观察：

train_loss 是否下降。
valid_loss 是否下降后变平。
如果 train_loss 下降但 valid_loss 上升，可能过拟合。

9. README 最小内容

更新项目根目录的 README.md，至少包含：

ompmarkdown

# Digits Deep Learning Baseline
Task
Classify 8x8 handwritten digit images from sklearn digits.
Environment

CachyOS
Python managed by uv
PyTorch CPU training

How to Run
uv venv
source .venv/bin/activate.fish
uv sync
python src/train.py --model mlp --epochs 20
python src/evaluate.py --checkpoint checkpoints/best_mlp.pt
Results




















Model Best Valid Accuracy Notes
MLP fill after training CPU baseline
CNN fill after training small convolution baseline
Limitations

Dataset is small and clean.
No external test set.
Hyperparameter search is minimal.

Model	Best Valid Accuracy	Notes
MLP	fill after training	CPU baseline
CNN	fill after training	small convolution baseline

如果 Markdown 中嵌套代码块让 VS Code 高亮混乱，可以先只写命令，不必追求复杂排版。

10. 练习

比较 mlp 和 cnn 的 best validation accuracy。
把 configs/digits.toml 中 learning_rate 改成 0.01，观察 loss 是否更不稳定。
把 hidden_dim 从 128 改成 32，比较 MLP 表现。
把训练 epoch 从 5 增加到 20，观察是否过拟合。
在 README 里写 3 句话解释为什么 CNN 可能比 MLP 更适合图像。

11. 验收检查

在项目根目录执行：

ompfish

source .venv/bin/activate.fish
test -f src/train.py; and test -f src/evaluate.py; and test -f configs/digits.toml
python src/train.py --model mlp --epochs 3
python src/evaluate.py --checkpoint checkpoints/best_mlp.pt
test -f reports/metrics_mlp.csv; and test -f figures/loss_curve_mlp.png

通过标准：

能训练 MLP baseline。
训练后生成 checkpoint、CSV 指标、loss 曲线。
evaluate.py 能读取 checkpoint 并打印 accuracy。
README 说明了任务、运行方式、结果和限制。

12. 常见错误

12.1 忘记激活 fish 虚拟环境

每次打开新终端后，先进入项目目录，再执行：

ompfish

source .venv/bin/activate.fish

12.2 checkpoint 路径写错

先检查文件名：

ompfish

ls checkpoints

如果只训练了 MLP，就不会有 best_cnn.pt。

12.3 MLP 和 CNN 输入 shape 混用

MLP 输入是 [batch, 64]，CNN 输入是 [batch, 1, 8, 8]。如果 checkpoint 是 MLP，就必须用 MLP 结构加载；如果 checkpoint 是 CNN，就必须用 CNN 结构加载。

12.4 只保存权重，没有保存配置

只保存 state_dict 不够。你还需要保存 model_type 和训练配置，否则评估脚本不知道该重建哪种模型。

12.5 loss 曲线没有生成

确认 matplotlib 已安装，并且训练脚本真的跑到了最后：

ompfish

uv add matplotlib
python src/train.py --model mlp --epochs 3

13. 下一步

进入 Week 11：把一个 AI 比赛或课程项目整理成可以展示的工程项目。你会清理目录、抽出配置、固定随机种子、写训练入口和 inference 脚本，让项目从“能在我电脑上跑”变成“别人也能复现”。

plain

Week 09：PyTorch 基础——从 Tensor 到完整训练循环

Sun, 26 Jul 2026 01:00:00 GMT

Oh My Pi / weekly tutorial / week09-pytorch-basics

miku@cachyos:~/Code/python-learning$ omp teach week09-pytorch-basics --fish-first --step-by-step

source516 行教学文档

weekWeek 09

shellfish-first 命令版

backlink20 周计划

Week 09：PyTorch 基础——从 Tensor 到完整训练循环

回到总路线：USTC 统计 AI / 量化 20 周成长计划
本周目标对应计划中的 Week 09：Tensor、Dataset / DataLoader、nn.Module、loss、optimizer、train / eval loop。

本教程默认你在 CachyOS + fish shell + VS Code + uv 环境下学习。所有命令默认都是 fish；如果你使用 Bash / Zsh，需要自己换成对应激活脚本。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	Tensor、Dataset、DataLoader、nn.Module、loss、optimizer
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`src/pytorch_mlp.py`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

for epoch in range(epochs):
    model.train()
    for xb, yb in train_loader:
        logits = model(xb)
        loss = criterion(logits, yb)
        optimizer.zero_grad()
        loss.backward()
        optimizer.step()
plain model.eval()
with torch.no_grad():
valid_logits = model(X_valid_tensor)

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `src/pytorch_mlp.py`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周目标

完成后你应该能做到：

知道 PyTorch 的 Tensor 和 NumPy array 有什么相似与不同。
会把表格数据包装成 Dataset，再交给 DataLoader 分批训练。
会写一个最小但完整的 nn.Module。
会写 CPU-first 的训练循环：model.train()、前向传播、loss、反向传播、optimizer step。
会写验证循环：model.eval()、torch.no_grad()、accuracy。
留下可运行的 src/pytorch_mlp.py 和学习笔记。

本周不追求高精度，也不追求 GPU。重点是把深度学习训练的骨架写明白。

2. 前置条件

你需要已经具备：

VS Code 能打开项目目录。
终端默认 shell 是 fish。
uv 可用。
会运行普通 Python 脚本。
知道监督学习中的 train / validation split。

先确认工具：

ompfish

python --version
uv --version
fish --version

如果这些命令都能输出版本号，就可以继续。

3. 建立 Week 09 项目

建议每周一个独立目录，避免依赖混在一起。

ompfish

mkdir -p ~/Code/ustc-ai/week09-pytorch-basics
cd ~/Code/ustc-ai/week09-pytorch-basics
uv init --name week09-pytorch-basics
uv venv
source .venv/bin/activate.fish
uv add torch scikit-learn matplotlib
code .

逐句解释：

命令	作用
`mkdir -p`	创建项目目录；如果上级目录不存在就一起创建
`cd`	进入本周项目目录
`uv init`	生成 `pyproject.toml` 等项目文件
`uv venv`	创建当前项目专用的 `.venv`
`source .venv/bin/activate.fish`	用 fish 方式激活虚拟环境
`uv add ...`	安装本周需要的依赖
`code .`	用 VS Code 打开当前目录

检查 PyTorch 是否可用：

ompfish

python -c "import torch; print(torch.__version__); print('cuda:', torch.cuda.is_available())"

在 CachyOS 笔记本上，cuda: False 很正常。本教程所有代码都按 CPU 设计。

4. 推荐文件布局

创建本周目录结构：

ompfish

mkdir -p src notes outputs

目标布局：

ompprompt

week09-pytorch-basics/
├── .venv/
├── pyproject.toml
├── src/
│   ├── tensor_basics.py
│   └── pytorch_mlp.py
├── notes/
│   └── week09_pytorch.md
└── outputs/

文件用途：

文件	用途
`src/tensor_basics.py`	练习 Tensor、shape、dtype、autograd
`src/pytorch_mlp.py`	本周核心：Dataset、DataLoader、MLP、训练循环
`notes/week09_pytorch.md`	记录你理解的训练流程和错误
`outputs/`	以后放日志、图、模型文件

5. Tensor 入门：先理解数据容器

在 VS Code 中创建 src/tensor_basics.py：

omppython

import torch
x = torch.tensor([[1.0, 2.0], [3.0, 4.0]])
y = torch.ones((2, 2))
print(“x =”)
print(x)
print(“shape:”, x.shape)
print(“dtype:”, x.dtype)
print(“x + y =”)
print(x + y)
print(“x @ y =”)
print(x @ y)
autograd: PyTorch 自动记录计算图，用于反向传播
w = torch.tensor([2.0], requires_grad=True)
b = torch.tensor([1.0], requires_grad=True)
feature = torch.tensor([3.0])
target = torch.tensor([10.0])
prediction = w * feature + b
loss = (prediction - target).pow(2).mean()
loss.backward()
print(“prediction:”, prediction.item())
print(“loss:”, loss.item())
print(“d loss / d w:”, w.grad.item())
print(“d loss / d b:”, b.grad.item())

运行：

ompfish

source .venv/bin/activate.fish
python src/tensor_basics.py

你需要重点观察：

shape：深度学习代码里最常见的错误来源。
dtype：模型通常使用 float32，标签分类通常使用 long。
requires_grad=True：告诉 PyTorch 这个 Tensor 需要梯度。
loss.backward()：从 loss 反向计算所有参数的梯度。

6. Dataset 和 DataLoader：把数据交给训练循环

PyTorch 不希望你在训练循环里手动切片全部数据。更常见的结构是：

ompprompt

原始数据 -> Dataset -> DataLoader -> 每个 batch 的 x, y -> model

概念区分：

名称	作用
`Dataset`	定义“第 i 条样本怎么取”
`DataLoader`	负责 batch、shuffle、迭代
`batch_size`	每次给模型多少条样本
`shuffle=True`	每个 epoch 打乱训练样本顺序

7. 写一个完整的 CPU-first MLP

创建 src/pytorch_mlp.py：

omppython

from __future__ import annotations
import argparse
import random
from dataclasses import dataclass
import numpy as np
import torch
from sklearn.datasets import make_classification
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
from torch import nn
from torch.utils.data import DataLoader, Dataset
@dataclass(frozen=True)
class TrainConfig:
epochs: int
batch_size: int
lr: float
seed: int
class TabularClassificationDataset(Dataset):
def init(self, features: np.ndarray, labels: np.ndarray) -> None:
self.features = torch.tensor(features, dtype=torch.float32)
self.labels = torch.tensor(labels, dtype=torch.long)
plain def len(self) -> int:
return len(self.labels)
plain def getitem(self, index: int) -> tuple[torch.Tensor, torch.Tensor]:
return self.features[index], self.labels[index]
class MLP(nn.Module):
def init(self, input_dim: int, hidden_dim: int, num_classes: int) -> None:
super().init()
self.net = nn.Sequential(
nn.Linear(input_dim, hidden_dim),
nn.ReLU(),
nn.Linear(hidden_dim, hidden_dim),
nn.ReLU(),
nn.Linear(hidden_dim, num_classes),
)
plain def forward(self, x: torch.Tensor) -> torch.Tensor:
return self.net(x)
def set_seed(seed: int) -> None:
random.seed(seed)
np.random.seed(seed)
torch.manual_seed(seed)
def build_loaders(config: TrainConfig) -> tuple[DataLoader, DataLoader, int, int]:
x, y = make_classification(
n_samples=1200,
n_features=20,
n_informative=10,
n_redundant=4,
n_classes=2,
random_state=config.seed,
)
x_train, x_valid, y_train, y_valid = train_test_split(
x,
y,
test_size=0.2,
stratify=y,
random_state=config.seed,
)
plain scaler = StandardScaler()
x_train = scaler.fit_transform(x_train)
x_valid = scaler.transform(x_valid)
plain train_dataset = TabularClassificationDataset(x_train, y_train)
valid_dataset = TabularClassificationDataset(x_valid, y_valid)
plain train_loader = DataLoader(
train_dataset,
batch_size=config.batch_size,
shuffle=True,
)
valid_loader = DataLoader(
valid_dataset,
batch_size=config.batch_size,
shuffle=False,
)
return train_loader, valid_loader, x_train.shape[1], len(np.unique(y))
def train_one_epoch(
model: nn.Module,
loader: DataLoader,
criterion: nn.Module,
optimizer: torch.optim.Optimizer,
device: torch.device,
) -> float:
model.train()
total_loss = 0.0
total_examples = 0
plain for features, labels in loader:
features = features.to(device)
labels = labels.to(device)
plain     logits = model(features)
loss = criterion(logits, labels)
plain     optimizer.zero_grad()
loss.backward()
optimizer.step()
    total_loss += loss.item() * len(labels)
    total_examples += len(labels)

return total_loss / total_examples
def evaluate(model: nn.Module, loader: DataLoader, criterion: nn.Module, device: torch.device) -> tuple[float, float]:
model.eval()
total_loss = 0.0
total_correct = 0
total_examples = 0
plain with torch.no_grad():
for features, labels in loader:
features = features.to(device)
labels = labels.to(device)
plain         logits = model(features)
loss = criterion(logits, labels)
predictions = logits.argmax(dim=1)
plain         total_loss += loss.item() * len(labels)
total_correct += (predictions == labels).sum().item()
total_examples += len(labels)
return total_loss / total_examples, total_correct / total_examples
def parse_args() -> TrainConfig:
parser = argparse.ArgumentParser()
parser.add_argument(“—epochs”, type=int, default=20)
parser.add_argument(“—batch-size”, type=int, default=32)
parser.add_argument(“—lr”, type=float, default=0.01)
parser.add_argument(“—seed”, type=int, default=42)
args = parser.parse_args()
return TrainConfig(
epochs=args.epochs,
batch_size=args.batch_size,
lr=args.lr,
seed=args.seed,
)
def main() -> None:
config = parse_args()
set_seed(config.seed)
plain device = torch.device(“cpu”)
train_loader, valid_loader, input_dim, num_classes = build_loaders(config)
model = MLP(input_dim=input_dim, hidden_dim=32, num_classes=num_classes).to(device)
criterion = nn.CrossEntropyLoss()
optimizer = torch.optim.Adam(model.parameters(), lr=config.lr)
plain for epoch in range(1, config.epochs + 1):
train_loss = train_one_epoch(model, train_loader, criterion, optimizer, device)
valid_loss, valid_acc = evaluate(model, valid_loader, criterion, device)
print(
f”epoch={epoch
} ”
f”train_loss={train_loss:.4f} ”
f”valid_loss={valid_loss:.4f} ”
f”valid_acc={valid_acc:.3f}”
)
if name == “main”:
main()

运行一个短训练：

ompfish

source .venv/bin/activate.fish
python src/pytorch_mlp.py --epochs 5 --batch-size 32 --lr 0.01

如果你看到类似下面的输出，说明训练循环已经跑通：

ompprompt

epoch=01 train_loss=0.6200 valid_loss=0.5100 valid_acc=0.760
epoch=02 train_loss=0.4200 valid_loss=0.3500 valid_acc=0.850

数字不需要完全一致，因为初始化和环境可能不同。你要看的是：脚本能运行，loss 大体下降，验证集 accuracy 高于随机猜测。

8. 训练循环逐句解释

核心结构是：

omppython

for epoch in range(num_epochs):
    model.train()
    for x, y in train_loader:
        pred = model(x)
        loss = criterion(pred, y)
        optimizer.zero_grad()
        loss.backward()
        optimizer.step()

逐句解释：

代码	含义
`model.train()`	切换到训练模式；以后遇到 Dropout / BatchNorm 时很重要
`for x, y in train_loader`	从 DataLoader 取一个 batch
`pred = model(x)`	前向传播，得到 logits 或预测值
`loss = criterion(pred, y)`	计算当前 batch 的损失
`optimizer.zero_grad()`	清空上一轮梯度；否则梯度会累加
`loss.backward()`	反向传播，计算每个参数的梯度
`optimizer.step()`	根据梯度更新参数

验证循环必须不同：

omppython

model.eval()
with torch.no_grad():
    ...

原因：验证时不更新参数，也不需要保存计算图。这样更快，也更不容易写错。

9. 写学习笔记

创建 notes/week09_pytorch.md，至少回答这些问题：

ompprompt

# Week 09 PyTorch Notes
Tensor

Tensor 和 NumPy array 的共同点：
Tensor 多出来的重要能力：

Dataset / DataLoader

Dataset 负责：
DataLoader 负责：

Train Loop

为什么要 zero_grad：
为什么 train 和 eval 要分开：

Errors I Met

错误信息：
原因：
修复方式：

10. 练习

把 hidden_dim=32 改成 hidden_dim=64，观察验证集 accuracy 是否变化。
把 lr=0.01 改成 lr=0.001，比较 loss 下降速度。
把 batch_size=32 改成 batch_size=128，观察每个 epoch 是否更快。
在 MLP 里增加一层 nn.Dropout(0.2)，再比较训练集和验证集表现。
故意删掉 optimizer.zero_grad()，观察训练是否变得不稳定，然后恢复。

每次只改一个因素，否则你无法判断到底是什么导致结果变化。

11. 验收检查

在项目根目录执行：

ompfish

source .venv/bin/activate.fish
test -f src/pytorch_mlp.py; and test -f notes/week09_pytorch.md
python src/tensor_basics.py
python src/pytorch_mlp.py --epochs 3 --batch-size 32 --lr 0.01

通过标准：

tensor_basics.py 能打印 Tensor、shape、dtype 和梯度。
pytorch_mlp.py 能完成至少 3 个 epoch。
输出中包含 train_loss、valid_loss、valid_acc。
notes/week09_pytorch.md 里有你自己的解释，而不是只复制代码。

12. 常见错误

12.1 fish 激活脚本用错

错误做法是执行 Bash / Zsh 版激活脚本。fish 里应该执行：

ompfish

source .venv/bin/activate.fish

12.2 标签 dtype 不对

nn.CrossEntropyLoss() 要求分类标签是整数类别，并且 dtype 通常是 torch.long。如果你把标签做成 float32，可能会报 dtype 错误。

12.3 忘记 `optimizer.zero_grad()`

PyTorch 默认会累加梯度。训练循环里每个 batch 更新前都要清空上一轮梯度。

12.4 训练和验证没有分开

训练时用：

omppython

model.train()

验证时用：

omppython

model.eval()
with torch.no_grad():
    ...

不要在验证集上调用 optimizer.step()。

12.5 shape 对不上

如果看到矩阵乘法 shape 错误，先打印：

omppython

print(features.shape)
print(logits.shape)
print(labels.shape)

分类任务中，logits 常见 shape 是 [batch_size, num_classes]，labels 常见 shape 是 [batch_size]。

13. 下一步

进入 Week 10：把这个最小训练脚本升级成一个小型深度学习项目。你会加入 MLP / CNN baseline、checkpoint、loss 曲线、验证集评估和独立的 evaluate.py。

plain

Week 08：统计机器学习项目收尾、复现与报告打磨

Sun, 26 Jul 2026 00:00:00 GMT

Oh My Pi / weekly tutorial / week08-stat-ml-project-finish

miku@cachyos:~/Code/python-learning$ omp teach week08-stat-ml-project-finish --fish-first --step-by-step

source610 行教学文档

weekWeek 08

shellfish-first 命令版

backlink20 周计划

Week 08：统计机器学习项目收尾、复现与报告打磨

返回主线计划：USTC 统计学：AI / 量化金融 20 周终端式成长计划

Week 07 你已经启动了一个统计机器学习项目：有项目骨架、数据卡、baseline 脚本、结果报告和错误分析。Week 08 的任务是把它整理成“可以给老师、导师、实习面试官或未来的自己看的项目”。

收尾不是美化封面，而是让项目可理解、可复现、可验证、可继续改进。命令默认 fish shell。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	实验表、误差分析、局限性、README
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`reports/error_analysis.md`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

errors = valid_df.assign(y_true=y_valid, y_pred=pred)
errors = errors[errors.y_true != errors.y_pred]
print(errors.head(10))
print(errors.groupby("y_true").size())

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `reports/error_analysis.md`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周目标

完成一个干净的项目版本：

README 清楚说明问题、数据、方法、实验、结果、限制和运行方式。
reports/final_report.md 形成完整实验报告。
结果表可复现，指标和 Week 07 报告一致。
运行命令从空环境开始可执行。
Git 提交历史清楚，不提交 .venv/、缓存、大文件或隐私数据。
写下下一步改进，而不是假装项目完美。

本周核心标准：

ompprompt

别人克隆项目后，按 README 执行命令，能得到同类结果。
别人读 final_report 后，能理解你做了什么、为什么做、结果说明什么。

2. 前置条件

你应该已有 Week 07 项目：

ompprompt

projects/stat-ml-baseline/
├── README.md
├── docs/data_card.md
├── reports/baseline_results.md
├── reports/error_analysis.md
└── src/train_baseline.py

进入项目并激活环境：

ompfish

cd ~/Code/python-learning/projects/stat-ml-baseline
source .venv/bin/activate.fish

检查 baseline 是否还能跑：

ompfish

python src/train_baseline.py

如果这一步失败，不要先写报告。先修复脚本或环境，因为 Week 08 的报告必须建立在可复现实验上。

3. 本周文件布局

Week 08 结束时建议结构：

ompprompt

stat-ml-baseline/
├── data/
│   ├── raw/
│   ├── interim/
│   └── processed/
├── docs/
│   └── data_card.md
├── notebooks/
│   └── 01_eda.ipynb
├── reports/
│   ├── baseline_results.md
│   ├── error_analysis.md
│   └── final_report.md
├── src/
│   ├── make_dataset.py
│   └── train_baseline.py
├── .gitignore
├── README.md
├── pyproject.toml
└── uv.lock

不要求每个项目都必须有 notebook，但 README 里提到的文件必须真实存在。不要写“见 reports/final_report.md”，结果文件却不存在。

4. 做一次复现前体检

先从项目根目录看关键文件：

ompfish

pwd
ls
ls src
ls reports
ls docs

检查依赖文件：

ompfish

test -f pyproject.toml; and echo "pyproject exists"
test -f uv.lock; and echo "uv lock exists"
test -f src/train_baseline.py; and echo "training script exists"

检查 Git 状态：

ompfish

git status --short

如果看到 .venv/、__pycache__/、.ipynb_checkpoints/，说明 .gitignore 需要修正。

5. 整理 .gitignore

打开或创建 .gitignore：

ompfish

code .gitignore

建议包含：

ompprompt

.venv/ __pycache__/ *.pyc .ipynb_checkpoints/ .DS_Store .cache/ Local large or restricted data archives data/raw/.zip data/raw/.tar.gz data/raw/*.7z Optional generated artifacts

reports/*.html

是否忽略 CSV 要看数据许可：

如果数据公开、小、允许再分发，可以提交一份小样本或完整 CSV。
如果数据大、需要登录下载、包含敏感信息，不要提交原始 CSV。README 必须说明如何取得数据、放到哪里。

不要把 .venv/ 提交到 Git。虚拟环境是本机生成物，不是项目源代码。

6. 确认可复现命令

README 的 How to Run 部分必须从克隆后的项目根目录开始。

推荐命令：

ompfish

uv venv
source .venv/bin/activate.fish
uv sync
python src/train_baseline.py

逐句解释：

命令	作用
`uv venv`	创建项目本地 `.venv`
`source .venv/bin/activate.fish`	用 fish 激活环境
`uv sync`	根据 `pyproject.toml` 和 `uv.lock` 安装依赖
`python src/train_baseline.py`	重新生成 baseline 报告

如果数据不能提交，README 在运行命令之前必须加上：

ompprompt

Download the dataset from ... and place it at data/raw/train.csv.

否则别人按照命令运行会直接找不到文件。

7. README 最终模板

打开 README：

ompfish

code README.md

建议改成下面结构：

ompmarkdown

# Statistical Machine Learning Baseline
Problem
State the prediction problem in 3-5 sentences.
Explain the unit of observation, target variable, and why this task matters.
Data

Source:
Download date:
Rows:
Columns:
Target:
License or usage condition:

See docs/data_card.md for field-level details.
Method
Describe preprocessing, train/test split, cross validation, baseline models, and selection metric.
Experiments























Model Validation Metric Test Metric Notes
Logistic Regression … … scaled numeric features
Random Forest … … tree baseline
Results
Summarize the chosen model and what the metric means.
Do not exaggerate the result.
Error Analysis
Summarize the main error types and link to reports/error_analysis.md.
Limitations
List data, modeling, validation, and interpretation limitations.
How to Run
uv venv
source .venv/bin/activate.fish
uv sync
python src/train_baseline.py
</code></pre></div>
<h2>Project Structure</h2>
<p>Explain the key directories.</p>
<h2>Next Steps</h2>
<p>List realistic improvements.</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code>
README 里不要只写“使用机器学习预测”。要写清楚预测对象和指标选择原因。

## 8. 写最终报告

创建：

```fish
code reports/final_report.md
</code></pre></div>
<p>建议结构：</p>
<div class="omp-code-frame" data-lang="markdown"><div class="omp-code-bar"><span>omp</span><span>markdown</span></div><pre><code class="language-markdown"># Final Report: Statistical Machine Learning Baseline

## 1. Problem

Define the task.

## 2. Data

Summarize source, rows, columns, target, missingness, and limitations.

## 3. Experimental Design

Explain train/test split, cross validation, preprocessing pipeline, and metric choice.

## 4. Models

Describe naive baseline and sklearn baselines.

## 5. Results

Include the result table from `reports/baseline_results.md`.

## 6. Error Analysis

Summarize errors from `reports/error_analysis.md`.

## 7. Limitations

State what this project cannot prove.

## 8. Next Steps

List concrete improvements.
</code></pre></div>
<p>最终报告和 README 的区别：</p>
<table>
<thead>
<tr>
<th>文件</th>
<th>读者目的</th>
</tr>
</thead>
<tbody><tr>
<td>README</td>
<td>快速了解项目、运行项目、判断项目结构</td>
</tr>
<tr>
<td>final_report</td>
<td>详细理解实验设计、结果、错误分析、限制</td>
</tr>
</tbody></table>
<p>README 可以短，报告要完整。</p>
<h2>9. 把 Week 07 的结果表转成可展示表格</h2>
<p>打开 Week 07 生成的报告：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">code reports/baseline_results.md
</code></pre></div>
<p>把关键结果复制到 README 和 <code>reports/final_report.md</code>。表格建议包含：</p>
<div class="omp-code-frame" data-lang="markdown"><div class="omp-code-bar"><span>omp</span><span>markdown</span></div><pre><code class="language-markdown">| Model | CV F1 Mean | CV F1 Std | Test F1 | Test ROC AUC | Notes |
|---|---:|---:|---:|---:|---|
| Naive baseline | ... | ... | ... | ... | majority class |
| Logistic Regression | ... | ... | ... | ... | scaled features |
| Random Forest | ... | ... | ... | ... | tree ensemble |
</code></pre></div>
<p>如果你没有 naive baseline，本周补上。一个没有 naive baseline 的项目，很难说明模型到底是否有价值。</p>
<h2>10. 检查指标叙述是否诚实</h2>
<p>不要写：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">The model performs very well.
</code></pre></div>
<p>应该写：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">The selected model reaches a test F1 of 0.XX on the current holdout split. This suggests it improves over the naive baseline, but the estimate may be optimistic because the dataset is small and only one final holdout split is used.
</code></pre></div>
<p>统计学项目尤其要避免过度宣称。你可以说“在当前数据和划分下表现更好”，不要说“证明该方法一定有效”。</p>
<h2>11. 复现测试：从干净环境重跑</h2>
<p>在当前项目里，先确认虚拟环境能用：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">source .venv/bin/activate.fish
uv sync
python src/train_baseline.py
</code></pre></div>
<p>如果想模拟新机器，不要删除项目文件，只移除本地虚拟环境后重建：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">rm -rf .venv
uv venv
source .venv/bin/activate.fish
uv sync
python src/train_baseline.py
</code></pre></div>
<p>注意：<code>rm -rf .venv</code> 只删除虚拟环境，不能删除 <code>data/</code>、<code>src/</code>、<code>reports/</code>。执行前用 <code>pwd</code> 确认你在项目根目录。</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">pwd
</code></pre></div>
<p>运行成功后，报告时间或数值可能重新生成，但主要结果应一致。</p>
<h2>12. 数据路径检查</h2>
<p>常见复现失败来自路径写死。脚本里不要写：</p>
<div class="omp-code-frame" data-lang="python"><div class="omp-code-bar"><span>omp</span><span>python</span></div><pre><code class="language-python">pd.read_csv(&quot;/home/miku/Downloads/train.csv&quot;)
</code></pre></div>
<p>应该写项目相对路径：</p>
<div class="omp-code-frame" data-lang="python"><div class="omp-code-bar"><span>omp</span><span>python</span></div><pre><code class="language-python">pd.read_csv(&quot;data/raw/train.csv&quot;)
</code></pre></div>
<p>如果你担心从不同目录运行脚本，可以用文件所在位置推导项目根目录：</p>
<div class="omp-code-frame" data-lang="python"><div class="omp-code-bar"><span>omp</span><span>python</span></div><pre><code class="language-python">from pathlib import Path

PROJECT_ROOT = Path(__file__).resolve().parents[1]
DATA_PATH = PROJECT_ROOT / &quot;data&quot; / &quot;raw&quot; / &quot;train.csv&quot;
</code></pre></div>
<p>这样从项目根目录运行更稳定。</p>
<h2>13. 报告中的错误分析要具体</h2>
<p>不要写：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">Some samples are predicted incorrectly.
</code></pre></div>
<p>应写：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">False negatives are more concerning for this task because missing a positive case has higher cost. In the wrong-prediction preview, several false negatives have feature values near the decision boundary, suggesting that a calibrated probability threshold or additional domain features may be useful.
</code></pre></div>
<p>错误分析至少包含：</p>
<ul>
<li>主要错误类型。</li>
<li>错误的可能原因。</li>
<li>这些错误对任务有什么影响。</li>
<li>下一步如何验证改进。</li>
</ul>
<h2>14. 清理 notebook 与临时文件</h2>
<p>Notebook 可以保留，但不要让它成为唯一入口。检查临时文件：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">find notebooks -maxdepth 2 -type f
find reports -maxdepth 2 -type f
find src -maxdepth 2 -type f
</code></pre></div>
<p>如果你有很多临时图、草稿 CSV、旧报告，决定：</p>
<table>
<thead>
<tr>
<th>类型</th>
<th>处理</th>
</tr>
</thead>
<tbody><tr>
<td>最终报告需要引用的图</td>
<td>放在 <code>reports/figures/</code> 并在报告中链接</td>
</tr>
<tr>
<td>notebook 自动缓存</td>
<td>加入 <code>.gitignore</code></td>
</tr>
<tr>
<td>临时实验输出</td>
<td>删除或移到明确命名目录</td>
</tr>
<tr>
<td>旧版本报告</td>
<td>如果不再引用，删除，避免读者混淆</td>
</tr>
</tbody></table>
<p>不要为了“看起来文件多”保留无用文件。项目越清晰越专业。</p>
<h2>15. Git 提交卫生</h2>
<p>先看状态：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">git status --short
</code></pre></div>
<p>查看将要提交的文件：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">git diff --stat
</code></pre></div>
<p>如果发现 <code>.venv/</code> 或缓存文件，先修 <code>.gitignore</code>。然后提交：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">git add README.md docs reports src pyproject.toml uv.lock .gitignore
git commit -m &quot;Finish statistical machine learning baseline project&quot;
</code></pre></div>
<p>提交信息要说明结果，不要写：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">update
final
fix
123
</code></pre></div>
<p>更好的提交信息：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">Add reproducible baseline report
Document data card and error analysis
Finish statistical ML project README
</code></pre></div>
<h2>16. 如果提交前发现大文件</h2>
<p>检查 Git 追踪文件大小可以用：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">git status --short
</code></pre></div>
<p>如果还没提交，但 <code>git status</code> 显示大数据文件被加入暂存区，可以取消暂存：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">git restore --staged data/raw/large_file.csv
</code></pre></div>
<p>然后把它加入 <code>.gitignore</code>，并在 README 写清楚下载方式。</p>
<p>如果数据已经提交过，处理历史会更复杂。初学阶段先养成提交前检查的习惯。</p>
<h2>17. 最终验收清单</h2>
<p>在项目根目录执行：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">source .venv/bin/activate.fish
uv sync
python src/train_baseline.py
test -f README.md; and echo &quot;README exists&quot;
test -f docs/data_card.md; and echo &quot;data card exists&quot;
test -f reports/final_report.md; and echo &quot;final report exists&quot;
test -f reports/error_analysis.md; and echo &quot;error analysis exists&quot;
</code></pre></div>
<p>人工检查 README：</p>
<ul>
<li>Problem 清楚。</li>
<li>Data 来源明确。</li>
<li>Method 说明了预处理、模型、验证方式。</li>
<li>Experiments 有结果表。</li>
<li>Results 没有夸大。</li>
<li>Error Analysis 有具体观察。</li>
<li>Limitations 诚实。</li>
<li>How to Run 可复制执行。</li>
<li>Project Structure 解释主要目录。</li>
</ul>
<p>人工检查报告：</p>
<ul>
<li>有数据说明。</li>
<li>有实验设计。</li>
<li>有 baseline 和至少一个 sklearn 模型。</li>
<li>有指标选择理由。</li>
<li>有结果表。</li>
<li>有错误分析。</li>
<li>有限制和下一步。</li>
</ul>
<p>人工检查 Git：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">git status --short
</code></pre></div>
<p>理想状态是没有未提交变更，或只剩你明确不想提交的数据文件。</p>
<h2>18. 常见错误</h2>
<h3>错误 1：README 的运行命令不完整</h3>
<p>只写 <code>python src/train_baseline.py</code> 不够。别人还需要知道如何创建环境、安装依赖、放置数据。</p>
<p>最低限度写：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">uv venv
source .venv/bin/activate.fish
uv sync
python src/train_baseline.py
</code></pre></div>
<h3>错误 2：报告和代码结果不一致</h3>
<p>如果你重新运行脚本后结果变了，README 和 final_report 也要更新。不要让报告写旧结果。</p>
<h3>错误 3：没有说明数据限制</h3>
<p>所有数据都有偏差。限制可以包括样本量、时间范围、采样方式、缺失值、标签噪声、不可观测变量。</p>
<h3>错误 4：把 notebook 当成最终交付</h3>
<p>Notebook 可以展示探索过程，但最终复现入口应是脚本。面试官更希望看到清楚的项目结构和可运行命令。</p>
<h3>错误 5：提交了虚拟环境</h3>
<p><code>.venv/</code> 可能包含成千上万个文件，只属于你的机器。提交它会让仓库巨大且不可维护。</p>
<p>修复：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">code .gitignore
git status --short
</code></pre></div>
<p>确认 <code>.gitignore</code> 有：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">.venv/
</code></pre></div>
<h3>错误 6：过度美化结论</h3>
<p>不要把一次课程项目写成工业级系统。诚实说明“这是 baseline 项目”，反而更专业。</p>
<h2>19. 面向老师或面试官的项目摘要</h2>
<p>你可以在 README 顶部或简历中写 3-4 行摘要：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">Built a reproducible statistical machine learning baseline for a tabular prediction task using Python, pandas, and scikit-learn. Designed a leakage-safe validation workflow with cross validation, compared interpretable baseline models, and documented error analysis and limitations. Packaged the project with uv environment management, clear README instructions, and Git-tracked reports.
</code></pre></div>
<p>如果是中文场景：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">使用 Python、pandas 与 scikit-learn 完成一个可复现的表格数据预测 baseline 项目；设计了防止数据泄漏的验证流程，比较多个经典模型，并整理数据卡、实验结果、错误分析与项目复现说明。
</code></pre></div>
<p>注意：摘要中不要写没有做过的东西，比如“部署”“深度学习”“自动化特征工程”。</p>
<h2>20. 本周练习</h2>
<ol>
<li>从零执行 README 的 How to Run，确认命令完整。</li>
<li>让同学或未来的自己只看 README，判断能否理解项目。</li>
<li>给 final_report 增加一个“Metric Choice”小节。</li>
<li>给 README 增加项目结构树，并解释每个目录。</li>
<li>检查 Git 状态，确保 <code>.venv/</code> 没被提交。</li>
<li>写 5 条 next steps，每条都必须可以在未来一周内验证。</li>
</ol>
<h2>21. 下一步</h2>
<p>回到主线：<a href="/post/ustc-stat-ai-quant-plan/">USTC 统计学：AI / 量化金融 20 周终端式成长计划</a>。Phase 2 到这里结束。接下来 Week 09-10 会进入 PyTorch：你将从 sklearn 的表格建模，转向张量、Dataset / DataLoader、神经网络训练循环与深度学习 baseline。</p>


    </article>
  </div>
</section>

Week 07：统计机器学习项目启动、数据卡与 Baseline

Sat, 25 Jul 2026 23:00:00 GMT

Oh My Pi / weekly tutorial / week07-stat-ml-project-start

miku@cachyos:~/Code/python-learning$ omp teach week07-stat-ml-project-start --fish-first --step-by-step

source710 行教学文档

weekWeek 07

shellfish-first 命令版

backlink20 周计划

Week 07：统计机器学习项目启动、数据卡与 Baseline

返回主线计划：USTC 统计学：AI / 量化金融 20 周终端式成长计划

Week 05-06 你已经能训练 sklearn baseline、做交叉验证和模型选择。Week 07 开始把这些能力组织成一个可以展示的统计机器学习项目。目标不是“写很多模型”，而是让一个陌生人打开你的仓库后能看懂：问题是什么、数据从哪里来、如何运行、baseline 是什么、目前错误在哪里。

本文默认 CachyOS + fish shell + VS Code + uv + Python + Git。命令按 fish 写。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	问题定义、数据卡、baseline、特征工程计划
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`projects/stat-ml-baseline/README.md`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

problem = {
    "target": "predict whether sample is positive",
    "unit": "one row is one observation",
    "baseline": "DummyClassifier + LogisticRegression",
    "risk": "target leakage from future columns",
}
for k, v in problem.items():
    print(f"{k}: {v}")

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `projects/stat-ml-baseline/README.md`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周目标

创建一个完整项目骨架：

ompprompt

projects/stat-ml-baseline/
├── README.md
├── data/
├── docs/
├── notebooks/
├── reports/
└── src/

并完成四个核心产物：

docs/data_card.md：说明数据来源、字段、目标变量、限制。
src/train_baseline.py：能训练并输出 baseline 结果。
reports/baseline_results.md：记录模型、指标、划分方式、初步结论。
reports/error_analysis.md：分析错误样本与下一步改进。

本周你要从“脚本能跑”升级为“项目能被别人理解”。

2. 前置条件

你应该已经完成：

Week 05：train / validation / test、多个 baseline、分类或回归指标。
Week 06：KFold / StratifiedKFold、Pipeline、GridSearchCV、防泄漏。
Week 03-04：pandas 清洗、EDA 图表、报告写作。
Git 基础：git status、git add、git commit。

检查工具：

ompfish

python --version
uv --version
git --version
code --version

如果你刚打开新终端，后面每次运行项目前都先激活：

ompfish

source .venv/bin/activate.fish

3. 选题原则

推荐题目：

ompprompt

基于统计学习的表格数据预测与误差分析

你可以选择：

Kaggle 入门数据：Titanic、House Prices、Spaceship Titanic。
UCI 数据集：Adult Income、Wine Quality、Bank Marketing。
金融或经济公开数据：指数收益、宏观指标、公司财务指标。
校内课程数据：只要不涉及隐私或不可公开数据。

选择标准：

标准	建议
数据规模	初学项目优先 500 到 100000 行，不要一开始选超大数据
数据类型	表格数据优先，特征包括数值和类别都可以
目标变量	明确：分类或回归，不要模糊
可解释性	能讲清楚每个字段大概含义
合法性	数据来源可引用，不含隐私或违反平台条款

如果不知道选什么，建议用 UCI Wine Quality 或 Kaggle Titanic。它们简单、可解释、适合展示完整流程。

4. 建立项目目录

在学习总目录下创建项目：

ompfish

cd ~/Code/python-learning
mkdir -p projects
cd projects
mkdir -p stat-ml-baseline
cd stat-ml-baseline
pwd

初始化 Python 项目：

ompfish

uv init
uv venv
source .venv/bin/activate.fish
uv add pandas numpy scikit-learn matplotlib seaborn tabulate

创建目录：

ompfish

mkdir -p data/raw data/interim data/processed docs notebooks reports src

用 VS Code 打开：

ompfish

code .

5. 文件布局

建议结构：

ompprompt

stat-ml-baseline/
├── .venv/                       # 本地虚拟环境，不提交
├── data/
│   ├── raw/                     # 原始数据，只读
│   ├── interim/                 # 中间处理结果
│   └── processed/               # 建模用数据
├── docs/
│   └── data_card.md             # 数据卡
├── notebooks/
│   └── 01_eda.ipynb             # 可选：探索分析
├── reports/
│   ├── baseline_results.md      # baseline 结果
│   └── error_analysis.md        # 错误分析
├── src/
│   ├── train_baseline.py        # 训练入口
│   └── make_dataset.py          # 可选：数据清洗入口
├── pyproject.toml
├── uv.lock
└── README.md

目录职责要清楚：

目录	职责
`data/raw/`	放原始数据，不在里面手工改值
`data/interim/`	放临时清洗结果，可删除重建
`data/processed/`	放最终建模输入
`docs/`	放数据说明、设计说明
`notebooks/`	放探索性分析，不做最终训练入口
`reports/`	放实验结果和错误分析
`src/`	放可重复运行的 Python 脚本

6. 创建 README 初稿

打开 README.md，先写一个能说明项目方向的初稿。不要等项目结束才写 README，否则你会忘记很多设计选择。

建议结构：

ompmarkdown

# Statistical Machine Learning Baseline
Problem
This project predicts … using tabular data. The task is classification / regression.
Data

Source:
Rows:
Columns:
Target:
Unit of observation:

Method

Baseline models:
Validation strategy:
Main metric:

Current Status
Week 07 project start. Baseline and error analysis are in progress.
How to Run

Create and activate a uv virtual environment.
Install dependencies.
Run the baseline script.

这不是最终版。Week 08 会继续打磨 README。本周的 README 只要能帮助你保持项目方向即可。

7. 创建数据卡

创建文件：

ompprompt

docs/data_card.md

建议内容：

ompmarkdown

# Data Card
Dataset Name
Write the dataset name here.
Source

URL:
License or access condition:
Download date:

Prediction Target

Target column:
Task type: classification / regression
Positive class definition if classification:

Unit of Observation
One row represents …
Columns

















Column Type Meaning Notes
example_column numeric … …
Missing Values
Describe missing columns and possible reasons.
Known Limitations

Sampling bias:
Time period limitation:
Measurement errors:
Possible leakage columns:

Ethical or Privacy Notes
State whether the dataset contains personal, financial, medical, or sensitive information.

数据卡不是形式主义。它能防止你在 Week 08 写报告时讲不清数据来源。

8. 下载或放入数据

如果数据已经手动下载，把 CSV 放到：

ompprompt

data/raw/dataset.csv

用 fish 检查文件：

ompfish

ls data/raw

如果你用 Kaggle，不建议本教程里展开认证流程。初学阶段可以手动从网页下载 zip，再解压到 data/raw/。如果使用 UCI 的公开 CSV，可以用浏览器下载，或者用 Python 下载。

重要原则：

ompprompt

原始数据进 data/raw/
脚本生成的数据进 data/processed/
不要在 Excel 里手改原始数据后覆盖 raw 文件

9. 如果暂时没有数据：使用 sklearn 数据集占位

为了先搭项目骨架，可以用 sklearn 自带数据集跑通流程。等你选定真实数据后再替换 load_data()。

本教程下面使用 breast cancer dataset 做可运行示例。它不是你的最终项目题目也没关系；Week 07 重点是项目结构。

10. 编写 baseline 训练脚本

创建文件：

ompprompt

src/train_baseline.py

粘贴下面代码：

omppython

from pathlib import Path
import pandas as pd
from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import accuracy_score, confusion_matrix, f1_score, precision_score, recall_score, roc_auc_score
from sklearn.model_selection import StratifiedKFold, cross_validate, train_test_split
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
RANDOM_STATE = 42
RESULT_PATH = Path(“reports/baseline_results.md”)
ERROR_PATH = Path(“reports/error_analysis.md”)
def load_project_data():
dataset = load_breast_cancer(as_frame=True)
X = dataset.data
y = dataset.target
return X, y, list(dataset.target_names)
def build_models():
return {
“logistic_regression”: Pipeline(
steps=[
(“scaler”, StandardScaler()),
(“model”, LogisticRegression(max_iter=3000, random_state=RANDOM_STATE)),
]
),
“random_forest”: RandomForestClassifier(
n_estimators=200,
max_depth=None,
min_samples_leaf=1,
random_state=RANDOM_STATE,
),
}
def score_models(models, X_train, y_train):
cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=RANDOM_STATE)
scoring = {
“accuracy”: “accuracy”,
“precision”: “precision”,
“recall”: “recall”,
“f1”: “f1”,
“roc_auc”: “roc_auc”,
}
rows = []
for name, model in models.items():
scores = cross_validate(model, X_train, y_train, cv=cv, scoring=scoring, n_jobs=-1)
row = {“model”: name}
for metric in scoring:
values = scores[f”test_{metric}”]
row[f”{metric}_mean”] = values.mean()
row[f”{metric}_std”] = values.std()
rows.append(row)
return sorted(rows, key=lambda item: item[“f1_mean”], reverse=True)
def evaluate_final_model(model, X_train, X_test, y_train, y_test):
model.fit(X_train, y_train)
predictions = model.predict(X_test)
probabilities = model.predict_proba(X_test)[:, 1]
metrics = {
“accuracy”: accuracy_score(y_test, predictions),
“precision”: precision_score(y_test, predictions),
“recall”: recall_score(y_test, predictions),
“f1”: f1_score(y_test, predictions),
“roc_auc”: roc_auc_score(y_test, probabilities),
}
matrix = confusion_matrix(y_test, predictions)
errors = X_test.assign(actual=y_test.to_numpy(), predicted=predictions, probability=probabilities)
errors = errors[errors[“actual”] != errors[“predicted”]]
return metrics, matrix, errors
def write_baseline_report(rows, test_metrics, target_names):
table_rows = []
for row in rows:
table_rows.append(
”| {model} | {f1_mean:.4f} | {f1_std:.4f} | {roc_auc_mean:.4f} | {recall_mean:.4f} |“.format(
**row
)
)
plain report = f"""# Baseline Results
Dataset

Dataset: sklearn breast cancer dataset or project replacement dataset
Target names:
Task: binary classification

Validation Design

Holdout test size: 20%
Cross validation: StratifiedKFold with 5 folds on the training portion
Selection metric: mean CV F1
Random state:

Cross-Validation Results



















Model Mean F1 Std F1 Mean ROC AUC Mean Recall
{chr(10).join(table_rows)} 
Final Test Metrics





























Metric Value
Accuracy {test_metrics[‘accuracy’]:.4f}
Precision {test_metrics[‘precision’]:.4f}
Recall {test_metrics[‘recall’]:.4f}
F1 {test_metrics[‘f1’]:.4f}
ROC AUC {test_metrics[‘roc_auc’]:.4f}
Notes

Replace this section with your interpretation.
Explain why the chosen metric matches the project goal.
Compare the model against a naive baseline if possible.
"""
RESULT_PATH.parent.mkdir(parents=True, exist_ok=True)
RESULT_PATH.write_text(report, encoding=“utf-8”)

def write_error_analysis(matrix, errors):
preview = errors.head(10).round(4).to_markdown(index=False)
report = f"""# Error Analysis
Confusion Matrix
Rows are actual labels, columns are predicted labels.
{matrix}
</code></pre></div>
<h2>Wrong Prediction Preview</h2>
<p>{preview}</p>
<h2>Observations To Fill In</h2>
<ul>
<li>What type of mistake appears most often?</li>
<li>Are false positives or false negatives more costly?</li>
<li>Do wrong predictions have low confidence or high confidence?</li>
<li>Which features look unusual among wrong predictions?</li>
<li>What data cleaning or feature engineering should be tried next?
&quot;&quot;&quot;
  ERROR_PATH.parent.mkdir(parents=True, exist_ok=True)
  ERROR_PATH.write_text(report, encoding=&quot;utf-8&quot;)</li>
</ul>
<p>def main():
    X, y, target_names = load_project_data()
    X_train, X_test, y_train, y_test = train_test_split(
        X,
        y,
        test_size=0.2,
        random_state=RANDOM_STATE,
        stratify=y,
    )
    models = build_models()
    rows = score_models(models, X_train, y_train)
    best_name = rows[0][&quot;model&quot;]
    test_metrics, matrix, errors = evaluate_final_model(models[best_name], X_train, X_test, y_train, y_test)</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code>write_baseline_report(rows, test_metrics, target_names)
write_error_analysis(matrix, errors)

print(pd.DataFrame(rows).round(4).to_string(index=False))
print()
print(&quot;Selected model:&quot;, best_name)
print(&quot;Reports written:&quot;, RESULT_PATH, ERROR_PATH)
</code></pre></div>
<p>if <strong>name</strong> == &quot;<strong>main</strong>&quot;:
    main()</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code>
## 11. 运行 baseline

```fish
source .venv/bin/activate.fish
python src/train_baseline.py
</code></pre></div>
<p>应该生成：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">reports/baseline_results.md
reports/error_analysis.md
</code></pre></div>
<p>检查：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">test -f reports/baseline_results.md; and echo &quot;baseline report exists&quot;
test -f reports/error_analysis.md; and echo &quot;error analysis exists&quot;
</code></pre></div>
<p>打开报告：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">code reports/baseline_results.md reports/error_analysis.md
</code></pre></div>
<h2>12. 把示例数据替换成真实项目数据</h2>
<p>假设真实 CSV 是：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">data/raw/train.csv
</code></pre></div>
<p>目标列叫：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">target
</code></pre></div>
<p>可以把 <code>load_project_data()</code> 改成：</p>
<div class="omp-code-frame" data-lang="python"><div class="omp-code-bar"><span>omp</span><span>python</span></div><pre><code class="language-python">def load_project_data():
    data = pd.read_csv(&quot;data/raw/train.csv&quot;)
    X = data.drop(columns=[&quot;target&quot;])
    y = data[&quot;target&quot;]
    target_names = sorted(y.astype(str).unique().tolist())
    return X, y, target_names
</code></pre></div>
<p>如果有类别变量，你需要在 Week 06 学过的 <code>ColumnTransformer</code> 中处理。不要用“随便把字符串替换成 0、1、2”的方式编码城市、行业、学校等无序类别。</p>
<h2>13. 明确问题定义</h2>
<p>在 README 的 <code>Problem</code> 部分回答：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">我要预测什么？
为什么这个预测有意义？
每一行数据代表什么？
目标变量是如何定义的？
预测提前量是多少？
这个项目是分类还是回归？
</code></pre></div>
<p>示例：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">This project predicts whether a passenger survived on the Titanic using passenger-level tabular features. Each row is one passenger. The target is Survived, where 1 means survived and 0 means not survived. This is a binary classification task.
</code></pre></div>
<p>统计学学生尤其要注意“单位”。一行是一个人、一家公司、一天、一笔交易，分析意义完全不同。</p>
<h2>14. 建立 naive baseline</h2>
<p>除了 sklearn 模型，还应该有 naive baseline。</p>
<p>分类任务：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">永远预测训练集中最多的类别
</code></pre></div>
<p>回归任务：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">永远预测训练集目标变量均值或中位数
</code></pre></div>
<p>你可以在报告中写：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">Naive baseline: always predict the majority class.
F1 is low because the model never identifies minority-class cases.
</code></pre></div>
<p>这样可以证明 sklearn 模型不仅比随机好，也比最简单策略好。</p>
<h2>15. 初步错误分析怎么做</h2>
<p>不要只看总分。打开 <code>reports/error_analysis.md</code>，观察错误样本：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">code reports/error_analysis.md
</code></pre></div>
<p>写下：</p>
<table>
<thead>
<tr>
<th>问题</th>
<th>例子</th>
</tr>
</thead>
<tbody><tr>
<td>哪类错误更多</td>
<td>false positives 多，还是 false negatives 多</td>
</tr>
<tr>
<td>错误样本有什么共同点</td>
<td>某些特征极端、缺失多、靠近决策边界</td>
</tr>
<tr>
<td>指标是否符合目标</td>
<td>如果漏判代价高，recall 是否足够</td>
</tr>
<tr>
<td>是否需要新特征</td>
<td>比如比例、分组统计、时间窗口</td>
</tr>
<tr>
<td>是否可能有数据问题</td>
<td>标签噪声、重复样本、泄漏列</td>
</tr>
</tbody></table>
<p>错误分析的价值在于指导 Week 08 的改进，不是为了装饰报告。</p>
<h2>16. README 本周至少要写到什么程度</h2>
<p>Week 07 的 README 不要求完美，但至少包含：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">项目标题
问题定义
数据来源
目标变量
运行命令
当前 baseline 结果链接
下一步计划
</code></pre></div>
<p>运行命令可以写成：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">uv venv
source .venv/bin/activate.fish
uv sync
python src/train_baseline.py
</code></pre></div>
<p>如果你用了手动下载数据，README 必须说明数据应该放在哪里：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">Download the dataset and place the CSV at data/raw/train.csv.
</code></pre></div>
<p>不要让读者猜文件名。</p>
<h2>17. Git 提交</h2>
<p>先创建 <code>.gitignore</code>，内容至少包括：</p>
<div class="omp-code-frame" data-lang="prompt"><div class="omp-code-bar"><span>omp</span><span>prompt</span></div><pre><code class="language-text">.venv/
__pycache__/
.ipynb_checkpoints/
.DS_Store
data/raw/*.zip
</code></pre></div>
<p>如果原始 CSV 很大，或数据许可不允许发布，也把它加入 <code>.gitignore</code>。然后提交：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">git status --short
git add README.md docs reports src pyproject.toml uv.lock .gitignore
git commit -m &quot;Start statistical machine learning baseline project&quot;
</code></pre></div>
<p>如果这是你第一次在该目录使用 Git：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">git init
</code></pre></div>
<p>再执行上面的 <code>git add</code> 与 <code>git commit</code>。</p>
<h2>18. 本周练习</h2>
<ol>
<li>在 <code>docs/data_card.md</code> 中写完至少 10 个字段的说明。</li>
<li>在 README 中用 5 句话讲清楚问题定义。</li>
<li>加入 naive baseline，并在报告中比较 naive baseline 与 sklearn baseline。</li>
<li>把错误样本保存为 <code>reports/wrong_predictions.csv</code>，用 pandas 查看前 20 行。</li>
<li>尝试一个新特征，并说明它为什么可能有用。</li>
<li>用 Git 做两次提交：一次提交项目骨架，一次提交 baseline 结果。</li>
</ol>
<h2>19. 验收检查</h2>
<p>在项目根目录执行：</p>
<div class="omp-code-frame" data-lang="fish"><div class="omp-code-bar"><span>omp</span><span>fish</span></div><pre><code class="language-fish">source .venv/bin/activate.fish
python src/train_baseline.py
test -f docs/data_card.md; and echo &quot;data card exists&quot;
test -f reports/baseline_results.md; and echo &quot;baseline report exists&quot;
test -f reports/error_analysis.md; and echo &quot;error analysis exists&quot;
</code></pre></div>
<p>人工确认：</p>
<ul>
<li>项目目录结构完整。</li>
<li>README 能说明问题、数据、运行方式。</li>
<li><code>docs/data_card.md</code> 写明数据来源、字段、目标、限制。</li>
<li>baseline 脚本能从头运行。</li>
<li>报告有模型、指标、验证方式、结果表。</li>
<li>错误分析不是空模板，至少有 5 条观察。</li>
<li>Git 提交不包含 <code>.venv/</code>。</li>
</ul>
<h2>20. 常见错误</h2>
<h3>错误 1：项目没有明确目标</h3>
<p>“分析 Titanic 数据”不是明确目标。“预测乘客是否生还，并分析哪些群体错误率高”才是明确目标。</p>
<h3>错误 2：README 最后才写</h3>
<p>README 是项目导航，不是交作业时补的封面。Week 07 就写初稿，Week 08 再打磨。</p>
<h3>错误 3：notebook 里能跑，但脚本不能跑</h3>
<p>Notebook 适合探索，最终训练入口应该是 <code>src/train_baseline.py</code>。否则别人无法稳定复现。</p>
<h3>错误 4：数据来源不清楚</h3>
<p>报告里必须能回答：数据从哪里来、下载日期、许可或引用方式、是否可以公开。</p>
<h3>错误 5：只写模型分数，不写错误分析</h3>
<p>模型项目的价值不只在分数，还在你能否解释错误、提出下一步改进。</p>
<h2>21. 下一步</h2>
<p>进入 Week 08：<a href="/post/ustc-stat-ai-quant-plan/">统计建模项目收尾</a>。你会把 Week 07 的项目整理成可以给老师、导师或实习面试官看的版本：README 打磨、报告成稿、复现命令、提交历史清理与成果展示。</p>


    </article>
  </div>
</section>

Week 06：交叉验证、模型选择与防止数据泄漏

Sat, 25 Jul 2026 22:00:00 GMT

Oh My Pi / weekly tutorial / week06-cross-validation-model-selection

miku@cachyos:~/Code/python-learning$ omp teach week06-cross-validation-model-selection --fish-first --step-by-step

source659 行教学文档

weekWeek 06

shellfish-first 命令版

backlink20 周计划

Week 06：交叉验证、模型选择与防止数据泄漏

返回主线计划：USTC 统计学：AI / 量化金融 20 周终端式成长计划

Week 05 你已经会写一个固定 train / validation / test 的 baseline。Week 06 要解决更真实的问题：一次随机划分可能让模型排序碰运气，特征处理如果放错位置会造成数据泄漏，调参如果没有记录就无法复现。

本周目标是把“跑一次分数”升级为“可解释、可复现、可比较的模型选择流程”。命令默认 fish shell。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	Pipeline、ColumnTransformer、KFold、GridSearch、防泄漏
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`src/model_selection.py`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression
from sklearn.model_selection import cross_validate
pipe = Pipeline([
(“scaler”, StandardScaler()),
(“model”, LogisticRegression(max_iter=1000)),
])
result = cross_validate(pipe, X, y, cv=5, scoring=[“accuracy”, “f1_macro”])
print(result[“test_f1_macro”].mean())

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `src/model_selection.py`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周目标

完成 src/model_selection.py 和 reports/week06_cv_report.md：

使用 KFold 或 StratifiedKFold 做交叉验证。
用 Pipeline 把标准化、编码、模型训练放在同一个流程里。
用 GridSearchCV 比较参数组合。
输出 classification 或 regression 指标表。
记录最佳模型、最佳参数、均值、标准差。
解释什么是数据泄漏，以及如何避免。

本周最重要的观念：

ompprompt

预处理必须只从训练折学习，再应用到验证折。
如果你先对全数据 fit scaler，再交叉验证，验证分数就被污染了。

2. 前置条件

你应该已经具备：

Week 05 的 src/train_baselines.py 能正常运行。
理解 train / validation / test 的角色。
会看 accuracy、precision、recall、F1、ROC AUC。
能用 VS Code 修改 Python 文件。
能用 Git 提交实验结果。

检查项目环境：

ompfish

cd ~/Code/python-learning/week05-sklearn-baselines
source .venv/bin/activate.fish
python src/train_baselines.py

如果你想把 Week 06 单独放在新目录，也可以按下一节创建新项目。

3. 建立 Week 06 项目

ompfish

cd ~/Code/python-learning
mkdir -p week06-cross-validation-model-selection
cd week06-cross-validation-model-selection
uv init
uv venv
source .venv/bin/activate.fish
uv add pandas numpy scikit-learn tabulate
mkdir -p src reports data/raw data/processed
code .

逐句解释：

命令	作用
`mkdir -p week06-cross-validation-model-selection`	建立本周项目目录
`uv init`	初始化 Python 项目配置
`uv venv`	创建隔离环境
`source .venv/bin/activate.fish`	激活 fish 专用虚拟环境
`uv add ...`	安装 sklearn 建模需要的包
`mkdir -p src reports ...`	创建代码、报告、数据目录
`code .`	用 VS Code 打开当前项目

4. 文件布局

建议结构：

ompprompt

week06-cross-validation-model-selection/
├── data/
│   ├── raw/
│   └── processed/
├── reports/
│   └── week06_cv_report.md
├── src/
│   └── model_selection.py
├── pyproject.toml
├── uv.lock
└── README.md

本周的主要产出是 model_selection.py。它不应该只是把 Week 05 的脚本复制一遍，而要明确体现：

ompprompt

cross validation + pipeline + grid search + result table

5. 为什么一次 validation 不够

Week 05 的流程是：

ompprompt

train -> valid -> choose model -> test

问题在于 validation 只有一份。如果某次随机划分刚好让某个模型“运气好”，你会误以为它更强。

K-fold cross validation 的想法：

ompprompt

把训练数据切成 K 份
第 1 次：第 1 份做验证，其余做训练
第 2 次：第 2 份做验证，其余做训练
...
第 K 次：第 K 份做验证，其余做训练
最后取 K 次分数的均值和标准差

你需要同时看：

指标	含义
mean score	平均表现
std score	稳定性，越小越稳定
best params	最优参数组合
test score	最终保留测试集上的一次评估

6. KFold 与 StratifiedKFold

6.1 KFold

适合回归任务，或分类任务中类别非常均衡的情况。

omppython

from sklearn.model_selection import KFold
cv = KFold(n_splits=5, shuffle=True, random_state=42)

6.2 StratifiedKFold

适合分类任务，尤其是类别不平衡时。它会尽量保持每一折的类别比例一致。

omppython

from sklearn.model_selection import StratifiedKFold
cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=42)

本周示例是分类任务，所以使用 StratifiedKFold。

7. 数据泄漏是什么

数据泄漏不是语法错误，而是实验设计错误。它会让验证分数看起来很好，但真实泛化很差。

常见泄漏：

错误做法	为什么错
对全数据 `fit_transform` 标准化，再划分训练验证	验证集均值和方差信息提前进入训练过程
用全数据填补缺失值，再交叉验证	验证折的分布信息泄漏到训练折
特征选择时先看全数据与目标的相关性	目标信息通过特征选择进入验证折
调参时反复查看 test 分数	test 被污染，不能再代表最终泛化

正确做法：把预处理放进 Pipeline。交叉验证时，sklearn 会在每个训练折上 fit 预处理器，再对对应验证折 transform。

8. 编写模型选择脚本

在 VS Code 创建：

ompprompt

src/model_selection.py

粘贴下面代码：

omppython

from pathlib import Path
import pandas as pd
from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import accuracy_score, f1_score, precision_score, recall_score, roc_auc_score
from sklearn.model_selection import GridSearchCV, StratifiedKFold, train_test_split
from sklearn.neighbors import KNeighborsClassifier
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.tree import DecisionTreeClassifier
RANDOM_STATE = 42
REPORT_PATH = Path(“reports/week06_cv_report.md”)
def load_data():
dataset = load_breast_cancer(as_frame=True)
return dataset.data, dataset.target, list(dataset.target_names)
def train_test_holdout(X, y):
return train_test_split(
X,
y,
test_size=0.2,
random_state=RANDOM_STATE,
stratify=y,
)
def build_search_spaces():
return {
“logistic_regression”: {
“pipeline”: Pipeline(
steps=[
(“scaler”, StandardScaler()),
(“model”, LogisticRegression(max_iter=3000, random_state=RANDOM_STATE)),
]
),
“params”: {
“model__C”: [0.1, 1.0, 10.0],
“model__class_weight”: [None, “balanced”],
},
},
“knn”: {
“pipeline”: Pipeline(
steps=[
(“scaler”, StandardScaler()),
(“model”, KNeighborsClassifier()),
]
),
“params”: {
“model__n_neighbors”: [3, 5, 9, 15],
“model__weights”: [“uniform”, “distance”],
},
},
“decision_tree”: {
“pipeline”: Pipeline(
steps=[
(“model”, DecisionTreeClassifier(random_state=RANDOM_STATE)),
]
),
“params”: {
“model__max_depth”: [2, 3, 4, 5, None],
“model__min_samples_leaf”: [1, 3, 5],
},
},
“random_forest”: {
“pipeline”: Pipeline(
steps=[
(“model”, RandomForestClassifier(random_state=RANDOM_STATE)),
]
),
“params”: {
“model__n_estimators”: [100, 200],
“model__max_depth”: [3, 5, None],
“model__min_samples_leaf”: [1, 3],
},
},
}
def evaluate_classifier(model, X_test, y_test):
predictions = model.predict(X_test)
probabilities = model.predict_proba(X_test)[:, 1]
return {
“test_accuracy”: accuracy_score(y_test, predictions),
“test_precision”: precision_score(y_test, predictions),
“test_recall”: recall_score(y_test, predictions),
“test_f1”: f1_score(y_test, predictions),
“test_roc_auc”: roc_auc_score(y_test, probabilities),
}
def run_model_selection(X_train, y_train):
cv = StratifiedKFold(n_splits=5, shuffle=True, random_state=RANDOM_STATE)
searches = []
plain for model_name, config in build_search_spaces().items():
search = GridSearchCV(
estimator=config[“pipeline”],
param_grid=config[“params”],
scoring=“f1”,
cv=cv,
n_jobs=-1,
refit=True,
return_train_score=True,
)
search.fit(X_train, y_train)
searches.append(
{
“model”: model_name,
“best_score”: search.best_score_,
“best_params”: search.best_params_,
“best_estimator”: search.best_estimator_,
}
)
plain return sorted(searches, key=lambda row: row[“best_score”], reverse=True)
def make_report(results, test_metrics, target_names):
table_rows = []
for row in results:
table_rows.append(
f”| {row[‘model’]} | {row[‘best_score’]:.4f} | {row[&#39;best_params&#39;]} |”
)
plain best = results[0]
report = f"""# Week 06 Cross Validation Report
Dataset

Source: sklearn breast cancer dataset
Task: binary classification
Target names:

Validation Design

Holdout test size: 20%
Cross validation: StratifiedKFold with 5 folds
Model selection metric: F1
Leakage prevention: preprocessing is inside sklearn Pipeline

Model Selection Results















Model Mean CV F1 Best Params
{chr(10).join(table_rows)} 
Best Model

Selected model: 
Selected by: highest mean cross-validation F1 on the training portion

Final Holdout Test Metrics





























Metric Value
Accuracy {test_metrics[‘test_accuracy’]:.4f}
Precision {test_metrics[‘test_precision’]:.4f}
Recall {test_metrics[‘test_recall’]:.4f}
F1 {test_metrics[‘test_f1’]:.4f}
ROC AUC {test_metrics[‘test_roc_auc’]:.4f}
Leakage Notes

StandardScaler is inside Pipeline, so it is fit only on each training fold.
The holdout test set is not used during GridSearchCV.
The chosen model is evaluated on the test set only after model selection.

Interpretation
Write your own explanation here:

Is the best CV model also clearly better than the others, or only slightly better?
Does the chosen metric match the business or scientific goal?
Are the best parameters reasonable, or do they suggest overfitting?
What should be checked with a larger dataset or repeated CV?
"""
return report

def main():
X, y, target_names = load_data()
X_train, X_test, y_train, y_test = train_test_holdout(X, y)
plain results = run_model_selection(X_train, y_train)
best_model = results[0][“best_estimator”]
test_metrics = evaluate_classifier(best_model, X_test, y_test)
plain report = make_report(results, test_metrics, target_names)
REPORT_PATH.parent.mkdir(parents=True, exist_ok=True)
REPORT_PATH.write_text(report, encoding=“utf-8”)
plain display_rows = [
{
“model”: row[“model”],
“mean_cv_f1”: round(row[“best_score”], 4),
“best_params”: row[“best_params”],
}
for row in results
]
print(pd.DataFrame(display_rows).to_string(index=False))
print()
print(“Best model:”, results[0][“model”])
print(“Test metrics:”, {key: round(value, 4) for key, value in test_metrics.items()})
print(“Report written to”, REPORT_PATH)
if name == “main”:
main()

9. 运行脚本

ompfish

source .venv/bin/activate.fish
python src/model_selection.py

预期输出结构类似：

ompprompt

model mean_cv_f1 best_params random_forest 0.9720 {'model__max_depth': None, 'model__min_samples_leaf': 1, 'model__n_estimators': 200} logistic_regression 0.9680 {'model__C': 1.0, 'model__class_weight': None} knn 0.9662 {'model__n_neighbors': 9, 'model__weights': 'uniform'} decision_tree 0.9371 {'model__max_depth': 4, 'model__min_samples_leaf': 3}

Best model: random_forest Test metrics: {‘test_accuracy’: 0.9649, ‘test_precision’: 0.9589, ‘test_recall’: 0.9859, ‘test_f1’: 0.9722, ‘test_roc_auc’: 0.9951} Report written to reports/week06_cv_report.md

数值可能不同，但必须具备：模型名、CV 均值、最佳参数、最终 test 指标。

10. 结果表怎么读

你会得到类似终端风格结果：

ompprompt

╭─ model selection ─────────────────────╮
│ model                 valid_score      │
├────────────────────────────────────────┤
│ logistic_regression   0.9680           │
│ random_forest         0.9720           │
│ knn                   0.9662           │
│ decision_tree         0.9371           │
╰────────────────────────────────────────╯

但是报告里不要只写一个分数。至少解释三件事：

最佳模型比第二名高多少？如果只高 0.002，可能没有实际差异。
标准差是否大？如果不同折波动很大，模型不稳定。
最优参数是否在网格边界？如果 C=10.0 永远最好，说明还可以继续扩大搜索范围，但不要无止境调参。

当前示例脚本为了简洁没有打印每个参数组合的标准差。你可以扩展 search.cv_results_ 生成更完整表格。

11. 如何加入标准差

在 run_model_selection() 中，GridSearchCV 保存了 cv_results_。可以取最佳行的标准差：

omppython

best_index = search.best_index_
best_std = search.cv_results_["std_test_score"][best_index]

然后把结果字典改成：

omppython

{
    "model": model_name,
    "best_score": search.best_score_,
    "best_std": best_std,
    "best_params": search.best_params_,
    "best_estimator": search.best_estimator_,
}

报告表就能写成：

ompprompt

| Model | Mean CV F1 | Std | Best Params |

这比只看均值更可靠。

12. 回归任务怎么改

如果目标是连续数值，比如房价、收益率、销量，不要用分类指标。改成：

omppython

from sklearn.model_selection import KFold
from sklearn.metrics import mean_absolute_error, mean_squared_error, r2_score
cv = KFold(n_splits=5, shuffle=True, random_state=42)

GridSearchCV 的 scoring 可以用：

omppython

scoring="neg_mean_absolute_error"

注意 sklearn 的误差类指标常用负号，因为 GridSearchCV 默认“越大越好”。报告里要转回正的 MAE：

omppython

mean_mae = -search.best_score_

回归报告建议包含：

指标	含义
MAE	平均绝对误差，单位和目标变量一致，最容易解释
MSE	平方误差，对大误差更敏感
RMSE	MSE 开根号，单位回到目标变量
R²	相对均值模型的解释程度

13. 自己数据中的类别特征

真实表格常有字符串列，比如：

ompprompt

city, gender, industry, education

不能直接喂给 LogisticRegression。Week 06 的正确方式是 ColumnTransformer：

omppython

from sklearn.compose import ColumnTransformer
from sklearn.preprocessing import OneHotEncoder, StandardScaler
numeric_features = [“age”, “income”, “score”]
categorical_features = [“city”, “gender”]
preprocess = ColumnTransformer(
transformers=[
(“num”, StandardScaler(), numeric_features),
(“cat”, OneHotEncoder(handle_unknown=“ignore”), categorical_features),
]
)

然后放进 Pipeline：

omppython

pipeline = Pipeline(
    steps=[
        ("preprocess", preprocess),
        ("model", LogisticRegression(max_iter=3000)),
    ]
)

这样每一折都会只在训练折上学习均值、标准差和类别编码，验证折不会泄漏信息。

14. 报告必须回答的问题

打开报告：

ompfish

code reports/week06_cv_report.md

补充下面内容：

ompprompt

## Model Choice 为什么选择这个模型？它是否明显优于其他模型？ Metric Choice 为什么用 F1 / AUC / MAE / R²？这个指标和问题目标是否一致？ Leakage Prevention 哪些预处理被放进 Pipeline？test 集有没有参与调参？ Limitations

数据量、特征、划分方式、参数网格有哪些限制？

不要写成“GridSearchCV 得分最高，所以最好”。要说明实验设计。

15. Git 保存成果

ompfish

git status --short
git add pyproject.toml uv.lock README.md src reports
git commit -m "Add week06 cross validation model selection"

如果你从 Week 05 复制项目继续做，不要提交 .venv/。如果 git status --short 里出现 .venv/，先确认 .gitignore 包含：

ompprompt

.venv/
__pycache__/
.ipynb_checkpoints/

16. 本周练习

把 scoring="f1" 改成 scoring="roc_auc"，观察模型排序是否改变。
把 n_splits=5 改成 3 和 10，比较结果稳定性与运行时间。
给结果表增加 std_test_score。
在报告中解释为什么 StandardScaler 必须放进 Pipeline。
用一个回归数据集重写脚本，输出 MAE、RMSE、R²。
设计一个小实验：故意在全数据上 fit_transform 标准化，再比较分数，写下为什么这是错误示范。

17. 验收检查

在项目根目录执行：

ompfish

source .venv/bin/activate.fish
python src/model_selection.py
test -f reports/week06_cv_report.md; and echo "report exists"

人工确认：

src/model_selection.py 存在。
使用了 StratifiedKFold 或 KFold。
使用了 Pipeline。
至少比较了 3 个模型。
至少有一个模型使用了参数网格。
报告里有模型、指标、CV 设计、结果表格、最佳参数。
报告明确说明如何防止数据泄漏。
test 集只在最后评估一次。

18. 常见错误

错误 1：先标准化全数据再交叉验证

错误逻辑：

ompprompt

scaler.fit_transform(X)
然后再 cross_validate

这会泄漏验证折信息。修复：把 scaler 放进 Pipeline。

错误 2：分类任务使用普通 KFold 导致类别比例异常

如果数据类别不平衡，某一折可能正类很少，指标波动巨大。

修复：

omppython

StratifiedKFold(n_splits=5, shuffle=True, random_state=42)

错误 3：忘记固定 random_state

没有固定随机种子，今天跑和明天跑结果不同，报告无法复现。

修复：统一设置：

omppython

RANDOM_STATE = 42

错误 4：参数网格过大

初学时不要一口气搜索几千种组合。先用小网格理解流程，再针对有希望的模型细化。

错误 5：把最高分当作唯一结论

如果两个模型均值接近，优先考虑：

稳定性。
可解释性。
训练时间。
是否容易部署。
是否和后续项目目标一致。

19. 下一步

进入 Week 07：统计建模项目启动。你会从练习脚本转向一个可展示的小项目：定义问题、整理数据卡、建立 baseline、记录错误分析，并为 Week 08 的成品报告做准备。

plain

Week 05：sklearn Baselines、数据划分与指标

Sat, 25 Jul 2026 21:00:00 GMT

Oh My Pi / weekly tutorial / week05-sklearn-baselines

miku@cachyos:~/Code/python-learning$ omp teach week05-sklearn-baselines --fish-first --step-by-step

source638 行教学文档

weekWeek 05

shellfish-first 命令版

backlink20 周计划

Week 05：sklearn Baselines、数据划分与指标

返回主线计划：USTC 统计学：AI / 量化金融 20 周终端式成长计划

本周进入 Phase 2：从“会清洗数据”转向“能建立一个可信的机器学习 baseline”。这里的重点不是追求最高分，而是建立一套以后每个项目都会复用的最小训练流程：固定数据划分、训练多个经典模型、记录指标、写下第一轮误差分析。

本文默认你使用 CachyOS、fish shell、VS Code、uv、Python、Git。命令都按 fish 写；如果不是 fish，需要自己转换激活命令。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	train/test、Dummy baseline、LogisticRegression、指标
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`src/train_baselines.py`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

from sklearn.dummy import DummyClassifier
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import classification_report
models = {
“dummy”: DummyClassifier(strategy=“most_frequent”),
“logreg”: LogisticRegression(max_iter=1000),
}
for name, model in models.items():
model.fit(X_train, y_train)
pred = model.predict(X_valid)
print(name)
print(classification_report(y_valid, pred))

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `src/train_baselines.py`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周目标

完成一个可以重复运行的 src/train_baselines.py：

读取一个表格数据集。
区分特征 X 与目标 y。
做 train / validation / test 三份划分。
训练至少 3 个 baseline 模型。
对分类或回归任务输出合适指标。
生成 reports/week05_baseline_results.md。
写下初步误差分析，而不是只贴一个分数。

你最终应理解：

ompprompt

baseline 不是“低级模型”，而是以后所有改进的比较基准。
没有 baseline，就不知道复杂模型到底有没有带来价值。

2. 前置条件

你应该已经完成 Week 01-04：

会在终端进入项目目录。
会用 uv 创建虚拟环境。
会用 VS Code 打开项目。
会用 pandas 读取 CSV。
会做基础 EDA：缺失值、分布、相关性、简单图表。
会用 Git 保存阶段性成果。

检查工具：

ompfish

python --version
uv --version
git --version
code --version

如果 python 指向系统 Python，不要急着安装包；先进入项目目录并激活 .venv。

3. 建议项目位置

如果你前几周已经有学习仓库，可以继续使用：

ompfish

cd ~/Code/python-learning

为 Week 05 单独建一个小项目：

ompfish

mkdir -p week05-sklearn-baselines
cd week05-sklearn-baselines
pwd

解释：

命令	作用
`mkdir -p`	创建目录；目录已存在也不报错
`cd`	进入项目目录
`pwd`	确认当前路径，避免在错误目录里初始化项目

建议输出类似：

ompprompt

/home/miku/Code/python-learning/week05-sklearn-baselines

4. 初始化 uv 项目

ompfish

uv init
uv venv
source .venv/bin/activate.fish

逐句解释：

命令	含义
`uv init`	生成 `pyproject.toml`、`README.md` 等项目文件
`uv venv`	在当前目录创建 `.venv/` 虚拟环境
`source .venv/bin/activate.fish`	fish shell 专用激活命令

激活后检查 Python 路径：

ompfish

command -v python
python --version

你希望看到路径里包含当前项目：

ompprompt

/home/miku/Code/python-learning/week05-sklearn-baselines/.venv/bin/python

如果看到 /usr/bin/python，说明环境没有激活成功。

5. 安装依赖

Week 05 需要 pandas、numpy、scikit-learn，以及一个简单制表工具。

ompfish

uv add pandas numpy scikit-learn tabulate

检查：

ompfish

python -c "import pandas, sklearn; print('pandas', pandas.__version__); print('sklearn', sklearn.__version__)"

这里用 python -c 运行一行小检查，不是写项目代码。真正的训练逻辑要放进 src/train_baselines.py。

6. 建立文件布局

创建目录：

ompfish

mkdir -p data/raw data/processed src reports

建议布局：

ompprompt

week05-sklearn-baselines/
├── .venv/                    # 当前项目虚拟环境，不提交到 Git
├── data/
│   ├── raw/                  # 原始数据，只读保存
│   └── processed/            # 处理后的数据，可重复生成
├── reports/
│   └── week05_baseline_results.md
├── src/
│   └── train_baselines.py
├── pyproject.toml
├── uv.lock
└── README.md

注意：data/raw/ 里的原始数据不要反复手工修改。你可以复制一份到 data/processed/ 做清洗输出，但原始文件最好保留。

7. 选择一个练习数据集

为了让脚本可直接运行，本周可以先用 sklearn 自带的 breast cancer 分类数据集。它适合练习：

二分类。
数值特征。
样本量不大，运行很快。
不需要联网下载。
可直接比较 Logistic Regression、KNN、Decision Tree、Random Forest。

真实项目中，你可以换成 Kaggle、UCI 或课程数据。baseline 结构保持不变。

8. 理解 train / validation / test

不要只划分 train/test。Week 05 应开始养成三份数据意识：

ompprompt

train      用来拟合模型参数
validation 用来比较模型、调参数、做选择
test       最后只使用一次，用来估计最终泛化表现

常见错误是：

ompprompt

在 test 上反复试模型，哪个分数高就选哪个。

这会让 test 变成新的 validation，最终分数偏乐观。正确流程是：

ompprompt

1. train 上训练多个模型
2. validation 上比较模型
3. 选定一个模型
4. 只在最后对 test 评估一次

对于分类任务，划分时使用 stratify=y，保证每份数据里的类别比例接近整体比例。

9. 创建 baseline 脚本

在 VS Code 中打开项目：

ompfish

code .

创建文件：

ompprompt

src/train_baselines.py

把下面代码放进去：

omppython

from pathlib import Path
import pandas as pd
from sklearn.datasets import load_breast_cancer
from sklearn.ensemble import RandomForestClassifier
from sklearn.linear_model import LogisticRegression
from sklearn.metrics import accuracy_score, f1_score, precision_score, recall_score, roc_auc_score
from sklearn.model_selection import train_test_split
from sklearn.neighbors import KNeighborsClassifier
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.tree import DecisionTreeClassifier
RANDOM_STATE = 42
REPORT_PATH = Path(“reports/week05_baseline_results.md”)
def load_data():
dataset = load_breast_cancer(as_frame=True)
X = dataset.data
y = dataset.target
target_names = list(dataset.target_names)
return X, y, target_names
def split_data(X, y):
X_train_valid, X_test, y_train_valid, y_test = train_test_split(
X,
y,
test_size=0.2,
random_state=RANDOM_STATE,
stratify=y,
)
X_train, X_valid, y_train, y_valid = train_test_split(
X_train_valid,
y_train_valid,
test_size=0.25,
random_state=RANDOM_STATE,
stratify=y_train_valid,
)
return X_train, X_valid, X_test, y_train, y_valid, y_test
def build_models():
return {
“logistic_regression”: Pipeline(
steps=[
(“scaler”, StandardScaler()),
(“model”, LogisticRegression(max_iter=2000, random_state=RANDOM_STATE)),
]
),
“knn”: Pipeline(
steps=[
(“scaler”, StandardScaler()),
(“model”, KNeighborsClassifier(n_neighbors=5)),
]
),
“decision_tree”: DecisionTreeClassifier(max_depth=4, random_state=RANDOM_STATE),
“random_forest”: RandomForestClassifier(n_estimators=200, random_state=RANDOM_STATE),
}
def evaluate_classifier(model, X, y):
predictions = model.predict(X)
probabilities = model.predict_proba(X)[:, 1]
return {
“accuracy”: accuracy_score(y, predictions),
“precision”: precision_score(y, predictions),
“recall”: recall_score(y, predictions),
“f1”: f1_score(y, predictions),
“roc_auc”: roc_auc_score(y, probabilities),
}
def format_metrics(metrics):
return {name: round(value, 4) for name, value in metrics.items()}
def make_report(results, split_sizes, target_names, best_model_name, test_metrics):
rows = []
for result in results:
rows.append(
”| {model} | {accuracy:.4f} | {precision:.4f} | {recall:.4f} | {f1:.4f} | {roc_auc:.4f} |“.format(
**result
)
)
plain report = f"""# Week 05 Baseline Results
Dataset

Source: sklearn breast cancer dataset
Task: binary classification
Target names:

Split





















Split Rows
Train {split_sizes[‘train’]}
Validation {split_sizes[‘valid’]}
Test {split_sizes[‘test’]}
The validation set is used for model comparison. The test set is used once after selecting the best validation model.
Validation Metrics





















Model Accuracy Precision Recall F1 ROC AUC
{chr(10).join(rows)} 
Selected Model

Best validation model by F1: 

Final Test Metrics





























Metric Value
Accuracy {test_metrics[‘accuracy’]:.4f}
Precision {test_metrics[‘precision’]:.4f}
Recall {test_metrics[‘recall’]:.4f}
F1 {test_metrics[‘f1’]:.4f}
ROC AUC {test_metrics[‘roc_auc’]:.4f}
Initial Error Analysis
Write 5-8 bullet points after reading the confusion matrix or wrong predictions. Suggested questions:

Which class is easier to miss?
Is high accuracy hiding weak recall?
Does the model make more false positives or false negatives?
Which metric should matter more for this problem?
Is the current split stable enough, or do we need cross validation in Week 06?
"""
return report

def main():
X, y, target_names = load_data()
X_train, X_valid, X_test, y_train, y_valid, y_test = split_data(X, y)
models = build_models()
plain results = []
fitted_models = {}
for name, model in models.items():
model.fit(X_train, y_train)
fitted_models[name] = model
metrics = evaluate_classifier(model, X_valid, y_valid)
results.append({“model”: name, **metrics})
plain results = sorted(results, key=lambda item: item[“f1”], reverse=True)
best_model_name = results[0][“model”]
best_model = fitted_models[best_model_name]
test_metrics = evaluate_classifier(best_model, X_test, y_test)
plain split_sizes = {
“train”: len(X_train),
“valid”: len(X_valid),
“test”: len(X_test),
}
report = make_report(results, split_sizes, target_names, best_model_name, test_metrics)
REPORT_PATH.parent.mkdir(parents=True, exist_ok=True)
REPORT_PATH.write_text(report, encoding=&quot;utf-8&quot;)

print(&quot;Validation results:&quot;)
print(pd.DataFrame(results).round(4).to_string(index=False))
print()
print(&quot;Best model:&quot;, best_model_name)
print(&quot;Test metrics:&quot;, format_metrics(test_metrics))
print(&quot;Report written to&quot;, REPORT_PATH)
if name == “main”:
main()

10. 运行 baseline

确认环境已激活：

ompfish

source .venv/bin/activate.fish
command -v python

运行脚本：

ompfish

python src/train_baselines.py

你应该看到类似输出：

ompprompt

Validation results: model accuracy precision recall f1 roc_auc random_forest 0.9649 0.9714 0.9714 0.9714 0.9921 logistic_regression 0.9561 0.9706 0.9429 0.9565 0.9954 knn 0.9474 0.9701 0.9286 0.9489 0.9868 decision_tree 0.9298 0.9444 0.9444 0.9444 0.9355

Best model: random_forest Test metrics: {‘accuracy’: 0.9561, ‘precision’: 0.9459, ‘recall’: 0.9859, ‘f1’: 0.9655, ‘roc_auc’: 0.9898} Report written to reports/week05_baseline_results.md

具体数值可能因 sklearn 版本略有差异。重要的是：脚本能跑通，报告能生成，模型比较逻辑清楚。

11. 指标怎么读

11.1 Accuracy

ompprompt

accuracy = 预测正确的样本数 / 总样本数

优点：直观。缺点：类别不平衡时可能误导。例如 95% 都是负类，模型全预测负类也有 95% accuracy。

11.2 Precision

ompprompt

precision = 预测为正类且真的为正类 / 所有预测为正类

问题意识：模型说“是”的时候，有多大概率真的“是”？

11.3 Recall

ompprompt

recall = 预测为正类且真的为正类 / 所有真实正类

问题意识：真实正类里，模型抓住了多少？如果漏诊代价高，recall 很重要。

11.4 F1

ompprompt

F1 = precision 和 recall 的调和平均

当你同时关心 precision 与 recall，可用 F1 做第一选择指标。

11.5 ROC AUC

ROC AUC 衡量模型把正类排在负类前面的能力。它不只看一个阈值，而是看不同阈值下的整体区分能力。

12. 为什么 Logistic Regression 和 KNN 要标准化

StandardScaler() 会把每列特征变成大致均值 0、标准差 1。

需要标准化的模型：

Logistic Regression：优化过程受特征尺度影响。
KNN：距离计算会被大尺度特征支配。
SVM：同样强烈依赖尺度。

不一定需要标准化的模型：

Decision Tree。
Random Forest。
Gradient Boosting Tree。

所以脚本里只给 Logistic Regression 和 KNN 放进 Pipeline。

13. 怎样替换成自己的 CSV

假设你的数据是：

ompprompt

data/raw/my_dataset.csv

并且目标列叫 target。可以把 load_data() 改成：

omppython

def load_data():
    data = pd.read_csv("data/raw/my_dataset.csv")
    X = data.drop(columns=["target"])
    y = data["target"]
    target_names = sorted(y.astype(str).unique().tolist())
    return X, y, target_names

如果有类别特征，暂时不要手工把字符串硬改成数字。Week 06 会学习 ColumnTransformer 和防泄漏 pipeline。Week 05 可以先选择全数值数据练手。

14. 报告怎么写

打开报告：

ompfish

code reports/week05_baseline_results.md

在 Initial Error Analysis 下补充你的观察。不要只写：

ompprompt

Random forest is best.

应写成类似：

ompprompt

- Random forest 在 validation F1 上最高，但 Logistic Regression 的 ROC AUC 也很高，说明线性边界已经有不错区分能力。
- 如果任务重视漏检，recall 比 accuracy 更重要。当前最佳模型 test recall 高于 precision，错误更偏向 false positives。
- Validation 集只有一份，结果可能受随机划分影响。Week 06 需要用交叉验证确认排序是否稳定。

15. Git 保存成果

先看状态：

ompfish

git status --short

如果这是独立学习项目，还没有 Git 仓库：

ompfish

git init

创建 .gitignore 可以用 VS Code，新建文件 .gitignore，写入：

ompprompt

.venv/
__pycache__/
.ipynb_checkpoints/
data/raw/*.zip

提交：

ompfish

git add pyproject.toml uv.lock README.md src reports .gitignore
git commit -m "Add week05 sklearn baseline training"

如果数据文件来自公开小数据，也可以提交；如果数据很大或有隐私，不要直接提交。

16. 本周练习

把 RANDOM_STATE 改成 7、21、100，观察 validation 排名是否稳定。
把 DecisionTreeClassifier(max_depth=4) 改成 max_depth=2 和 max_depth=None，比较过拟合迹象。
把 KNN 的 n_neighbors 改成 3、7、11，观察 F1 变化。
在报告里加一节 Metric Choice，说明为什么本任务不能只看 accuracy。
换一个 sklearn 自带数据集或你自己的 CSV，复用同一训练流程。

17. 验收检查

在项目根目录执行：

ompfish

source .venv/bin/activate.fish
python src/train_baselines.py
test -f reports/week05_baseline_results.md; and echo "report exists"

然后人工检查：

src/train_baselines.py 存在。
reports/week05_baseline_results.md 存在。
报告里有模型名称、指标、划分方式、结果表格、初步误差分析。
代码里有固定的 RANDOM_STATE。
test set 没有参与模型选择，只在最后评估一次。
Git 至少有一次提交。

如果这些都满足，Week 05 合格。

18. 常见错误

错误 1：fish 激活命令写错

现象：

ompprompt

Unsupported use of '='

原因：在 fish 里用了 Bash / Zsh 的激活脚本。

修复：

ompfish

source .venv/bin/activate.fish

错误 2：`ModuleNotFoundError: No module named 'sklearn'`

原因通常是没有激活当前项目虚拟环境，或依赖安装在别的环境。

检查：

ompfish

command -v python
uv pip list

修复：

ompfish

source .venv/bin/activate.fish
uv add scikit-learn

错误 3：忘记 `stratify=y`

分类任务如果类别不平衡，某一份 split 可能类别比例异常，导致分数不稳定。

修复：

omppython

train_test_split(X, y, stratify=y, random_state=RANDOM_STATE)

错误 4：在 test 上选模型

不要比较所有模型的 test 分数再选最高。这样 test 已经被你用来调参了。

正确做法：validation 选模型，test 做最终确认。

错误 5：把 baseline 当成最终结论

Week 05 的 baseline 只是起点。它告诉你：如果后续特征工程、交叉验证、模型选择没有超过 baseline，就说明复杂度没有带来收益。

19. 下一步

进入 Week 06：交叉验证与模型选择。你会把本周的一次固定划分，升级为 K-fold cross validation、GridSearchCV 和防止数据泄漏的 Pipeline。

plain

Week 04：可视化 + EDA 报告

Sat, 25 Jul 2026 20:00:00 GMT

Oh My Pi / weekly tutorial / week04-visualization-eda

miku@cachyos:~/Code/python-learning$ omp teach week04-visualization-eda --fish-first --step-by-step

source713 行教学文档

weekWeek 04

shellfish-first 命令版

backlink20 周计划

Week 04：可视化 + EDA 报告

返回主线计划：USTC 统计学 AI / 量化 20 周成长计划

本文命令默认使用 fish shell。本周目标不是“画很多图”，而是学会用图表支持数据观察，并把观察写成一份结构清楚、可复现、不过度解释的 EDA 报告。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	matplotlib、分布、箱线图、相关性、报告叙事
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`reports/week04_eda_report.md`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(8, 4))
df[“value”].hist(ax=ax, bins=30)
ax.set_title(“Value distribution”)
ax.set_xlabel(“value”)
ax.set_ylabel(“count”)
fig.tight_layout()
fig.savefig(“figures/value_distribution.png”, dpi=160)

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `reports/week04_eda_report.md`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周目标

完成 Week 04 后，你应该能：

使用 matplotlib 绘制直方图、散点图、箱线图。
在安装 seaborn 时使用 seaborn 画更省力的统计图。
把图保存到 figures/*.png，而不是只显示在 notebook 输出里。
建立 EDA 报告结构：数据来源、字段说明、缺失值、主要分布、相关性观察、可能建模目标。
理解 notebook 和 script 的分工：探索可以用 notebook，最终结果要能用脚本复现。

文件布局

建议本周交付物：

ompprompt

week04-visualization-eda/
├── data/
│   ├── raw/
│   │   └── student_scores.csv
│   └── processed/
│       └── student_scores_clean.csv
├── figures/
│   ├── average_score_hist.png
│   ├── study_hours_vs_average_score.png
│   ├── average_score_by_major.png
│   └── correlation_heatmap.png
├── notebooks/
│   └── week04_visualization_eda.ipynb
├── reports/
│   └── week04_eda_report.md
├── src/
│   ├── prepare_data.py
│   └── make_figures.py
├── .venv/
├── pyproject.toml
└── README.md

2. 前置要求

你需要已经会：

用 pandas 读取 CSV。
检查缺失值和描述统计。
使用 uv run python ... 运行脚本。
在 VS Code 中编辑 .py 和 .md 文件。
使用 fish 激活虚拟环境。

如果 Week 03 的项目还在，也可以直接复制 Week 03 的清洗后数据到 Week 04 项目。为了教程完整，下面从新项目开始。

3. 创建 Week 04 项目

ompfish

mkdir -p ~/Code/python-learning/week04-visualization-eda
cd ~/Code/python-learning/week04-visualization-eda
mkdir -p src data/raw data/processed figures notebooks reports
uv init
uv venv
source .venv/bin/activate.fish
uv add numpy pandas matplotlib
code .

解释：

命令	作用
`mkdir -p ...`	创建本周项目目录和子目录
`uv init`	初始化项目配置
`uv venv`	创建 `.venv`
`source .venv/bin/activate.fish`	fish 中激活虚拟环境
`uv add numpy pandas matplotlib`	安装数据处理和绘图库
`code .`	用 VS Code 打开项目

检查安装：

ompfish

uv run python -c "import pandas, matplotlib; print('ok')"

如果你想使用 seaborn，可以额外安装：

ompfish

uv add seaborn

本教程会给出 matplotlib 主线；seaborn 是可选增强。

4. 准备数据

创建原始数据：

ompfish

printf 'student,major,gender,math,english,python,study_hours\nA,statistics,F,88,79,85,12\nB,statistics,M,92,81,90,14\nC,finance,F,75,86,78,9\nD,finance,M,80,,82,8\nE,statistics,F,95,88,,15\nF,computer,M,70,76,88,10\nG,computer,F,,90,91,11\nH,statistics,M,84,82,86,13\nI,finance,F,78,84,80,9\nJ,computer,M,73,78,84,10\nK,statistics,F,90,85,92,14\nL,finance,M,82,80,79,7\n' > data/raw/student_scores.csv

检查：

ompfish

head data/raw/student_scores.csv
wc -l data/raw/student_scores.csv

这里仍然是练习数据，但比 Week 03 多几行，方便画图。

5. 写数据准备脚本

创建 src/prepare_data.py：

omppython

from pathlib import Path
import pandas as pd
RAW_PATH = Path(“data/raw/student_scores.csv”)
OUTPUT_PATH = Path(“data/processed/student_scores_clean.csv”)
NUMERIC_COLUMNS = [“math”, “english”, “python”, “study_hours”]
SCORE_COLUMNS = [“math”, “english”, “python”]
def load_data(path: Path) -> pd.DataFrame:
return pd.read_csv(path)
def clean_data(df: pd.DataFrame) -> pd.DataFrame:
cleaned = df.copy()
plain for column in NUMERIC_COLUMNS:
cleaned[column] = pd.to_numeric(cleaned[column], errors=“coerce”)
cleaned[column] = cleaned[column].fillna(cleaned[column].median())
plain cleaned[“average_score”] = cleaned[SCORE_COLUMNS].mean(axis=1)
return cleaned
def save_data(df: pd.DataFrame, path: Path) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
df.to_csv(path, index=False)
def main() -> None:
raw = load_data(RAW_PATH)
cleaned = clean_data(raw)
save_data(cleaned, OUTPUT_PATH)
print(f”Rows: {len(cleaned)}”)
print(f”Columns: {len(cleaned.columns)}”)
print(f”Saved: {OUTPUT_PATH}”)
if name == “main”:
main()

运行：

ompfish

uv run python src/prepare_data.py
ls data/processed
head data/processed/student_scores_clean.csv

这一步保证后续画图总是使用同一份清洗后数据。

6. matplotlib 基础概念

matplotlib 的核心是 figure 和 axes：

figure：整张画布。
axes：画布上的一个坐标系，真正画图的位置。

常用模板：

omppython

import matplotlib.pyplot as plt
fig, ax = plt.subplots(figsize=(8, 5))
ax.hist(values, bins=10)
ax.set_title(“Title”)
ax.set_xlabel(“X label”)
ax.set_ylabel(“Y label”)
fig.tight_layout()
fig.savefig(“figures/example.png”, dpi=150)
plt.close(fig)

为什么要 plt.close(fig)：脚本批量生成多张图时，关闭旧图可以避免内存和状态混乱。

7. 写可复现画图脚本

创建 src/make_figures.py：

omppython

from pathlib import Path
import matplotlib.pyplot as plt
import pandas as pd
DATA_PATH = Path(“data/processed/student_scores_clean.csv”)
FIGURE_DIR = Path(“figures”)
SCORE_COLUMNS = [“math”, “english”, “python”, “average_score”]
def load_data(path: Path) -> pd.DataFrame:
return pd.read_csv(path)
def save_current_figure(fig, filename: str) -> None:
FIGURE_DIR.mkdir(parents=True, exist_ok=True)
output_path = FIGURE_DIR / filename
fig.tight_layout()
fig.savefig(output_path, dpi=150)
plt.close(fig)
print(f”Saved {output_path}”)
def plot_average_score_hist(df: pd.DataFrame) -> None:
fig, ax = plt.subplots(figsize=(8, 5))
ax.hist(df[“average_score”], bins=8, edgecolor=“black”)
ax.set_title(“Distribution of Average Score”)
ax.set_xlabel(“Average score”)
ax.set_ylabel(“Student count”)
save_current_figure(fig, “average_score_hist.png”)
def plot_study_hours_scatter(df: pd.DataFrame) -> None:
fig, ax = plt.subplots(figsize=(8, 5))
ax.scatter(df[“study_hours”], df[“average_score”])
ax.set_title(“Study Hours vs Average Score”)
ax.set_xlabel(“Study hours per week”)
ax.set_ylabel(“Average score”)
save_current_figure(fig, “study_hours_vs_average_score.png”)
def plot_major_boxplot(df: pd.DataFrame) -> None:
majors = sorted(df[“major”].unique())
values = [df.loc[df[“major”] == major, “average_score”] for major in majors]
plain fig, ax = plt.subplots(figsize=(8, 5))
ax.boxplot(values, labels=majors)
ax.set_title(“Average Score by Major”)
ax.set_xlabel(“Major”)
ax.set_ylabel(“Average score”)
save_current_figure(fig, “average_score_by_major.png”)
def plot_correlation_heatmap(df: pd.DataFrame) -> None:
corr = df[SCORE_COLUMNS + [“study_hours”]].corr()
plain fig, ax = plt.subplots(figsize=(7, 6))
image = ax.imshow(corr, cmap=“coolwarm”, vmin=-1, vmax=1)
plain ax.set_xticks(range(len(corr.columns)))
ax.set_yticks(range(len(corr.index)))
ax.set_xticklabels(corr.columns, rotation=45, ha=“right”)
ax.set_yticklabels(corr.index)
ax.set_title(“Correlation Heatmap”)
plain for row in range(len(corr.index)):
for col in range(len(corr.columns)):
ax.text(col, row, f”{corr.iloc[row, col]:.2f}”, ha=“center”, va=“center”, color=“black”)
fig.colorbar(image, ax=ax)
save_current_figure(fig, &quot;correlation_heatmap.png&quot;)
def main() -> None:
df = load_data(DATA_PATH)
plot_average_score_hist(df)
plot_study_hours_scatter(df)
plot_major_boxplot(df)
plot_correlation_heatmap(df)
if name == “main”:
main()

运行完整流程：

ompfish

uv run python src/prepare_data.py
uv run python src/make_figures.py
ls figures

你应该看到：

ompprompt

average_score_by_major.png
average_score_hist.png
correlation_heatmap.png
study_hours_vs_average_score.png

8. 图表一：直方图看分布

直方图回答的问题是：一个数值变量大致集中在哪里？是否偏态？是否有异常值？

本教程中的直方图：

omppython

ax.hist(df["average_score"], bins=8, edgecolor="black")

解释：

参数	含义
`df["average_score"]`	要观察分布的变量
`bins=8`	分成 8 个区间
`edgecolor="black"`	给柱子加边框，方便阅读

报告中不要只写“画了直方图”，要写观察：

ompprompt

平均分主要集中在 80 到 90 分之间，样本中没有特别低的平均分。由于样本量很小，这个分布只能用于流程练习，不能代表真实学生群体。

9. 图表二：散点图看两个变量关系

散点图回答的问题是：两个数值变量之间是否有明显关系？

本教程中：

omppython

ax.scatter(df["study_hours"], df["average_score"])

横轴是学习时长，纵轴是平均分。

报告写法示例：

ompprompt

散点图显示学习时长和平均分大致同向变化：学习时长较高的学生平均分往往也较高。但样本只有 12 行，不能据此得出稳定因果结论。

注意“相关不等于因果”。统计学同学尤其要避免把 EDA 观察写成因果判断。

10. 图表三：箱线图看组间差异

箱线图适合比较不同组的数值分布。这里按 major 比较 average_score。

代码核心：

omppython

majors = sorted(df["major"].unique())
values = [df.loc[df["major"] == major, "average_score"] for major in majors]
ax.boxplot(values, labels=majors)

报告中可以写：

ompprompt

statistics 组平均分中位数较高，computer 和 finance 组略低。但每组样本数量很少，箱线图主要用于展示方法，不适合做群体差异结论。

真实项目中还应补充每组样本数，否则箱线图容易误导。

11. 图表四：相关性热力图

相关性热力图用来观察多个数值变量之间的线性相关关系。

核心代码：

omppython

corr = df[["math", "english", "python", "average_score", "study_hours"]].corr()

corr() 默认计算 Pearson 相关系数，范围从 -1 到 1：

值	含义
接近 1	强正相关
接近 -1	强负相关
接近 0	线性相关较弱

注意：average_score 本来就是由 math、english、python 算出来的，所以它和各科成绩相关很正常。这不是新的发现，而是变量定义带来的结果。

12. seaborn 可选增强

如果已经安装 seaborn：

ompfish

uv add seaborn

可以用更少代码画热力图：

omppython

import seaborn as sns
corr = df[[“math”, “english”, “python”, “average_score”, “study_hours”]].corr()
fig, ax = plt.subplots(figsize=(7, 6))
sns.heatmap(corr, annot=True, cmap=“coolwarm”, vmin=-1, vmax=1, ax=ax)
fig.tight_layout()
fig.savefig(“figures/correlation_heatmap_seaborn.png”, dpi=150)
plt.close(fig)

但本周主线仍应掌握 matplotlib，因为它是 Python 可视化生态的底层基础。seaborn 很好用，但不应成为你完全不理解坐标轴、标题、标签、保存图片的理由。

13. 保存图像的规范

建议统一把图放在 figures/：

ompfish

ls figures

命名建议：

文件名	含义
`average_score_hist.png`	平均分直方图
`study_hours_vs_average_score.png`	学习时长与平均分散点图
`average_score_by_major.png`	不同专业平均分箱线图
`correlation_heatmap.png`	数值变量相关性热力图

不要用：

ompprompt

1.png
new.png
final_final.png

图片文件名应该让读者不用打开也能猜到内容。

14. EDA 报告结构

创建 reports/week04_eda_report.md，建议结构如下：

ompmarkdown

# Week 04 EDA 报告 1. 数据来源说明数据来自本周练习 CSV，包含学生专业、性别、三科成绩和每周学习时长。 2. 字段说明字段含义类型 student 学生编号分类 major 专业分类 gender 性别分类 math 数学成绩数值 english 英语成绩数值 python Python 成绩数值 study_hours 每周学习时长数值 average_score 三科平均分数值 3. 缺失值情况说明原始数据中哪些列有缺失值，以及使用中位数填补数值列。 4. 主要分布引用 figures/average_score_hist.png，描述平均分集中区间和异常值情况。 5. 分组观察引用 figures/average_score_by_major.png，描述不同专业组的平均分分布，并说明样本量限制。 6. 相关性观察引用 figures/study_hours_vs_average_score.png 和 figures/correlation_heatmap.png，描述学习时长与平均分、各科成绩之间的相关性。 7. 可能的建模目标可以提出一个后续建模问题，例如：根据学习时长、专业和前两科成绩预测 Python 成绩，或根据特征判断 average_score 是否高于 85。 8. 局限性

说明样本量小、数据为练习数据、不能代表真实 USTC 学生群体。

报告必须用文字解释图，而不是只把图片贴进去。

Markdown 引用图片写法：

ompmarkdown

![平均分直方图](../figures/average_score_hist.png)

如果报告和 figures 都在项目根目录下的不同子目录，上面这种 ../figures/... 路径是合理的：从 reports/ 回到上一级，再进入 figures/。

15. Notebook vs script：本周更要分清

Notebook 的优点：

适合一步步看数据。
适合临时尝试不同图表。
适合在同一页面写图和解释。

Script 的优点：

能一键复现所有图片。
Git diff 更清楚。
不依赖手动运行某个单元格。
适合以后放到作品集。

推荐流程：

ompprompt

notebooks/week04_visualization_eda.ipynb：探索
src/prepare_data.py：固定清洗流程
src/make_figures.py：固定画图流程
reports/week04_eda_report.md：写最终解释

如果使用 notebook：

ompfish

uv add ipykernel

然后在 VS Code 中选择当前项目 .venv 作为 kernel。即使使用 notebook，也要保留 src/make_figures.py，确保图片可重新生成。

16. 一键复现本周结果

在项目根目录执行：

ompfish

source .venv/bin/activate.fish
uv run python src/prepare_data.py
uv run python src/make_figures.py
ls figures

这组命令应该能从原始 CSV 生成清洗数据，再生成所有图片。

如果以后换电脑或把项目交给同学，理想流程是：

ompfish

uv sync
uv run python src/prepare_data.py
uv run python src/make_figures.py

这里的关键思想是“可复现”。EDA 不是只在你电脑上偶然跑通，而是别人按说明也能得到同样文件。

17. 本周练习

练习 A：增加单科成绩直方图

在 src/make_figures.py 中增加函数：

omppython

def plot_python_score_hist(df: pd.DataFrame) -> None:
    fig, ax = plt.subplots(figsize=(8, 5))
    ax.hist(df["python"], bins=8, edgecolor="black")
    ax.set_title("Distribution of Python Score")
    ax.set_xlabel("Python score")
    ax.set_ylabel("Student count")
    save_current_figure(fig, "python_score_hist.png")

然后在 main() 中调用它。

运行：

ompfish

uv run python src/make_figures.py
ls figures

练习 B：按性别画箱线图

仿照 plot_major_boxplot，按 gender 比较 average_score。

输出文件命名为：

ompprompt

average_score_by_gender.png

报告中必须写样本量限制，不能把练习数据解释成真实群体差异。

练习 C：保存描述统计表

创建 src/export_summary.py，把描述统计保存为 CSV：

omppython

from pathlib import Path
import pandas as pd
df = pd.read_csv(Path(“data/processed/student_scores_clean.csv”))
summary = df.describe()
summary.to_csv(Path(“reports/descriptive_statistics.csv”))

运行：

ompfish

uv run python src/export_summary.py
ls reports

练习 D：改进报告

在 reports/week04_eda_report.md 中为每张图写三句话：

这张图看什么变量？
从图中观察到什么？
这个观察有什么限制？

18. 验收检查

在项目根目录执行：

ompfish

pwd
ls
source .venv/bin/activate.fish
uv run python src/prepare_data.py
uv run python src/make_figures.py
ls data/processed
ls figures

验收标准：

当前目录是 week04-visualization-eda。
source .venv/bin/activate.fish 不报错。
data/processed/student_scores_clean.csv 存在。
figures/average_score_hist.png 存在。
figures/study_hours_vs_average_score.png 存在。
figures/average_score_by_major.png 存在。
figures/correlation_heatmap.png 存在。
reports/week04_eda_report.md 包含数据来源、字段说明、缺失值情况、主要分布、相关性观察、可能的建模目标。
报告中的结论使用“观察”“可能”“样本有限”等谨慎表述，而不是过度因果解释。

19. 常见错误

错误 1：`ModuleNotFoundError: No module named 'matplotlib'`

说明当前环境没有安装 matplotlib，或没有使用项目环境运行。

修复：

ompfish

cd ~/Code/python-learning/week04-visualization-eda
uv add matplotlib
uv run python src/make_figures.py

错误 2：图片没有生成

先检查脚本是否真的运行到保存函数：

ompfish

uv run python src/make_figures.py
ls figures

如果没有 figures/，检查是否调用了：

omppython

fig.savefig(output_path, dpi=150)

以及是否创建目录：

omppython

FIGURE_DIR.mkdir(parents=True, exist_ok=True)

错误 3：`FileNotFoundError: data/processed/student_scores_clean.csv`

原因：还没运行数据准备脚本。

修复：

ompfish

uv run python src/prepare_data.py
uv run python src/make_figures.py

错误 4：中文标题显示成方块

matplotlib 默认字体可能不支持中文。初学阶段最简单的办法是图表标题先使用英文，报告正文使用中文解释。等后续需要正式中文图表时，再单独配置中文字体。

错误 5：热力图颜色看起来很夸张

如果不固定颜色范围，不同数据集的颜色尺度可能不一致。建议相关性热力图使用：

omppython

ax.imshow(corr, cmap="coolwarm", vmin=-1, vmax=1)

这样 -1 到 1 的颜色含义稳定。

错误 6：报告只有图片，没有分析

EDA 报告不是图库。每张图至少要回答：

这张图为什么画？
图中最明显的模式是什么？
这个结论有什么限制？

如果答不出来，说明这张图可能不该放进报告，或者你还没理解变量含义。

20. 下一步

Phase 1 到这里结束。你已经从 Python 环境、Linux / Git、Pandas 表格处理走到了完整 EDA 报告。Week 05 开始进入机器学习基础：用 scikit-learn 做回归 / 分类、训练集测试集划分、交叉验证和评价指标。Week 04 的清洗数据与 EDA 报告，会成为后续建模项目的输入。

plain

CachyOS + VS Code + uv：Python 学习环境搭建教学

Sat, 25 Jul 2026 19:00:00 GMT

Oh My Pi / python environment / fish-first lesson

miku@cachyos:~/Code/python-learning$ omp teach python-env --fish-first --vscode --uv

source642 行教学文档

platformCachyOS / Arch 系

shellfish-first 命令版

env manageruv + .venv

CachyOS + VS Code + uv：Python 学习环境搭建教学

适用对象：已经安装 VS Code，正在用 CachyOS / Arch 系 Linux，准备按 20 周 AI / 量化成长计划开始 Week 01：Python / Linux / Git / 数据分析基础。

核心结论
不需要把所有事情都放在命令行里做。你可以主要在 VS Code 里写代码、看文件、运行 notebook；但必须掌握少量命令行，因为 Python 环境、包管理、脚本运行、Git、项目复现都依赖这些基础命令。

本教程采用：

ompprompt

VS Code 负责：写代码、看文件、运行脚本、调试、使用 notebook
uv 负责：创建虚拟环境、安装依赖、记录项目配置
终端负责：创建目录、激活环境、运行命令、检查结果

本文命令行默认按 fish shell 写；如果某一步需要 Bash / Zsh，会单独标注。

当前机器已经具备：

ompprompt

Python 3.14.6
uv 0.11.31
VS Code 1.130.0

因此不需要从零安装 Python，直接建立学习环境即可。

1. 为什么不能完全不用命令行

你不需要成为 Linux 高手，但不能完全绕开命令行。

原因有四个：

环境隔离需要命令：每个项目应有自己的 .venv，避免不同项目的包互相污染。
安装包需要命令：例如 numpy、pandas、matplotlib、scikit-learn。
复现实验需要命令：以后别人看你的项目，需要知道如何一键安装依赖并运行。
Git 和部署需要命令：提交代码、查看状态、解决冲突，迟早会用到。

最低限度只需要会这些：

ompfish

pwd        # 看当前在哪个目录
ls         # 看当前目录有什么文件
cd         # 进入目录
mkdir      # 创建文件夹
code .     # 用 VS Code 打开当前目录
uv init    # 初始化 Python 项目
uv venv    # 创建虚拟环境
uv add     # 安装依赖
python     # 运行 Python

2. 建立统一学习目录

先给未来 20 周的学习项目留一个统一位置。

打开终端，执行：

ompfish

mkdir -p ~/Code/python-learning
cd ~/Code/python-learning
pwd

逐句解释：

命令	含义
`mkdir`	创建文件夹
`-p`	如果上级目录不存在，就一起创建；如果目录已存在，也不要报错
`~/Code/python-learning`	你的 Python 学习总目录，`~` 表示当前用户主目录
`cd`	进入这个目录
`pwd`	打印当前所在路径，用来确认你没有走错目录

如果输出类似：

ompprompt

/home/miku/Code/python-learning

说明位置正确。

3. 创建第一个 Week 01 项目

每周一个小项目，不要把所有练习都堆在一个文件夹里。

ompfish

mkdir week01-basics
cd week01-basics

建议结构：

ompprompt

week01-basics/
├── notes/       # 学习笔记
├── src/         # Python 源代码
├── data/        # 小数据文件
├── notebooks/   # Jupyter notebook
└── reports/     # 报告或总结

创建这些目录：

ompfish

mkdir -p notes src data notebooks reports

检查：

ompfish

ls

应该看到：

ompprompt

data  notebooks  notes  reports  src

4. 初始化 Python 项目

在 week01-basics 目录里执行：

ompfish

uv init

这一步会生成项目配置文件，通常包括：

ompprompt

pyproject.toml
README.md
main.py

解释：

文件	作用
`pyproject.toml`	记录项目名称、Python 版本、依赖包
`README.md`	项目说明，未来给老师、面试官或自己回看
`main.py`	默认入口脚本，可以改也可以删除

如果 uv init 提示文件已存在，不用慌，说明当前目录里已经有项目文件。

5. 创建虚拟环境 `.venv`

执行：

ompfish

uv venv

它会创建：

ompprompt

.venv/

.venv 是这个项目自己的 Python 环境。以后这个项目安装的包都放在里面，不污染系统 Python。

为什么重要：

ompprompt

系统 Python：给操作系统和系统工具用
项目 .venv：给当前学习项目用

不要把所有包直接装进系统 Python。CachyOS / Arch 是滚动发行版，系统 Python 更应该保持干净。

6. 激活虚拟环境

先确认你在真正的项目目录里，而不是只在总目录 ~/Code/python-learning 里：

ompfish

pwd
ls

如果你按本文创建的是 week01-basics 项目，那么应先进入：

ompfish

cd ~/Code/python-learning/week01-basics

判断标准：当前目录里应该能看到 pyproject.toml 和 .venv/。如果你在 ~/Code/python-learning 总目录下执行激活命令，而虚拟环境其实建在 week01-basics/.venv/，就会找错位置。

6.1 如果你使用 fish shell

你现在遇到的报错就是 fish shell 把 Bash 版激活脚本当成 fish 脚本执行了。

fish 里应执行：

ompfish

source .venv/bin/activate.fish

不要在 fish 里执行：

ompbash/zsh

source .venv/bin/activate

.venv/bin/activate 是给 Bash / Zsh 用的，里面有 变量=值 这种语法；fish 不支持这种写法，所以会报：

ompprompt

不支持使用 '='

6.2 如果你使用 bash 或 zsh

Bash / Zsh 才使用：

ompbash/zsh

source .venv/bin/activate

6.3 激活成功后的检查

成功后，终端提示符前面通常会出现：

ompprompt

(.venv)

这表示当前终端已经进入项目环境。

验证 Python 路径：

ompfish

command -v python
python --version

你希望看到的 command -v python 应该类似：

ompprompt

/home/miku/Code/python-learning/week01-basics/.venv/bin/python

如果看到的是 /usr/bin/python，说明虚拟环境没有激活成功，或者你不在创建 .venv 的项目目录里。

7. 安装第一批学习包

Week 01 到 Week 04 建议安装：

ompfish

uv add numpy pandas matplotlib jupyter ipykernel

逐个解释：

包	用途
`numpy`	数值计算，数组、矩阵、随机数
`pandas`	表格数据处理，CSV、DataFrame
`matplotlib`	基础画图
`jupyter`	notebook 环境
`ipykernel`	让 VS Code / Jupyter 使用当前虚拟环境

安装完成后，pyproject.toml 会记录这些依赖。以后别人拿到你的项目，可以根据配置恢复环境。

8. 用 VS Code 打开项目

确认你还在项目目录：

ompfish

pwd

然后执行：

ompfish

code .

含义：用 VS Code 打开当前目录。

不要只打开单个 .py 文件，应该打开整个项目文件夹。这样 VS Code 才能识别 .venv、pyproject.toml、目录结构和相对路径。

9. 在 VS Code 里选择 Python 解释器

打开 VS Code 后：

按 Ctrl + Shift + P。
输入 Python: Select Interpreter。
选择当前项目的解释器：

ompprompt

.venv/bin/python

如果列表里没看到，可以手动选择：

ompprompt

/home/miku/Code/python-learning/week01-basics/.venv/bin/python

这一步的意义：告诉 VS Code 使用当前项目环境，而不是系统 Python。

10. 写第一个脚本

在 src/ 下新建文件：

ompprompt

src/hello.py

内容：

omppython

print("Hello, Python")
scores = [85, 92, 78]
mean_score = sum(scores) / len(scores)
print(mean_score)

用终端运行：

ompfish

python src/hello.py

应该输出：

ompprompt

Hello, Python
85.0

如果 VS Code 右上角运行按钮也能跑出同样结果，说明解释器配置正确。

11. 写第一个 pandas 练习

新建：

ompprompt

src/pandas_demo.py

内容：

omppython

import pandas as pd
data = {
“name”: [“Alice”, “Bob”, “Cindy”],
“score”: [85, 92, 78],
}
df = pd.DataFrame(data)
print(df)
print(“mean score:”, df[“score”].mean())

运行：

ompfish

python src/pandas_demo.py

如果能看到表格和平均分，说明：

ompprompt

Python 能运行
pandas 已安装
VS Code 项目路径正确
虚拟环境可用

12. 建立 notebook

在 VS Code 里新建：

ompprompt

notebooks/week01.ipynb

第一次打开 notebook 时，右上角选择 Kernel：

ompprompt

.venv/bin/python

新建一个 cell：

omppython

import pandas as pd
pd.DataFrame({“x”: [1, 2, 3], “y”: [2, 4, 6]})

如果表格正常显示，notebook 环境配置成功。

13. 推荐项目结构

Week 01 最终建议变成：

ompprompt

week01-basics/
├── .venv/
├── data/
│   └── scores.csv
├── notebooks/
│   └── week01.ipynb
├── notes/
│   └── week01-python.md
├── reports/
│   └── week01-summary.md
├── src/
│   ├── hello.py
│   └── pandas_demo.py
├── pyproject.toml
├── README.md
└── uv.lock

其中：

路径	说明
`.venv/`	虚拟环境，不手动编辑，不提交到 Git
`data/`	小数据文件
`notebooks/`	交互式分析
`notes/`	学习笔记
`reports/`	阶段总结
`src/`	正式 Python 脚本
`pyproject.toml`	项目依赖配置
`uv.lock`	锁定依赖版本，保证复现

14. Git 初始化

如果你要把练习当成项目积累，建议从 Week 01 就用 Git。

ompfish

git init

创建 .gitignore：

ompfish

printf "%s\n" ".venv/" "__pycache__/" ".ipynb_checkpoints/" "*.pyc" ".env" > .gitignore

解释：

条目	为什么忽略
`.venv/`	虚拟环境很大，可以重建，不应提交
`__pycache__/`	Python 自动缓存
`.ipynb_checkpoints/`	Jupyter 自动生成
`*.pyc`	编译缓存
`.env`	可能包含 API key

查看状态：

ompfish

git status

提交：

ompfish

git add README.md pyproject.toml uv.lock src notes notebooks reports data .gitignore
git commit -m "init python learning environment"

如果你暂时还不熟 Git，可以先不提交，但至少要理解 .venv/ 不该放进仓库。

15. 以后每天怎么用

每次重新打开项目，如果你使用 fish：

ompfish

cd ~/Code/python-learning/week01-basics
source .venv/bin/activate.fish
code .

如果你使用 bash / zsh：

ompbash/zsh

cd ~/Code/python-learning/week01-basics
source .venv/bin/activate
code .

如果只在 VS Code 里运行，解释器选好后不一定每次都要手动激活；但只要你在终端里运行 python，建议先激活。

16. 常见错误排查

16.1 VS Code 找不到 pandas

现象：

ompprompt

ModuleNotFoundError: No module named 'pandas'

检查：

ompfish

command -v python
python -c "import pandas as pd; print(pd.__version__)"

如果终端能导入，但 VS Code 不能，说明 VS Code 解释器没选 .venv/bin/python。

16.2 终端前面没有 `(.venv)`

先确认当前目录：

ompfish

pwd
ls

如果你在 ~/Code/python-learning 总目录，先进入具体项目：

ompfish

cd ~/Code/python-learning/week01-basics

fish 用户重新激活：

ompfish

source .venv/bin/activate.fish

bash / zsh 用户重新激活：

ompbash/zsh

source .venv/bin/activate

16.3 不知道当前在哪个目录

执行：

ompfish

pwd
ls

如果看不到 pyproject.toml，说明你不在项目根目录。

16.4 uv add 失败

先检查网络和当前目录：

ompfish

pwd
uv --version

确认在项目目录后再执行：

ompfish

uv add pandas

17. Week 01 验收清单

完成后你应该能做到：

能解释 .venv 是什么。
能用 uv add 安装包。
能在 VS Code 里选择 .venv/bin/python。
能运行 python src/hello.py。
能运行 pandas 示例。
能创建 notebook 并选择当前 kernel。
知道 .venv/ 不应该提交到 Git。
知道如何从终端进入项目目录。

18. 最小命令速查

18.1 创建项目

ompfish

mkdir -p ~/Code/python-learning/week01-basics
cd ~/Code/python-learning/week01-basics

18.2 初始化环境

ompfish

uv init
uv venv

18.3 激活环境

fish 用户执行：

ompfish

source .venv/bin/activate.fish

bash / zsh 用户才执行：

ompbash/zsh

source .venv/bin/activate

18.4 安装包

ompfish

uv add numpy pandas matplotlib jupyter ipykernel

18.5 打开 VS Code

ompfish

code .

18.6 运行脚本

ompfish

python src/hello.py

19. 和 20 周计划的关系

这篇文档对应 20 周 AI / 量化成长计划的：

ompprompt

Phase 1 / Week 01：环境与 Python 基础

完成本文后，你就可以进入下一步：

ompprompt

Week 01：Python 基础语法、函数、列表、字典、字符串、文件读写
Week 02：Python 进阶 + Linux 工作流
Week 03：NumPy / Pandas
Week 04：可视化 + EDA 报告

最终目标不是“装好了环境”，而是能持续产出可运行、可复现、可解释的小项目。

plain

Week 03：NumPy / Pandas 表格数据处理

Sat, 25 Jul 2026 19:00:00 GMT

Oh My Pi / weekly tutorial / week03-numpy-pandas

miku@cachyos:~/Code/python-learning$ omp teach week03-numpy-pandas --fish-first --step-by-step

source739 行教学文档

weekWeek 03

shellfish-first 命令版

backlink20 周计划

Week 03：NumPy / Pandas 表格数据处理

返回主线计划：USTC 统计学 AI / 量化 20 周成长计划

本文命令默认使用 fish shell。本周从“会写 Python 脚本”过渡到“能处理真实表格数据”。对统计学同学来说，NumPy / Pandas 是以后做统计建模、机器学习、时间序列、量化金融的共同地基。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	ndarray、DataFrame、缺失值、groupby、merge
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`notebooks/week03_pandas_eda.ipynb`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

import pandas as pd
df = pd.read_csv(“data/raw.csv”)
df.columns = [c.strip().lower().replace(” ”, ”_”) for c in df.columns]
missing = df.isna().sum().sort_values(ascending=False)
summary = df.groupby(“category”).agg(n=(“value”, “size”), mean_value=(“value”, “mean”))
print(missing)
print(summary)

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `notebooks/week03_pandas_eda.ipynb`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周目标

完成 Week 03 后，你应该能：

理解 NumPy array 和 Python list 的区别。
用 Pandas DataFrame 表示表格数据。
读取 CSV、查看数据结构、保存清洗后的 CSV。
识别和处理缺失值。
使用 groupby 做分组统计。
做一轮简单 EDA：行列数、字段类型、描述统计、缺失值、分组均值。
输出一个可复现的数据处理脚本和一份简短数据报告。

文件布局

建议本周交付物：

ompprompt

week03-numpy-pandas/
├── data/
│   ├── raw/
│   │   └── student_scores.csv
│   └── processed/
│       └── student_scores_clean.csv
├── notebooks/
│   └── week03_pandas_eda.ipynb
├── reports/
│   └── week03_data_report.md
├── src/
│   └── clean_scores.py
├── .venv/
├── pyproject.toml
└── README.md

Notebook 可以用来探索；脚本用来固定最终流程。以后项目展示时，脚本比“只保存在 notebook 里的零散代码”更容易复现。

2. 前置要求

你需要已经具备：

会在 fish 终端里 cd 到项目目录。
会使用 uv init、uv venv、uv add。
知道 list / dict / function 的基本用法。
能运行 uv run python script.py。
VS Code 可以打开项目目录。

检查基础命令：

ompfish

python --version
uv --version
pwd

如果 Python 或 uv 找不到，先回到 Week 01 环境搭建教程检查。

3. 创建 Week 03 项目

ompfish

mkdir -p ~/Code/python-learning/week03-numpy-pandas
cd ~/Code/python-learning/week03-numpy-pandas
mkdir -p src data/raw data/processed notebooks reports
uv init
uv venv
source .venv/bin/activate.fish
uv add numpy pandas
code .

解释：

命令	作用
`mkdir -p ~/Code/python-learning/week03-numpy-pandas`	创建本周项目目录
`mkdir -p src data/raw data/processed notebooks reports`	区分原始数据、清洗后数据、代码和报告
`uv init`	初始化 Python 项目配置
`uv venv`	创建 `.venv` 虚拟环境
`source .venv/bin/activate.fish`	fish 中激活虚拟环境
`uv add numpy pandas`	安装 NumPy 和 Pandas
`code .`	用 VS Code 打开当前项目

检查：

ompfish

which python
uv run python -c "import numpy, pandas; print(numpy.__version__); print(pandas.__version__)"

如果能打印版本号，环境可用。

4. 准备一个练习 CSV

先用小数据理解流程。创建 data/raw/student_scores.csv。

你可以在 VS Code 手动创建，也可以用 fish：

ompfish

printf 'student,major,gender,math,english,python,study_hours\nA,statistics,F,88,79,85,12\nB,statistics,M,92,81,90,14\nC,finance,F,75,86,78,9\nD,finance,M,80,,82,8\nE,statistics,F,95,88,,15\nF,computer,M,70,76,88,10\nG,computer,F,,90,91,11\nH,statistics,M,84,82,86,13\n' > data/raw/student_scores.csv

检查文件：

ompfish

head data/raw/student_scores.csv
wc -l data/raw/student_scores.csv

说明：

第一行是列名。
有些成绩故意留空，用来练习缺失值处理。
major 和 gender 是分类变量。
math、english、python、study_hours 是数值变量。

5. NumPy array 入门

NumPy 的核心对象是 array。它适合做数值计算，尤其是向量、矩阵、批量运算。

创建 src/numpy_intro.py：

omppython

import numpy as np
scores = np.array([88, 92, 75, 80, 95])
print(scores)
print(scores.mean())
print(scores.std())
print(scores >= 80)
print(scores[scores >= 80])

运行：

ompfish

uv run python src/numpy_intro.py

你会看到：

scores.mean() 计算均值。
scores.std() 计算标准差。
scores >= 80 返回布尔数组。
scores[scores >= 80] 用布尔条件筛选数组。

Python list 和 NumPy array 的一个重要区别：

omppython

python_list = [1, 2, 3]
numpy_array = np.array([1, 2, 3])
print(python_list * 2)
print(numpy_array * 2)

输出含义：

ompprompt

[1, 2, 3, 1, 2, 3]  # list 的 * 2 是重复
[2 4 6]             # array 的 * 2 是逐元素乘法

这就是为什么数据分析和机器学习大量使用 NumPy。

6. Pandas DataFrame 入门

Pandas 的核心对象是 DataFrame，可以理解为“带列名和索引的表格”。

创建 src/pandas_intro.py：

omppython

import pandas as pd
students = pd.DataFrame(
{
“student”: [“A”, “B”, “C”],
“major”: [“statistics”, “statistics”, “finance”],
“math”: [88, 92, 75],
“python”: [85, 90, 78],
}
)
print(students)
print(students[“math”])
print(students[[“student”, “python”]])
print(students[students[“math”] >= 80])

运行：

ompfish

uv run python src/pandas_intro.py

常见操作：

写法	作用
`df.head()`	查看前 5 行
`df.tail()`	查看后 5 行
`df.shape`	查看行数和列数
`df.columns`	查看列名
`df.dtypes`	查看每列数据类型
`df["math"]`	取单列，结果是 Series
`df[["math", "python"]]`	取多列，结果是 DataFrame
`df[df["math"] >= 80]`	按条件筛选行

7. 读取 CSV 并快速查看

创建 src/read_scores.py：

omppython

from pathlib import Path
import pandas as pd
path = Path(“data/raw/student_scores.csv”)
df = pd.read_csv(path)
print(“Shape:”, df.shape)
print(“Columns:”, list(df.columns))
print(“Head:”)
print(df.head())
print(“Data types:”)
print(df.dtypes)

运行：

ompfish

uv run python src/read_scores.py

解释：

代码	作用
`Path("data/raw/student_scores.csv")`	用 pathlib 表示路径
`pd.read_csv(path)`	读取 CSV 为 DataFrame
`df.shape`	输出 `(行数, 列数)`
`df.head()`	快速看前几行，确认读入正确
`df.dtypes`	判断数值列是否真的被识别为数值

读取真实数据后，第一步永远不是建模，而是看：

omppython

print(df.head())
print(df.info())
print(df.describe())

8. 缺失值检查

在数据分析里，缺失值不是小事。它会影响均值、相关性、模型训练和图表解释。

创建 src/missing_values.py：

omppython

from pathlib import Path
import pandas as pd
path = Path(“data/raw/student_scores.csv”)
df = pd.read_csv(path)
missing_by_column = df.isna().sum()
missing_total = int(df.isna().sum().sum())
missing_rate = df.isna().mean().sort_values(ascending=False)
print(“Missing values by column:”)
print(missing_by_column)
print(“Total missing values:”, missing_total)
print(“Missing rate:”)
print(missing_rate)

运行：

ompfish

uv run python src/missing_values.py

常用方法：

写法	作用
`df.isna()`	判断每个单元格是否缺失
`df.isna().sum()`	每列缺失数量
`df.isna().mean()`	每列缺失比例
`df.dropna()`	删除包含缺失值的行
`df.fillna(value)`	用指定值填补缺失

初学阶段可以使用简单策略：

数值成绩列：用该列均值或中位数填补。
分类列：用众数或 "unknown" 填补。
缺失太多的字段：在报告中说明，暂时不用于分析。

9. 清洗数据并保存 CSV

创建 src/clean_scores.py：

omppython

from pathlib import Path
import pandas as pd
RAW_PATH = Path(“data/raw/student_scores.csv”)
OUTPUT_PATH = Path(“data/processed/student_scores_clean.csv”)
NUMERIC_COLUMNS = [“math”, “english”, “python”, “study_hours”]
def load_data(path: Path) -> pd.DataFrame:
return pd.read_csv(path)
def clean_data(df: pd.DataFrame) -> pd.DataFrame:
cleaned = df.copy()
plain for column in NUMERIC_COLUMNS:
median_value = cleaned[column].median()
cleaned[column] = cleaned[column].fillna(median_value)
plain cleaned[“average_score”] = cleaned[[“math”, “english”, “python”]].mean(axis=1)
cleaned[“passed_python”] = cleaned[“python”] >= 80
plain return cleaned
def save_data(df: pd.DataFrame, path: Path) -> None:
path.parent.mkdir(parents=True, exist_ok=True)
df.to_csv(path, index=False)
def main() -> None:
df = load_data(RAW_PATH)
cleaned = clean_data(df)
save_data(cleaned, OUTPUT_PATH)
print(f”Saved cleaned data to {OUTPUT_PATH}”)
print(cleaned.head())
if name == “main”:
main()

运行：

ompfish

uv run python src/clean_scores.py
ls data/processed
head data/processed/student_scores_clean.csv

重点解释：

代码	作用
`cleaned = df.copy()`	不直接修改原始 DataFrame，保留原数据
`median()`	用中位数作为简单填补值，抗极端值能力比均值稍好
`fillna(median_value)`	填补缺失成绩
`mean(axis=1)`	对每一行计算平均分
`to_csv(..., index=False)`	保存 CSV 时不额外写入索引列

10. groupby 分组统计

groupby 是 Pandas 最重要的操作之一。统计学同学可以把它理解为：按某个分类变量分组，然后对每组计算统计量。

创建 src/groupby_scores.py：

omppython

from pathlib import Path
import pandas as pd
path = Path(“data/processed/student_scores_clean.csv”)
df = pd.read_csv(path)
major_summary = df.groupby(“major”)[[“math”, “english”, “python”, “average_score”]].mean()
gender_summary = df.groupby(“gender”)[“average_score”].agg([“count”, “mean”, “std”, “min”, “max”])
print(“Average scores by major:”)
print(major_summary)
print()
print(“Average score distribution by gender:”)
print(gender_summary)

运行：

ompfish

uv run python src/groupby_scores.py

解释：

写法	含义
`df.groupby("major")`	按专业分组
`[["math", "english"]]`	选择要统计的列
`.mean()`	对每组求均值
`.agg(["count", "mean", "std"])`	一次计算多个统计量

注意：分组统计是观察，不是因果结论。比如某专业平均分更高，不能直接说“专业导致成绩更高”，还要考虑样本量、选课背景、数据来源等。

11. merge 简介

计划里提到 merge。本周先理解它的用途：把两张表按共同键合并。

创建 data/raw/major_info.csv：

ompfish

printf 'major,school\nstatistics,School of Management\nfinance,School of Management\ncomputer,School of Computer Science\n' > data/raw/major_info.csv

创建 src/merge_intro.py：

omppython

from pathlib import Path
import pandas as pd
scores = pd.read_csv(Path(“data/processed/student_scores_clean.csv”))
major_info = pd.read_csv(Path(“data/raw/major_info.csv”))
merged = scores.merge(major_info, on=“major”, how=“left”)
print(merged[[“student”, “major”, “school”, “average_score”]])

运行：

ompfish

uv run python src/merge_intro.py

常见合并方式：

参数	含义
`on="major"`	两张表都用 `major` 列作为键
`how="left"`	保留左表所有行，右表匹配不到则为缺失
`how="inner"`	只保留两边都匹配到的行

12. 时间索引简介

时间序列和量化金融会大量使用时间索引。本周先学会把日期列转成时间类型并设为索引。

创建 data/raw/daily_price.csv：

ompfish

printf 'date,close,volume\n2026-07-20,10.2,1200\n2026-07-21,10.5,1500\n2026-07-22,10.1,1100\n2026-07-23,10.8,1800\n' > data/raw/daily_price.csv

创建 src/time_index_intro.py：

omppython

from pathlib import Path
import pandas as pd
price = pd.read_csv(Path(“data/raw/daily_price.csv”))
price[“date”] = pd.to_datetime(price[“date”])
price = price.set_index(“date”)
price[“daily_return”] = price[“close”].pct_change()
print(price)
print(price.loc[“2026-07-21”:“2026-07-23”])

运行：

ompfish

uv run python src/time_index_intro.py

重点：

pd.to_datetime 把字符串日期转成时间类型。
set_index("date") 把日期作为索引。
pct_change() 计算相邻时期的变化率，是量化和时间序列的常见起点。

13. 简单 EDA 脚本

创建 src/simple_eda.py，把常用检查固定下来：

omppython

from pathlib import Path
import pandas as pd
path = Path(“data/processed/student_scores_clean.csv”)
df = pd.read_csv(path)
print(“1. Shape”)
print(df.shape)
print()
print(“2. Columns”)
print(list(df.columns))
print()
print(“3. Data types”)
print(df.dtypes)
print()
print(“4. Missing values”)
print(df.isna().sum())
print()
print(“5. Descriptive statistics”)
print(df.describe())
print()
print(“6. Group summary by major”)
print(df.groupby(“major”)[“average_score”].agg([“count”, “mean”, “std”, “min”, “max”]))

运行：

ompfish

uv run python src/simple_eda.py

这份输出可以直接作为 reports/week03_data_report.md 的素材。

14. Notebook vs script：怎么选

本周计划的交付物包含 notebook，但你也应该保留脚本。

工具	适合做什么	不适合做什么
Notebook	逐步探索、看表格、尝试图表、写观察	长期维护的完整清洗流程
Script	固化流程、复现结果、命令行运行、Git diff 清楚	交互式尝试和即时展示

推荐工作方式：

ompprompt

1. 在 notebook 中探索：看字段、缺失值、分布、分组统计。
2. 把确认有效的步骤整理到 src/clean_scores.py。
3. 用 src/simple_eda.py 输出稳定统计结果。
4. 在 reports/week03_data_report.md 写结论。

如果使用 VS Code Notebook：

ompfish

uv add ipykernel

然后在 VS Code 中新建 notebooks/week03_pandas_eda.ipynb，选择当前 .venv 作为 kernel。

15. 报告结构 `reports/week03_data_report.md`

在 VS Code 创建报告文件，建议结构：

ompmarkdown

# Week 03 数据处理报告 1. 数据来源说明数据来自练习 CSV，字段包含学生、专业、性别、数学、英语、Python、学习时长。 2. 数据规模原始数据行数：8 原始数据列数：7 清洗后数据行数：8 清洗后数据列数：9 3. 缺失值处理说明哪些列有缺失值，以及使用中位数填补数值列。 4. 描述统计摘录 df.describe() 中重要结果，例如各科均值、标准差、最小值、最大值。 5. 分组统计按 major 比较 average_score，注意样本很小，只能作为练习观察。 6. 下一步

Week 04 将对清洗后的数据做可视化，生成直方图、散点图、箱线图和相关性热力图。

报告应该写“观察到了什么”和“不能过度解释什么”。这是统计学训练的一部分。

16. 本周练习

练习 A：NumPy 基础

创建 src/numpy_exercises.py：

创建数组 [1, 2, 3, 4, 5]。
计算均值、标准差、最大值、最小值。
筛选出大于 3 的元素。
创建一个 2 行 3 列矩阵，并计算每列均值。

运行：

ompfish

uv run python src/numpy_exercises.py

练习 B：Pandas 筛选

在 student_scores_clean.csv 中筛选：

major == "statistics" 的学生。
python >= 85 的学生。
study_hours >= 12 且 average_score >= 85 的学生。

练习 C：缺失值策略比较

分别尝试：

删除缺失值行。
用均值填补。
用中位数填补。

比较每种策略下 average_score 的均值是否变化。

练习 D：分组统计

按 major 和 gender 分组，计算：

样本数。
average_score 均值。
python 均值。

提示：可以使用：

omppython

df.groupby(["major", "gender"])[["average_score", "python"]].mean()

17. 验收检查

在项目根目录执行：

ompfish

pwd
ls
source .venv/bin/activate.fish
uv run python -c "import numpy, pandas; print('ok')"
uv run python src/clean_scores.py
uv run python src/simple_eda.py
ls data/processed
head data/processed/student_scores_clean.csv

验收标准：

当前目录是 week03-numpy-pandas。
source .venv/bin/activate.fish 不报错。
NumPy / Pandas 能成功 import。
src/clean_scores.py 能生成 data/processed/student_scores_clean.csv。
src/simple_eda.py 能输出 shape、columns、dtypes、missing values、describe、groupby。
报告 reports/week03_data_report.md 能解释数据来源、缺失值处理、描述统计和分组统计。

18. 常见错误

错误 1：`ModuleNotFoundError: No module named 'pandas'`

说明当前环境没有 pandas，或运行时没有使用 uv 项目环境。

修复：

ompfish

cd ~/Code/python-learning/week03-numpy-pandas
uv add pandas numpy
uv run python src/read_scores.py

错误 2：`FileNotFoundError: data/raw/student_scores.csv`

多数情况是当前目录错了。

检查：

ompfish

pwd
ls data/raw

如果不在项目根目录，执行：

ompfish

cd ~/Code/python-learning/week03-numpy-pandas

错误 3：保存 CSV 后多了一列 `Unnamed: 0`

原因：保存时把 DataFrame 索引也写进 CSV。

修复：

omppython

df.to_csv(path, index=False)

错误 4：均值计算报错或结果奇怪

原因可能是数字列被读成字符串，或者包含非数字符号。

检查：

omppython

print(df.dtypes)

必要时转换：

omppython

df["math"] = pd.to_numeric(df["math"], errors="coerce")

errors="coerce" 会把无法转换的值变成缺失值，然后再统一处理。

错误 5：Notebook 找不到当前虚拟环境

先安装 kernel 支持：

ompfish

uv add ipykernel

然后在 VS Code Notebook 右上角选择当前项目 .venv 对应的 Python kernel。

19. 下一步

Week 04 会把本周清洗后的表格数据转成可读图表：直方图看分布，散点图看关系，箱线图看组间差异，相关性热力图看变量关联。最终目标是写出一份结构清楚的 EDA 报告，而不是只生成几张图片。

plain

Week 02：Python 进阶 + Linux 工作流

Sat, 25 Jul 2026 18:00:00 GMT

Oh My Pi / weekly tutorial / week02-python-linux-workflow

miku@cachyos:~/Code/python-learning$ omp teach week02-python-linux-workflow --fish-first --step-by-step

source791 行教学文档

weekWeek 02

shellfish-first 命令版

backlink20 周计划

Week 02：Python 进阶 + Linux 工作流

返回主线计划：USTC 统计学 AI / 量化 20 周成长计划

本文命令默认使用 fish shell。如果你在 VS Code 终端里看到的不是 fish，可以先执行 fish 进入 fish；后续不再重复说明。目标不是把 Linux 背熟，而是把“写脚本、运行脚本、查看结果、提交 Git”变成稳定流程。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	list/dict、模块、异常、argparse、pathlib、Git commit
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`src/data_summary.py`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

from argparse import ArgumentParser
from pathlib import Path
parser = ArgumentParser()
parser.add_argument(“—input”, required=True)
args = parser.parse_args()
path = Path(args.input)
if not path.exists():
raise SystemExit(f”missing input: {path}”)
print(path.read_text(encoding=“utf-8”)[
])

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `src/data_summary.py`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 本周目标

完成 Week 02 后，你应该能独立做到：

用 list comprehension / dict comprehension 写简洁的数据转换代码。
把重复逻辑封装成函数，而不是把所有代码堆在一个文件里。
用 pathlib 处理文件路径，避免手动拼接字符串路径。
写一个可从命令行运行的 CSV 汇总脚本 src/data_summary.py。
在 fish 终端里完成目录导航、文件检查、uv run 运行、Git status/add/commit。

文件布局

本周交付物建议放在：

ompprompt

week02-python-linux-workflow/
├── data/
│   └── scores.csv
├── notes/
│   └── week02-linux-git.md
├── src/
│   └── data_summary.py
├── .venv/
├── pyproject.toml
└── README.md

2. 前置要求

你需要已经完成 Week 01 的基础环境：

CachyOS / Arch 系 Linux 可正常打开终端。
VS Code 已安装，并能用 code . 打开当前目录。
uv 已安装。
Git 可用：git --version 能输出版本号。
知道 Python 基础变量、列表、字典、for 循环、if 判断。

先检查工具：

ompfish

python --version
uv --version
git --version
pwd

解释：

命令	作用
`python --version`	查看当前终端能找到的 Python 版本
`uv --version`	确认 uv 可用
`git --version`	确认 Git 可用
`pwd`	打印当前位置，避免在错误目录创建项目

3. 创建 Week 02 项目目录

建议每周一个独立项目，这样 Git 提交、依赖和报告都清楚。

ompfish

mkdir -p ~/Code/python-learning/week02-python-linux-workflow
cd ~/Code/python-learning/week02-python-linux-workflow
mkdir -p src data notes reports
code .

逐句解释：

命令	含义
`mkdir -p ...`	创建目录；如果上级目录不存在就一起创建
`cd ...`	进入 Week 02 项目目录
`mkdir -p src data notes reports`	创建源码、数据、笔记、报告目录
`code .`	用 VS Code 打开当前项目

检查当前结构：

ompfish

pwd
ls

你应该看到类似：

ompprompt

data  notes  reports  src

4. 初始化 uv 项目和虚拟环境

在项目根目录执行：

ompfish

uv init
uv venv
source .venv/bin/activate.fish

解释：

命令	作用
`uv init`	生成 `pyproject.toml`、`README.md`、示例入口文件
`uv venv`	创建当前项目专用虚拟环境 `.venv/`
`source .venv/bin/activate.fish`	在 fish shell 中激活虚拟环境

激活后检查：

ompfish

which python
python --version

如果 which python 输出路径包含当前项目的 .venv/bin/python，说明环境正确。

fish 注意：不要在 fish 里执行 Bash / Zsh 版本的虚拟环境激活脚本；fish 应使用 source .venv/bin/activate.fish。

本周需要 pandas 来读 CSV：

ompfish

uv add pandas

之后运行脚本时优先使用：

ompfish

uv run python src/data_summary.py --help

uv run 会自动使用项目环境，比“碰运气使用系统 Python”更稳。

5. fish 终端导航：从“知道在哪”开始

Linux 工作流第一件事不是命令多，而是永远知道自己在什么目录。

ompfish

pwd
ls
cd src
pwd
cd ..
ls data

解释：

命令	作用
`pwd`	打印当前目录
`ls`	列出当前目录文件
`cd src`	进入 `src` 子目录
`cd ..`	回到上一级目录
`ls data`	不进入 `data`，直接查看它里面有什么

常用路径写法：

写法	含义
`.`	当前目录
`..`	上一级目录
`~`	当前用户主目录，例如 `/home/miku`
`~/Code`	主目录下的 `Code` 文件夹
`src/data_summary.py`	当前目录下的相对路径

建议养成习惯：运行任何脚本前先看一眼：

ompfish

pwd
ls

如果当前目录不是项目根目录，先 cd 回来：

ompfish

cd ~/Code/python-learning/week02-python-linux-workflow

6. 创建练习 CSV 数据

可以先用 VS Code 新建 data/scores.csv，内容如下：

ompcsv

student,major,math,english,python
A,statistics,88,79,85
B,statistics,92,81,90
C,finance,75,86,78
D,finance,80,,82
E,statistics,95,88,

如果想用 fish 命令创建，也可以执行：

ompfish

printf 'student,major,math,english,python\nA,statistics,88,79,85\nB,statistics,92,81,90\nC,finance,75,86,78\nD,finance,80,,82\nE,statistics,95,88,\n' > data/scores.csv

检查文件：

ompfish

cat data/scores.csv
wc -l data/scores.csv

解释：

命令	作用
`cat`	把整个小文件打印出来，适合查看短文件
`wc -l`	统计行数；CSV 第一行表头也算一行

真实数据通常不建议用 cat 一次打印几万行。可以用：

ompfish

head data/scores.csv
tail data/scores.csv

head 看开头，tail 看结尾。

7. Python 进阶一：list comprehension

list comprehension 适合把“循环生成新列表”的代码写得更清楚。

普通写法：

omppython

scores = [88, 92, 75, 80, 95]
passed = []
for score in scores:
if score >= 80:
passed.append(score)
print(passed)

list comprehension 写法：

omppython

scores = [88, 92, 75, 80, 95]
passed = [score for score in scores if score >= 80]
print(passed)

读法是：

ompprompt

[要放进新列表的值 for 临时变量 in 原列表 if 条件]

常见例子：

omppython

names = ["alice", "bob", "cathy"]
upper_names = [name.upper() for name in names]
scores = [88, 92, 75, 80, 95]
labels = [“pass” if score >= 80 else “review” for score in scores]
raw_values = [“88”, “92”, "", “80”]
clean_values = [int(value) for value in raw_values if value != ""]

注意：不要为了炫技把太复杂的逻辑塞进一行。如果一行里同时有多层循环、多层条件，普通 for 循环更适合。

8. Python 进阶二：dict comprehension

dict comprehension 用来从已有数据生成字典。

omppython

names = ["math", "english", "python"]
scores = [88, 79, 85]
score_dict = {name: score for name, score in zip(names, scores)}
print(score_dict)

输出：

ompprompt

{'math': 88, 'english': 79, 'python': 85}

筛选字典：

omppython

score_dict = {"math": 88, "english": 79, "python": 85}
high_scores = {subject: score for subject, score in score_dict.items() if score >= 80}
print(high_scores)

输出：

ompprompt

{'math': 88, 'python': 85}

在数据分析脚本中，dict comprehension 常用于生成摘要结果：

omppython

missing_counts = {column: 0 for column in ["math", "english", "python"]}

9. Python 进阶三：函数

函数的作用是把一段有明确职责的逻辑命名，方便重复使用和测试。

不推荐把所有逻辑写成这样：

omppython

import pandas as pd
df = pd.read_csv(“data/scores.csv”)
print(df.shape)
print(df.isna().sum())
print(df.mean(numeric_only=True))

更推荐拆成函数：

omppython

from pathlib import Path
import pandas as pd
def load_csv(path: Path) -> pd.DataFrame:
return pd.read_csv(path)
def summarize(df: pd.DataFrame) -> dict:
return {
“rows”: len(df),
“columns”: len(df.columns),
“missing_values”: int(df.isna().sum().sum()),
“numeric_means”: df.mean(numeric_only=True).to_dict(),
}

判断函数是否清楚，可以问三个问题：

函数名是否说明它做什么？
输入参数是否明确？
返回值是否明确？

对初学者来说，函数不需要一开始写得很抽象。先把“读取数据”“计算摘要”“打印摘要”拆开，就已经很好。

10. Python 进阶四：pathlib

pathlib 是 Python 处理路径的现代方式。

不要这样手动拼路径：

omppython

path = "data" + "/" + "scores.csv"

推荐这样：

omppython

from pathlib import Path
project_root = Path.cwd()
data_path = project_root / “data” / “scores.csv”
print(data_path)

常用方法：

写法	作用
`Path.cwd()`	当前运行命令的目录
`Path("data/scores.csv")`	创建相对路径对象
`path.exists()`	判断路径是否存在
`path.parent`	获取父目录
`path.name`	获取文件名
`path.suffix`	获取扩展名，例如 `.csv`

在 CLI 脚本里，用户传入的路径建议立刻转成 Path：

omppython

csv_path = Path(args.csv)

11. 编写 CLI 脚本 `src/data_summary.py`

在 VS Code 中创建文件：

ompprompt

src/data_summary.py

写入下面代码：

omppython

from argparse import ArgumentParser
from pathlib import Path
import pandas as pd
def parse_args():
parser = ArgumentParser(description=“Summarize a CSV file.”)
parser.add_argument(“csv”, help=“Path to the input CSV file”)
return parser.parse_args()
def load_csv(path: Path) -> pd.DataFrame:
if not path.exists():
raise FileNotFoundError(f”CSV file not found: {path}”)
if path.suffix.lower() != “.csv”:
raise ValueError(f”Expected a .csv file, got: {path}”)
return pd.read_csv(path)
def build_summary(df: pd.DataFrame) -> dict:
numeric_means = df.mean(numeric_only=True).to_dict()
return {
“rows”: len(df),
“columns”: len(df.columns),
“missing_values”: int(df.isna().sum().sum()),
“numeric_means”: numeric_means,
}
def print_summary(summary: dict) -> None:
print(“CSV Summary”)
print(”===========”)
print(f”Rows: {summary[‘rows’]}”)
print(f”Columns: {summary[‘columns’]}”)
print(f”Missing values: {summary[‘missing_values’]}”)
print(“Numeric column means:”)
plain for column, value in summary[“numeric_means”].items():
print(f”- {column}: {value:.2f}”)
def main() -> None:
args = parse_args()
csv_path = Path(args.csv)
df = load_csv(csv_path)
summary = build_summary(df)
print_summary(summary)
if name == “main”:
main()

这段脚本分成四层：

函数	职责
`parse_args`	读取命令行参数
`load_csv`	检查路径并读取 CSV
`build_summary`	计算行数、列数、缺失值、均值
`print_summary`	把结果打印给用户
`main`	串起完整流程

12. 运行 CLI 脚本

先看帮助：

ompfish

uv run python src/data_summary.py --help

你应该看到脚本说明和参数说明。

再运行实际数据：

ompfish

uv run python src/data_summary.py data/scores.csv

期望输出类似：

ompprompt

CSV Summary
===========
Rows: 5
Columns: 5
Missing values: 2
Numeric column means:
- math: 86.00
- english: 83.50
- python: 83.75

如果你已经激活虚拟环境，也可以运行：

ompfish

python src/data_summary.py data/scores.csv

但为了可复现，本教程更推荐在说明文档里写 uv run python ...。

13. 常用 Linux 文件检查命令

本周不要求成为 Linux 专家，但这些命令会反复出现。

ompfish

pwd
ls
cat data/scores.csv
head data/scores.csv
tail data/scores.csv
wc -l data/scores.csv
grep statistics data/scores.csv

解释：

命令	适合场景
`pwd`	确认当前目录
`ls`	看目录内容
`cat`	查看很短的小文件
`head`	查看文件开头
`tail`	查看文件结尾
`wc -l`	统计行数
`grep statistics ...`	找包含 `statistics` 的行

复制、移动、删除文件要更谨慎：

ompfish

cp data/scores.csv data/scores_backup.csv
mv data/scores_backup.csv data/scores_copy.csv
rm data/scores_copy.csv

解释：

命令	作用	风险
`cp`	复制文件	可能覆盖同名文件
`mv`	移动或重命名文件	可能把文件移到意外位置
`rm`	删除文件	删除后通常不能轻松恢复

初学阶段，执行 rm 前先 ls 确认目标。

14. Git 基础：status / add / commit

在项目根目录初始化 Git：

ompfish

git init
git status

git status 是最重要的 Git 命令之一。任何不确定的时候先运行它。

建议创建 .gitignore，避免把虚拟环境提交进去。在 VS Code 新建 .gitignore，写入：

ompprompt

.venv/
__pycache__/
.ipynb_checkpoints/
*.pyc

再次检查：

ompfish

git status

把本周文件加入暂存区：

ompfish

git add pyproject.toml uv.lock README.md .gitignore src data notes
git status

如果某个文件不存在，Git 会提示 pathspec 错误。可以先用 ls 看实际文件，再重新 git add 存在的文件。

提交：

ompfish

git commit -m "Add week02 Python Linux workflow exercise"

提交后检查：

ompfish

git status
git log --oneline -3

期望看到：

ompprompt

nothing to commit, working tree clean

以及最近提交列表中包含你的提交信息。

15. 写学习笔记 `notes/week02-linux-git.md`

在 VS Code 创建：

ompprompt

notes/week02-linux-git.md

建议包含四块：

ompmarkdown

# Week 02 Linux + Git 笔记
今天学会的命令

pwd：查看当前目录
ls：查看文件
cd：切换目录
uv run：用项目环境运行 Python
git status：查看 Git 状态

今天写的脚本

src/data_summary.py：读取 CSV，输出行数、列数、缺失值、数值列均值。

遇到的问题

问题：fish 中误用了 Bash 激活脚本。
解决：使用 source .venv/bin/activate.fish。

下次要改进

给脚本增加输出到 Markdown 文件的功能。

笔记不是为了凑字数，而是为了让两周后的你能复盘：当时怎么跑、哪里报错、怎么修。

16. 本周练习

练习 A：list comprehension

创建 src/comprehension_practice.py，完成：

给定分数列表 [58, 72, 81, 90, 45, 66]，生成及格分数列表。
生成所有分数的平方列表。
把名字列表 ['alice', 'bob', 'cathy'] 转成首字母大写。

运行：

ompfish

uv run python src/comprehension_practice.py

练习 B：dict comprehension

创建科目到分数的字典：

omppython

subjects = ["math", "english", "python"]
scores = [88, 79, 85]

要求生成：

ompprompt

{'math': 88, 'english': 79, 'python': 85}

再筛选出分数大于等于 80 的科目。

练习 C：增强 `data_summary.py`

给脚本增加一个可选参数：

ompfish

uv run python src/data_summary.py data/scores.csv --show-columns

当用户传入 --show-columns 时，额外打印列名。

提示：在 parse_args() 中增加：

omppython

parser.add_argument("--show-columns", action="store_true", help="Show CSV column names")

练习 D：Git 小循环

每完成一个小改动，就练习一次：

ompfish

git status
git add src/data_summary.py
git commit -m "Improve data summary script"
git status

重点不是提交很多次，而是理解：工作区、暂存区、提交记录分别是什么。

17. 验收检查

在 Week 02 项目根目录执行：

ompfish

pwd
ls
source .venv/bin/activate.fish
uv run python src/data_summary.py --help
uv run python src/data_summary.py data/scores.csv
git status

你应能确认：

pwd 位于 week02-python-linux-workflow 项目目录。
ls 能看到 src、data、notes、pyproject.toml。
source .venv/bin/activate.fish 不报错。
uv run python src/data_summary.py --help 能显示帮助。
uv run python src/data_summary.py data/scores.csv 能输出行数、列数、缺失值数量、数值列均值。
git status 能解释当前哪些文件未提交，或显示工作区干净。

18. 常见错误

错误 1：fish 中激活环境报语法错误

错误原因：执行了 Bash / Zsh 激活脚本。

fish 正确命令：

ompfish

source .venv/bin/activate.fish

错误 2：`ModuleNotFoundError: No module named 'pandas'`

原因：当前环境没有安装 pandas，或没有使用项目环境运行。

修复：

ompfish

cd ~/Code/python-learning/week02-python-linux-workflow
uv add pandas
uv run python src/data_summary.py data/scores.csv

错误 3：`CSV file not found`

原因：路径相对于当前目录解释，你可能不在项目根目录。

检查：

ompfish

pwd
ls data

如果 data/scores.csv 不存在，就回到正确目录或重新创建文件。

错误 4：Git 把 `.venv/` 也显示为待提交

原因：忘记写 .gitignore。

修复：

ompfish

printf '.venv/\n__pycache__/\n.ipynb_checkpoints/\n*.pyc\n' > .gitignore
git status

如果 .venv/ 已经被 git add，先取消暂存：

ompfish

git restore --staged .venv

错误 5：`git commit` 提示身份未知

Git 第一次提交可能要求配置姓名和邮箱。用你的真实或常用学习身份配置：

ompfish

git config --global user.name "Miku"
git config --global user.email "miku@example.com"

然后重新提交。

19. 下一步

下一周进入 NumPy / Pandas。你会把本周的“能读 CSV 并打印摘要”升级成真正的数据处理流程：读取真实表格、处理缺失值、做分组统计、保存清洗后的数据，并为 Week 04 的 EDA 报告准备数据基础。

plain

🔒 USTC 统计学：AI / Quant 全栈终端式练习手册

Sat, 25 Jul 2026 18:00:00 GMT

此文章已加密，请在网页中查看

Week 01：CachyOS Python 环境与基础语法

Sat, 25 Jul 2026 17:00:00 GMT

Oh My Pi / weekly tutorial / week01-python-environment-basics

miku@cachyos:~/Code/python-learning$ omp teach week01-python-environment-basics --fish-first --step-by-step

source780 行教学文档

weekWeek 01

shellfish-first 命令版

backlink20 周计划

Week 01：CachyOS Python 环境与基础语法

适用对象：已经安装 VS Code，正在用 CachyOS / Arch 系 Linux，准备按 20 周 AI / 量化成长计划开始 Week 01：环境与 Python 基础。

本教程采用：

ompprompt

VS Code 负责：写代码、看文件、运行脚本、调试、使用 notebook
uv 负责：创建虚拟环境、安装依赖、记录项目配置
终端负责：创建目录、激活环境、运行命令、检查结果

本文命令行默认按 fish shell 写；如果某一步需要 Bash / Zsh，会单独标注。

当前机器已经具备：

ompprompt

Python 3.14.6
uv 0.11.31
VS Code 1.130.0

因此不需要从零安装 Python，直接建立学习环境即可。

0. 本周详细教学：语法、规范、验收

本节不是追加在尾部的复习，而是本周正文的入口。先读这里，再做后面的命令和项目。

0.1 本周真正要学会什么

维度	要求
知识点	变量、字符串、列表、函数、文件读写
代码语法	能从空文件写出本周核心脚本，而不是只复制运行
程序规范	函数拆分、路径清楚、输入输出明确、错误能解释
交付物	`src/week01_basic.py`
验收方式	从 fish 终端运行命令，得到可复查的文件或指标

0.2 代码语法精讲

下面的代码不是最终答案，而是本周必须理解的最小骨架：

omppython

def mean(xs):
    if not xs:
        raise ValueError("xs must not be empty")
    return sum(xs) / len(xs)
with open(“data/numbers.txt”, “w”, encoding=“utf-8”) as f:
f.write(“1\n2\n3\n”)
with open(“data/numbers.txt”, encoding=“utf-8”) as f:
nums = [float(line.strip()) for line in f if line.strip()]
print(mean(nums))

读代码时按四步检查：输入从哪里来；中间变量的类型和 shape 是什么；函数或脚本输出什么；哪些错误应该显式报出来。

0.3 本周程序规范

所有路径用相对路径或 `pathlib.Path`，不要写死 `/home/miku/...`。
核心逻辑进 `src/`，notebook 只做探索和解释。
每个脚本能从 fish 终端运行，并在 README 写出命令。
输出必须落盘到 `reports/`、`figures/` 或 `outputs/`，不能只在屏幕上看。

0.4 本周练习分层

层级	任务	不合格表现	合格验收
最小练习	手写上面的最小骨架	只在 notebook 里运行	终端运行成功
标准练习	把逻辑拆成函数/模块	一个大脚本从头写到尾	至少 2 个函数，职责清楚
项目练习	生成本周交付物 `src/week01_basic.py`	只有屏幕输出	文件落盘，可复查
复盘练习	写 3 个错误和修复	只写“已解决”	写清报错、原因、修复、预防

0.5 本周和主线的连接

回到总计划：USTC AI / Quant 练习手册
查详细练习索引：技术练习详解
查质量评分：最终质量门槛

1. 为什么不能完全不用命令行

你不需要成为 Linux 高手，但不能完全绕开命令行。

原因有四个：

环境隔离需要命令：每个项目应有自己的 .venv，避免不同项目的包互相污染。
安装包需要命令：例如 numpy、pandas、matplotlib、scikit-learn。
复现实验需要命令：以后别人看你的项目，需要知道如何一键安装依赖并运行。
Git 和部署需要命令：提交代码、查看状态、解决冲突，迟早会用到。

最低限度只需要会这些：

ompfish

pwd        # 看当前在哪个目录
ls         # 看当前目录有什么文件
cd         # 进入目录
mkdir      # 创建文件夹
code .     # 用 VS Code 打开当前目录
uv init    # 初始化 Python 项目
uv venv    # 创建虚拟环境
uv add     # 安装依赖
python     # 运行 Python

2. 建立统一学习目录

先给未来 20 周的学习项目留一个统一位置。

打开终端，执行：

ompfish

mkdir -p ~/Code/python-learning
cd ~/Code/python-learning
pwd

逐句解释：

命令	含义
`mkdir`	创建文件夹
`-p`	如果上级目录不存在，就一起创建；如果目录已存在，也不要报错
`~/Code/python-learning`	你的 Python 学习总目录，`~` 表示当前用户主目录
`cd`	进入这个目录
`pwd`	打印当前所在路径，用来确认你没有走错目录

如果输出类似：

ompprompt

/home/miku/Code/python-learning

说明位置正确。

3. 创建第一个 Week 01 项目

每周一个小项目，不要把所有练习都堆在一个文件夹里。

ompfish

mkdir week01-basics
cd week01-basics

建议结构：

ompprompt

week01-basics/
├── notes/       # 学习笔记
├── src/         # Python 源代码
├── data/        # 小数据文件
├── notebooks/   # Jupyter notebook
└── reports/     # 报告或总结

创建这些目录：

ompfish

mkdir -p notes src data notebooks reports

检查：

ompfish

ls

应该看到：

ompprompt

data  notebooks  notes  reports  src

4. 初始化 Python 项目

在 week01-basics 目录里执行：

ompfish

uv init

这一步会生成项目配置文件，通常包括：

ompprompt

pyproject.toml
README.md
main.py

解释：

文件	作用
`pyproject.toml`	记录项目名称、Python 版本、依赖包
`README.md`	项目说明，未来给老师、面试官或自己回看
`main.py`	默认入口脚本，可以改也可以删除

如果 uv init 提示文件已存在，不用慌，说明当前目录里已经有项目文件。

5. 创建虚拟环境 `.venv`

执行：

ompfish

uv venv

它会创建：

ompprompt

.venv/

.venv 是这个项目自己的 Python 环境。以后这个项目安装的包都放在里面，不污染系统 Python。

为什么重要：

ompprompt

系统 Python：给操作系统和系统工具用
项目 .venv：给当前学习项目用

不要把所有包直接装进系统 Python。CachyOS / Arch 是滚动发行版，系统 Python 更应该保持干净。

6. 激活虚拟环境

先确认你在真正的项目目录里，而不是只在总目录 ~/Code/python-learning 里：

ompfish

pwd
ls

如果你按本文创建的是 week01-basics 项目，那么应先进入：

ompfish

cd ~/Code/python-learning/week01-basics

6.1 如果你使用 fish shell

你现在遇到的报错就是 fish shell 把 Bash 版激活脚本当成 fish 脚本执行了。

fish 里应执行：

ompfish

source .venv/bin/activate.fish

不要在 fish 里执行：

ompprompt

Bash/Zsh activate 脚本

.venv/bin/activate 是给 Bash / Zsh 用的，里面有 变量=值 这种语法；fish 不支持这种写法，所以会报：

ompprompt

不支持使用 '='

6.2 如果你使用 bash 或 zsh

Bash / Zsh 才使用：

ompprompt

Bash/Zsh activate 脚本

6.3 激活成功后的检查

成功后，终端提示符前面通常会出现：

ompprompt

(.venv)

这表示当前终端已经进入项目环境。

验证 Python 路径：

ompfish

command -v python
python --version

你希望看到的 command -v python 应该类似：

ompprompt

/home/miku/Code/python-learning/week01-basics/.venv/bin/python

如果看到的是 /usr/bin/python，说明虚拟环境没有激活成功，或者你不在创建 .venv 的项目目录里。

7. 安装第一批学习包

Week 01 到 Week 04 建议安装：

ompfish

uv add numpy pandas matplotlib jupyter ipykernel

逐个解释：

包	用途
`numpy`	数值计算，数组、矩阵、随机数
`pandas`	表格数据处理，CSV、DataFrame
`matplotlib`	基础画图
`jupyter`	notebook 环境
`ipykernel`	让 VS Code / Jupyter 使用当前虚拟环境

安装完成后，pyproject.toml 会记录这些依赖。以后别人拿到你的项目，可以根据配置恢复环境。

8. 用 VS Code 打开项目

确认你还在项目目录：

ompfish

pwd

然后执行：

ompfish

code .

含义：用 VS Code 打开当前目录。

不要只打开单个 .py 文件，应该打开整个项目文件夹。这样 VS Code 才能识别 .venv、pyproject.toml、目录结构和相对路径。

9. 在 VS Code 里选择 Python 解释器

打开 VS Code 后：

按 Ctrl + Shift + P。
输入 Python: Select Interpreter。
选择当前项目的解释器：

ompprompt

.venv/bin/python

如果列表里没看到，可以手动选择：

ompprompt

/home/miku/Code/python-learning/week01-basics/.venv/bin/python

这一步的意义：告诉 VS Code 使用当前项目环境，而不是系统 Python。

10. 写第一个脚本

在 src/ 下新建文件：

ompprompt

src/hello.py

内容：

omppython

print("Hello, Python")
scores = [85, 92, 78]
mean_score = sum(scores) / len(scores)
print(mean_score)

用终端运行：

ompfish

python src/hello.py

应该输出：

ompprompt

Hello, Python
85.0

如果 VS Code 右上角运行按钮也能跑出同样结果，说明解释器配置正确。

11. 写第一个 pandas 练习

新建：

ompprompt

src/pandas_demo.py

内容：

omppython

import pandas as pd
data = {
“name”: [“Alice”, “Bob”, “Cindy”],
“score”: [85, 92, 78],
}
df = pd.DataFrame(data)
print(df)
print(“mean score:”, df[“score”].mean())

运行：

ompfish

python src/pandas_demo.py

如果能看到表格和平均分，说明：

ompprompt

Python 能运行
pandas 已安装
VS Code 项目路径正确
虚拟环境可用

12. 建立 notebook

在 VS Code 里新建：

ompprompt

notebooks/week01.ipynb

第一次打开 notebook 时，右上角选择 Kernel：

ompprompt

.venv/bin/python

新建一个 cell：

omppython

import pandas as pd
pd.DataFrame({“x”: [1, 2, 3], “y”: [2, 4, 6]})

如果表格正常显示，notebook 环境配置成功。

13. 推荐项目结构

Week 01 最终建议变成：

ompprompt

week01-basics/
├── .venv/
├── data/
│   └── scores.csv
├── notebooks/
│   └── week01.ipynb
├── notes/
│   └── week01-python.md
├── reports/
│   └── week01-summary.md
├── src/
│   ├── hello.py
│   └── pandas_demo.py
├── pyproject.toml
├── README.md
└── uv.lock

其中：

路径	说明
`.venv/`	虚拟环境，不手动编辑，不提交到 Git
`data/`	小数据文件
`notebooks/`	交互式分析
`notes/`	学习笔记
`reports/`	阶段总结
`src/`	正式 Python 脚本
`pyproject.toml`	项目依赖配置
`uv.lock`	锁定依赖版本，保证复现

14. Git 初始化

如果你要把练习当成项目积累，建议从 Week 01 就用 Git。

ompfish

git init

创建 .gitignore：

ompfish

printf "%s\n" ".venv/" "__pycache__/" ".ipynb_checkpoints/" "*.pyc" ".env" > .gitignore

解释：

条目	为什么忽略
`.venv/`	虚拟环境很大，可以重建，不应提交
`__pycache__/`	Python 自动缓存
`.ipynb_checkpoints/`	Jupyter 自动生成
`*.pyc`	编译缓存
`.env`	可能包含 API key

查看状态：

ompfish

git status

提交：

ompfish

git add README.md pyproject.toml uv.lock src notes notebooks reports data .gitignore
git commit -m "init python learning environment"

如果你暂时还不熟 Git，可以先不提交，但至少要理解 .venv/ 不该放进仓库。

15. 以后每天怎么用

每次重新打开项目，如果你使用 fish：

ompfish

cd ~/Code/python-learning/week01-basics
source .venv/bin/activate.fish
code .

如果教程不是 fish 版本，可能会写：

ompprompt

cd ~/Code/python-learning/week01-basics
Bash/Zsh activate 脚本
code .

如果只在 VS Code 里运行，解释器选好后不一定每次都要手动激活；但只要你在终端里运行 python，建议先激活。

16. 常见错误排查

16.1 VS Code 找不到 pandas

现象：

ompprompt

ModuleNotFoundError: No module named 'pandas'

检查：

ompfish

command -v python
python -c "import pandas as pd; print(pd.__version__)"

如果终端能导入，但 VS Code 不能，说明 VS Code 解释器没选 .venv/bin/python。

16.2 终端前面没有 `(.venv)`

先确认当前目录：

ompfish

pwd
ls

如果你在 ~/Code/python-learning 总目录，先进入具体项目：

ompfish

cd ~/Code/python-learning/week01-basics

fish 用户重新激活：

ompfish

source .venv/bin/activate.fish

如果你看到别人使用 Bash / Zsh：

ompprompt

Bash/Zsh activate 脚本

16.3 不知道当前在哪个目录

执行：

ompfish

pwd
ls

如果看不到 pyproject.toml，说明你不在项目根目录。

16.4 uv add 失败

先检查网络和当前目录：

ompfish

pwd
uv --version

确认在项目目录后再执行：

ompfish

uv add pandas

17. Week 01 验收清单

完成后你应该能做到：

能解释 .venv 是什么。
能用 uv add 安装包。
能在 VS Code 里选择 .venv/bin/python。
能运行 python src/hello.py。
能运行 pandas 示例。
能创建 notebook 并选择当前 kernel。
知道 .venv/ 不应该提交到 Git。
知道如何从终端进入项目目录。

18. 最小命令速查

18.1 创建项目

ompfish

mkdir -p ~/Code/python-learning/week01-basics
cd ~/Code/python-learning/week01-basics

18.2 初始化环境

ompfish

uv init
uv venv

18.3 激活环境

fish 用户执行：

ompfish

source .venv/bin/activate.fish

如果教程不是 fish 版本，可能会提到：

ompprompt

Bash/Zsh activate 脚本

18.4 安装包

ompfish

uv add numpy pandas matplotlib jupyter ipykernel

18.5 打开 VS Code

ompfish

code .

18.6 运行脚本

ompfish

python src/hello.py

19. 和 20 周计划的关系

这篇文档对应 20 周 AI / 量化成长计划的：

ompprompt

Phase 1 / Week 01：环境与 Python 基础

完成本文后，你就可以进入下一步：

ompprompt

Week 01：Python 基础语法、函数、列表、字典、字符串、文件读写
Week 02：Python 进阶 + Linux 工作流
Week 03：NumPy / Pandas
Week 04：可视化 + EDA 报告

最终目标不是“装好了环境”，而是能持续产出可运行、可复现、可解释的小项目。

20. Week 01 Python 基础语法练习

前面的步骤解决“环境能不能跑”。Week 01 还要完成一个最小 Python 脚本，证明你能写函数、处理列表、读写文件，并从终端运行。

20.1 新建练习脚本

确认你在项目目录：

ompfish

cd ~/Code/python-learning/week01-basics
source .venv/bin/activate.fish
pwd

新建脚本：

ompfish

mkdir -p src data notes
printf "%s\n" "name,score" "Alice,85" "Bob,92" "Cindy,78" > data/scores.csv
code src/week01_basic.py

逐句解释：

命令	含义
`mkdir -p src data notes`	确保代码、数据、笔记目录存在
`printf ... > data/scores.csv`	用 fish 兼容方式生成一个小 CSV 文件
`code src/week01_basic.py`	用 VS Code 打开脚本文件

20.2 写入 Python 代码

在 src/week01_basic.py 里写：

omppython

from pathlib import Path
def mean(xs: list[float]) -> float:
if not xs:
raise ValueError(“xs must not be empty”)
return sum(xs) / len(xs)
def read_scores(path: str) -> list[float]:
lines = Path(path).read_text(encoding=“utf-8”).strip().splitlines()
scores: list[float] = []
for line in lines[1:]:
name, score_text = line.split(”,”)
scores.append(float(score_text))
return scores
scores = read_scores(“data/scores.csv”)
print(“scores:”, scores)
print(“mean:”, mean(scores))

这段代码练到的能力：

代码	训练点
`def mean(...)`	函数定义
`list[float]`	类型提示
`if not xs`	基础条件判断
`Path(...).read_text(...)`	文件读取
`splitlines()`	字符串处理
`for line in lines[1:]`	列表切片和循环
`float(score_text)`	类型转换
`print(...)`	终端输出

20.3 从 fish 终端运行

ompfish

python src/week01_basic.py

期望输出类似：

ompprompt

scores: [85.0, 92.0, 78.0]
mean: 85.0

如果能跑通，说明你已经完成 Week 01 最小代码闭环：

ompprompt

创建数据 -> 写 Python 函数 -> 读取文件 -> 终端运行 -> 得到结果

20.4 写学习笔记

ompfish

code notes/week01-python.md

建议写下：

ompmarkdown

# Week 01 Python 笔记
我今天学会了

如何用 fish 激活 .venv
如何用 python 运行脚本
如何定义函数
如何读取 CSV 文本

我还不熟的地方

路径和当前目录
list / dict / for loop
报错信息怎么读

下次要做

把 read_scores 改得更健壮
学 pandas 读取 CSV

20.5 Week 01 最终验收

ompfish

cd ~/Code/python-learning/week01-basics
source .venv/bin/activate.fish
python src/week01_basic.py
test -f notes/week01-python.md; and echo "notes exists"
test -f data/scores.csv; and echo "data exists"

你应该能确认：

source .venv/bin/activate.fish 不报错。
command -v python 指向 .venv/bin/python。
python src/week01_basic.py 能输出平均分。
notes/week01-python.md 存在。
你能解释 mean(xs) 为什么要处理空列表。

完成这些后，再进入 Week 02：Python 进阶 + Linux 工作流。

plain

Model	Validation Metric	Test Metric	Notes
Logistic Regression	…	…	scaled numeric features
Random Forest	…	…	tree baseline

Metric	Value
Accuracy	{test_metrics[‘accuracy’]:.4f}
Precision	{test_metrics[‘precision’]:.4f}
Recall	{test_metrics[‘recall’]:.4f}
F1	{test_metrics[‘f1’]:.4f}
ROC AUC	{test_metrics[‘roc_auc’]:.4f}

Metric	Value
Accuracy	{test_metrics[‘test_accuracy’]:.4f}
Precision	{test_metrics[‘test_precision’]:.4f}
Recall	{test_metrics[‘test_recall’]:.4f}
F1	{test_metrics[‘test_f1’]:.4f}
ROC AUC	{test_metrics[‘test_roc_auc’]:.4f}

Split	Rows
Train	{split_sizes[‘train’]}
Validation	{split_sizes[‘valid’]}
Test	{split_sizes[‘test’]}

字段	含义	类型
student	学生编号	分类
major	专业	分类
gender	性别	分类
math	数学成绩	数值
english	英语成绩	数值
python	Python 成绩	数值
study_hours	每周学习时长	数值
average_score	三科平均分	数值

江无没有月の博客

Python 官方教程综合练习手册：Oh My Pi Terminal Edition

把官方教程变成能敲、能跑、能解释的 4 周终端练习。

Python 官方教程综合练习手册：Oh My Pi Terminal Edition

0. 使用方式

0.1 官方教程映射

0.2 最终项目结构

0.3 四周路线

1. Week A：解释器、虚拟环境、基本类型、控制流

1.1 先理解：解释器、脚本、虚拟环境

函数和命令怎么用

代码逻辑

Exercise A-00：创建练习项目

1.2 数字：先把统计量算出来

你要学的函数

代码逻辑

Exercise A-01：均值、最小值、最大值

1.3 字符串：把脏列名清洗成规范列名

你要学的方法

代码逻辑

Exercise A-02：清洗字段名

1.4 列表过滤：去掉缺失值和异常值

你要学的语法

代码逻辑

Exercise A-03：过滤缺失值

1.5 条件函数：把分数变成等级

函数怎么用

函数定义长什么样

代码逻辑

Exercise A-04：分数等级

1.6 match：根据命令选择行为

函数怎么用

最小例子

代码逻辑

Exercise A-05：实现命令分发

2. Week B：函数、参数、数据结构、编码风格

2.1 均值函数：从公式变成可复用函数

函数怎么用

先写最小版本

加上错误处理

代码逻辑

Exercise B-01：统计函数库

2.2 默认参数：不要让多个调用共享同一个列表

错误函数怎么用会出问题

正确函数怎么用

代码逻辑

Exercise B-02：安全默认参数

2.3 数据结构：选择合适的容器

函数怎么用

代码逻辑

Exercise B-03：指标字典

2.4 列表推导式：把循环写短，但不要写晦涩

普通循环写法

函数怎么用

代码逻辑

Exercise B-04：批量清洗字符串

3. Week C：模块、文件、JSON、异常、CLI

3.1 模块：把函数放进文件

模块怎么用

代码逻辑

Exercise C-01：模块拆分

3.2 文件读取：从磁盘拿数据

函数怎么用

你要学的标准库

最小数据

代码逻辑

Exercise C-02：CSV 读写

3.3 JSON：保存配置

函数怎么用

最小配置

代码逻辑

Exercise C-03：实验配置

3.4 异常：让错误变得可理解

函数怎么用

错误写法

正确写法

代码逻辑

Exercise C-04：异常条件

3.5 CLI：从命令行传参数

命令怎么用

1.6 `match`：根据命令选择行为

4.3 浮点数：不要用 `==` 比较小数

4. 建立 `.gitignore`

8. 在 `pyproject.toml` 中添加命令入口