A Python implementation of Forecastable Component Analysis (ForeCA) — a dimension reduction technique for multivariate time series that finds linear combinations with maximum forecastability. It is sklearn compatible, with the usual .fit() and .transform() methods. Can be used as a drop-in replacement of PCA() or FastICA() for example.

Note: pyforeca aims to be an sklearn-compatible Python sibling to the ForeCA R package.

Unlike PCA (maximum variance) or ICA (maximum independence), ForeCA finds components that are maximally forecastable. This makes it ideal for time series analysis where prediction is often the primary goal.

Forecastability is measured using spectral entropy:

• Low spectral entropy → High forecastability (predictable patterns)
• High spectral entropy → Low forecastability (randomness)

The forecastability measure Omega equals 1 minus the normalized spectral entropy of a signal. See Goerg (2013) for details.

poetry add git+https://github.com/gmgeorg/pyforeca.git#main

The code snippet here is a minimum working example to validate that your installation works. For real data examples and tutorials see below.

import numpy as np from pyforeca.base import ForeCA from pyforeca.datasets import simulations latent, mixing_mat, observed = simulations.gen_toy_data(1000) # Apply ForeCA foreca = ForeCA(n_components=3, spectrum_method='welch') # forecastable components found by ForeCA forecs = foreca.fit_transform(observed) # View forecastability of components print("Component-wise Omega (higher = more forecastable):") for i, omega in enumerate(foreca.omegas_): print(f"ForeC{i+1}: {omega:.4f}")

Forecastability Ω values: ForeC1: 0.505 ForeC2: 0.193 ForeC3: 0.013

pyforeca.viz provides several visualizations for spot-checking ForeCA transformers, and inspectings results from the training runs.

from pyforeca import viz viz.plot_foreca(mod_foreca)

viz.plot_time_series(forecs)

• ForeCA estimator compatible with scikit-learn API (fit, transform, fit_transform)
• Utility functions for univariate and multivariate spectral entropy
• Welch and periodogram spectral estimation options
• Various helper functions for visualization of time series data, biplots (like R), and multivariate/univariate spectral densities.

For interesting real world data examples see the tutorials & demo notebooks

• simulated data: pyforeca-toy-example-data.ipynb
• stock market data: pyforeca-stock-example.ipynb
• weather/climate data: pyforeca-weather-example.ipynb

See also SO posts for some data & code examples (in R).

1. Compute the multivariate spectral density of the input time series.
2. Solve an optimization problem to find linear combinations that minimize spectral entropy.
3. Return components ordered by forecastability (most predictable first).

• Goerg, G. M. (2013). Forecastable Component Analysis. Proceedings of the 30th International Conference on Machine Learning (ICML-13). https://proceedings.mlr.press/v28/goerg13.html
• Original R implementation: ForeCA R package

MIT License — see LICENSE file for details.