Package: tsbootstrap
Generate bootstrapped samples from time-series data. The full documentation is availablehere.📒 Table of Contents📍 Time Series BootstrappingOverviewBootstrapping MethodologyBlock BootstrapMoving Block BootstrapCircular Block BootstrapStationary Block BootstrapNonOverlapping Block BootstrapBartletts BootstrapBlackman BootstrapHamming BootstrapHanning BootstrapTukey BootstrapResidual BootstrapBias Corrected BootstrapDistribution BootstrapMarkov BootstrapSieve Bootstrap🧩 Modules🚀 Getting Started🗺 Roadmap🤝 Contributing📄 License👏 Acknowledgments📍 Time Series Bootstrappingtsbootstrapis 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.OverviewTime 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 MethodologyThetsbootstrapproject offers a diverse set of bootstrapping techniques that can be applied to either the entire input time series (classes prefixed withWhole), or after partitioning the data into blocks (classes prefixed withBlock). 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 intime_series_model.py(classes withResidualin their names).Block BootstrapBlock 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.tsbootstrapprovides highly flexible block bootstrapping, allowing the user to specify the block length sampling, block generation, and block resampling strategies. For additional details, refer toblock_length_sampler.py,block_generator.py, andblock_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. Intsbootstrap, these methods inherit fromMovingBlockBootstrap, 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 BootstrapThis method is implemented inMovingBlockBootstrapand 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 BootstrapThis method is implemented inCircularBlockBootstrapand 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 BootstrapThis method is implemented inStationaryBlockBootstrapand 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 BootstrapThis method is implemented inNonOverlappingBlockBootstrapand 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 BootstrapBartlett'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 inBartlettsBootstrap.(vi) Blackman BootstrapSimilar 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 inBlackmanBootstrap.(vii) Hamming BootstrapSimilar 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 inHammingBootstrap.(viii) Hanning BootstrapThis 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 inHanningBootstrap.(ix) Tukey BootstrapSimilar 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 inTukeyBootstrap.Residual BootstrapResidual 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.tsbootstrapprovides four time series models to fit to the input data --AutoReg,ARIMA,SARIMA, andVAR(for multivariate input time series data). For more details, refer totime_series_model.pyandtsfit.py.Statistic-Preserving BootstrapStatistic-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 inStatisticPreservingBootstrap.Distribution BootstrapDistribution 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 inDistributionBootstrap.Markov BootstrapMarkov 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 inMarkovBootstrap. Seemarkov_sampler.pyfor implementation details.Sieve BootstrapSieve 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 inSieveBootstrap. Seetime_series_simulator.pyfor implementations details.🧩 ModulesThetsbootstrappackage 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.rootFileSummarysetup.shShell script for initial setup and environment configuration.commitlint.config.jsConfiguration for enforcing conventional commit messages.CITATION.cffCitation metadata for the project.CODE_OF_CONDUCT.mdGuidelines for community conduct and interactions.CONTRIBUTING.mdInstructions for contributing to the project..codeclimate.ymlConfiguration for Code Climate quality checks..gitignoreSpecifies files and folders to be ignored by Git..pre-commit-config.yamlConfiguration for pre-commit hooks.poetry.lockLock file generated by Poetry, pinning exact package versions.poetry.tomlConfiguration file for Poetry package management.tsbootstrap_logo.pngProject logo image.tsbootstrapFileSummaryblock_generator.pyGenerates blocks for bootstrapping.markov_sampler.pyImplements sampling methods based on Markov models.time_series_model.pyDefines base and specific time series models.block_length_sampler.pySamples block lengths for block bootstrapping methods.base_bootstrap.pyContains the implementation for different types of base, abstract bootstrapping classes for time series data.base_bootstrap_configs.pyProvides configuration classes for different base, abstract bootstrapping classes.block_bootstrap.pyContains the implementation for different types of block bootstrapping methods for time series data.block_bootstrap_configs.pyProvides configuration classes for different block bootstrapping methods.bootstrap.pyContains the implementation for different types of bootstrapping methods for time series data, including residual, distribution, markov, statistic-preserving, and sieve.time_series_simulator.pySimulates time series data based on various models.block_resampler.pyImplements methods for block resampling in time series.tsfit.pyFits time series models to data.ranklags.pyProvides functionalities to rank lags in a time series.utilsFileSummarytypes.pyDefines custom types used across the project.validate.pyContains validation utilities.odds_and_ends.pyContains miscellaneous utility functions.🚀 Getting Started✔️ PrerequisitesBefore you begin, ensure that you have the following prerequisites installed:ℹ️ Requirement 1ℹ️ Requirement 2ℹ️ ...📦 Installation and SetupThis project comes with asetup.shscript to ease the setup process. The script will create a new Python virtual environment, install the necessary dependencies, and handle some version-specific installations.Here are the steps to follow:Ensure that you have Python, Poetry, and Bash installed on your system. If not, you can install them using the links below:PythonPoetryBashClone the tsbootstrap repository:gitclonehttps://github.com/astrogilda/tsbootstrapChange to the project directory:cdtsbootstrapMake thesetup.shscript executable:chmod+xsetup.shRun thesetup.shscript:./setup.shThesetup.shscript sets up a Python environment using Poetry, locks and installs the necessary dependencies, and installsdtaidistanceif the Python version is 3.9 or lower.Activate the python shell:poetryshellThat's it! You are now set up and ready to go.🎮 Using tsbootstrapHere's a basic example using the Moving Block Bootstrap method:fromtsbootstrapimportMovingBlockBootstrap,MovingBlockBootstrapConfigimportpandasaspdimportnumpyasnpnp.random.seed(0)# Create custom time series datan_samples=1000y=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)# Instantiate the bootstrap objectmbb_config=MovingBlockBootstrapConfig(n_bootstraps=1000,rng=42,block_length=10)mbb=MovingBlockBootstrap(config=mbb_config)# Generate the generator for 1000 bootstrapped samplesbootstrapped_samples=bootstrap.bootstrap(n=1000)🧪 Running Testspytesttests/🗺 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🤝 ContributingContributions are always welcome! Please follow these steps:Fork the project repository. This creates a copy of the project on your account that you can modify without affecting the original project.Clone the forked repository to your local machine using a Git client like Git or GitHub Desktop.Create a new branch with a descriptive name (e.g.,new-feature-branchorbugfix-issue-123).gitcheckout-bnew-feature-branchMake changes to the project's codebase.Commit your changes to your local branch with a clear commit message that explains the changes you've made.gitcommit-m'Implemented new feature.'Push your changes to your forked repository on GitHub using the following commandgitpushoriginnew-feature-branchCreate 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.📄 LicenseThis project is licensed under theℹ️  MITLicense. See theLICENSEfile for additional info.👏 Acknowledgmentsℹ️  List any resources, contributors, inspiration, etc.