Tsbootstrap

https://github.com/astrogilda/tsbootstrap
Admin
Tsbootstrap is a Python package designed to generate bootstrapped samples from time-series data,...
Tokens:197,733
Snippets:1,173
Trust Score:9.2
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install tsbootstrap with examples extra

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/AA_datasets_and_dgps.ipynb

Installs tsbootstrap with the examples extra on Colab or Binder if it is not already present. The installation is skipped when tsbootstrap is already importable.

```python
# On Colab or Binder, install tsbootstrap first (skipped if already present):
try:
    import tsbootstrap  # noqa: F401
except ImportError:
    %pip install -q "tsbootstrap[examples]"
```

--------------------------------

### Install tsbootstrap with examples extra

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/multivariate_var.ipynb

Install tsbootstrap with the examples extra if not already present. Useful for Colab or Binder environments.

```python
try:
    import tsbootstrap  # noqa: F401
except ImportError:
    %pip install -q "tsbootstrap[examples]"
```

--------------------------------

### Run full asv regression suite

Source: https://github.com/astrogilda/tsbootstrap/blob/main/benchmarks/README.md

One-time setup installs asv and virtualenv. Then run all benchmarks on the current commit, on a range of commits, and view results in a browser. asv automatically installs numba and arch into its managed environment via the matrix.req block in asv.conf.json.

```sh
# One-time setup
pip install asv virtualenv

# Run all benchmarks on the current commit
asv run HEAD^!

# Run on a range of commits (e.g. to compare main vs a feature branch)
asv run main..HEAD

# View results in a browser
asv publish
asv preview
```

--------------------------------

### Use compiled backend for faster bootstrap

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/quickstart.ipynb

Optional numba-accelerated fast path for larger runs. Equal in distribution to the default numpy path but not bit-identical, so replicates differ even with the same random_state. Requires the extra dependency installed with pip install "tsbootstrap[accel]".

```python
result_fast = bootstrap(x, method=MovingBlock(block_length="auto"), n_bootstraps=200, random_state=0, backend="compiled")
```

--------------------------------

### Install tsbootstrap with models extra

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/methods_guide.rst

Install the `models` extra to enable ARIMA support via statsmodels. Use `uv add` or `pip install`.

```sh
uv add "tsbootstrap[models]"     # or: pip install "tsbootstrap[models]"
```

--------------------------------

### Diagnose recommended bootstrap methods

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/quickstart.ipynb

Calls diagnose on the series to recommend method specifications based on serial dependence and stationarity. It is a heuristic starting point, not a guarantee.

```python
from tsbootstrap import diagnose

diagnose(x).recommended_methods
```

```text
Result:
('StationaryBlock', 'MovingBlock', 'SieveAR')
```

--------------------------------

### Install tsbootstrap with examples extra

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/residual_and_sieve.ipynb

Install tsbootstrap with the [examples] extra on Colab or Binder if not already present. The extra includes statsmodels, sktime, and other dependencies needed for the ARIMA and sieve examples.

```python
# On Colab or Binder, install tsbootstrap first (skipped if already present):
try:
    import tsbootstrap  # noqa: F401
except ImportError:
    %pip install -q "tsbootstrap[examples]"

# The ARIMA and sieve paths use statsmodels, which ships in the [examples] extra
# (it pulls in tsbootstrap[models]). The bundled datasets come from sktime and
# statsmodels, both also in [examples].
```

--------------------------------

### Use diagnose() to recommend a method

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/quickstart.rst

Call diagnose() on the data to get recommended methods and notes.

```python
from tsbootstrap import diagnose

d = diagnose(x)
print(d.recommended_methods)
print(d.notes)
```

--------------------------------

### Install extras with uv sync

Source: https://github.com/astrogilda/tsbootstrap/blob/main/DEVELOPER_NOTES.md

Use uv to install the core package or include optional extras. `uv sync` installs only the core dependencies, `uv sync --extra dev` adds the development environment, and `uv sync --all-extras` installs all optional extras.

```bash
uv sync                       # core only
uv sync --extra dev           # development environment
uv sync --all-extras          # everything
```

--------------------------------

### Install profiling dependencies

Source: https://github.com/astrogilda/tsbootstrap/blob/main/profiling/README.md

Install the package with the 'profile' extra to get scalene, line_profiler, memory_profiler, py-spy, and snakeviz.

```bash
pip install -e ".[profile]"   # scalene, line_profiler, memory_profiler, py-spy, snakeviz
```

--------------------------------

### Install tsbootstrap with compiled backend (pip install)

Source: https://github.com/astrogilda/tsbootstrap/blob/main/README.md

Alternative installation command using pip for the same [accel] extra.

```sh
pip install "tsbootstrap[accel]"
```

--------------------------------

### Install tsbootstrap with uv or pip

Source: https://github.com/astrogilda/tsbootstrap/blob/main/README.md

Installation commands for core and `models` extras using uv and pip. The `models` extra adds statsmodels for ARIMA.

```sh
# 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]"
```

--------------------------------

### Choosing a bootstrap method

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/quickstart.rst

Demonstrates all available methods: IID, block methods (MovingBlock, CircularBlock, StationaryBlock, NonOverlappingBlock, TaperedBlock), and residual methods (ResidualBootstrap with AR/ARIMA, SieveAR). Block methods preserve short-range dependence; residual methods regenerate recursively from a fitted model.

```python
from tsbootstrap import (
    bootstrap,
    IID, MovingBlock, CircularBlock, StationaryBlock,
    NonOverlappingBlock, TaperedBlock,
    ResidualBootstrap, SieveAR,
    AR, ARIMA, VAR,
)

# Baseline, no serial dependence assumed
bootstrap(x, method=IID())

# Block methods (block_length defaults to "auto" = Politis-White selection)
bootstrap(x, method=MovingBlock())
bootstrap(x, method=CircularBlock())
bootstrap(x, method=StationaryBlock())           # avg_block_length parameter
bootstrap(x, method=NonOverlappingBlock())
bootstrap(x, method=TaperedBlock(window="bartlett"))

# Recursive model-based; 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())
```

--------------------------------

### Install tsbootstrap with compiled backend and arch

Source: https://github.com/astrogilda/tsbootstrap/blob/main/benchmarks/README.md

Prerequisite installation for running benchmarks. Use pip or uv to install tsbootstrap with the 'accel' extra and the arch package.

```sh
# Install tsbootstrap with the compiled backend and arch
pip install "tsbootstrap[accel]"
pip install arch

# Or with uv
uv add "tsbootstrap[accel]" arch
```

--------------------------------

### Install tsbootstrap with compiled backend (uv add)

Source: https://github.com/astrogilda/tsbootstrap/blob/main/README.md

Installs the optional compiled backend via the [accel] extra using uv. Required to use backend="compiled" for faster reduce paths.

```sh
uv add "tsbootstrap[accel]"
```

--------------------------------

### Install tsbootstrap with compiled backend extra

Source: https://github.com/astrogilda/tsbootstrap/blob/main/benchmarks/README.md

Install the optional compiled backend powered by numba using the [accel] extra. Required before using backend="compiled" in bootstrap or bootstrap_reduce. The default backend remains available without extra dependencies.

```shell
pip install "tsbootstrap[accel]"
# or
uv add "tsbootstrap[accel]"
```

--------------------------------

### Install pre-commit hooks

Source: https://github.com/astrogilda/tsbootstrap/blob/main/README.md

Installs pre-commit hooks that run ruff, formatting, and other code-quality checks on each commit.

```sh
uv run pre-commit install
```

--------------------------------

### Basic usage of tsbootstrap.bootstrap()

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/quickstart.rst

Generate an AR(1) series and bootstrap it with the MovingBlock method. Returns a BootstrapResult with samples and out-of-bag mask.

```python
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()      # ndarray shape (999, 200)
oob     = result.get_oob_mask()  # ndarray shape (999, 200)
```

--------------------------------

### Install tsbootstrap with accel extra using uv and pip

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/whats_new_0_3_0.rst

Install the compiled backend's required extra. The default numpy backend has no extra dependencies.

```sh
# with uv (recommended):
uv add "tsbootstrap[accel]"

# with pip:
pip install "tsbootstrap[accel]"
```

--------------------------------

### Output for random walk, near-i.i.d., and bivariate series

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/which_bootstrap_when.ipynb

Shows the recommended methods for the remaining three series: random walk gets ('ResidualBootstrap(model=ARIMA(...))', 'SieveAR'), near-i.i.d. gets ('IID', 'MovingBlock'), and bivariate gets ('ResidualBootstrap(model=VAR(...))', 'StationaryBlock', 'MovingBlock', 'SieveAR').

```text
Output:
random walk            -> ('ResidualBootstrap(model=ARIMA(...))', 'SieveAR')
near-i.i.d.            -> ('IID', 'MovingBlock')
bivariate (VAR-like)   -> ('ResidualBootstrap(model=VAR(...))', 'StationaryBlock', 'MovingBlock', 'SieveAR')

```

--------------------------------

### Install tsbootstrap with sktime extras

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/adapters_guide.rst

Install the package with the sktime extra to enable the adapters. Use uv or pip as shown.

```sh
uv add "tsbootstrap[sktime]"     # or: pip install "tsbootstrap[sktime]"
```

--------------------------------

### Use sktime adapter MovingBlockBootstrap

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/quickstart.rst

Use the sktime-compatible estimator class from tsbootstrap.adapters. Each sample is an ndarray of shape (n,).

```python
from tsbootstrap.adapters import MovingBlockBootstrap

est = MovingBlockBootstrap(block_length=10, n_bootstraps=100, random_state=0)
for sample in est.bootstrap(x):
    ...  # each sample is an ndarray of shape (n,)
```

--------------------------------

### Reproducible results with random_state

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/quickstart.rst

Passing the same integer seed to random_state yields identical results, even in parallel execution.

```python
r1 = bootstrap(x, method=MovingBlock(), n_bootstraps=100, random_state=42)
r2 = bootstrap(x, method=MovingBlock(), n_bootstraps=100, random_state=42)
import numpy as np
assert np.array_equal(r1.values(), r2.values())
```

--------------------------------

### Get recommended bootstrap methods with diagnose

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/cheat_sheet.ipynb

Call diagnose to programmatically inspect a series for serial dependence and stationarity, returning recommended method specifications as a heuristic starting point. Access the recommendations via the recommended_methods attribute.

```python
from tsbootstrap import diagnose
diagnose(x).recommended_methods
```

--------------------------------

### Verify installation by printing tsbootstrap version

Source: https://github.com/astrogilda/tsbootstrap/blob/main/CONTRIBUTING.md

Confirms the editable install works and prints the installed version.

```sh
uv run python -c "import tsbootstrap; print(tsbootstrap.__version__)"
```

--------------------------------

### Bootstrap a pandas Series

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/quickstart.rst

X can be a pandas Series; it is coerced to a (n, d) float64 array internally.

```python
import pandas as pd

s = pd.Series(x)
result = bootstrap(s, method=MovingBlock(), n_bootstraps=100)
```

--------------------------------

### Install pre-commit and custom hooks

Source: https://github.com/astrogilda/tsbootstrap/blob/main/CONTRIBUTING.md

Installs Ruff lint/format hooks and the version-controlled pre-push gate. The pre-push gate runs Ruff, mypy, and pyright with the same extras CI uses; skip it in an emergency with `PRE_PUSH_SKIP=1 git push`.

```sh
uv run pre-commit install
```

```sh
scripts/install-hooks.sh
```

--------------------------------

### Example workflow: diagnose then bootstrap with ResidualBootstrap

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/diagnostics_guide.rst

Shows a full workflow: generate a random walk, run diagnose() to confirm nonstationarity, then act on the recommendation by bootstrapping with ResidualBootstrap(model=ARIMA(order=(0, 1, 0))). The printed output shows nonstationary is True and recommended methods are ('ResidualBootstrap(model=ARIMA(...))', 'SieveAR').

```python
import numpy as np
from tsbootstrap import bootstrap, diagnose, MovingBlock, StationaryBlock

rng = np.random.default_rng(1)
x = np.cumsum(rng.standard_normal(300))   # random walk

d = diagnose(x)
print(d.nonstationary)        # True
print(d.recommended_methods)  # ('ResidualBootstrap(model=ARIMA(...))', 'SieveAR')

# Act on the recommendation
from tsbootstrap import ResidualBootstrap, ARIMA
result = bootstrap(x, method=ResidualBootstrap(model=ARIMA(order=(0, 1, 0))))
```

--------------------------------

### Plot original series and replicates

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/quickstart.ipynb

Visualizes the original series and five moving-block replicates to show that each replicate preserves local dependence. Uses matplotlib with a figure size of 8x3 inches.

```python
import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(8, 3))
for i in range(5):
    ax.plot(samples[i], color="tab:blue", alpha=0.35, lw=0.8)
ax.plot(x, color="black", lw=1.6, label="original")
ax.set_title("Original series and 5 moving-block replicates")
ax.set_xlabel("time")
ax.legend()
plt.show()
```

```text
Result:
<Figure size 800x300 with 1 Axes>
```

--------------------------------

### Output of test series setup

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/observation_resampling.ipynb

Expected output from the previous setup snippet, showing the lengths of the two test series.

```text
Output:
AR(1): n = 240,  lynx: n = 114
```

--------------------------------

### Get out-of-bag mask

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/quickstart.ipynb

Retrieves the out-of-bag mask from the bootstrap result, showing which points were left out of each replicate. The mean fraction of OOB points per replicate is approximately 0.37.

```python
mask = result.get_oob_mask()
mask.shape, round(float(mask.mean()), 3)  # ~0.37 of points are OOB per replicate
```

```text
Result:
((200, 200), 0.361)
```

--------------------------------

### Run property tests with ci Hypothesis profile

Source: https://github.com/astrogilda/tsbootstrap/blob/main/tests/README.md

Runs property tests using the ci Hypothesis profile, which uses 100 examples and relaxed slow-health checks.

```bash
HYPOTHESIS_PROFILE=ci uv run pytest tests/property/
```

--------------------------------

### enbpi_intervals() and fit_predict_oob()

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/uq_guide.rst

Thin wrappers for the simple in-sample, static-width path of EnbPI. They cover the basic usage without explicit calibration.

```APIDOC
## enbpi_intervals() and fit_predict_oob()

### Description
Thin wrappers for the simple in-sample, static-width path of EnbPI. They cover the basic usage without explicit calibration.

### Method
Function call

### Endpoint
`enbpi_intervals(...)` and `fit_predict_oob(...)`

### Parameters
#### Function Parameters
- Parameters are not explicitly documented in the source; refer to the EnbPIEnsemble interface for typical arguments.

### Request Example
```python
# Usage not explicitly shown in source
```

### Response
#### Success Response
- Returns prediction intervals and point estimates.

#### Response Example
```python
# Returns tuple (lower, upper, point)
```
```

--------------------------------

### Generate a stationary AR(1) series

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/quickstart.ipynb

Creates a stationary AR(1) process with known dependence structure (phi=0.6, n=200) using a seeded random generator. The first five values are displayed.

```python
import numpy as np

rng = np.random.default_rng(0)
n, phi = 200, 0.6
x = np.zeros(n)
for t in range(1, n):
    x[t] = phi * x[t - 1] + rng.standard_normal()
x[:5]
```

```text
Result:
array([ 0.        ,  0.12573022, -0.05666673,  0.60642261,  0.46875368])
```

--------------------------------

### Run the MCP server with uvx

Source: https://github.com/astrogilda/tsbootstrap/blob/main/README.md

Starts the read-only MCP server using `uvx` with the `mcp` extra. The server exposes two tools: `diagnose_series` and `bootstrap_confidence_interval`, both limited to 500 observations and 500 replicates.

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

--------------------------------

### Compiled backend example with bootstrap_reduce_panel

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/whats_new_0_3_0.rst

Shows the compiled backend for panel bootstrap reduction. Requires the [accel] extra and a named reducer (here 'mean'); an arbitrary callable raises MethodConfigError. Results are equal in distribution to the numpy path but not bit-identical.

```python
import numpy as np
from tsbootstrap import bootstrap_reduce_panel, MovingBlock

rng = np.random.default_rng(0)
panel = [rng.standard_normal(n) for n in range(100, 600, 50)]  # 10 series

# Compiled path (requires [accel] extra)
result = bootstrap_reduce_panel(
    panel,
    method=MovingBlock(block_length="auto"),
    statistic="mean",
    n_bootstraps=9999,
    random_state=0,
    backend="compiled",
)
print(result.statistics.shape)  # (9999, 10)
```

--------------------------------

### Compute BCa confidence interval for the mean

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/quickstart.ipynb

Uses conf_int with IID() method and kind="bca" to return a bias-corrected and accelerated confidence interval for the mean at alpha=0.1. Prints the 90% interval.

```python
from tsbootstrap import IID, conf_int

lower, upper, point = conf_int(x, "mean", method=IID(), kind="bca", alpha=0.1)
print(f"90% BCa interval for the mean: [{float(lower):.3f}, {float(upper):.3f}]")
```

```text
Output:
90% BCa interval for the mean: [-0.099, 0.182]
```

--------------------------------

### Run test suite with coverage

Source: https://github.com/astrogilda/tsbootstrap/blob/main/DEVELOPER_NOTES.md

Coverage is configured under `[tool.coverage.run]` with source set to `src/` and tests omitted. The command runs pytest with parallel execution and generates an HTML coverage report.

```bash
uv run pytest tests/ -n auto --dist loadscope --cov=src/tsbootstrap --cov-report=html
```

--------------------------------

### forecast_intervals()

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/uq_guide.rst

Simulates a fitted model forward over a horizon and returns per-step empirical quantiles. Supports the AR model only in this release.

```APIDOC
## forecast_intervals()

### Description
Simulates a fitted model forward over a horizon and returns per-step empirical quantiles. Supports the AR model only in this release.

### Method
Function call

### Signature
```python
forecast_intervals(x, model=AR(order=2), horizon=12, alpha=0.1, random_state=0)
```

### Parameters
- **x** (array-like) - Required - Input time series data.
- **model** (AR) - Optional - The fitted model to simulate forward. Default is `AR(order=2)`.
- **horizon** (int) - Optional - Number of steps to forecast ahead. Default is 12.
- **alpha** (float) - Optional - Significance level for quantiles. Default is 0.1.
- **random_state** (int) - Optional - Seed for random number generation. Default is 0.

### Returns
- **lower** (array) - Lower bound of the forecast interval.
- **upper** (array) - Upper bound of the forecast interval.
- **median** (array) - Median forecast.

### Example
```python
from tsbootstrap import AR, forecast_intervals

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

--------------------------------

### Generate forecast intervals with forecast_intervals

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/uq_guide.rst

Simulates a fitted AR model forward over a horizon and reads per-step empirical quantiles. Supports only the AR model in this release; ARIMA and VAR are planned.

```python
from tsbootstrap import AR, forecast_intervals

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

--------------------------------

### Sync development environment with uv sync --extra dev

Source: https://github.com/astrogilda/tsbootstrap/blob/main/CONTRIBUTING.md

Run from the project root after cloning. Builds the locked virtual environment with an editable install so edits take effect immediately; invoke tools with `uv run`.

```sh
uv sync --extra dev
```

--------------------------------

### diagnose

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/cheat_sheet.ipynb

Inspects a time series for serial dependence and stationarity, and returns recommended bootstrap method specifications. Treat as a heuristic starting point.

```APIDOC
## diagnose

### Description
Inspects a time series for serial dependence and stationarity, and returns recommended bootstrap method specifications. Treat as a heuristic starting point.

### Method
Function call

### Endpoint
`diagnose(x)`

### Parameters
- **x** (array-like) - Required - The time series to diagnose.

### Returns
- **recommended_methods** - Recommended bootstrap method specifications.

### Example
```python
from tsbootstrap import diagnose
diagnose(x).recommended_methods
```
```

--------------------------------

### Run diagnose() on four example series

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/which_bootstrap_when.ipynb

Creates four time series with different structures (AR(1) stationary, random walk, near-i.i.d., bivariate VAR-like) and runs diagnose() on each, printing the recommended methods. Uses a fixed random seed for reproducibility.

```python
rng = np.random.default_rng(7)
series_ar1 = ar1(600, PHI, rng)
series_rw = np.cumsum(rng.standard_normal(600))  # random walk (unit root)
series_iid = rng.standard_normal(600)  # near-i.i.d.
series_var = np.column_stack([ar1(600, 0.6, rng), ar1(600, 0.6, rng)])  # bivariate

examples = {
    "AR(1) stationary": series_ar1,
    "random walk": series_rw,
    "near-i.i.d.": series_iid,
    "bivariate (VAR-like)": series_var,
}
for name, s in examples.items():
    d = diagnose(s)
    print(f"{name:22s} -> {d.recommended_methods}")
```

--------------------------------

### Run full and targeted test suites with uv run pytest

Source: https://github.com/astrogilda/tsbootstrap/blob/main/DEVELOPER_NOTES.md

Runs the test suite under the project's own interpreter. A bare pytest run is single-process. Use the full suite command or target unit or property-based tests.

```bash
uv run pytest tests/          # full suite
```

```bash
uv run pytest tests/unit      # unit tests
```

```bash
uv run pytest tests/property  # property-based (Hypothesis) tests
```

--------------------------------

### Run a moving block bootstrap

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/quickstart.ipynb

Calls bootstrap with MovingBlock(block_length="auto") which uses the Politis-White rule to pick block length. Returns a result with samples, provenance, and out-of-bag primitives. The shape of samples is (n_bootstraps, n).

```python
from tsbootstrap import MovingBlock, bootstrap

result = bootstrap(x, method=MovingBlock(block_length="auto"), n_bootstraps=200, random_state=0)
samples = result.values()
samples.shape  # (n_bootstraps, n)
```

```text
Result:
(200, 200)
```

--------------------------------

### StationaryBlock

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/methods_guide.rst

Stationary bootstrap (Politis-Romano 1994). Block lengths are drawn from a geometric distribution with mean avg_block_length; restart points are uniformly distributed (true Politis-Romano; not deterministic starts). The resulting distribution is exactly stationary.

```APIDOC
## StationaryBlock

### Description
Stationary bootstrap (Politis-Romano 1994). Block lengths are drawn from a geometric distribution with mean `avg_block_length`; restart points are uniformly distributed (true Politis-Romano; not deterministic starts). The resulting distribution is exactly stationary.

### Constructor
```python
from tsbootstrap import StationaryBlock
method = StationaryBlock(avg_block_length="auto")
```

### Parameters
- **avg_block_length** (str or int) - Optional - Average block length. Defaults to `"auto"` for automatic selection.

```

--------------------------------

### Run quality gates with uv run (mypy, pyright, ruff)

Source: https://github.com/astrogilda/tsbootstrap/blob/main/DEVELOPER_NOTES.md

All tooling runs through `uv run` using pinned versions from the `dev` extra. The mypy gate is strict-minus, pyright is strict, and ruff format uses line length 100.

```bash
uv run mypy src/tsbootstrap      # strict-minus typing gate (config: [tool.mypy])
uv run pyright                   # strict type checking (config: [tool.pyright])
uv run ruff check src/ tests/    # lint (config: [tool.ruff])
uv run ruff format src/ tests/   # formatting (line length 100)
```

--------------------------------

### StationaryBlock method specification

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/methods_guide.rst

Stationary bootstrap (Politis-Romano 1994). Block lengths are drawn from a geometric distribution with mean avg_block_length; restart points are uniformly distributed (true Politis-Romano; not deterministic starts). The resulting distribution is exactly stationary.

```python
from tsbootstrap import StationaryBlock
method = StationaryBlock(avg_block_length="auto")
```

--------------------------------

### bootstrap(x, ..., backend="compiled")

Source: https://github.com/astrogilda/tsbootstrap/blob/main/benchmarks/README.md

Fast, reproducible samples with opt-in speed. Uses a compiled backend for improved performance.

```APIDOC
## bootstrap(x, ..., backend="compiled")

### Description
Fast, reproducible samples with opt-in speed. Uses a compiled backend for improved performance.

### Method
Function call

### Endpoint
bootstrap(x, ..., backend="compiled")

### Parameters
- **x** (array-like) - Required - Input data.
- **backend** (str) - Optional - Backend to use (default "compiled").
- **...** - Additional arguments (e.g., method, n_bootstraps).

### Response
Returns bootstrap samples.
```

--------------------------------

### conf_int() with IID method and BCa interval

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/uq_guide.rst

Runs a single bootstrap pass to compute a confidence interval for a statistic of one series. The example uses the built-in 'mean' statistic, the IID method spec, the 'bca' interval family, and alpha=0.1. The statistic can also be a ('quantile', q) tuple or a callable, as with bootstrap_reduce().

```python
import numpy as np
from tsbootstrap import IID, conf_int

x = np.random.default_rng(0).standard_normal(100)
lower, upper, point = conf_int(x, "mean", method=IID(), kind="bca", alpha=0.1)
```

--------------------------------

### Run mutation testing with mutmut

Source: https://github.com/astrogilda/tsbootstrap/blob/main/DEVELOPER_NOTES.md

Runs the mutation-score ratchet over the engine and model core. `NUMBA_DISABLE_JIT=1` is required to avoid cache-masking of the `@njit` VAR kernel, and `HYPOTHESIS_PROFILE=mutmut` selects the derandomized profile for reproducibility. `only_mutate` restricts mutation to `src/tsbootstrap/engines/*` and `src/tsbootstrap/model/*`.

```bash
NUMBA_DISABLE_JIT=1 HYPOTHESIS_PROFILE=mutmut uv run mutmut run
```

--------------------------------

### bootstrap(x, method=..., n_bootstraps=B)

Source: https://github.com/astrogilda/tsbootstrap/blob/main/benchmarks/README.md

Fast, reproducible samples (default). This is the primary entry point for generating bootstrap samples.

```APIDOC
## bootstrap(x, method=..., n_bootstraps=B)

### Description
Fast, reproducible samples (default). This is the primary entry point for generating bootstrap samples.

### Method
Function call

### Endpoint
bootstrap(x, method=..., n_bootstraps=B)

### Parameters
- **x** (array-like) - Required - Input data.
- **method** (str) - Optional - Bootstrap method (e.g., 'residual', 'block', etc.).
- **n_bootstraps** (int) - Optional - Number of bootstrap samples (default B).

### Response
Returns bootstrap samples.
```

--------------------------------

### Plot forecast fan with training series, band, median, and actuals

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/forecast_intervals.ipynb

Creates a matplotlib figure showing the tail of the training series, the 90% forecast band, the forecast median, and the held-out actuals, anchored at the last observed training point. Uses a colorblind-safe palette and annotates the forecast start.

```python
tail = 30
years = np.arange(len(lynx))
train_years = years[:-HOLDOUT]
fut_years = years[-HOLDOUT:]

# Anchor the forecast at the last observed training point so the fan, the median,
# and the actuals all start from the data rather than floating one step to the right.
anchor_year = train_years[-1]
anchor_val = lynx[:-HOLDOUT][-1]
band_years = np.concatenate(([anchor_year], fut_years))
lo_p = np.concatenate(([anchor_val], lo))
up_p = np.concatenate(([anchor_val], up))
med_p = np.concatenate(([anchor_val], med))
act_p = np.concatenate(([anchor_val], actual))

# Okabe-Ito colorblind-safe palette.
C_TRAIN = "#000000"
C_FCST = "#0072B2"  # blue
C_ACTUAL = "#D55E00"  # vermillion

fig, ax = plt.subplots(figsize=(9, 4.8), layout="constrained")
ax.plot(
    train_years[-tail:],
    lynx[:-HOLDOUT][-tail:],
    color=C_TRAIN,
    lw=1.6,
    label="training series (observed)",
)
ax.fill_between(band_years, lo_p, up_p, color=C_FCST, alpha=0.22, label="90% forecast band")
ax.plot(band_years, med_p, color=C_FCST, lw=2.0, ls="--", marker="s", ms=4, label="forecast median")
ax.plot(band_years, act_p, color=C_ACTUAL, lw=2.0, marker="o", ms=5, label="actual (held out)")
ax.axvline(anchor_year, color="0.5", ls=":", lw=1.2)
ax.annotate(
    "forecast start",
    xy=(anchor_year, ax.get_ylim()[1]),
    xytext=(4, -10),
    textcoords="offset points",
    color="0.4",
    fontsize=9,
    ha="left",
    va="top",
)
ax.set_xlabel("year index (annual observation)")
ax.set_ylabel("lynx pelts (count)")
ax.set_title("AR(4) 90% band covers the held-out lynx counts; the median misses the peak")
ax.grid(True, alpha=0.3)
ax.legend(fontsize=9, loc="upper left", framealpha=0.9)
plt.show()
```

--------------------------------

### Generate forecast intervals on log-transformed lynx series

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/forecast_intervals.ipynb

Loads the lynx series, transforms to log scale, holds out the last 8 years, and computes 90% forecast intervals using an AR(4) model. Prints the forecast horizon, shapes of the lower/upper/median arrays, and the first-year band in pelts.

```python
from sktime.datasets import load_lynx

lynx = np.asarray(load_lynx(), dtype=float)
log_lynx = np.log(lynx)

HOLDOUT = 8
train = log_lynx[:-HOLDOUT]
actual = lynx[-HOLDOUT:]  # the held-out years, on the original count scale

lo_log, up_log, med_log = forecast_intervals(
    train, model=AR(order=4), horizon=HOLDOUT, alpha=0.1, random_state=0
)
lo, up, med = np.exp(lo_log), np.exp(up_log), np.exp(med_log)
print("forecast horizon:", HOLDOUT)
print("lower/upper/median shapes:", lo.shape, up.shape, med.shape)
print(f"90% band, year ahead +1: [{lo[0]:.0f}, {up[0]:.0f}] pelts")
```

--------------------------------

### Monte-Carlo coverage check for forecast_intervals

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/forecast_intervals.ipynb

Fits an 80% forecast band from a single AR(2) realisation, then draws 2000 fresh future paths from the true AR(2) process to measure per-step hit rates. The mean coverage should be near the nominal 0.80; small deviations are expected due to sampling noise and asymptotic bootstrap coverage.

```python
rng = np.random.default_rng(0)
n, H, alpha = 400, 8, 0.2  # 80% nominal coverage
x = ar2(n, rng)

lo_c, up_c, med_c = forecast_intervals(
    x, model=AR(order=2), horizon=H, alpha=alpha, n_bootstraps=999, random_state=0
)

M = 2000  # fresh future paths
last = x[-P:]
hits = np.zeros(H)
for _ in range(M):
    path = np.empty(H + P)
    path[:P] = last
    e = rng.standard_normal(H)
    for h in range(H):
        path[P + h] = PHI[0] * path[P + h - 1] + PHI[1] * path[P + h - 2] + e[h]
    future = path[P:]
    hits += ((future >= lo_c) & (future <= up_c)).astype(float)

coverage = hits / M
print("per-step coverage:", np.round(coverage, 3))
print(f"mean coverage:    {coverage.mean():.3f}   (nominal {1 - alpha:.2f})")
```

```text
Output:
per-step coverage: [0.78  0.815 0.762 0.774 0.799 0.794 0.783 0.784]
mean coverage:    0.786   (nominal 0.80)
```

--------------------------------

### ARIMA

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/methods_guide.rst

ARMA model with differencing for use with ResidualBootstrap.

```APIDOC
## ARIMA

### Description
ARMA model with differencing for use with ResidualBootstrap.

### Constructor
`ARIMA(order=(1, 1, 1), burn_in=0, initial="fixed", stability_policy="raise")`

### Parameters
- **order** (tuple) - Required - ARIMA order (p, d, q).
- **burn_in** (int) - Optional - Number of initial samples to discard. Defaults to 0.
- **initial** (str) - Optional - Initialization method. Defaults to "fixed".
- **stability_policy** (str) - Optional - Policy for non-stationary fits. Defaults to "raise".

### Usage Example
```python
from tsbootstrap import ARIMA
model = ARIMA(order=(1, 1, 1))
```

### Notes
- SARIMA is not yet supported; raises TSB_UNSUPPORTED_MODEL_FEATURE.
```

--------------------------------

### AR

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/methods_guide.rst

Autoregressive model of fixed order for use with ResidualBootstrap.

```APIDOC
## AR

### Description
Autoregressive model of fixed order for use with ResidualBootstrap.

### Constructor
`AR(order, burn_in=0, initial="fixed", stability_policy="raise")`

### Parameters
- **order** (int) - Required - Order of the autoregressive model.
- **burn_in** (int) - Optional - Number of initial samples to discard. Defaults to 0.
- **initial** (str) - Optional - Initialization method. Defaults to "fixed".
- **stability_policy** (str) - Optional - Policy for non-stationary fits. Defaults to "raise".

### Usage Example
```python
from tsbootstrap import AR
model = AR(order=2)
```
```

--------------------------------

### VAR

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/methods_guide.rst

Vector autoregression for multivariate series with shape (n, d) where d >= 2.

```APIDOC
## VAR

### Description
Vector autoregression for multivariate series with shape (n, d) where d >= 2.

### Constructor
`VAR(order, burn_in=0, initial="fixed", stability_policy="raise")`

### Parameters
- **order** (int) - Required - Order of the vector autoregressive model.
- **burn_in** (int) - Optional - Number of initial samples to discard. Defaults to 0.
- **initial** (str) - Optional - Initialization method. Defaults to "fixed".
- **stability_policy** (str) - Optional - Policy for non-stationary fits. Defaults to "raise".

### Usage Example
```python
from tsbootstrap import VAR
model = VAR(order=1)
```
```

--------------------------------

### ARIMA model spec

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/methods_guide.rst

ARMA with differencing. SARIMA is not yet supported and raises `TSB_UNSUPPORTED_MODEL_FEATURE`.

```python
ARIMA(order=(1, 1, 1), burn_in=0, initial="fixed", stability_policy="raise")
```

--------------------------------

### Run all deterministic profilers

Source: https://github.com/astrogilda/tsbootstrap/blob/main/profiling/README.md

Executes cProfile, line_profiler, and tracemalloc in one shot. Reports are written to profiling/REPORTS/.

```bash
python -m profiling.run_all
```

--------------------------------

### Push changes with git push

Source: https://github.com/astrogilda/tsbootstrap/wiki/Contributor's-Guide

Pushes the local branch to the forked repository on GitHub.

```sh
git push origin new-feature-branch
```

--------------------------------

### Plot interval width vs. horizon for AR(2) forecast

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/forecast_intervals.ipynb

Generates a 600-step AR(2) series, computes 90% forecast intervals for a 20-step horizon with 999 bootstraps, and plots the interval width against the horizon. The plot shows the width rising from the one-step value and flattening at the process-variance ceiling. Prints the widths at step 1 and step 20.

```python
rng = np.random.default_rng(1)
x_long = ar2(600, rng)
H_long = 20
lo_w, up_w, _ = forecast_intervals(
    x_long, model=AR(order=2), horizon=H_long, alpha=0.1, n_bootstraps=999, random_state=1
)
width = up_w - lo_w
steps = np.arange(1, H_long + 1)

fig, ax = plt.subplots(figsize=(8, 4.4), layout="constrained")
ax.plot(
    steps,
    width,
    "o-",
    color="#009E73",
    lw=1.8,
    ms=5,  # Okabe-Ito green
    label="90% interval width",
)
# Mark the one-step width and the long-horizon plateau so the rise is legible.
ax.axhline(width[0], color="0.6", ls=":", lw=1.0)
ax.annotate(
    "one-step width",
    xy=(1, width[0]),
    xytext=(2.5, width[0] - 0.18),
    color="0.4",
    fontsize=9,
    va="top",
)
ax.set_xlabel("forecast horizon (steps ahead)")
ax.set_ylabel("90% interval width (series units)")
ax.set_title("Interval width rises, then flattens at the AR(2) process-variance ceiling")
ax.set_xticks(steps[::2])
ax.margins(y=0.15)
ax.grid(True, alpha=0.3)
ax.legend(fontsize=9, loc="lower right", framealpha=0.9)
plt.show()

print(f"width at step 1: {width[0]:.2f}")
print(f"width at step {H_long}: {width[-1]:.2f}")
```

```text
Result:
<Figure size 800x440 with 1 Axes>
```

```text
Output:
width at step 1: 3.29
width at step 20: 3.67

```

--------------------------------

### Static

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/uq_guide.rst

A calibrator that uses one global quantile, the same width everywhere. Use when residuals are stationary.

```APIDOC
## Static

### Description
A calibrator that uses one global quantile, the same width everywhere. Use when residuals are stationary.

### Usage
Select with a frozen spec from `tsbootstrap.uq.calibrators` and pass to `predict_interval(calibrator=SomeSpec(...))`.

### Parameters
No parameters documented.
```

--------------------------------

### Commit changes with git commit

Source: https://github.com/astrogilda/tsbootstrap/wiki/Contributor's-Guide

Commits changes to the local branch with a clear commit message.

```sh
git commit -m 'Implemented new feature.'
```

--------------------------------

### VAR model spec

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/methods_guide.rst

Vector autoregression for multivariate series. `X` must have shape `(n, d)` with `d >= 2`.

```python
VAR(order=1, burn_in=0, initial="fixed", stability_policy="raise")
```

--------------------------------

### enbpi_intervals

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/api_uq.rst

Thin wrapper for the simple in-sample, static-width path.

```APIDOC
## enbpi_intervals

### Description
Thin wrapper for the simple in-sample, static-width path. Fits an EnbPI ensemble and returns intervals for the training data.

### Method
enbpi_intervals

### Parameters
- **estimator** (object) - Required - An unfitted, order-invariant sklearn-style regressor.
- **X** (array-like) - Required - Design matrix `(n, d)`.
- **y** (array-like) - Required - Targets `(n,)`.
- **method** (object) - Required - An observation-resampling method.
- **n_bootstraps** (int) - Optional - Number of bootstrap replicates. Default: 100.
- **random_state** (object) - Optional - Seed or generator.
- **alpha** (float) - Required - Significance level.

### Returns
- **array-like** - Intervals of shape `(n, 2)`.
```

--------------------------------

### AR model spec

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/methods_guide.rst

Autoregressive model of fixed order. Parameters include `burn_in`, `initial`, and `stability_policy`.

```python
AR(order=2, burn_in=0, initial="fixed", stability_policy="raise")
```

--------------------------------

### SieveAR

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/methods_guide.rst

Sieve bootstrap method that selects AR order using an information criterion and runs the AR recursion.

```APIDOC
## SieveAR

### Description
Sieve bootstrap method that selects AR order using an information criterion and runs the AR recursion.

### Constructor
`SieveAR(min_lag=1, max_lag=None, criterion="bic")`

### Parameters
- **min_lag** (int) - Optional - Minimum lag for order selection. Defaults to 1.
- **max_lag** (int or None) - Optional - Maximum lag for order selection. Defaults to None.
- **criterion** (str) - Optional - Information criterion to use: "aic", "bic", or "hqic". Defaults to "bic".

### Usage Example
```python
from tsbootstrap import SieveAR
method = SieveAR(min_lag=1, max_lag=None, criterion="bic")
```
```

--------------------------------

### Replay a random run using recorded seed_entropy

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/provenance_and_scaling.ipynb

Shows how to reproduce a run that used `random_state=None` by feeding the recorded `seed_entropy` back as a `np.random.SeedSequence`. The output confirms that `random_state_kind` is `'none'` and that the replay produces identical values.

```python
# The recorded entropy replays a 'random' run exactly.
auto = bootstrap(x, method=MovingBlock(block_length=10), n_bootstraps=50, random_state=None)
recorded = auto.metadata.seed_entropy
print(f"random_state_kind: {auto.metadata.random_state_kind!r}")
print(f"recorded seed_entropy: {recorded}")

replay = bootstrap(
    x,
    method=MovingBlock(block_length=10),
    n_bootstraps=50,
    random_state=np.random.SeedSequence(recorded),
)
print(
    f"replay from recorded entropy reproduces the run: {np.array_equal(auto.values(), replay.values())}"
)
```

```text
Output:
random_state_kind: 'none'
recorded seed_entropy: 241030189321615554197432467218918731436
replay from recorded entropy reproduces the run: True
```

--------------------------------

### Define AR(2) data-generating process and import forecast_intervals

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/tutorials/forecast_intervals.ipynb

Sets up a stationary AR(2) data-generating process with unit-variance Gaussian noise and true mean 0. Imports forecast_intervals and related classes from tsbootstrap, and defines the AR(2) coefficients used as ground truth.

```python
import matplotlib.pyplot as plt
import numpy as np

from tsbootstrap import AR, ARIMA, VAR, forecast_intervals
from tsbootstrap.errors import MethodConfigError

PHI = (0.5, -0.3)  # stationary AR(2) coefficients we will reuse as ground truth
P = len(PHI)


def ar2(n, rng, phi=PHI, burn=100):
    """Stationary AR(2) with unit-variance Gaussian noise, true mean 0."""
    z = np.zeros(n + burn)
    e = rng.standard_normal(n + burn)
    for t in range(len(phi), n + burn):
        z[t] = phi[0] * z[t - 1] + phi[1] * z[t - 2] + e[t]
    return z[burn:]
```

--------------------------------

### Run a Single Test File or Test

Source: https://github.com/astrogilda/tsbootstrap/blob/main/tests/README.md

Runs a specific test file or a single test within a file. Use the `::` syntax to target a specific test function.

```bash
uv run pytest tests/unit/test_uq.py
```

```bash
uv run pytest tests/unit/test_uq.py::test_enbpi_coverage
```

--------------------------------

### Import method specs from tsbootstrap

Source: https://github.com/astrogilda/tsbootstrap/blob/main/docs/source/methods_guide.rst

All method specifications are importable directly from the tsbootstrap package. The full union type is MethodSpec.

```python
from tsbootstrap import MovingBlock, ResidualBootstrap, AR
```
Tokens:
Raw