tsmoothie

repository·master·Indexed 21 days ago

https://github.com/cerlymarco/tsmoothie

A Python library for fast, vectorized time-series smoothing and outlier detection. It supports various algorithms including Exponential, Convolutional, Spectral, Polynomial, Spline, Gaussian, Binner, LOWESS, Seasonal Decompose, and Kalman smoothing. The library provides tools for calculating smoothing intervals (sigma, confidence, prediction, and kalman), a WindowWrapper for sliding smoothing, and a BootstrappingWrapper for time-series bootstrap operations.

Tokens
4.9K
Snippets
25
Records
29
Agent score
70%

What's inside tsmoothie

  1. Overview of smoothing techniques in tsmoothie

    master

    tsmoothie provides vectorized smoothing for single or multiple time-series using several techniques:

    • Exponential Smoothing
    • Convolutional Smoothing: Supports various window types (constant, hanning, hamming, bartlett, blackman).
    • Spectral Smoothing: Uses Fourier Transform.
    • Polynomial Smoothing
    • Spline Smoothing: Supports linear, cubic, and natural cubic.
    • Gaussian Smoothing
    • Binner Smoothing
    • LOWESS
    • Seasonal Decompose Smoothing: Supports convolution, lowess, and natural cubic spline.
    • Kalman Smoothing: Customizable components include level, trend, seasonality, and long seasonality.
  2. Use BootstrappingWrapper for time-series bootstrap

    master

    The BootstrappingWrapper class allows you to perform time-series bootstrap operations. It supports the following algorithms:

    • none overlapping block bootstrap
    • moving block bootstrap (mbb)
    • circular block bootstrap
    • stationary bootstrap
  3. Use WindowWrapper for sliding smoothing

    master
    To simulate online usage, you can use the WindowWrapper class. This implements a sliding smoothing approach by splitting the time-series into equal-sized pieces and smoothing them independently in a vectorized way.
  4. Calculate smoothing intervals for outlier detection

    master

    After performing smoothing, you can generate intervals to help identify outliers and anomalies. The available interval types depend on the smoothing method used:

    • sigma_interval
    • confidence_interval
    • prediction_interval
    • kalman_interval
  5. Install tsmoothie and dependencies

    master

    To use tsmoothie for time series smoothing, ensure you have numpy and matplotlib installed alongside the library. While the specific install command is not in this notebook, the usage requires these core scientific computing libraries.

    import numpy as np
    import matplotlib.pyplot as plt
    from tsmoothie.utils_func import sim_seasonal_data
    from tsmoothie.smoother import *
  6. Smooth time series data using various smoothers

    master

    The tsmoothie.smoother module provides several smoothing algorithms. To use them, instantiate the desired smoother class, call .smooth(data), and access the results via the .smooth_data attribute.

    Available smoothers demonstrated in the documentation:

    • ExponentialSmoother(window_len, alpha)
    • ConvolutionSmoother(window_len, window_type)
    • SpectralSmoother(smooth_fraction, pad_len)
    • SplineSmoother(n_knots, spline_type)
    • LowessSmoother(smooth_fraction, iterations)
    • KalmanSmoother(component, component_noise, n_seasons, n_longseasons)
    • DecomposeSmoother(smooth_type, periods, window_len, window_type)
    from tsmoothie.smoother import ExponentialSmoother
    
    smoother = ExponentialSmoother(window_len=20, alpha=0.3)
    smoother.smooth(data)
    # Access smoothed results
    print(smoother.smooth_data)
  7. Access smoothed and original data from a smoother instance

    master

    Once .smooth(data) has been called on a smoother instance, you can access the results via these attributes:

    • smoother.data: The original input data.
    • smoother.smooth_data: The resulting smoothed time series.
    # Accessing the first series in a multi-series dataset
    original_series = smoother.data[0]
    smoothed_series = smoother.smooth_data[0]
  8. Wrap LowessSmoother for scikit-learn pipelines

    master

    To use tsmoothie.smoother.LowessSmoother within a scikit-learn Pipeline, you must create a wrapper class that inherits from sklearn.base.BaseEstimator, sklearn.base.TransformerMixin, and LowessSmoother.

    Because scikit-learn expects input data in the shape (n_samples, n_features) (where samples are timesteps and features are series), and tsmoothie typically operates on (n_series, timesteps), you must handle transposition within the transform method of your wrapper.

    When using the wrapper in a pipeline, pass the data transposed (data.T) to fit_transform to ensure compatibility with standard scikit-learn transformers like StandardScaler.

    from sklearn.pipeline import make_pipeline
    from sklearn.preprocessing import StandardScaler
    from sklearn.base import TransformerMixin, BaseEstimator
    from tsmoothie.smoother import LowessSmoother
    
    class LowessSmootherWrap(TransformerMixin, BaseEstimator, LowessSmoother):
        def fit(self, X, y=None):
            self._is_fitted = True
            return self
    
        def transform(self, X, y=None):
            # Transpose X to match tsmoothie expectations (n_series, timesteps)
            self.smooth(X.T)
            # Transpose result back to (timesteps, n_series)
            return self.smooth_data.T
    
        def fit_transform(self, X, y=None):
            return self.fit(X).transform(X)
    
    # Usage in a pipeline
    smoother = LowessSmootherWrap(smooth_fraction=0.1, iterations=1)
    pipe = make_pipeline(StandardScaler(), smoother)
    
    # data.T shape: (timesteps, n_series)
    smoothdata = pipe.fit_transform(data.T)
  9. Perform time-series bootstrap with BootstrappingWrapper

    master

    Wrap a smoother (like ConvolutionSmoother) inside a BootstrappingWrapper to generate bootstrap samples. You must specify the bootstrap_type and block_length.

    import numpy as np
    from tsmoothie.utils_func import sim_seasonal_data
    from tsmoothie.smoother import ConvolutionSmoother
    from tsmoothie.bootstrap import BootstrappingWrapper
    
    # generate a periodic timeseries of length 300
    np.random.seed(123)
    data = sim_seasonal_data(n_series=1, timesteps=300, 
                             freq=24, measure_noise=15)
    
    # operate bootstrap
    bts = BootstrappingWrapper(ConvolutionSmoother(window_len=8, window_type='ones'), 
                               bootstrap_type='mbb', block_length=24)
    bts_samples = bts.sample(data, n_samples=100)
  10. Smooth seasonal data using DecomposeSmoother

    master

    Use DecomposeSmoother for seasonal decomposition smoothing. You can specify the smooth_type (e.g., 'lowess'), the periods (frequency), and the smooth_fraction.

    import numpy as np
    from tsmoothie.utils_func import sim_seasonal_data
    from tsmoothie.smoother import DecomposeSmoother
    
    # generate 3 periodic timeseries of length 300
    np.random.seed(123)
    data = sim_seasonal_data(n_series=3, timesteps=300, 
                             freq=24, measure_noise=30)
    
    # operate smoothing
    smoother = DecomposeSmoother(smooth_type='lowess', periods=24,
                                 smooth_fraction=0.3)
    smoother.smooth(data)
    
    # generate intervals
    low, up = smoother.get_intervals('sigma_interval')
  11. Smooth time-series using LowessSmoother

    master

    Use LowessSmoother to apply LOWESS smoothing to your data. You can then retrieve prediction intervals using get_intervals('prediction_interval').

    import numpy as np
    from tsmoothie.utils_func import sim_randomwalk
    from tsmoothie.smoother import LowessSmoother
    
    # generate 3 randomwalks of length 200
    np.random.seed(123)
    data = sim_randomwalk(n_series=3, timesteps=200, 
                          process_noise=10, measure_noise=30)
    
    # operate smoothing
    smoother = LowessSmoother(smooth_fraction=0.1, iterations=1)
    smoother.smooth(data)
    
    # generate intervals
    low, up = smoother.get_intervals('prediction_interval')