tsbootstrap 0.2.0

A Python package to generate bootstrapped time series

Generate bootstrapped samples from time-series data. The full documentation is available here.

📒 Table of Contents

1. 🚀 Getting Started
2. 🧩 Modules
3. 🗺 Roadmap
4. 🤝 Contributing
5. 📄 License
6. 📍 Time Series Bootstrapping Methods intro
7. 👏 Contributors

---

🚀 Getting Started

🎮 Using tsbootstrap

tsbootstrap exposes one typed entry point, bootstrap, configured with a method specification. The same call works for every method.

import numpy as np
from tsbootstrap import bootstrap, MovingBlock

x = np.random.default_rng(0).standard_normal(200)

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

Choose a method spec for the structure you need (block lengths default to the automatic Politis-White selection):

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

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

# recursive model-based bootstraps (need the model extra: pip install "tsbootstrap[models]")
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)

Inputs can be NumPy arrays, lists, or pandas / Polars DataFrames and Series. The result is a BootstrapResult carrying the samples, provenance metadata, and out-of-bag / in-bag primitives. For the sktime ecosystem, the same methods are also available as estimator classes (MovingBlockBootstrap, ResidualBootstrap, …) under tsbootstrap.adapters.

📦 Installation

Requires Python 3.10 or higher.

pip install tsbootstrap              # core: i.i.d. and block methods
pip install "tsbootstrap[models]"    # adds AR / ARIMA / VAR / sieve (statsmodels)

The model-based methods import statsmodels lazily and raise a clear install hint if the models extra is missing.

🧩 Modules

The package is small and layered around the functional core:

Area	Module(s)	Role
Public API	api.py, methods.py, results.py, errors.py, diagnostics.py	the bootstrap() entry point, typed method specs, structured results, error taxonomy, and diagnose()
Infrastructure	rng.py, validation.py, dispatch.py, metadata.py	deterministic RNG contract, input coercion (incl. the narwhals DataFrame boundary), spec → executor dispatch, method metadata
Block methods	block/	vectorized index kernels, true Politis-Romano stationary, energy-normalized tapering, PWSD block length, OOB primitives
Model methods	model/, engines/	model fitting, stability guards, and recursive AR/ARMA/VAR simulation
Ecosystem	adapters/	skbase / sktime estimator classes over the functional core

🗺 Roadmap

This is an abridged version; for the complete and evolving list of plans and improvements, see Issue #144.

• Performance and Scaling: handling large datasets, distributed backend integration (Dask, Spark, Ray), profiling/optimization
• Tuning and AutoML: adaptive block length, adaptive resampling, evaluation based parameter selection
• Real-time and Stream Data: stream bootstraps, data update interface
• Stage 2 sktime Integration: evaluation module, datasets, benchmarks, sktime forecasters in bootstraps
• API and Capability Extension: panel/hierarchical data, exogenous data, update/stream, model state management
• Scope Extension (TBD): time series augmentation, fully probabilistic models

🤝 Contributing

We welcome contributions.

See our good first issues for getting started.

Below is a quick start guide to contributing.

Developer setup

1. Fork the tsbootstrap repository

2. Clone the fork to local:

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

3. In the local repository root, set up a python environment, e.g., venv or conda.

4. Editable install via pip, including developer dependencies:

pip install -e ".[dev]"

The editable install ensures that changes to the package are reflected in your environment.

5. Set up git hooks and pre-commit:

# Install pre-commit hooks
pre-commit install

# Configure git to use the project's hooks
git config core.hooksPath .githooks

This ensures that docs requirements stay in sync with pyproject.toml and other code quality checks run automatically.

Verifying the Installation

After installation, you can verify that tsbootstrap has been installed correctly by checking its version or by trying to import it in Python:

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

This command should output the version number of tsbootstrap without any errors, indicating that the installation was successful.

Contribution workflow

Please follow these steps:

3. Create a new branch with a descriptive name (e.g., new-feature-branch or bugfix-issue-123).

git checkout -b new-feature-branch

4. Make changes to the project's codebase.
5. Commit your changes to your local branch with a clear commit message that explains the changes you've made.

git commit -m 'Implemented new feature.'

6. Push your changes to your forked repository on GitHub using the following command

git push origin new-feature-branch

7. Create a new pull request to the original project repository. In the pull request, describe the changes you've made and why they're necessary. The project maintainers will review your changes and provide feedback or merge them into the main branch.

🧪 Running Tests

To run all tests, in your developer environment, run:

pytest tests/

The sktime adapter classes can be validated with sktime's estimator checks:

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

check_estimator(MovingBlockBootstrap)

Contribution guide

For more detailed information on how to contribute, please refer to our CONTRIBUTING.md guide.

📄 License

This project is licensed under the ℹ️ MIT License. See the LICENSE file for additional info.

---

👏 Contributors

Thanks goes to these wonderful people:

This project follows the all-contributors specification. Contributions of any kind welcome!

---

📍 Time Series Bootstrapping

tsbootstrap implements bootstrapping methods for time series data. It generates resampled copies of univariate and multivariate series that preserve their chronological order and dependence structure.

Overview

Traditional bootstrap methods resample observations independently, which breaks the dependence in a time series: each observation usually depends on the ones before it. Time series bootstraps resample while preserving chronological order and correlation, so the resulting uncertainty estimates stay valid under that dependence.

Bootstrapping methodology

tsbootstrap resamples either the observations directly (i.i.d. and block methods) or the innovations of a fitted model (residual and sieve methods), respecting the chronological order and dependence structure of the data.

Block bootstrap

Block methods resample blocks of consecutive observations to preserve short-range dependence. The block length defaults to the automatic Politis-White (2004) selection.

• Moving block (MovingBlock): overlapping fixed-length blocks (Kunsch 1989).
• Circular block (CircularBlock): blocks wrap around the series end (Politis-Romano 1992).
• Stationary block (StationaryBlock): geometric block lengths with independent uniform restart points (Politis-Romano 1994).
• Non-overlapping block (NonOverlappingBlock): disjoint blocks (Carlstein 1986).
• Tapered block (TaperedBlock(window=...)): blocks weighted by an energy-normalized window (Bartlett, Blackman, Hamming, Hann, or Tukey; Paparoditis-Politis 2001).

Residual bootstrap

For dependent data with a good model fit, ResidualBootstrap(model=...) regenerates the series recursively from the fitted dynamics and resampled, centered innovations (not fitted + residuals). Supported models: AR, ARIMA, and VAR (multivariate). A non-stationary fit is refused (or skipped, per stability_policy) rather than producing explosive paths.

Sieve bootstrap

SieveAR selects an autoregressive order on the original series, then runs the AR recursion; suited to data with autoregressive structure.

Deferred to a later release

Markov resampling, the distribution bootstrap, GARCH/volatility models, and frequency-domain / seasonal block methods are planned for a future version. The statistic-preserving method has been removed.