k-diagram 1.4.3

Rethinking Forecasting Uncertainty via Polar-Based Visualization

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)

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:

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.

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

# 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

---

📚 Documentation

For detailed usage, API reference, and more examples, please visit the official documentation:

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:

k-diagram --help

Example: Generate a Coverage Diagnostic plot:

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 for options specific to each plot type).

---

🙌 Contributing

Contributions are welcome. Please:

1. Check the Issues Tracker 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 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 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

• Author contact: For collaboration inquiries or questions about the project’s background, you can contact the author:

  Laurent Kouadio — https://lkouadio.com/ 📧 [e-mail]