Usage

Basic Example

Here’s a basic example of how to use ESSA for time series decomposition:

from essa import Decompose, reconstruct
import numpy as np
import matplotlib.pyplot as plt

# Generate synthetic data
t = np.linspace(0, 2*np.pi, 100)
series = np.sin(t) + 0.5*np.sin(3*t)

# Create decomposer with window size of 20
decomposer = Decompose(time_series=series, window_size=20)
decomposer.fit()  # Perform decomposition

# Reconstruct components
trend = reconstruct(decomposer, [[0]])[0]  # First component as trend
seasonal = reconstruct(decomposer, [[1, 2]])[0]  # 2nd and 3rd components as seasonality
noise = reconstruct(decomposer, [[3]])[0]  # 4th component as noise

# Plot results
plt.figure(figsize=(10, 6))
plt.plot(t, series, label='Original Series')
plt.plot(t, trend, label='Trend')
plt.plot(t, seasonal, label='Seasonality')
plt.plot(t, noise, label='Noise')
plt.legend()
plt.title('SSA Decomposition')
plt.show()

Advanced Usage

Non-stationary Series Analysis

For a time series with a trend component (non-stationary):

# Non-stationary series with trend
t = np.linspace(0, 10, 500)
trend = 0.5 * t
seasonal = 2 * np.sin(t) + 1.5 * np.sin(2 * t)
noise = 0.5 * np.random.randn(len(t))
non_stationary_series = trend + seasonal + noise

# Basic SSA method
decomposer = Decompose(time_series=non_stationary_series, window_size=60)
decomposer.fit()

# Reconstruct components
# For trend, we typically use the first few components
trend_component = reconstruct(decomposer, [[0, 1]])[0]
# For seasonality, we use paired components
seasonal_component = reconstruct(decomposer, [[2, 3, 4, 5]])[0]
# Noise components are typically the higher frequency components
noise_component = reconstruct(decomposer, [[i for i in range(6, 20)]])[0]

Stationary Series Analysis with Toeplitz Method

For a stationary time series, the Toeplitz method can provide better results:

# Stationary series (no trend)
stationary_seasonal = 3 * np.sin(t) + np.sin(2 * t + 0.5) + 0.8 * np.sin(3 * t)
stationary_noise = 0.7 * np.random.randn(len(t))
stationary_series = stationary_seasonal + stationary_noise

# Toeplitz SSA method
decomposer = Decompose(time_series=stationary_series, window_size=60, method="toeplitz")
decomposer.fit()

# Reconstruct components
trend = reconstruct(decomposer, [[0]])[0]
seasonal = reconstruct(decomposer, [[1, 2, 3, 4, 5]])[0]
noise = reconstruct(decomposer, [[i for i in range(6, 20)]])[0]