Metadata-Version: 2.4
Name: xeries
Version: 0.2.0
Summary: Forecasting explanations for global forecasters, with support for skforecast and more.
Project-URL: Homepage, https://github.com/thec0dewriter/xeries
Project-URL: Documentation, https://thec0dewriter.github.io/xeries
Project-URL: Repository, https://github.com/thec0dewriter/xeries
Project-URL: DOI, https://doi.org/10.5281/zenodo.19482748
Author-email: Mátyás Kuti-Kreszács <kutikmatyas@gmail.com>
Maintainer-email: Mátyás Kuti-Kreszács <kutikmatyas@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: explainability,feature-importance,forecasting,machine-learning,multi-series,permutation-importance,shap,skforecast,time-series
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: joblib>=1.5.3
Requires-Dist: numpy>=2.2.6
Requires-Dist: pandas>=2.3.3
Requires-Dist: scikit-learn>=1.7.2
Requires-Dist: shap>=0.49.1
Provides-Extra: all
Requires-Dist: causal-learn>=0.1.3; extra == 'all'
Requires-Dist: jinja2>=3.1; extra == 'all'
Requires-Dist: shapiq>=1.0; extra == 'all'
Requires-Dist: skforecast>=0.21.0; extra == 'all'
Requires-Dist: u8darts>=0.34; extra == 'all'
Provides-Extra: causal-discovery
Requires-Dist: causal-learn>=0.1.3; extra == 'causal-discovery'
Provides-Extra: darts
Requires-Dist: u8darts>=0.34; extra == 'darts'
Provides-Extra: dashboard
Requires-Dist: jinja2>=3.1; extra == 'dashboard'
Provides-Extra: notebooks
Requires-Dist: ipykernel>=6.29; extra == 'notebooks'
Requires-Dist: jupyter>=1.0; extra == 'notebooks'
Requires-Dist: matplotlib>=3.8; extra == 'notebooks'
Requires-Dist: nbclient>=0.10; extra == 'notebooks'
Requires-Dist: nbformat>=5.10; extra == 'notebooks'
Requires-Dist: nbval>=0.11; extra == 'notebooks'
Provides-Extra: shapiq
Requires-Dist: shapiq>=1.0; extra == 'shapiq'
Provides-Extra: skforecast
Requires-Dist: skforecast>=0.21.0; extra == 'skforecast'
Description-Content-Type: text/markdown

# xeries

[![CI](https://github.com/thec0dewriter/xeries/actions/workflows/ci.yml/badge.svg)](https://github.com/thec0dewriter/xeries/actions/workflows/ci.yml)
[![PyPI version](https://badge.fury.io/py/xeries.svg)](https://badge.fury.io/py/xeries)
[![Python versions](https://img.shields.io/pypi/pyversions/xeries.svg)](https://pypi.org/project/xeries/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19482748.svg)](https://doi.org/10.5281/zenodo.19482748)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**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

```bash
pip install xeries
```

With UV:

```bash
uv add xeries
```

For skforecast integration:

```bash
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)

```python
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

```python
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

```python
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](https://thec0dewriter.github.io/xeries)

## Development

Clone the repository:

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

Install with development dependencies:

```bash
uv sync --dev
```

Run tests:

```bash
uv run pytest
```

Run linting:

```bash
uv run ruff check src tests
uv run ruff format src tests
```

Type checking:

```bash
uv run ty check src
```

Build documentation:

```bash
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](LICENSE) file for details.

## Citation

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

```bibtex
@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](https://arxiv.org/abs/1705.07874)
- **SHAP Interaction Values** — [Janzing et al., 2020](https://arxiv.org/abs/1908.08474)
- **Controlled Feature Dropping** — Model modification for importance estimation
- **Causal Inference** using **DoWhy** and **EconML** frameworks
- **skforecast** — [Multi-series forecasting framework](https://skforecast.org/)
