tsbootstrap

tsbootstrap 通过带类型的方法规范、假设元数据和可重放的运行元数据，明确指定抽样设计。其可选的编译型归约器可在生成重采样数据时计算统计量，面板 API 还支持长度不等的时间序列。

实测证明	结果	范围与记录
与 arch.apply 对比的四种共有方法	所有 16 个实测单元格均更快；较长序列上快 4.7x 到 33x	IID、移动、循环、平稳；均值统计量；n=2,000，B=999 或 10,000；八核上可选编译归约器；settled-min 记录 和方法说明。
一万条序列，单次融合遍历	比逐序列归约循环快 220x	时间，B=1,000，n=200，MovingBlock(20) 均值；面板基准测试。
同一面板，不创建重采样路径张量	峰值内存比先物化再归约少 141x	内存，相同工作负载；物化是与时间对比不同的基准；面板基准测试。

阅读 Count the bytes, not the FLOPs 和 Ten thousand series, one pass，了解这些结果背后的工程实践。

能力	tsbootstrap 中的实现	对比范围
共有的观测值自助法	IID、移动区块、循环区块、平稳区块	arch.bootstrap 也包含这四种方法，并且均纳入实测对比。
其他重采样方法	非重叠和渐缩区块；递归 AR、ARIMA、VAR 和筛法自助法；野生和区块野生创新	不在四种方法的正面对比基准范围内。
不确定性工作流	自助法置信区间、AR 预测区间、EnbPI 和自适应保形校准	这些工作流不属于速度对比范围。
大型面板和工具	不规则面板归约器、方法诊断与元数据、可选的只读 MCP 工具	面板基准测试对比的是三种 tsbootstrap 工作流，而非 arch。

这些速度数据描述的是编译后的命名统计量归约路径；默认 NumPy 后端、任意 Python 统计量、物化样本和单线程执行的性能表现各不相同。有关这些路径，请参阅完整基准测试矩阵。arch 自助法模块还提供独立样本自助法，而更广泛的 arch 包还包含计量经济学工具。这两者均不在这项四种方法的对比范围内。

📒 目录

1. 🚀 入门
2. ⚡ 性能
3. 📚 文章
4. 🧩 模块
5. 🗺 路线图
6. 🤝 参与贡献
7. 📄 许可证
8. 📍 时间序列自助法简介
9. 👏 贡献者

---

🚀 入门

🎮 使用 tsbootstrap

tsbootstrap 提供一个带类型的入口 bootstrap，通过方法规格进行配置。 所有方法都可以使用相同的调用方式。

import numpy as np
from tsbootstrap import bootstrap, MovingBlock

rng = np.random.default_rng(0)
innovations = rng.standard_normal(200)
x = np.empty_like(innovations)
x[0] = innovations[0]
for t in range(1, len(x)):
    x[t] = 0.6 * x[t - 1] + innovations[t]

result = bootstrap(x, method=MovingBlock(block_length="auto"), n_bootstraps=999, random_state=0)

samples = result.values()  # (n_bootstraps, n) resampled series
oob = result.get_oob_mask()  # (n_bootstraps, n) out-of-bag mask

根据所需结构选择方法规格（区块长度默认采用 Politis-White 自动选择）：

from tsbootstrap import StationaryBlock, ResidualBootstrap, SieveAR, AR, ARIMA, diagnose

bootstrap(x, method=StationaryBlock(avg_block_length="auto"))

# recursive model-based bootstraps; only ARIMA needs the models extra
bootstrap(x, method=ResidualBootstrap(model=AR(order=2)))
bootstrap(x, method=ResidualBootstrap(model=ARIMA(order=(1, 1, 1))))
bootstrap(x, method=SieveAR())

# not sure which fits? ask:
print(diagnose(x).recommended_methods)

输入可以是 NumPy 数组、列表或 pandas / Polars DataFrame 和 Series。结果是一个 BootstrapResult，包含样本、来源元数据以及样本外 / 样本内原语。对于 sktime 生态系统，同样的方法也可作为估计器类（MovingBlockBootstrap、ARResidualBootstrap、 SieveBootstrap 等）通过 tsbootstrap.adapters 使用。

不确定性量化

uq 层将重采样序列转换为预测区间。forecast_intervals 为 AR 模型提供向前预测区间；EnbPIEnsemble 为 sklearn 风格的回归器生成袋外 预测区间，并针对平稳数据、波动聚集数据和漂移数据提供校准器（静态、滑动窗口，以及自适应 ACI、 AgACI 和 NexCP 方案）；bootstrap_reduce 流式计算每个重复样本的统计量，因此即使重复次数很大， 也无需将所有路径保存在内存中即可完成校准。

from tsbootstrap import AR, forecast_intervals

lower, upper, median = forecast_intervals(x, model=AR(order=2), horizon=12, alpha=0.1)

要获取单个序列统计量的置信区间，可通过一次调用让 conf_int 执行自助法 并读取区间：

from tsbootstrap import IID, conf_int

lower, upper, point = conf_int(x, "mean", method=IID(), kind="bca", alpha=0.1)

保形预测组件（EnbPIEnsemble 和校准器）需要 uq extra （scikit-learn）。交互式 教程集 会通过真实和合成数据演示每种方法，其中包括“我应该使用哪种自助法？”决策指南。

MCP 服务

tsbootstrap 提供了一个只读的模型上下文协议 服务，因此 MCP 客户端（大模型 Agent、IDE）无需编写任何 Python 代码，即可诊断短序列并计算自助法置信区间。无需安装即可运行：

uvx --from "tsbootstrap[mcp]" tsbootstrap-mcp

它使用 stdio 传输，并且只公开两个只读工具：

• diagnose_series：序列依赖性和平稳性诊断、推荐的 Politis-White 块长度，以及服务支持的该序列自助法。
• bootstrap_confidence_interval：针对均值、中位数、标准差或方差计算百分位置信区间，使用 i.i.d. 或分块自助法。

这两个工具最多接受 500 个观测值，最多运行 500 次重复。对于更长的 序列、基于模型的方法或不确定性量化层，请直接在本地脚本中使用该库。

📦 安装

需要 Python 3.10 或更高版本。

# with uv (recommended):
uv add tsbootstrap                   # core: i.i.d. and block methods
uv add "tsbootstrap[models]"         # adds statsmodels for ARIMA

# with pip:
pip install tsbootstrap
pip install "tsbootstrap[models]"

AR、VAR 和 sieve 拟合使用核心 NumPy 实现。ARIMA 会延迟导入 statsmodels，并且需要 models extra。

⚡ 性能

左：编译后的 reduce 路径在四种重叠方法上相较于 arch 库的加速比。右：两个主要 reduce 工作负载的前后峰值内存（基线 = 先物化所有路径，再进行 reduce）。图表和下表根据 benchmarks/results/ 中已提交的基准测试数据生成；运行 python benchmarks/plot_launch.py 可重新生成。

tsbootstrap 提供可选的编译后端（backend="compiled"，通过 [accel] extra 启用）。在测得的均值归约工作负载上，它在四种共有的 重采样方法中均比 arch.apply 更快。下表 展示了 8 核 CPU 上流式 reduce 路径相较于 arch.apply 的加速比（越高越好）， 数据来自 benchmarks/results/vs_arch_ccx33_2026-07-11_settled.json （settled-min 统计量；方法见 benchmarks/README.md）。

方法	n=200, B=999	n=200, B=10000	n=2000, B=999	n=2000, B=10000
IID	15x	19x	4.7x	8.6x
MovingBlock	38x	61x	9.8x	26x
CircularBlock	41x	66x	13x	33x
StationaryBlock	19x	24x	6.8x	12x

这些结果表明，在较大的 n=2000 工作负载上，加速比稳定在约 4.7x 到 33x；小 n 时极高的倍数来自 arch 在 bs.apply 中对每个重复样本都调用一次 Python 回调。当每次重采样开销很低时，这部分开销会主导其运行时间，因此这些倍数反映的 不只是编译内核的性能，也包括这部分开销。

编译后的 reduce 将索引构建、数据收集和归约融合为单次遍历，因此峰值内存不会随 重复样本数量增加：n=2000 时，B=50000 的流式 reduce 占用约 20 MB，而物化所有 重复样本则需要约 1.94 GB（约轻 96 倍），数据来自 benchmarks/results/membench_2026-07-04.json。 arch 没有对应的多变量和不规则面板 reduce 路径。面板 reduce （bootstrap_reduce_panel）会返回统计量在每个序列上的完整自助法分布 （n_bootstraps x num_series），因此可直接支持对估计量进行分位数和尾部分析， 无需创建重复样本张量。只有在工作流需要使用重采样路径本身时，才使用物化路径。 完整方法、单线程行为和复现脚本见 benchmarks/README.md。

# install the compiled backend
uv add "tsbootstrap[accel]"
# or
pip install "tsbootstrap[accel]"

📚 相关文章

深入介绍该库背后的统计学原理和工程实践，并附有完整示例和动画：

• 你的自助法在欺骗你： 为什么普通的 i.i.d. 自助法在自相关数据上会失效（名义覆盖率为 90% 的区间，实际覆盖率只有 49.6%），以及区块重采样如何解决这一问题。
• 当你的误差并不相等： 用于处理异方差误差的 wild bootstrap，以及区块 wild 变体能保留哪些特性。
• 计算字节数，而非 FLOPs： 编译后端背后的内存墙工程实践，以及硬件计数器提供的实测数据。
• 一万条序列，一次遍历： 面板基准测试、独立的时间和内存基线，以及不规则面板设计。

🧩 模块

软件包布局：

区域	模块	作用
公共 API	api.py、methods.py、results.py、errors.py、diagnostics.py	bootstrap() 入口点、类型化方法规范、结构化结果、错误分类体系和 diagnose()
基础设施	rng.py、validation.py、dispatch.py、metadata.py	确定性 RNG 契约、输入强制转换（包括 narwhals DataFrame 边界）、从规范到执行器的分发、方法元数据
区块方法	block/	向量化索引内核、真正的 Politis-Romano 平稳自助法、能量归一化渐变处理、PWSD 区块长度、OOB 基元
模型方法	model/、engines/	模型拟合、稳定性保护，以及递归 AR/ARMA/VAR 模拟
不确定性量化	uq/	通过 conf_int 实现经典置信区间（百分位数、基本、学生化、BCa）、EnbPI 预测区间、静态 / 滑动窗口 / ACI / AgACI / NexCP 校准器，以及 AR 预测区间
生态系统	adapters/	基于函数核心的 skbase / sktime 估计器类

🗺 路线图

完整且持续更新的路线图见 issue #181。重点内容：

近期计划：

• ARIMA 和 VAR 的样本外预测区间（目前仅支持 AR）。

候选方法（适合作为新手入门问题）：

• 广义区块（#104）、局部区块（#105）和频域（#107）自助法。
• GARCH / 波动率残差自助法，以及平滑核依赖型野自助法。

分布式执行（Dask / Spark / Ray）、异步层和字符串键控工厂均经过考虑，并被有意排除在外。该库是一个受 CPU 限制的单进程工具包。

🤝 贡献

请参阅适合新手入门的问题 以开始参与。

开发者环境设置

1. Fork tsbootstrap 仓库

2. 将 fork 克隆到本地：

git clone https://github.com/astrogilda/tsbootstrap

3. 在本地仓库根目录中，使用 uv 同步锁定的开发环境：

uv sync --extra dev

4. uv 会根据 uv.lock 创建隔离的虚拟环境，并以可编辑模式安装软件包，因此对软件包的更改会自动反映到环境中。使用 uv run 在该环境中运行工具（例如 uv run pytest）。

5. 安装 pre-commit 钩子：

uv run pre-commit install

这些钩子会在每次提交时运行 ruff、格式化工具和其他代码质量检查。

验证安装

验证安装：

python -c "import tsbootstrap; print(tsbootstrap.__version__)"

这会打印已安装的版本。

贡献工作流

1. 创建一个名称清晰的新分支（例如 new-feature-branch 或 bugfix-issue-123）。

git checkout -b new-feature-branch

2. 修改项目代码。
3. 将更改提交到本地分支，并使用清晰的提交消息说明所做的更改。

git commit -m 'Implemented new feature.'

4. 使用以下命令，将更改推送到 GitHub 上 fork 的仓库

git push origin new-feature-branch

5. 向原始项目仓库创建新的拉取请求。在拉取请求中，描述所做的更改及其必要性。

🧪 运行测试

要运行所有测试，请在开发环境中运行：

uv run pytest tests/

这会在单个进程中运行测试。添加 CI 用于并行运行测试套件的 pytest-xdist 标志；在多核机器上，这样会快好几倍：

uv run pytest tests/ -n auto --dist loadscope --max-worker-restart 3

可使用 sktime 的估计器检查来验证 sktime 适配器类：

from sktime.utils import check_estimator
from tsbootstrap.adapters import MovingBlockBootstrap

check_estimator(MovingBlockBootstrap)

贡献指南

详情请参阅 CONTRIBUTING.md。

📄 许可证

本项目采用 ℹ️ MIT 许可证授权。更多信息请参阅 LICENSE 文件。

---

👏 贡献者

贡献者：

本项目遵循 all-contributors 规范。欢迎以任何形式参与贡献！

---

📍 时间序列自助法

tsbootstrap 为单变量和多变量时间序列实现了自助法。分块方法将相邻观测值作为整体重新抽样；基于模型的方法则根据拟合的动态模拟新的路径。

概览

i.i.d. 自助法通过对单个观测值重新抽样来打破序列相关性。分块方法和基于模型的方法则会在其假设范围内保留某些相关性。区间覆盖率仍取决于数据所处的情形、统计量和方法选择；请参阅不确定性指南。

自助法方法

tsbootstrap 会直接对观测值（i.i.d. 和分块方法）或拟合模型的创新项（残差和筛法）重新抽样，同时遵循数据的时间顺序和相关结构。

分块自助法

分块方法会对连续观测值组成的块重新抽样，以保留短程相关性。块长度默认为 Politis-White (2004) 自动选择的长度。

• 移动块（MovingBlock）：固定长度的重叠块（Kunsch 1989）。
• 循环块（CircularBlock）：块会从序列末尾绕回开头（Politis-Romano 1992）。
• 平稳块（StationaryBlock）：块长度服从几何分布，重启点独立且均匀分布（Politis-Romano 1994）。
• 非重叠块（NonOverlappingBlock）：互不重叠的块（Carlstein 1986）。
• 锥化块（TaperedBlock(window=...)）：使用能量归一化窗函数（Bartlett、Blackman、Hamming、Hann 或 Tukey）对块加权（Paparoditis-Politis 2001）。

残差自助法

对于拟合良好的依赖数据，ResidualBootstrap(model=...) 会根据拟合动态和重新抽样后的中心化创新项，递归地重新生成序列（而不是使用 fitted + residuals）。支持的模型包括：AR、ARIMA 和 VAR（多变量）。对于非平稳拟合，此方法会拒绝处理（或根据 stability_policy 跳过），而不会生成爆炸性路径。

筛法自助法

SieveAR 会在原始序列上选择自回归阶数，然后执行 AR 递归；适用于具有自回归结构的数据。

创新项重新抽样方法

ResidualBootstrap 和 SieveAR 的 innovation 参数控制中心化残差的重新抽样方式。默认值为 IID（均匀抽样）；两种 wild 重新抽样方法放宽了其所依赖的可交换性假设。

• Wild（Wild(distribution=...)）：将每个残差就地乘以一个均值为零、方差为一的随机值（e*_t = v_t * e_hat_t），保留其时间位置和幅度，因此在条件异方差情况下仍然有效（Wu 1986；Liu 1988；默认使用 Rademacher，依据 Davidson-Flachaire 2008）。
• 分块 wild（BlockWild(block_length=...)）：在每个残差块内使用同一个乘数，因此由均值模型设定错误导致的序列相关性仍会在重新抽样后保留（分段常数依赖 wild 自助法，Shao 2010）。

两者都要求宿主模型使用 burn_in=0 和 initial="fixed" 默认值，以确保乘数与残差一一对应。

延后至后续版本

计划在未来版本中加入 Markov 重新抽样、分布自助法、GARCH/波动率模型，以及频域／季节性分块方法。保留统计量的方法已移除。