xeries 0.2.1

Forecasting explanations for global forecasters, with support for skforecast and more.

xeries

Time Series eXplainability (XAI) for Forecasting

A comprehensive Python library for explainability and interpretability in multi-time series forecasting. xeries provides multiple explanation methods—including conditional permutation importance, SHAP, feature dropping, and causal analysis—with a unified API and interactive dashboard for understanding forecast decisions.

Why xeries?

Explaining and interpreting multi-time series forecasts is challenging:

1. Standard methods fail on series-dependent features: Permutation importance and SHAP can create invalid data by pairing a lag from one series with a target from another.

2. No unified explainability framework: Most libraries offer a single method (e.g., SHAP only) with limited support for time-series-specific analysis.

3. Lack of temporal and comparative insights: Understanding performance across time windows, detecting significance, and comparing methods are difficult without custom tools.

xeries addresses these gaps with:

• Conditional explanations that respect data structure
• A focused CPI workflow for current production use
• A roadmap for future explanation methods
• A simple API for current cs-PFI workflows

Features

📊 Current Capability

• Conditional Permutation Importance (cs-PFI): Permute features only within meaningful subgroups
  • Auto-discover groups using decision trees
  • Define custom groups based on domain knowledge

🛣️ Planned Roadmap

• Conditional SHAP: Planned for a future release
• SHAP-IQ: Planned for a future release
• Feature Dropping: Planned for a future release
• Causal Feature Importance: Planned for a future release

📡 Framework Adapters

• scikit-learn: Direct support for sklearn estimators
• skforecast: Seamless integration with multi-series forecasters (0.21+)
• Custom Models: Wrap any forecaster with the BaseAdapter

📈 Visualization

Ready-to-use plotting utilities for feature importance and temporal analysis.

• Publication-Ready Plots:
  • Feature importance bar charts
  • Heatmaps comparing multiple methods or conditions

Planned:

• Interactive Dashboard: Unified interface for all explainability components
  • Method comparison visualizations
  • Interaction plots
• HTML Report Generation: Auto-generate dashboards with Jinja2 templates
• Jupyter Integration: Works seamlessly in notebooks

Installation

pip install xeries

With UV:

uv add xeries

For skforecast integration:

pip install xeries[skforecast]

Supported Explanation Methods

Method	Status	Use Case	Notes
Conditional Permutation Importance	Available	Default choice; fast & interpretable	Auto/manual grouping with tree-based or manual partitioning
Conditional SHAP	Planned	Local & global explanations	Future release
SHAP-IQ	Planned	Feature interactions	Future release
Feature Dropping	Planned	Complementary to importance	Future release
Causal Feature Importance	Planned	Treatment effects	Future release

Quick Start

Conditional Permutation Importance (Default)

from sklearn.ensemble import RandomForestRegressor
from skforecast.recursive import ForecasterRecursiveMultiSeries

from xeries import ConditionalPermutationImportance
from xeries.adapters.skforecast import from_skforecast

# Train your multi-series forecaster (skforecast 0.21+)
forecaster = ForecasterRecursiveMultiSeries(
    estimator=RandomForestRegressor(n_estimators=100, random_state=42),
    lags=24,
)
forecaster.fit(series=your_data)

# Same `series` as fit() is required for create_train_X_y (pass here or to get_training_data)
adapter = from_skforecast(forecaster, series=your_data)
X, y = adapter.get_training_data()

# Compute conditional importance (automatic tree-based cs-PFI)
explainer = ConditionalPermutationImportance(
    model=adapter,
    metric='mse',
    strategy='auto',
    n_repeats=5,
    random_state=42,
)

result = explainer.explain(X, y, features=['lag_1', 'lag_2', 'lag_3'])
print(result.to_dataframe())

Using Manual Groups

from xeries import ManualPartitioner, ConditionalPermutationImportance

# Domain groups: with skforecast 0.21+ wide data, series are ordinal-encoded in X.
# Map integers 0,1,... in the same order as forecaster.series_names_in_ (see adapter.forecaster).
mapping = {
    0: 'urban',
    1: 'suburban',
    2: 'urban',
}

partitioner = ManualPartitioner(mapping, series_col=adapter.get_series_column())

explainer = ConditionalPermutationImportance(
    model=adapter,
    metric='mse',
    strategy='manual',
    partitioner=partitioner,
)

result = explainer.explain(X, y)

Visualization

from xeries.visualization import plot_importance_bar, plot_importance_heatmap

# Bar chart
fig, ax = plot_importance_bar(result, max_features=10)

# Heatmap comparing multiple cs-PFI configurations
results = {'Auto': result_auto, 'Manual': result_manual}
fig, ax = plot_importance_heatmap(results)

Planned Methods

The following methods are planned for future releases and are not part of the current release:

• Conditional SHAP
• SHAP-IQ
• Feature Dropping
• Causal Feature Importance

Documentation

Full documentation is available at https://thec0dewriter.github.io/xeries

Development

Clone the repository:

git clone https://github.com/thec0dewriter/xeries.git
cd xeries

Install with development dependencies:

uv sync --dev

Run tests:

uv run pytest

Run linting:

uv run ruff check src tests
uv run ruff format src tests

Type checking:

uv run ty check src

Build documentation:

uv sync --group docs
uv run mkdocs serve

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use this library in your research, please cite:

@software{xeries,
  title = {xeries: Time Series eXplainability for Forecasting},
  author = {Kuti-Kreszács, Mátyás},
  year = {2026},
  doi = {10.5281/zenodo.19482748},
  publisher = {Zenodo},
  url = {https://github.com/thec0dewriter/xeries},
}

Related Publications

This project is informed by the following techniques and references:

• Conditional Subgroup Permutation Feature Importance (cs-PFI)
• SHAP (SHapley Additive exPlanations) — Lundberg & Lee, 2017
• SHAP Interaction Values — Janzing et al., 2020
• Controlled Feature Dropping — Model modification for importance estimation
• Causal Inference using DoWhy and EconML frameworks
• skforecast — Multi-series forecasting framework