https://github.com/earthai-tech/k-diagram
k-diagram: Rethinking Forecasting Uncertainty via Polar-based Visualization
https://github.com/earthai-tech/k-diagram
artifical-intelligense deep-learning environments forecasting machine-learning polar visualization
Last synced: 5 months ago
JSON representation
k-diagram: Rethinking Forecasting Uncertainty via Polar-based Visualization
- Host: GitHub
- URL: https://github.com/earthai-tech/k-diagram
- Owner: earthai-tech
- License: apache-2.0
- Created: 2025-04-09T12:58:09.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-12-22T00:59:06.000Z (6 months ago)
- Last Synced: 2025-12-22T23:49:23.539Z (6 months ago)
- Topics: artifical-intelligense, deep-learning, environments, forecasting, machine-learning, polar, visualization
- Language: Python
- Homepage: https://k-diagram.readthedocs.io/
- Size: 47.5 MB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
Awesome Lists containing this project
README
Polar Diagnostics for Forecast Uncertainty
k-diagram provides polar diagnostic plots to evaluate
forecast models with an emphasis on uncertainty. It helps you look
beyond single metrics and understand where and why models
behave as they do.
-----------------------------------------------------
## ✨ Why k-diagram?
Key questions it helps answer:
- **Forecast uncertainty** — Are prediction intervals well calibrated?
- **Model drift** — Does performance degrade over time or horizon?
- **Anomalies** — Where do predictions miss, and by how much?
- **Patterns** — How does accuracy vary across conditions or locations?
The package is designed with applied settings in mind, including
environmental forecasting (subsidence, floods, climate impacts), but
is general enough for many time-series and geospatial tasks.
-----
## 📥 Installation
### From PyPI (recommended)
```bash
pip install k-diagram
````
This installs *k-diagram* and the scientific Python stack it depends
on (NumPy, Pandas, SciPy, Matplotlib, Seaborn, scikit-learn). Python
3.9+ is supported.
### Development install (editable)
If you plan to contribute or run tests locally:
```bash
git clone https://github.com/earthai-tech/k-diagram.git
cd k-diagram
pip install -e .[dev]
```
The `[dev]` extra installs pytest, coverage, Sphinx, Ruff (Black), and
other developer tools defined in `pyproject.toml`.
### Reproducible dev environment via conda
We ship an `environment.yml` mirroring our CI setup. It includes
runtime deps plus test and docs tooling.
```bash
git clone https://github.com/earthai-tech/k-diagram.git
cd k-diagram
conda env create -f environment.yml
conda activate k-diagram-dev
python -m pip install . --no-deps --force-reinstall
```
> For more detailed instructions, including how to **build the documentation locally**,
> please see the full [Installation Guide](https://k-diagram.readthedocs.io/en/latest/installation#building-documentation)
> in our documentation.
>
> Tip: Prefer a virtual environment (either `venv` or `conda`) to keep
> project dependencies isolated.
-----
## ⚡ Quick Start
Visualize how the entire spatial pattern of forecast uncertainty evolves
over multiple time steps with `plot_uncertainty_drift`. This plot uses
concentric rings to represent each forecast period, revealing at a glance
how the "map" of uncertainty changes over time.
```python
# Code Snippet
import kdiagram as kd
# (Requires df with multiple qlow/qup cols like sample_data_drift_uncertainty)
# Example using dummy data generation:
import pandas as pd
import numpy as np
years = range(2023, 2028) # 2028 excluded
N=100
df_drift = pd.DataFrame({'id': range(N)})
qlow_cols, qup_cols = [], []
for i, year in enumerate(years):
ql, qu = f'q10_{year}', f'q90_{year}'
qlow_cols.append(ql); qup_cols.append(qu)
base = np.random.rand(N)*5; width=(np.random.rand(N)+0.5)*(1+i)
df_drift[ql] = base; df_drift[qu]=base+width
kd.plot_uncertainty_drift(
df_drift,
qlow_cols=qlow_cols,
qup_cols=qup_cols,
acov="half_circle",
dt_labels=[str(y) for y in years],
title='Uncertainty Drift (Interval Width)'
)
```
-----
## 📊 Explore the Visualizations
The Quick Start shows just one of the many specialized plots available.
The full documentation gallery showcases the complete suite of
diagnostic tools. Discover how to:
- **Compare Models:** Use radar charts to weigh the trade-offs between
accuracy, speed, and other metrics.
- **Diagnose Reliability:** Go beyond accuracy with calibration spirals to
see if your probability forecasts are trustworthy.
- **Analyze Error Structures:** Uncover hidden biases and patterns in your
model's mistakes with polar residual plots.
- **Understand Feature Effects:** Visualize feature importance "fingerprints"
and complex two-way feature interactions.
➡️ **Explore the [Full Gallery](https://k-diagram.readthedocs.io/en/latest/gallery/index.html)**
-----
## 📚 Documentation
For detailed usage, API reference, and more examples, please
visit the official documentation:
**[k-diagram.readthedocs.io](https://k-diagram.readthedocs.io/)**
-----
## 💻 Using the CLI
`k-diagram` also provides a command-line interface for generating
plots directly from CSV files.
**Check available commands:**
```bash
k-diagram --help
```
**Example: Generate a Coverage Diagnostic plot:**
```bash
k-diagram plot-coverage-diagnostic data.csv \
--actual-col actual_obs \
--q-cols q10_pred q90_pred \
--title "Coverage for My Model" \
--savefig coverage_plot.png
```
See **[k-diagram --help](https://k-diagram.readthedocs.io/en/latest/cli/introduction.html)**
for options specific to each plot type).
-----
## 🙌 Contributing
Contributions are welcome. Please:
1. Check the **[Issues Tracker](https://github.com/earthai-tech/k-diagram/issues)**
for existing bugs or ideas.
2. Fork the repository.
3. Create a new branch for your feature or fix.
4. Make your changes and add tests.
5. Submit a Pull Request.
Please refer to the [CONTRIBUTING](https://k-diagram.readthedocs.io/en/latest/contributing.html)
page or the contributing section in the documentation
for more detailed guidelines.
-----
## 📜 License
`k-diagram` is distributed under the terms of the **Apache License 2.0**.
See the [LICENSE](https://github.com/earthai-tech/k-diagram/blob/main/LICENSE)
file for details.
-----
## 📞 Contact & Support
* **Bug reports & feature requests:** Please use the project’s **GitHub Issues**
tracker to report bugs, ask usage questions, or suggest enhancements:
[GitHub Issues](https://github.com/earthai-tech/k-diagram/issues)
* **Author contact:** For collaboration inquiries or questions about the
project’s background, you can contact the author:
**Laurent Kouadio** — [https://lkouadio.com/](https://lkouadio.com/)
📧 **[etanoyau@gmail.com](mailto:etanoyau@gmail.com)**
[badge-ci]: https://img.shields.io/github/actions/workflow/status/earthai-tech/k-diagram/python-package-conda.yml?branch=main&style=flat-square
[link-ci]: https://github.com/earthai-tech/k-diagram/actions/workflows/python-package-conda.yml
[badge-docs]: https://readthedocs.org/projects/k-diagram/badge/?version=latest&style=flat-square
[link-docs]: https://k-diagram.readthedocs.io/en/latest/?badge=latest
[badge-license]: https://img.shields.io/github/license/earthai-tech/k-diagram?style=flat-square&logo=apache&color=purple
[badge-black]: https://img.shields.io/badge/code%20style-Black-000000.svg?style=flat-square
[link-black]: https://github.com/psf/black
[badge-contrib]: https://img.shields.io/badge/Contributions-Welcome-brightgreen?style=flat-square
[link-contrib]: https://github.com/earthai-tech/k-diagram/blob/main/CONTRIBUTING.md
[badge-codecov]: https://codecov.io/gh/earthai-tech/k-diagram/branch/main/graph/badge.svg
[link-codecov]: https://codecov.io/gh/earthai-tech/k-diagram