tsbootstrap

tsbootstrap は、型付きメソッド仕様、仮定メタデータ、再実行可能な実行メタデータを通じて、サンプリング設計を明示します。オプションのコンパイル済みリデューサーはリサンプルの生成中に統計量を計算し、パネル API は長さの異なる時系列に対応します。

測定による実証	結果	対象範囲と記録
arch.apply に対する4つの共通メソッド	測定した16項目すべてで高速化。長い系列では 4.7倍～33倍	IID、移動、循環、定常；平均統計量；n=2,000、B=999 または 10,000；8コアでのオプションのコンパイル済みリデューサー；settled-min の記録 と 方法論。
1万系列を1回の融合処理で	系列ごとの reduce ループより 220倍高速	時間、B=1,000、n=200、MovingBlock(20) の平均；パネルベンチマーク。
同じパネルで、リサンプリング済みパスのテンソルを使わない場合	materialize してから reduce する方法より ピークメモリを141分の1に削減	メモリ、同じワークロード；materialize は時間比較とは異なるベースラインです；パネルベンチマーク。

これらの結果を支えるエンジニアリングについては、FLOPs ではなくバイト数を数える と1万系列を1回の処理でをご覧ください。

機能	tsbootstrap での対応	比較の対象範囲
共通の観測値ブートストラップメソッド	IID、移動ブロック、循環ブロック、定常ブロック	4つすべてが arch.bootstrap にもあり、測定比較の対象です。
追加のリサンプリング	非重複ブロックとテーパードブロック；再帰的な AR、ARIMA、VAR、シーブブートストラップ；ワイルドおよびブロックワイルドのイノベーション	4メソッドの直接比較ベンチマークの対象外です。
不確実性ワークフロー	ブートストラップ信頼区間、AR 予測帯、EnbPI、適応的コンフォーマル較正	これらのワークフローは速度比較の対象外です。
大規模パネルとツール	不規則パネル用リデューサー、メソッドの診断とメタデータ、オプションの読み取り専用 MCP ツール	パネルベンチマークでは arch ではなく、3つの tsbootstrap ワークフローを比較しています。

速度の数値は、コンパイル済みの名前付き統計量 reduce パスを示しています。 デフォルトの NumPy バックエンド、任意の Python 統計量、マテリアライズ済みサンプル、 単一スレッド実行では、それぞれ異なるパフォーマンス特性があります。これらのパスについては、 ベンチマークの全体像をご覧ください。arch のブートストラップ モジュールは独立サンプルのブートストラップにも対応しており、より広範な arch パッケージには計量経済学のツールも含まれています。いずれも、この4メソッドの 比較対象には含まれていません。

📒 目次

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 を使用できます。 結果は、サンプル、由来を示すメタデータ、out-of-bag / in-bag プリミティブを含む 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)

1 つの系列の統計量に対する信頼区間を求める場合は、conf_int を使うとブートストラップの実行と 区間の取得を 1 回の呼び出しで行えます。

from tsbootstrap import IID, conf_int

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

共形予測の機能（EnbPIEnsemble とキャリブレーター）には、uq エクストラ （scikit-learn）が必要です。対話型の チュートリアルギャラリー では、実データと合成データを使ってすべての手法を解説しており、「どのブートストラップを使うべきか？」という判断ガイドも含まれています。

MCP サーバー

tsbootstrap には、読み取り専用の Model Context Protocol サーバーが付属しているため、MCP クライアント（LLM エージェント、IDE）は Python を書かずに短い系列を診断し、ブートストラップ信頼区間を計算できます。インストール手順なしで実行できます。

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

stdio トランスポートを使用し、読み取り専用のツールを 2 つだけ公開します。

• 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 エクストラが必要です。

⚡ パフォーマンス

左：4 つの共通メソッドにおける、コンパイル済み reduce パスの arch ライブラリに対する高速化。右：主要な 2 つの reduce ワークロードにおける、処理前後のピークメモリ（ベースライン＝すべてのパスを具体化してから reduce）。図と以下の表は、コミット済みのベンチマークデータ benchmarks/results/ から生成されています。再生成するには python benchmarks/plot_launch.py を実行してください。

tsbootstrap には、オプションのコンパイル済みバックエンド（[accel] エクストラ経由の backend="compiled"）が付属しています。測定した平均値の reduction ワークロードでは、4 つの共通リサンプリングメソッドすべてで arch.apply より高速です。以下の表は、8 コア CPU での arch.apply に対するストリーミング reduce パスの高速化を示しています（値が大きいほど高速です）。データは 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 はインデックスの構築、データの収集、reduction を 1 回のパスに統合するため、ピークメモリは反復数に左右されません。n=2000 では、B=50000 のときストリーミング reduce の使用メモリは約 20 MB です。一方、すべての反復を具体化すると約 1.94 GB が必要です（約 96 倍軽量）。データは benchmarks/results/membench_2026-07-04.json を参照してください。多変量および不揃いなパネルの reduce パスに相当する機能は arch にはありません。パネル 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% しかカバーしない）と、ブロックリサンプリングによる解決方法。
• 誤差が等分散でない場合: 不均一分散誤差に対するワイルドブートストラップと、ブロックワイルド変法で保持できる性質。
• FLOP ではなくバイト数を数える: コンパイル済みバックエンドを支えるメモリウォールへのエンジニアリング上の取り組みと、ハードウェアカウンターによる実測結果。
• 1 万系列を 1 回のパスで: パネルのベンチマーク、時間とメモリそれぞれの個別ベースライン、不揃いなパネルの設計。

🧩 モジュール

パッケージの構成：

領域	モジュール	役割
パブリック 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 のみ）。

候補となるメソッド（最初に取り組むのに適した Issue）：

• 一般化ブロック（#104）、ローカルブロック（#105）、および周波数領域（#107）のブートストラップ。
• GARCH／ボラティリティ残差ブートストラップ、および平滑カーネル従属ワイルドブートストラップ。

分散実行（Dask／Spark／Ray）、非同期レイヤー、文字列キー型のファクトリーは検討されましたが、意図的に対象外としました。このライブラリは CPU バウンドの単一プロセス用ツールキットです。

🤝 コントリビューション

始めるには、最初に取り組むのに適した Issue をご覧ください。

開発環境のセットアップ

1. tsbootstrap リポジトリをフォークします。

2. フォークをローカルにクローンします：

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 上のフォークしたリポジトリにプッシュします。

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（一様再サンプリング）です。2 種類のワイルド再サンプラーでは、交換可能性の仮定を緩和します。

• ワイルド（Wild(distribution=...)）：各残差の位置で、その残差に平均 0、分散 1 の乱数を乗じます（e*_t = v_t * e_hat_t）。時間上の位置と大きさが保たれるため、条件付き分散不均一性がある場合にも妥当性を保ちます（Wu 1986；Liu 1988；既定値の Rademacher は Davidson-Flachaire 2008 に準拠）。
• ブロックワイルド（BlockWild(block_length=...)）：残差の各ブロック内で乗数を一定に保ち、平均の誤指定によって残る系列依存性が再サンプリング後も保たれるようにします（区分的定数の従属ワイルドブートストラップ、Shao 2010）。

どちらも、乗数と残差が 1 対 1 で対応するよう、ホストモデルの既定値である burn_in=0 と initial="fixed" が必要です。

後続のリリースに延期

マルコフ再サンプリング、分布ブートストラップ、GARCH／ボラティリティモデル、および周波数領域／季節ブロック法は、将来のバージョンで予定されています。統計量を保持する手法は削除されました。