{"id":29932842,"url":"https://github.com/karyframling/py-ciu","last_synced_at":"2025-08-02T18:10:48.186Z","repository":{"id":57467341,"uuid":"234038671","full_name":"KaryFramling/py-ciu","owner":"KaryFramling","description":"Explainable Artificial Intelligence through Contextual Importance and Utility","archived":false,"fork":false,"pushed_at":"2024-08-19T16:18:16.000Z","size":28692,"stargazers_count":28,"open_issues_count":4,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-17T09:43:38.691Z","etag":null,"topics":["explainable-ai","explainable-artificial-intelligence","explainable-ml","python"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KaryFramling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-01-15T08:52:28.000Z","updated_at":"2025-04-06T07:10:07.000Z","dependencies_parsed_at":"2023-12-04T13:36:46.163Z","dependency_job_id":"9ee72933-ec92-4968-b261-0b7bce6cc483","html_url":"https://github.com/KaryFramling/py-ciu","commit_stats":{"total_commits":63,"total_committers":4,"mean_commits":15.75,"dds":"0.25396825396825395","last_synced_commit":"07ece43335a9d23c9bc91f913a7bdcbac20b0234"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/KaryFramling/py-ciu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaryFramling%2Fpy-ciu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaryFramling%2Fpy-ciu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaryFramling%2Fpy-ciu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaryFramling%2Fpy-ciu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KaryFramling","download_url":"https://codeload.github.com/KaryFramling/py-ciu/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KaryFramling%2Fpy-ciu/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268431644,"owners_count":24249413,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["explainable-ai","explainable-artificial-intelligence","explainable-ml","python"],"created_at":"2025-08-02T18:10:46.138Z","updated_at":"2025-08-02T18:10:48.178Z","avatar_url":"https://github.com/KaryFramling.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# py-ciu\n\n*Explainable Machine Learning through Contextual Importance and Utility*\n\nThe *py-ciu* library provides methods to generate post-hoc explanations for\nmachine learning-based classifiers.\n\n**NOTE: This implementation is the result of a major rewrite made in November/December 2023. This was made in order to make the use of this py-ciu package similar to the [R CIU](https://github.com/KaryFramling/ciu) and [py.ciu.image](https://github.com/KaryFramling/py.ciu.image) (re-written in Nov 2023) packages. Also, the core CIU development is still done in \"R\" and some of the functionality present in the R version may not be available in this python version.**\n\nThe version of py-ciu that has been replaced on 12 January 2024 is available in the branch `VersionUntilNov2023`.\n\n## Usage\n\nFirst install the `py-ciu` package. The recommended approach is to clone this repository and use it from there. The current version has been tested with Python versions 3.11.5 and 3.12.1. More extensive testing against different versions will be performed in the future. \n\nThe other approach is to install it using `pip install py-ciu` but since the development of CIU is sometimes quite rapid, you should not except that all functionality is available in that version.\n\nA quick overview of the use of py-ciu with different datasets amd ML models is available as a Jupyter notebook [README_notebook.ipynb](README_notebook.ipynb). All the notebooks have been ran in Visual Studio Code, presumably with the latest versions of all packages. There will be errors or strange results in case of library version mismatches and that seems to happen quite frequently for Python libraries. So if your results are not identical to the ones that you see in these notebooks, then you probably have to update some/many libraries in your installation. \n\nOther notebooks available in the repository are:\n\n- [BostonTests.ipynb](BostonTests.ipynb): Examples of py-ciu use for Boston data set. This notebook provides a good overview of CIU capabilities for a regression task. \n- [TitanicTests.ipynb](TitanicTests.ipynb): Examples of py-ciu use for Titanic data set. This notebook provides a good overview of CIU capabilities for a classification task. It also gives a small example of the use of CIU's \"intermediate concepts\". \n- [AmesHousingTests.ipynb](AmesHousingTests.ipynb): Examples of py-ciu use for Ames housing data set. This data set has 80 input features and provides a good example of the use of CIU's \"intermediate concepts\", as well as why they are necessary in order to give \"correct\" explanations even in the presence of dependencies between features (which is also the case for Titanic). \n- [IrisTests.ipynb](IrisTests.ipynb): Examples of py-ciu use for Iris data set. This notebook includes some \"low-level\" use of the package that may not be found in the other notebooks. \n- [Beeswarms.ipynb](Beeswarms.ipynb): Examples of beeswarm plots as a means of \"global explanation\" by visualising importance/influence/utility/whatever for a set of instances.\n- [ContrastiveTests.ipynb](ContrastiveTests.ipynb): Examples of contrastive \"Why A and not B?\" and \"\"Why not B but rather A?\" explanations. \n- [RunTests.ipynb](RunTests.ipynb): Notebook for running various tests that are found in the `ciu_tests` directory. \n\n## Documentation\n\nThe package has been documented using Sphinx and is available at [https://py-ciu.readthedocs.io/](https://py-ciu.readthedocs.io/). Sphinx HTML documentation can also be generated by doing `cd docs` and then `make html`. Other formats such as PDF can also be produced, as for the PDF version at: [docs/py-ciu.pdf](docs/py-ciu.pdf). \n\n# What is CIU?\n\n**Remark**: It seems like Github Markdown doesn’t show correctly the “{”\nand “}” characters in Latex equations, whereas they are shown correctly\nin Rstudio. Therefore, in most cases where there is an $i$ shown in\nGithub, it actually signifies `{i}` and where there is an $I$ it\nsignifies `{I}`.\n\nCIU is a model-agnostic method for producing outcome explanations of\nresults of any “black-box” model `y=f(x)`. CIU directly estimates two\nelements of explanation by observing the behaviour of the black-box\nmodel (without creating any “surrogate” model `g` of `f(x)`).\n\n**Contextual Importance (CI)** answers the question: ***how much can the\nresult (or the utility of it) change as a function of feature*** $i$ or a\nset of features $\\{i\\}$ jointly, in the context $x$?\n\n**Contextual Utility (CU)** answers the question: ***how favorable is the\ncurrent value*** of feature $i$ (or a set of features $\\{i\\}$ jointly) for a good\n(high-utility) result, in the context $x$?\n\nCI of one feature or a set of features (jointly) $\\{i\\}$ compared to a\nsuperset of features $\\{I\\}$ is defined as\n\n$$\n\\omega_{j,\\{i\\},\\{I\\}}(x)=\\frac{umax_{j}(x,\\{i\\})-umin_{j}(x,\\{i\\})}{umax_{j}(x,\\{I\\})-umin_{j}(x,\\{I\\})},  \n$$\n\nwhere $\\{i\\} \\subseteq \\{I\\}$ and $\\{I\\} \\subseteq \\{1,\\dots,n\\}$. $x$\nis the instance/context to be explained and defines the values of input\nfeatures that do not belong to $\\{i\\}$ or $\\{I\\}$. In practice, CI is\ncalculated as:\n\n$$\n\\omega_{j,\\{i\\},\\{I\\}}(x)= \\frac{ymax_{j,\\{i\\}}(x)-ymin_{j,\\{i\\}}(x)}{ ymax_{j,\\{I\\}}(x)-ymin_{j,\\{I\\}}(x)}, \n$$\n\nwhere $ymin_{j}()$ and $ymax_{j}()$ are the minimal and maximal $y_{j}$\nvalues observed for output $j$.\n\nCU is defined as\n\n$$\nCU_{j,\\{i\\}}(x)=\\frac{u_{j}(x)-umin_{j,\\{i\\}}(x)}{umax_{j,\\{i\\}}(x)-umin_{j,\\{i\\}}(x)}. \n$$\n\nWhen $u_{j}(y_{j})=Ay_{j}+b$, this can be written as:\n\n$$\nCU_{j,\\{i\\}}(x)=\\left|\\frac{ y_{j}(x)-yumin_{j,\\{i\\}}(x)}{ymax_{j,\\{i\\}}(x)-ymin_{j,\\{i\\}}(x)}\\right|, \n$$\n\nwhere $yumin=ymin$ if $A$ is positive and $yumin=ymax$ if $A$ is\nnegative.\n\n# Related resources\n\nThe original R implementation can be found at: \u003chttps://github.com/KaryFramling/ciu\u003e\n\nThere are also two implementations of CIU for explaining images:\n\n- Python: \u003chttps://github.com/KaryFramling/py.ciu.image\u003e\n- R: \u003chttps://github.com/KaryFramling/ciu.image\u003e\n\nFuture work on image explanation will presumably focus on the Python version, due to the extensive use of deep neural networks that tend to be implemented mainly for Python.\n\n## Authors\n* [Kary Främling](https://github.com/KaryFramling)\n* [Vlad Apopei](https://github.com/vladapopei/)\n* [Timotheus Kampik](https://github.com/TimKam/)\n\nThe first version of py-ciu was mainly implemented by [Timotheus Kampik](https://github.com/TimKam/). The old code is available in the branch \"Historical\".\n\nThe re-write in 2022 was mainly made by [Vlad Apopei](https://github.com/vladapopei/) and is available in the branch \"VersionUntilNov2023\".\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaryframling%2Fpy-ciu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkaryframling%2Fpy-ciu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkaryframling%2Fpy-ciu/lists"}