Skip to content

🔀 SeriesDecomposition

🔀 SeriesDecomposition

🟡 Intermediate ✅ Stable ⏱️ Time Series

🎯 Overview

The SeriesDecomposition layer decomposes time series into trend and seasonal components using moving average. This is a fundamental technique in time series analysis that separates long-term trends from recurring patterns.

The layer: - Extracts Trend: Using moving average smoothing - Captures Seasonality: As residual after trend removal - Preserves Information: No information loss in decomposition - Enables Hierarchical Analysis: Process components separately

🔍 How It Works

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
Input Time Series
       |
       V
+------------------+
| Moving Average   | <- Extracts trend
+--------+--------+
         |
         V
    Trend Component
         |
Input - Trend
         |
         V
Seasonal Component

The trend is computed using a moving average filter, preserving temporal length through edge padding.

💡 Why Use This Layer?

Problem Solution
Mixed Patterns Separate trend and seasonality
Noisy Data Trend extraction via smoothing
Pattern Analysis Analyze components independently
Forecasting Model trend and seasonal separately

📊 Use Cases

  • Classical Time Series Analysis: Traditional decomposition
  • Trend Forecasting: Separate trend prediction
  • Seasonal Adjustment: Remove seasonality for analysis
  • Anomaly Detection: Decompose before detection
  • Feature Engineering: Use components as features

🚀 Quick Start

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from kerasfactory.layers import SeriesDecomposition
import keras

# Create decomposition layer
decomp = SeriesDecomposition(kernel_size=25)

# Input data
x = keras.random.normal((32, 100, 8))

# Decompose
seasonal, trend = decomp(x)

print(f"Seasonal shape: {seasonal.shape}")  # (32, 100, 8)
print(f"Trend shape: {trend.shape}")        # (32, 100, 8)

# Verify decomposition: seasonal + trend ≈ original
reconstructed = seasonal + trend  # Approximately equals x

🔧 API Reference

1
2
3
4
5
kerasfactory.layers.SeriesDecomposition(
    kernel_size: int,
    name: str | None = None,
    **kwargs
)

Parameters

Parameter Type Description
kernel_size int Moving average window size
name str \| None Optional layer name

Returns

Tuple of (seasonal, trend) tensors with same shape as input.

💡 Best Practices

  1. Kernel Size: Choose based on seasonality frequency
  2. Daily data: kernel_size=7 (weekly pattern)
  3. Monthly data: kernel_size=12 (annual pattern)
  4. Edge Handling: Automatically paddles edges to preserve length
  5. Multiple Scales: Apply recursively for hierarchical decomposition
  6. Information Preservation: Guaranteed: seasonal + trend = original

⚠️ Common Pitfalls

  • ❌ Small kernel_size: Misses true trends
  • ❌ Large kernel_size: Removes important patterns
  • ❌ Wrong frequency: Choose kernel based on domain knowledge
  • ❌ Assuming perfect reconstruction: Numerical precision limits

📚 References

  • Classical time series decomposition (Additive/Multiplicative)
  • Cleveland et al. (1990). "STL: A Seasonal-Trend Decomposition"
  • Hyndman & Athanasopoulos. "Forecasting: Principles and Practice"

Last Updated: 2025-11-04 | Keras: 3.0+ | Status: ✅ Production Ready