{"id":39687161,"url":"https://github.com/earthai-tech/k-diagram","last_synced_at":"2026-01-26T19:03:45.342Z","repository":{"id":287105013,"uuid":"963287421","full_name":"earthai-tech/k-diagram","owner":"earthai-tech","description":"k-diagram: Rethinking  Forecasting Uncertainty via Polar-based Visualization","archived":false,"fork":false,"pushed_at":"2025-12-22T00:59:06.000Z","size":49762,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-22T23:49:23.539Z","etag":null,"topics":["artifical-intelligense","deep-learning","environments","forecasting","machine-learning","polar","visualization"],"latest_commit_sha":null,"homepage":"https://k-diagram.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/earthai-tech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-09T12:58:09.000Z","updated_at":"2025-12-22T17:13:46.000Z","dependencies_parsed_at":"2025-04-10T01:32:16.144Z","dependency_job_id":"ccc1b80d-bdc0-4265-be58-e019d034b4ed","html_url":"https://github.com/earthai-tech/k-diagram","commit_stats":null,"previous_names":["earthai-tech/k-diagram"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/earthai-tech/k-diagram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthai-tech%2Fk-diagram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthai-tech%2Fk-diagram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthai-tech%2Fk-diagram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthai-tech%2Fk-diagram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/earthai-tech","download_url":"https://codeload.github.com/earthai-tech/k-diagram/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/earthai-tech%2Fk-diagram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28785172,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T13:55:28.044Z","status":"ssl_error","status_checked_at":"2026-01-26T13:55:26.068Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artifical-intelligense","deep-learning","environments","forecasting","machine-learning","polar","visualization"],"created_at":"2026-01-18T10:01:03.632Z","updated_at":"2026-01-26T19:03:45.330Z","avatar_url":"https://github.com/earthai-tech.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n  \u003cimg src=\"https://raw.githubusercontent.com/earthai-tech/k-diagram/main/docs/source/_static/k_diagram.svg\" alt=\"k-diagram logo\" width=\"300\"\u003e\u003cbr\u003e\n  \u003ch1\u003ePolar Diagnostics for Forecast Uncertainty\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/earthai-tech/k-diagram/actions/workflows/python-package-conda.yml\"\u003e\n        \u003cimg alt=\"Build Status\" src=\"https://img.shields.io/github/actions/workflow/status/earthai-tech/k-diagram/python-package-conda.yml?branch=main\u0026style=flat-square\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://k-diagram.readthedocs.io/en/latest/\"\u003e\n        \u003cimg alt=\"Docs Status\" src=\"https://img.shields.io/readthedocs/k-diagram?style=flat-square\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/earthai-tech/k-diagram/blob/main/LICENSE\"\u003e\n        \u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/earthai-tech/k-diagram?style=flat-square\u0026logo=apache\u0026color=purple\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/psf/black\"\u003e\n        \u003cimg alt=\"Black\" src=\"https://img.shields.io/badge/code%20style-Black-000000.svg?style=flat-square\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/earthai-tech/k-diagram/blob/main/CONTRIBUTING.md\"\u003e\n        \u003cimg alt=\"Contributions\" src=\"https://img.shields.io/badge/Contributions-Welcome-brightgreen?style=flat-square\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://codecov.io/gh/earthai-tech/k-diagram\"\u003e\n        \u003cimg alt=\"Codecov\" src=\"https://codecov.io/gh/earthai-tech/k-diagram/branch/main/graph/badge.svg\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/earthai-tech/k-diagram/releases/latest\"\u003e\n        \u003cimg alt=\"GitHub Release\" src=\"https://img.shields.io/github/v/release/earthai-tech/k-diagram\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://joss.theoj.org/papers/b1b83d205263117e0b54b670d4600174\"\u003e\n      \u003cimg src=\"https://joss.theoj.org/papers/b1b83d205263117e0b54b670d4600174/status.svg\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://doi.org/10.5281/zenodo.17211576\"\u003e\n      \u003cimg src=\"https://zenodo.org/badge/DOI/10.5281/zenodo.17211576.svg\" alt=\"DOI\"\u003e\n   \u003c/a\u003e\n\u003c/p\u003e\n  \n  \u003cp\u003e\n    \u003cem\u003ek-diagram\u003c/em\u003e provides polar diagnostic plots to evaluate\n    forecast models with an emphasis on uncertainty. It helps you look\n    beyond single metrics and understand \u003cstrong\u003ewhere\u003c/strong\u003e and \u003cstrong\u003ewhy\u003c/strong\u003e models\n    behave as they do.\n  \u003c/p\u003e\n\n\u003c/div\u003e\n\n-----------------------------------------------------\n\n## ✨ Why k-diagram?\n\nKey questions it helps answer:\n\n- **Forecast uncertainty** — Are prediction intervals well calibrated?\n- **Model drift** — Does performance degrade over time or horizon?\n- **Anomalies** — Where do predictions miss, and by how much?\n- **Patterns** — How does accuracy vary across conditions or locations?\n\nThe package is designed with applied settings in mind, including\nenvironmental forecasting (subsidence, floods, climate impacts), but\nis general enough for many time-series and geospatial tasks.\n\n-----\n\n## 📥 Installation\n\n### From PyPI (recommended)\n\n```bash\npip install k-diagram\n````\n\nThis installs *k-diagram* and the scientific Python stack it depends\non (NumPy, Pandas, SciPy, Matplotlib, Seaborn, scikit-learn). Python\n3.9+ is supported.\n\n### Development install (editable)\n\nIf you plan to contribute or run tests locally:\n\n```bash\ngit clone https://github.com/earthai-tech/k-diagram.git\ncd k-diagram\npip install -e .[dev]\n```\n\nThe `[dev]` extra installs pytest, coverage, Sphinx, Ruff (Black), and\nother developer tools defined in `pyproject.toml`.\n\n### Reproducible dev environment via conda\n\nWe ship an `environment.yml` mirroring our CI setup. It includes\nruntime deps plus test and docs tooling.\n\n```bash\ngit clone https://github.com/earthai-tech/k-diagram.git\ncd k-diagram\nconda env create -f environment.yml\nconda activate k-diagram-dev\npython -m pip install . --no-deps --force-reinstall\n```\n\n\u003e For more detailed instructions, including how to **build the documentation locally**, \n\u003e please see the full [Installation Guide](https://k-diagram.readthedocs.io/en/latest/installation#building-documentation) \n\u003e in our documentation.\n\u003e \n\u003e Tip: Prefer a virtual environment (either `venv` or `conda`) to keep\n\u003e project dependencies isolated.\n\n-----\n\n## ⚡ Quick Start\n\nVisualize how the entire spatial pattern of forecast uncertainty evolves \nover multiple time steps with `plot_uncertainty_drift`. This plot uses \nconcentric rings to represent each forecast period, revealing at a glance \nhow the \"map\" of uncertainty changes over time.\n\n```python\n# Code Snippet\nimport kdiagram as kd\n# (Requires df with multiple qlow/qup cols like sample_data_drift_uncertainty)\n# Example using dummy data generation:\nimport pandas as pd\nimport numpy as np\nyears = range(2023, 2028) # 2028 excluded\nN=100\ndf_drift = pd.DataFrame({'id': range(N)})\nqlow_cols, qup_cols = [], []\nfor i, year in enumerate(years):\n   ql, qu = f'q10_{year}', f'q90_{year}'\n   qlow_cols.append(ql); qup_cols.append(qu)\n   base = np.random.rand(N)*5; width=(np.random.rand(N)+0.5)*(1+i)\n   df_drift[ql] = base; df_drift[qu]=base+width\n\nkd.plot_uncertainty_drift(\n    df_drift,\n    qlow_cols=qlow_cols,\n    qup_cols=qup_cols,\n    acov=\"half_circle\", \n    dt_labels=[str(y) for y in years],\n    title='Uncertainty Drift (Interval Width)'\n)\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg\n    src=\"https://raw.githubusercontent.com/earthai-tech/k-diagram/main/docs/source/_static/readme_uncertainty_drift_plot.png\"\n    alt=\"Uncertainty Drift Plot\"\n    width=\"500\"\n  /\u003e\n\u003c/p\u003e\n\n-----\n\n## 📊 Explore the Visualizations\n\nThe Quick Start shows just one of the many specialized plots available. \nThe full documentation gallery showcases the complete suite of \ndiagnostic tools. Discover how to:\n\n- **Compare Models:** Use radar charts to weigh the trade-offs between \n  accuracy, speed, and other metrics.\n- **Diagnose Reliability:** Go beyond accuracy with calibration spirals to \n  see if your probability forecasts are trustworthy.\n- **Analyze Error Structures:** Uncover hidden biases and patterns in your \n  model's mistakes with polar residual plots.\n- **Understand Feature Effects:** Visualize feature importance \"fingerprints\" \n  and complex two-way feature interactions.\n\n➡️ **Explore the [Full Gallery](https://k-diagram.readthedocs.io/en/latest/gallery/index.html)**\n\n-----\n## 📚 Documentation\n\nFor detailed usage, API reference, and more examples, please \nvisit the official documentation:\n\n**[k-diagram.readthedocs.io](https://k-diagram.readthedocs.io/)** \n\n-----\n\n## 💻 Using the CLI\n\n`k-diagram` also provides a command-line interface for generating \nplots directly from CSV files.\n\n**Check available commands:**\n\n```bash\nk-diagram --help\n```\n\n**Example: Generate a Coverage Diagnostic plot:**\n\n```bash\nk-diagram plot-coverage-diagnostic data.csv \\\n    --actual-col actual_obs \\\n    --q-cols q10_pred q90_pred \\\n    --title \"Coverage for My Model\" \\\n    --savefig coverage_plot.png\n```\n\nSee **[k-diagram \u003ccommand\u003e --help](https://k-diagram.readthedocs.io/en/latest/cli/introduction.html)**\nfor options specific to each plot type).\n\n-----\n\n## 🙌 Contributing\n\nContributions are welcome. Please:\n\n1.  Check the **[Issues Tracker](https://github.com/earthai-tech/k-diagram/issues)** \n    for existing bugs or ideas.\n2.  Fork the repository.\n3.  Create a new branch for your feature or fix.\n4.  Make your changes and add tests.\n5.  Submit a Pull Request.\n\nPlease refer to the [CONTRIBUTING](https://k-diagram.readthedocs.io/en/latest/contributing.html) \npage or the contributing section in the documentation \nfor more detailed guidelines.\n\n-----\n\n## 📜 License\n\n`k-diagram` is distributed under the terms of the **Apache License 2.0**. \nSee the [LICENSE](https://github.com/earthai-tech/k-diagram/blob/main/LICENSE) \nfile for details.\n\n-----\n\n## 📞 Contact \u0026 Support\n\n* **Bug reports \u0026 feature requests:** Please use the project’s **GitHub Issues** \n  tracker to report bugs, ask usage questions, or suggest enhancements:\n  [GitHub Issues](https://github.com/earthai-tech/k-diagram/issues)\n\n* **Author contact:** For collaboration inquiries or questions about the \n  project’s background, you can contact the author:\n  \n  **Laurent Kouadio** — [https://lkouadio.com/](https://lkouadio.com/)\n  📧 **[etanoyau@gmail.com](mailto:etanoyau@gmail.com)**\n\n\n[badge-ci]: https://img.shields.io/github/actions/workflow/status/earthai-tech/k-diagram/python-package-conda.yml?branch=main\u0026style=flat-square\n[link-ci]: https://github.com/earthai-tech/k-diagram/actions/workflows/python-package-conda.yml\n[badge-docs]: https://readthedocs.org/projects/k-diagram/badge/?version=latest\u0026style=flat-square\n[link-docs]: https://k-diagram.readthedocs.io/en/latest/?badge=latest\n[badge-license]: https://img.shields.io/github/license/earthai-tech/k-diagram?style=flat-square\u0026logo=apache\u0026color=purple\n[badge-black]: https://img.shields.io/badge/code%20style-Black-000000.svg?style=flat-square\n[link-black]: https://github.com/psf/black\n[badge-contrib]: https://img.shields.io/badge/Contributions-Welcome-brightgreen?style=flat-square\n[link-contrib]: https://github.com/earthai-tech/k-diagram/blob/main/CONTRIBUTING.md\n[badge-codecov]: https://codecov.io/gh/earthai-tech/k-diagram/branch/main/graph/badge.svg\n[link-codecov]: https://codecov.io/gh/earthai-tech/k-diagram\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fearthai-tech%2Fk-diagram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fearthai-tech%2Fk-diagram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fearthai-tech%2Fk-diagram/lists"}