tsbootstrap 0.1.0__tar.gz → 0.1.2__tar.gz

{tsbootstrap-0.1.0/src/tsbootstrap.egg-info → tsbootstrap-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: tsbootstrap
-Version: 0.1.0
+Version: 0.1.2
 Summary: A Python package to generate bootstrapped time series
 Author-email: Sankalp Gilda <sankalp.gilda@gmail.com>
 Maintainer-email: Sankalp Gilda <sankalp.gilda@gmail.com>, Franz Kiraly <franz.kiraly@sktime.net>, Benedikt Heidrich <benedikt.heidrich@sktime.net>
@@ -43,16 +43,17 @@ Requires-Python: <3.13,>=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy<1.27,>=1.21
-Requires-Dist: scikit-base<0.8.0,>=0.6.1
-Requires-Dist: scikit-learn<1.5.0,>=0.24
+Requires-Dist: scikit-base<=0.9.0,>=0.8.0
+Requires-Dist: scikit-learn<=1.5.1,>=0.24
 Requires-Dist: scipy<2.0.0,>=1.2
 Requires-Dist: packaging
 Provides-Extra: all-extras
-Requires-Dist: arch<6.0.0,>=5.0.0; extra == "all-extras"
+Requires-Dist: arch<=7.0.0,>=5.0.0; extra == "all-extras"
 Requires-Dist: hmmlearn<0.3.2,>=0.3.0; extra == "all-extras"
 Requires-Dist: pyclustering<0.11.0,>=0.10.0; extra == "all-extras"
 Requires-Dist: scikit_learn_extra<0.4.0,>=0.3.0; extra == "all-extras"
 Requires-Dist: statsmodels<0.15.0,>=0.12.1; extra == "all-extras"
+Requires-Dist: dtaidistance; python_version < "3.10" and extra == "all-extras"
 Provides-Extra: docs
 Requires-Dist: furo; extra == "docs"
 Requires-Dist: jupyter; extra == "docs"
@@ -62,19 +63,30 @@ Requires-Dist: numpydoc; extra == "docs"
 Requires-Dist: pydata-sphinx-theme; extra == "docs"
 Requires-Dist: Sphinx!=7.2.0,<8.0.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
-Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
 Requires-Dist: sphinx-design<0.6.0; extra == "docs"
 Requires-Dist: sphinx-gallery<0.15.0; extra == "docs"
 Requires-Dist: sphinx-issues<4.0.0; extra == "docs"
 Requires-Dist: sphinx-version-warning; extra == "docs"
-Requires-Dist: tabulate; extra == "docs"
+Requires-Dist: tabulate>=0.9.0; extra == "docs"
 Provides-Extra: dev
-Requires-Dist: black; extra == "dev"
+Requires-Dist: black>=24.3.0; extra == "dev"
 Requires-Dist: blacken-docs; extra == "dev"
 Requires-Dist: hypothesis; extra == "dev"
 Requires-Dist: pre-commit; extra == "dev"
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: github-actions; extra == "dev"
+Requires-Dist: importlib-metadata; extra == "dev"
+Requires-Dist: pip-tools; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: autoflake; extra == "dev"
+Requires-Dist: typos; extra == "dev"
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: tox-gh-actions; extra == "dev"
+Requires-Dist: pycobertura; extra == "dev"
+Requires-Dist: tomlkit; extra == "dev"
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 [![All Contributors](https://img.shields.io/github/all-contributors/astrogilda/tsbootstrap?color=ee8449&style=flat-square)](#contributors)
@@ -107,7 +119,7 @@ Requires-Dist: pytest-cov; extra == "dev"
     </a>
     <img src="https://github.com/astrogilda/tsbootstrap/workflows/CI/badge.svg" alt="Build Status"/>
     <a href="https://codecov.io/gh/astrogilda/tsbootstrap"><img src="https://codecov.io/gh/astrogilda/tsbootstrap/branch/main/graph/badge.svg" alt="codecov"/></a>
-    <a href="https://doi.org/10.5281/zenodo.8226496"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.8226496.svg" alt="DOI"/></a>
+    <a href="https://doi.org/10.5281/zenodo.8226495"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.8226495.svg" alt="DOI"/></a>
     <a href="https://codeclimate.com/github/astrogilda/tsbootstrap/maintainability"><img src="https://api.codeclimate.com/v1/badges/d80a0615a8c00f31565c/maintainability" alt="Code Quality"/></a>
     <img src="https://img.shields.io/github/last-commit/astrogilda/tsbootstrap" alt="Last Commit"/>
     <img src="https://img.shields.io/github/issues/astrogilda/tsbootstrap" alt="Issues"/>
@@ -118,94 +130,84 @@ Requires-Dist: pytest-cov; extra == "dev"
 
 
 ## 📒 Table of Contents
-1. [📍 Time Series Bootstrapping](#time-series-bootstrapping)
-    - [Overview](#overview)
-    - [Bootstrapping Methodology](#bootstrapping-methodology)
-    - [Block Bootstrap](#block-bootstrap)
-        - [Moving Block Bootstrap](#moving-block-bootstrap)
-        - [Circular Block Bootstrap](#circular-block-bootstrap)
-        - [Stationary Block Bootstrap](#stationary-block-bootstrap)
-        - [NonOverlapping Block Bootstrap](#nonoverlapping-block-bootstrap)
-        - [Bartletts Bootstrap](#bartletts-bootstrap)
-        - [Blackman Bootstrap](#blackman-bootstrap)
-        - [Hamming Bootstrap](#hamming-bootstrap)
-        - [Hanning Bootstrap](#hanning-bootstrap)
-        - [Tukey Bootstrap](#tukey-bootstrap)
-    - [Residual Bootstrap](#residual-bootstrap)
-    - [Bias Corrected Bootstrap](#bias-corrected-bootstrap)
-    - [Distribution Bootstrap](#distribution-bootstrap)
-    - [Markov Bootstrap](#markov-bootstrap)
-    - [Sieve Bootstrap](#sieve-bootstrap)
-3. [🧩 Modules](#-modules)
-4. [🚀 Getting Started](#-getting-started)
-5. [🗺 Roadmap](#-roadmap)
-6. [🤝 Contributing](#-contributing)
-7. [📄 License](#-license)
-8. [👏 Acknowledgments](#-acknowledgments)
 
-
----
+1. [🚀 Getting Started](#-getting-started)
+2. [🧩 Modules](#-modules)
+3. [🗺 Roadmap](#-roadmap)
+4. [🤝 Contributing](#-contributing)
+5. [📄 License](#-license)
+6. [📍 Time Series Bootstrapping Methods intro](#time-series-bootstrapping)
+7. [👏 Contributors](#-contributors)
 
 
-## 📍 Time Series Bootstrapping
-`tsbootstrap` is a comprehensive project designed to implement an array of bootstrapping techniques specifically tailored for time series data. This project is targeted towards data scientists, statisticians, economists, and other professionals or researchers who regularly work with time series data and require robust methods for generating bootstrapped copies of univariate and multivariate time series data.
 
-### Overview
-Time series bootstrapping is a nuanced resampling method that is applied to time-dependent data. Traditional bootstrapping methods often assume independence between data points, which is an assumption that does not hold true for time series data where a data point is often dependent on previous data points. Time series bootstrapping techniques respect the chronological order and correlations of the data, providing more accurate estimates of uncertainty or variability.
+---
 
-### Bootstrapping Methodology
-The `tsbootstrap` project offers a diverse set of bootstrapping techniques that can be applied to either the entire input time series (classes prefixed with `Whole`), or after partitioning the data into blocks (classes prefixed with `Block`). These methodologies can be applied directly to the raw input data or to the residuals obtained after fitting one of the five statistical models defined in `time_series_model.py` (classes with `Residual` in their names).
+## 🚀 Getting Started
 
-### Block Bootstrap
-Block Bootstrap is a prevalent approach in time series bootstrapping. It involves resampling blocks of consecutive data points, thus respecting the internal structures of the data. There are several techniques under Block Bootstrap, each with its unique approach. `tsbootstrap` provides highly flexible block bootstrapping, allowing the user to specify the block length sampling, block generation, and block resampling strategies. For additional details, refer to `block_length_sampler.py`, `block_generator.py`, and `block_resampler.py`.
 
-The Moving Block Bootstrap, Circular Block Bootstrap, Stationary Block Bootstrap, and NonOverlapping Block Bootstrap methods are all variations of the Block Bootstrap that use different methods to sample the data, maintaining various types of dependencies.
+### 🎮 Using tsbootstrap
 
-Bartlett's, Blackman's, Hamming's, Hanning's, and Tukey's Bootstrap methods are specific implementations of the Block Bootstrap that use different window shapes to taper the data, reducing the influence of data points far from the center. In `tsbootstrap`, these methods inherit from `MovingBlockBootstrap`, but can easily be modified to inherit from any of the other three base block bootstrapping classes.
+`tsbootstrap` provides a unified, `sklearn`-like interface to all bootstrap methods.
 
-Each method comes with its distinct strengths and weaknesses. The choice of method should be based on the characteristics of the data and the specific requirements of the analysis.
+Example using a `MovingBlockBootstrap` - all bootstrap algorithms follow
+the same interface!
 
-#### (i) Moving Block Bootstrap
-This method is implemented in `MovingBlockBootstrap` and is used for time series data where blocks of data are resampled to maintain the dependency structure within the blocks. It's useful when the data has dependencies that need to be preserved. It's not recommended when the data does not have any significant dependencies.
+```python
+from tsbootstrap import MovingBlockBootstrap
+import numpy as np
 
-#### (ii) Circular Block Bootstrap
-This method is implemented in `CircularBlockBootstrap` and treats the data as if it is circular (the end of the data is next to the beginning of the data). It's useful when the data is cyclical or seasonal in nature. It's not recommended when the data does not have a cyclical or seasonal component.
+# Create custom time series data. While below is for univariate time series, the bootstraps can handle multivariate time series as well.
+n_samples = 10
+X = np.arange(n_samples)
 
-#### (iii) Stationary Block Bootstrap
-This method is implemented in `StationaryBlockBootstrap` and randomly resamples blocks of data with block lengths that follow a geometric distribution. It's useful for time series data where the degree of dependency needs to be preserved, and it doesn't require strict stationarity of the underlying process. It's not recommended when the data has strong seasonality or trend components which violate the weak dependence assumption.
+# Instantiate the bootstrap object
+n_bootstraps = 3
+block_length = 3
+rng = 42
+mbb = MovingBlockBootstrap(n_bootstraps=n_bootstraps, rng=rng, block_length=block_length)
+
+# Generate bootstrapped samples
+return_indices = False
+bootstrapped_samples = mbb.bootstrap(
+    X, return_indices=return_indices)
+
+# Collect bootstrap samples
+X_bootstrapped = []
+for data in bootstrapped_samples:
+    X_bootstrapped.append(data)
+
+X_bootstrapped = np.array(X_bootstrapped)
+```
 
-#### (iv) NonOverlapping Block Bootstrap
- This method is implemented in `NonOverlappingBlockBootstrap` and resamples blocks of data without overlap. It's useful when the data has dependencies that need to be preserved and when overfitting is a concern. It's not recommended when the data does not have any significant dependencies or when the introduction of bias due to non-overlapping selection is a concern.
+### 📦 Installation and Setup
 
-#### (v) Bartlett's Bootstrap
- Bartlett's method is a time series bootstrap method that uses a window or filter that tapers off as you move away from the center of the window. It's useful when you have a large amount of data and you want to reduce the influence of the data points far away from the center. This method is not advised when the tapering of data points is not desired or when the dataset is small as the tapered data points might contain valuable information. It is implemented in `BartlettsBootstrap`.
+``tsbootstrap`` is installed via ``pip``, either from PyPI or locally.
 
-#### (vi) Blackman Bootstrap
-Similar to Bartlett's method, Blackman's method uses a window that tapers off as you move away from the center of the window. The key difference is the shape of the window (Blackman window has a different shape than Bartlett). It's useful when you want to reduce the influence of the data points far from the center with a different window shape. It's not recommended when the dataset is small or tapering of data points is not desired. It is implemented in `BlackmanBootstrap`.
+#### ✔️ Prerequisites
 
-#### (vii) Hamming Bootstrap
- Similar to the Bartlett and Blackman methods, the Hamming method uses a specific type of window function. It's useful when you want to reduce the influence of the data points far from the center with the Hamming window shape. It's not recommended for small datasets or when tapering of data points is not desired. It is implemented in `HammingBootstrap`.
+- Python (3.8 or higher)
+- `pip` (latest version recommended), plus suitable environment manager (`venv`, `conda`)
 
-#### (viii) Hanning Bootstrap
-This method also uses a specific type of window function. It's useful when you want to reduce the influence of the data points far from the center with the Hanning window shape. It's not recommended for small datasets or when tapering of data points is not desired. It is implemented in `HanningBootstrap`.
+You can also consider using ``uv`` to speed up environment setu.
 
-#### (ix) Tukey Bootstrap
-Similar to the Bartlett, Blackman, Hamming, and Hanning methods, the Tukey method uses a specific type of window function. It's useful when you want to reduce the influence of the data points far from the center with the Tukey window shape. It's not recommended for small datasets or when tapering of data points is not desired. It is implemented in `TukeyBootstrap`.
+#### Installing from PyPI
 
-### Residual Bootstrap
-Residual Bootstrap is a method designed for time series data where a model is fit to the data, and the residuals (the difference between the observed and predicted data) are bootstrapped. It's particularly useful when a good model fit is available for the data. However, it's not recommended when a model fit is not available or is poor. `tsbootstrap` provides four time series models to fit to the input data -- `AutoReg`, `ARIMA`, `SARIMA`, and `VAR` (for multivariate input time series data). For more details, refer to `time_series_model.py` and `tsfit.py`.
+To install the latest release of `tsbootstrap` directly from PyPI, run:
 
-### Statistic-Preserving Bootstrap
-Statistic-Preserving Bootstrap is a unique method designed to generate bootstrapped time series data while preserving a specific statistic of the original data. This method can be beneficial in scenarios where it's important to maintain the original data's characteristics in the bootstrapped samples. It is implemented in `StatisticPreservingBootstrap`.
+```sh
+pip install tsbootstrap
+```
 
-### Distribution Bootstrap
-Distribution Bootstrap generates bootstrapped samples by fitting a distribution to the residuals and then generating new residuals from the fitted distribution. The new residuals are then added to the fitted values to create the bootstrapped samples. This method is based on the assumption that the residuals follow a specific distribution (like Gaussian, Poisson, etc). It's not recommended when the distribution of residuals is unknown or hard to determine. It is implemented in `DistributionBootstrap`.
+To install with all optional dependencies:
 
-### Markov Bootstrap
-Markov Bootstrap is used for bootstrapping time series data where the residuals of the data are presumed to follow a Markov process. This method is especially useful in scenarios where the current residual primarily depends on the previous one, with little to no dependency on residuals from further in the past. Markov Bootstrap technique is designed to preserve this dependency structure in the bootstrapped samples, making it particularly valuable for time series data that exhibits Markov properties. However, it's not advisable when the residuals of the time series data exhibit long-range dependencies, as the Markov assumption of limited dependency may not hold true. It is implemented in `MarkovBootstrap`. See `markov_sampler.py` for implementation details.
+```
+pip install "tsbootstrap[all_extras]"
+```
+---
 
-### Sieve Bootstrap
-Sieve Bootstrap is designed for handling dependent data, where the residuals of the time series data follow an autoregressive process. This method aims to preserve and simulate the dependencies inherent in the original data within the bootstrapped samples. It operates by approximating the autoregressive process ofthe residuals using a finite order autoregressive model. The order of the model is determined based on the data, and the residuals are then bootstrapped. The Sieve Bootstrap technique is particularly valuable for time series data that exhibits autoregressive properties. However, it's not advisable when the residuals of the time series data do not follow an autoregressive process. It is implemented in `SieveBootstrap`. See `time_series_simulator.py` for implementations details.
+Bootstrap algorithms manage their own dependencies - if an extra is needed but not
+present, the object will raise this at construction.
 
 ## 🧩 Modules
 The `tsbootstrap` package contains various modules that handle tasks such as bootstrapping, time series simulation, and utility functions. This modular approach ensures flexibility, extensibility, and ease of maintenance.
@@ -219,7 +221,7 @@ The `tsbootstrap` package contains various modules that handle tasks such as boo
 | [commitlint.config.js](https://github.com/astrogilda/tsbootstrap/blob/main/commitlint.config.js) | Configuration for enforcing conventional commit messages. |
 | [CITATION.cff](https://github.com/astrogilda/tsbootstrap/blob/main/CITATION.cff)                 | Citation metadata for the project. |
 | [CODE_OF_CONDUCT.md](https://github.com/astrogilda/tsbootstrap/blob/main/CODE_OF_CONDUCT.md)                 | Guidelines for community conduct and interactions. |
-| [CONTRIBUTING.md](https://github.com/astrogilda/tsbootstrap/blob/main/CITATION.md)                 | Instructions for contributing to the project. |
+| [CONTRIBUTING.md](https://github.com/astrogilda/tsbootstrap/blob/main/CONTRIBUTING.md)                 | Instructions for contributing to the project. |
 | [.codeclimate.yml](https://github.com/astrogilda/tsbootstrap/blob/main/.codeclimate.yml)                 | Configuration for Code Climate quality checks. |
 | [.gitignore](https://github.com/astrogilda/tsbootstrap/blob/main/.gitignore)                 | Specifies files and folders to be ignored by Git. |
 | [.pre-commit-config.yaml](https://github.com/astrogilda/tsbootstrap/blob/main/.pre-commit-config.yaml)                 | Configuration for pre-commit hooks. |
@@ -261,108 +263,62 @@ The `tsbootstrap` package contains various modules that handle tasks such as boo
 
 </details>
 
----
 
-## 🚀 Getting Started
+## 🗺 Roadmap
 
-### ✔️ Prerequisites
+This is an abridged version; for the complete and evolving list of plans and improvements, see [Issue #144](https://github.com/astrogilda/tsbootstrap/issues/144).
 
-Before you begin, ensure that you have the following prerequisites installed:
-> - `ℹ️ Requirement 1`
-> - `ℹ️ Requirement 2`
-> - `ℹ️ ...`
+- **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
 
-### 📦 Installation and Setup
+## 🤝 Contributing
 
-This project comes with a `setup.sh` script to ease the setup process. The script will create a new Python virtual environment, install the necessary dependencies, and handle some version-specific installations.
+Contributions are always welcome!
 
-Here are the steps to follow:
+See our [good first issues ](https://github.com/astrogilda/tsbootstrap/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
+for getting started.
 
-1. Ensure that you have Python, Poetry, and Bash installed on your system. If not, you can install them using the links below:
-    - [Python](https://www.python.org/downloads/)
-    - [Poetry](https://python-poetry.org/docs/#installation)
-    - [Bash](https://www.gnu.org/software/bash/)
+Below is a quick start guide to contributing.
 
-2. Clone the tsbootstrap repository:
-```sh
-git clone https://github.com/astrogilda/tsbootstrap
-```
+### Developer setup
 
-3. Change to the project directory:
-```sh
-cd tsbootstrap
-```
+1. Fork the tsbootstrap repository
 
-4. Make the `setup.sh` script executable:
+2. Clone the fork to local:
 ```sh
-chmod +x setup.sh
+git clone https://github.com/astrogilda/tsbootstrap
 ```
 
-5. Run the `setup.sh` script:
-```sh
-./setup.sh
-```
+3. In the local repository root, set up a python environment, e.g., `venv` or `conda`.
 
-The `setup.sh` script sets up a Python environment using Poetry, locks and installs the necessary dependencies, and installs `dtaidistance` if the Python version is 3.9 or lower.
 
-6. Activate the python shell:
-```sh
-poetry shell
+4. Editable install via `pip`, including developer dependencies:
+```
+pip install -e ".[dev]"
 ```
 
-That's it! You are now set up and ready to go.
-
-### 🎮 Using tsbootstrap
-
-Here's a basic example using the Moving Block Bootstrap method:
-
-```python
-from tsbootstrap import MovingBlockBootstrap, MovingBlockBootstrapConfig
-import numpy as np
-
-np.random.seed(0)
-
-# Create custom time series data
-
-n_samples = 1000
-
-y = np.random.normal(0, 1, n_samples).cumsum()
-
-x1 = np.arange(1, n_samples + 1).reshape(-1, 1)
-x2 = np.random.normal(0, 1, (n_samples, 1))
-exog = np.concatenate([x1, x2], axis=1)
+The editable install ensures that changes to the package are reflected in
+your environment.
 
-# Instantiate the bootstrap object
-mbb_config = MovingBlockBootstrapConfig(
-    n_bootstraps=1000, rng=42, block_length=10
-)
-mbb = MovingBlockBootstrap(config=mbb_config)
+### Verifying the Installation
 
-# Generate the generator for 1000 bootstrapped samples
-bootstrapped_samples = bootstrap.bootstrap(n=1000)
+After installation, you can verify that tsbootstrap has been installed correctly by checking its version or by trying to import it in Python:
 ```
-
-### 🧪 Running Tests
-```sh
-pytest tests/
+python -c "import tsbootstrap; print(tsbootstrap.__version__)"
 ```
 
----
-
-
-## 🗺 Roadmap
-
-> - [ ] `ℹ️  Task 1: in distributionbootstrap, allow mixture of distributions`
-> - [ ] `ℹ️  Task 2: allow fractional block_length`
-> - [ ] `ℹ️  Task 3: enable multi-processing`
-> - [ ] `ℹ️  Task 4: test -- for biascorrectblockbootstrap, see if the statistic on the bootstrapped sample is close to the statistic on the original sample`
+This command should output the version number of tsbootstrap without any errors, indicating that the installation was successful.
 
+That's it! You are now set up and ready to go. You can start using tsbootstrap for your time series bootstrapping needs.
 
-## 🤝 Contributing
+### Contribution workflow
 
 Contributions are always welcome! Please follow these steps:
-1. Fork the project repository. This creates a copy of the project on your account that you can modify without affecting the original project.
-2. Clone the forked repository to your local machine using a Git client like Git or GitHub Desktop.
+
 3. Create a new branch with a descriptive name (e.g., `new-feature-branch` or `bugfix-issue-123`).
 ```sh
 git checkout -b new-feature-branch
@@ -379,6 +335,25 @@ 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:
+
+```sh
+pytest tests/
+```
+
+Individual bootstrap algorithms can be tested as follows:
+
+```python
+from tsbootstrap.utils import check_estimator
+
+check_estimator(my_bootstrap_algo)
+```
+
+### Contribution guide
+
+For more detailed information on how to contribute, please refer to our [CONTRIBUTING.md](https://github.com/astrogilda/tsbootstrap/blob/main/CONTRIBUTING.md)  guide.
 ---
 
 ## 📄 License
@@ -400,3 +375,67 @@ Thanks goes to these wonderful people:
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+
+
+---
+
+
+## 📍 Time Series Bootstrapping
+`tsbootstrap` is a comprehensive project designed to implement an array of bootstrapping techniques specifically tailored for time series data. This project is targeted towards data scientists, statisticians, economists, and other professionals or researchers who regularly work with time series data and require robust methods for generating bootstrapped copies of univariate and multivariate time series data.
+
+### Overview
+Time series bootstrapping is a nuanced resampling method that is applied to time-dependent data. Traditional bootstrapping methods often assume independence between data points, which is an assumption that does not hold true for time series data where a data point is often dependent on previous data points. Time series bootstrapping techniques respect the chronological order and correlations of the data, providing more accurate estimates of uncertainty or variability.
+
+### Bootstrapping Methodology
+The `tsbootstrap` project offers a diverse set of bootstrapping techniques that can be applied to either the entire input time series (classes prefixed with `Whole`), or after partitioning the data into blocks (classes prefixed with `Block`). These methodologies can be applied directly to the raw input data or to the residuals obtained after fitting one of the five statistical models defined in `time_series_model.py` (classes with `Residual` in their names).
+
+### Block Bootstrap
+Block Bootstrap is a prevalent approach in time series bootstrapping. It involves resampling blocks of consecutive data points, thus respecting the internal structures of the data. There are several techniques under Block Bootstrap, each with its unique approach. `tsbootstrap` provides highly flexible block bootstrapping, allowing the user to specify the block length sampling, block generation, and block resampling strategies. For additional details, refer to `block_length_sampler.py`, `block_generator.py`, and `block_resampler.py`.
+
+The Moving Block Bootstrap, Circular Block Bootstrap, Stationary Block Bootstrap, and NonOverlapping Block Bootstrap methods are all variations of the Block Bootstrap that use different methods to sample the data, maintaining various types of dependencies.
+
+Bartlett's, Blackman's, Hamming's, Hanning's, and Tukey's Bootstrap methods are specific implementations of the Block Bootstrap that use different window shapes to taper the data, reducing the influence of data points far from the center. In `tsbootstrap`, these methods inherit from `MovingBlockBootstrap`, but can easily be modified to inherit from any of the other three base block bootstrapping classes.
+
+Each method comes with its distinct strengths and weaknesses. The choice of method should be based on the characteristics of the data and the specific requirements of the analysis.
+
+#### (i) Moving Block Bootstrap
+This method is implemented in `MovingBlockBootstrap` and is used for time series data where blocks of data are resampled to maintain the dependency structure within the blocks. It's useful when the data has dependencies that need to be preserved. It's not recommended when the data does not have any significant dependencies.
+
+#### (ii) Circular Block Bootstrap
+This method is implemented in `CircularBlockBootstrap` and treats the data as if it is circular (the end of the data is next to the beginning of the data). It's useful when the data is cyclical or seasonal in nature. It's not recommended when the data does not have a cyclical or seasonal component.
+
+#### (iii) Stationary Block Bootstrap
+This method is implemented in `StationaryBlockBootstrap` and randomly resamples blocks of data with block lengths that follow a geometric distribution. It's useful for time series data where the degree of dependency needs to be preserved, and it doesn't require strict stationarity of the underlying process. It's not recommended when the data has strong seasonality or trend components which violate the weak dependence assumption.
+
+#### (iv) NonOverlapping Block Bootstrap
+ This method is implemented in `NonOverlappingBlockBootstrap` and resamples blocks of data without overlap. It's useful when the data has dependencies that need to be preserved and when overfitting is a concern. It's not recommended when the data does not have any significant dependencies or when the introduction of bias due to non-overlapping selection is a concern.
+
+#### (v) Bartlett's Bootstrap
+ Bartlett's method is a time series bootstrap method that uses a window or filter that tapers off as you move away from the center of the window. It's useful when you have a large amount of data and you want to reduce the influence of the data points far away from the center. This method is not advised when the tapering of data points is not desired or when the dataset is small as the tapered data points might contain valuable information. It is implemented in `BartlettsBootstrap`.
+
+#### (vi) Blackman Bootstrap
+Similar to Bartlett's method, Blackman's method uses a window that tapers off as you move away from the center of the window. The key difference is the shape of the window (Blackman window has a different shape than Bartlett). It's useful when you want to reduce the influence of the data points far from the center with a different window shape. It's not recommended when the dataset is small or tapering of data points is not desired. It is implemented in `BlackmanBootstrap`.
+
+#### (vii) Hamming Bootstrap
+ Similar to the Bartlett and Blackman methods, the Hamming method uses a specific type of window function. It's useful when you want to reduce the influence of the data points far from the center with the Hamming window shape. It's not recommended for small datasets or when tapering of data points is not desired. It is implemented in `HammingBootstrap`.
+
+#### (viii) Hanning Bootstrap
+This method also uses a specific type of window function. It's useful when you want to reduce the influence of the data points far from the center with the Hanning window shape. It's not recommended for small datasets or when tapering of data points is not desired. It is implemented in `HanningBootstrap`.
+
+#### (ix) Tukey Bootstrap
+Similar to the Bartlett, Blackman, Hamming, and Hanning methods, the Tukey method uses a specific type of window function. It's useful when you want to reduce the influence of the data points far from the center with the Tukey window shape. It's not recommended for small datasets or when tapering of data points is not desired. It is implemented in `TukeyBootstrap`.
+
+### Residual Bootstrap
+Residual Bootstrap is a method designed for time series data where a model is fit to the data, and the residuals (the difference between the observed and predicted data) are bootstrapped. It's particularly useful when a good model fit is available for the data. However, it's not recommended when a model fit is not available or is poor. `tsbootstrap` provides four time series models to fit to the input data -- `AutoReg`, `ARIMA`, `SARIMA`, and `VAR` (for multivariate input time series data). For more details, refer to `time_series_model.py` and `tsfit.py`.
+
+### Statistic-Preserving Bootstrap
+Statistic-Preserving Bootstrap is a unique method designed to generate bootstrapped time series data while preserving a specific statistic of the original data. This method can be beneficial in scenarios where it's important to maintain the original data's characteristics in the bootstrapped samples. It is implemented in `StatisticPreservingBootstrap`.
+
+### Distribution Bootstrap
+Distribution Bootstrap generates bootstrapped samples by fitting a distribution to the residuals and then generating new residuals from the fitted distribution. The new residuals are then added to the fitted values to create the bootstrapped samples. This method is based on the assumption that the residuals follow a specific distribution (like Gaussian, Poisson, etc). It's not recommended when the distribution of residuals is unknown or hard to determine. It is implemented in `DistributionBootstrap`.
+
+### Markov Bootstrap
+Markov Bootstrap is used for bootstrapping time series data where the residuals of the data are presumed to follow a Markov process. This method is especially useful in scenarios where the current residual primarily depends on the previous one, with little to no dependency on residuals from further in the past. Markov Bootstrap technique is designed to preserve this dependency structure in the bootstrapped samples, making it particularly valuable for time series data that exhibits Markov properties. However, it's not advisable when the residuals of the time series data exhibit long-range dependencies, as the Markov assumption of limited dependency may not hold true. It is implemented in `MarkovBootstrap`. See `markov_sampler.py` for implementation details.
+
+### Sieve Bootstrap
+Sieve Bootstrap is designed for handling dependent data, where the residuals of the time series data follow an autoregressive process. This method aims to preserve and simulate the dependencies inherent in the original data within the bootstrapped samples. It operates by approximating the autoregressive process ofthe residuals using a finite order autoregressive model. The order of the model is determined based on the data, and the residuals are then bootstrapped. The Sieve Bootstrap technique is particularly valuable for time series data that exhibits autoregressive properties. However, it's not advisable when the residuals of the time series data do not follow an autoregressive process. It is implemented in `SieveBootstrap`. See `time_series_simulator.py` for implementations details.