137 lines
4.0 KiB
Markdown
137 lines
4.0 KiB
Markdown
|
# S 档「函数卡片」模板
|
|||
|
|
|
|||
|
|
> **只给 S 档用**（约 15 个招牌算法，见 `docs/03-roadmap.md` §3.1）。
|
|||
|
|
> 其余 A 档函数只要求 docstring 一句话 + 一条 pytest，不写卡片。
|
|||
|
|
>
|
|||
|
|
> 卡片写在哪：`docs/algorithms/<函数名>.md`。
|
|||
|
|
> 为什么写：S 档是自己实现、以后会去改内部实现的算法，
|
|||
|
|
> 卡片是"半年后还看得懂当时为什么这么写"的唯一保障。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 卡片模板
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# <函数名>
|
|||
|
|
|
|||
|
|
| 项 | 内容 |
|
|||
|
|
|---|---|
|
|||
|
|
| 模块 | `mcm_toolkit.<包>.<模块>` |
|
|||
|
|
| 档位 | S |
|
|||
|
|
| 参考来源 | <教材 / 论文 / 库；自己实现时参考了什么> |
|
|||
|
|
|
|||
|
|
## 1. 数学定义
|
|||
|
|
|
|||
|
|
<公式。用 LaTeX 写，例如 \`\\hat{\\theta}^* = \\arg\\min_\\theta ...\`。
|
|||
|
|
一句话说清输入输出分别是什么数学对象。>
|
|||
|
|
|
|||
|
|
## 2. 适用场景
|
|||
|
|
|
|||
|
|
**用**：<什么题型、什么数据条件下该用它>
|
|||
|
|
**不用**：<什么条件下它失效或不该用>
|
|||
|
|
|
|||
|
|
## 3. 参数与返回值
|
|||
|
|
|
|||
|
|
| 参数 | 类型 | 默认 | 含义 | 取值影响 |
|
|||
|
|
|---|---|---|---|---|
|
|||
|
|
| | | | | |
|
|||
|
|
|
|||
|
|
返回 `Result`：
|
|||
|
|
|
|||
|
|
| 字段 | 内容 |
|
|||
|
|
|---|---|
|
|||
|
|
| `params` | |
|
|||
|
|
| `metrics` | |
|
|||
|
|
| `data` | |
|
|||
|
|
|
|||
|
|
## 4. 复杂度
|
|||
|
|
|
|||
|
|
- 时间：`O(...)`
|
|||
|
|
- 空间：`O(...)`
|
|||
|
|
- **什么时候会跑不完**：<给出具体数字量级，例如"n > 1e6 时内存 8GB 打不住">
|
|||
|
|
|
|||
|
|
## 5. 数值稳定性
|
|||
|
|
|
|||
|
|
<浮点误差、除零、log(0)、上溢下溢、病态矩阵……
|
|||
|
|
写清"什么输入会出问题"和"代码里怎么防的"。>
|
|||
|
|
|
|||
|
|
## 6. 常见错误
|
|||
|
|
|
|||
|
|
1. <错误用法> → <后果> → <正确做法>
|
|||
|
|
2. …
|
|||
|
|
|
|||
|
|
## 7. 最小示例
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# 能直接复制进 notebook 跑通的 5～15 行
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 8. 单元测试要点
|
|||
|
|
|
|||
|
|
| 测什么 | 期望 |
|
|||
|
|
|---|---|
|
|||
|
|
| <已知解析解> | <精度要求> |
|
|||
|
|
| <边界输入> | <行为> |
|
|||
|
|
|
|||
|
|
## 9. MCM/ICM 用法
|
|||
|
|
|
|||
|
|
- **哪类题**：<例如"评价类 / 预测类 / 优化类">
|
|||
|
|
- **论文里怎么表述**：<一句话，能直接改写成论文的"方法"小节>
|
|||
|
|
- **图**：<配哪张图，用哪个 `viz` 函数>
|
|||
|
|
- **踩坑提醒**：<评审最可能质疑什么>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 示例：`bootstrap_ci` 的卡片（示范，未定稿）
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# bootstrap_ci
|
|||
|
|
|
|||
|
|
| 项 | 内容 |
|
|||
|
|
|---|---|
|
|||
|
|
| 模块 | `mcm_toolkit.stats.bootstrap` |
|
|||
|
|
| 档位 | S |
|
|||
|
|
| 参考来源 | Efron (1979); Efron & Tibshirani (1993) *An Introduction to the Bootstrap* |
|
|||
|
|
|
|||
|
|
## 1. 数学定义
|
|||
|
|
|
|||
|
|
给定样本 \`x_1..x_n\` 与统计量 \`T(·)\`，从 \`x\` 中有放回抽 \`n\` 个得到 \`x^*\`，
|
|||
|
|
重复 \`B\` 次得 \`T^*_1..T^*_B\`。百分位法区间为
|
|||
|
|
\`[T^*_{(α/2·B)}, T^*_{(1-α/2)·B}]\`。
|
|||
|
|
|
|||
|
|
## 2. 适用场景
|
|||
|
|
|
|||
|
|
**用**：统计量没有解析分布（中位数、极差、自定义指标）、样本有偏、想给区间但不想假设正态。
|
|||
|
|
**不用**：\`n < 10\`（经验分布不可靠）；数据有强时间相关性时（要用 block bootstrap）。
|
|||
|
|
|
|||
|
|
## 3. 参数与返回值
|
|||
|
|
|
|||
|
|
| 参数 | 类型 | 默认 | 含义 | 取值影响 |
|
|||
|
|
|---|---|---|---|---|
|
|||
|
|
| `statistic` | callable | `np.mean` | 任意 `f(sample) -> float` | 换 `np.median` 就得到中位数的 CI |
|
|||
|
|
| `n_resamples` | int | 10000 | 重采样次数 `B` | 越大区间端点越稳；10000 通常够 |
|
|||
|
|
| `confidence` | float | 0.95 | 置信水平 | |
|
|||
|
|
| `method` | str | `"percentile"` | `"percentile"` / `"bca"` | BCa 更准但慢 |
|
|||
|
|
|
|||
|
|
## 4. 复杂度
|
|||
|
|
|
|||
|
|
时间 \`O(B·n)\`；空间 \`O(B)\`（**按块处理，不落地 B×n 矩阵**）。
|
|||
|
|
`n=1e6, B=1e4` 约 \`1e10\` 次操作 → **跑不完**，此时应改用解析近似或降 `B`。
|
|||
|
|
|
|||
|
|
## 7. 最小示例
|
|||
|
|
|
|||
|
|
\`\`\`python
|
|||
|
|
import numpy as np
|
|||
|
|
from mcm_toolkit.stats import bootstrap_ci
|
|||
|
|
r = bootstrap_ci(heights, statistic=np.median, n_resamples=10000, random_state=42)
|
|||
|
|
print(r.params["low"], r.params["high"])
|
|||
|
|
\`\`\`
|
|||
|
|
|
|||
|
|
## 9. MCM/ICM 用法
|
|||
|
|
|
|||
|
|
- **哪类题**：任何要"给结论 + 给不确定性"的题，尤其评价类和预测类。
|
|||
|
|
- **论文里怎么表述**："采用非参数 bootstrap（B=10000，seed=42）估计中位数的 95% 置信区间。"
|
|||
|
|
- **图**：预测曲线 + 阴影区间；用 `viz.plot`。
|
|||
|
|
- **踩坑提醒**：必须报 `B` 和 seed；BCa 与 percentile 结果不同时要说明选了哪个及理由。
|
|||
|
|
```
|