{"id":15032611,"url":"https://github.com/ethicalml/xai","last_synced_at":"2025-05-15T16:06:24.511Z","repository":{"id":46339297,"uuid":"165302201","full_name":"EthicalML/xai","owner":"EthicalML","description":"XAI - An eXplainability toolbox for machine learning","archived":false,"fork":false,"pushed_at":"2021-10-30T06:35:19.000Z","size":18684,"stargazers_count":1168,"open_issues_count":4,"forks_count":179,"subscribers_count":43,"default_branch":"master","last_synced_at":"2025-05-09T14:07:11.824Z","etag":null,"topics":["ai","artificial-intelligence","bias","bias-evaluation","downsampling","evaluation","explainability","explainable-ai","explainable-ml","feature-importance","imbalance","interpretability","machine-learning","machine-learning-explainability","ml","upsampling","xai","xai-library"],"latest_commit_sha":null,"homepage":"https://ethical.institute/principles.html#commitment-3","language":"Python","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/EthicalML.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}},"created_at":"2019-01-11T20:00:09.000Z","updated_at":"2025-05-07T17:09:10.000Z","dependencies_parsed_at":"2022-07-19T22:08:18.653Z","dependency_job_id":null,"html_url":"https://github.com/EthicalML/xai","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EthicalML%2Fxai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EthicalML%2Fxai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EthicalML%2Fxai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EthicalML%2Fxai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EthicalML","download_url":"https://codeload.github.com/EthicalML/xai/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254374470,"owners_count":22060611,"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","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":["ai","artificial-intelligence","bias","bias-evaluation","downsampling","evaluation","explainability","explainable-ai","explainable-ml","feature-importance","imbalance","interpretability","machine-learning","machine-learning-explainability","ml","upsampling","xai","xai-library"],"created_at":"2024-09-24T20:18:52.934Z","updated_at":"2025-05-15T16:06:22.186Z","avatar_url":"https://github.com/EthicalML.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![GitHub](https://img.shields.io/badge/Release-ALPHA-yellow.svg)\n![GitHub](https://img.shields.io/badge/Version-0.0.5_ALPHA-lightgrey.svg)\n![GitHub](https://img.shields.io/badge/Python-3.5_|_3.6_|_3.7-blue.svg)\n![GitHub](https://img.shields.io/badge/License-MIT-lightgrey.svg)\n\n# XAI - An eXplainability toolbox for machine learning \n\nXAI is a Machine Learning library that is designed with AI explainability in its core. XAI contains various tools that enable for analysis and evaluation of data and models. The XAI library is maintained by [The Institute for Ethical AI \u0026 ML](http://ethical.institute/), and it was developed based on the [8 principles for Responsible Machine Learning](http://ethical.institute/principles.html).\n\nYou can find the documentation at [https://ethicalml.github.io/xai/index.html](https://ethicalml.github.io/xai/index.html). You can also check out our [talk at Tensorflow London](https://www.youtube.com/watch?v=GZpfBhQJ0H4) where the idea was first conceived - the talk also contains an insight on the definitions and principles in this library.\n\n## YouTube video showing how to use XAI to mitigate undesired biases\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"30%\"\u003e\n        This \u003ca href=\"https://www.youtube.com/watch?v=vq8mDiDODhc\"\u003evideo of the talk presented at the PyData London 2019 Conference \u003c/a\u003e which provides an overview on the motivations for machine learning explainability as well as techniques to introduce explainability and mitigate undesired biases using the XAI Library.\n    \u003c/td\u003e\n    \u003ctd width=\"70%\"\u003e\n        \u003ca href=\"https://www.youtube.com/watch?v=vq8mDiDODhc\"\u003e\u003cimg src=\"images/video.jpg\"\u003e\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"30%\"\u003e\n        Do you want to learn about more awesome machine learning explainability tools? Check out our community-built \u003ca href=\"https://github.com/EthicalML/awesome-machine-learning-operations\"\u003e\"Awesome Machine Learning Production \u0026 Operations\"\u003c/a\u003e list which contains an extensive list of tools for explainability, privacy, orchestration and beyond.\n    \u003c/td\u003e\n    \u003ctd width=\"70%\"\u003e\n        \u003ca href=\"https://github.com/EthicalML/awesome-machine-learning-operations\"\u003e\u003cimg src=\"images/mlops-link.png\"\u003e\u003c/a\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\n\u003c/table\u003e\n\n# 0.1.0\n\nIf you want to see a fully functional demo in action clone this repo and run the \u003ca href=\"https://github.com/EthicalML/xai/blob/master/examples/XAI%20Example%20Usage.ipynb\"\u003eExample Jupyter Notebook in the Examples folder\u003c/a\u003e.\n\n## What do we mean by eXplainable AI?\n\nWe see the challenge of explainability as more than just an algorithmic challenge, which requires a combination of data science best practices with domain-specific knowledge. The XAI library is designed to empower machine learning engineers and relevant domain experts to analyse the end-to-end solution and identify discrepancies that may result in sub-optimal performance relative to the objectives required. More broadly, the XAI library is designed using the 3-steps of explainable machine learning, which involve 1) data analysis, 2) model evaluation, and 3) production monitoring. \n\nWe provide a visual overview of these three steps mentioned above in this diagram:\n\n\u003cimg width=\"100%\" src=\"images/bias.png\"\u003e\n\n# XAI Quickstart\n\n## Installation\n\nThe XAI package is on PyPI. To install you can run:\n\n```\npip install xai\n```\n\nAlternatively you can install from source by cloning the repo and running:\n\n```\npython setup.py install \n```\n\n## Usage\n\nYou can find example usage in the examples folder.\n\n### 1) Data Analysis\n\nWith XAI you can identify imbalances in the data. For this, we will load the census dataset from the XAI library.\n\n``` python\nimport xai.data\ndf = xai.data.load_census()\ndf.head()\n```\n\u003cimg width=\"100%\" src=\"images/readme-csv-head.jpg\"\u003e\n\n#### View class imbalances for all categories of one column\n``` python\nims = xai.imbalance_plot(df, \"gender\")\n```\n\u003cimg width=\"100%\" src=\"images/readme-imbalance-gender.jpg\"\u003e\n\n#### View imbalances for all categories across multiple columns\n``` python\nim = xai.imbalance_plot(df, \"gender\", \"loan\")\n```\n\u003cimg width=\"100%\" src=\"images/readme-imbalance-multiple.jpg\"\u003e\n\n#### Balance classes using upsampling and/or downsampling\n``` python\nbal_df = xai.balance(df, \"gender\", \"loan\", upsample=0.8)\n```\n\u003cimg width=\"100%\" src=\"images/readme-balance-upsample.jpg\"\u003e\n\n#### Perform custom operations on groups\n``` python\ngroups = xai.group_by_columns(df, [\"gender\", \"loan\"])\nfor group, group_df in groups:    \n    print(group) \n    print(group_df[\"loan\"].head(), \"\\n\")\n```\n\u003cimg width=\"100%\" src=\"images/readme-groups.jpg\"\u003e\n\n#### Visualise correlations as a matrix\n``` python\n_ = xai.correlations(df, include_categorical=True, plot_type=\"matrix\")\n```\n\u003cimg width=\"100%\" src=\"images/readme-correlation-matrix.jpg\"\u003e\n\n#### Visualise correlations as a hierarchical dendogram\n``` python\n_ = xai.correlations(df, include_categorical=True)\n```\n\u003cimg width=\"100%\" src=\"images/readme-correlation-dendogram.jpg\"\u003e\n\n#### Create a balanced validation and training split dataset\n``` python\n# Balanced train-test split with minimum 300 examples of \n#     the cross of the target y and the column gender\nx_train, y_train, x_test, y_test, train_idx, test_idx = \\\n    xai.balanced_train_test_split(\n            x, y, \"gender\", \n            min_per_group=300,\n            max_per_group=300,\n            categorical_cols=categorical_cols)\n\nx_train_display = bal_df[train_idx]\nx_test_display = bal_df[test_idx]\n\nprint(\"Total number of examples: \", x_test.shape[0])\n\ndf_test = x_test_display.copy()\ndf_test[\"loan\"] = y_test\n\n_= xai.imbalance_plot(df_test, \"gender\", \"loan\", categorical_cols=categorical_cols)\n```\n\u003cimg width=\"100%\" src=\"images/readme-balance-split.jpg\"\u003e\n\n### 2) Model Evaluation\n\nWe are able to also analyse the interaction between inference results and input features. For this, we will train a single layer deep learning model.\n\n```\nmodel = build_model(proc_df.drop(\"loan\", axis=1))\n\nmodel.fit(f_in(x_train), y_train, epochs=50, batch_size=512)\n\nprobabilities = model.predict(f_in(x_test))\npredictions = list((probabilities \u003e= 0.5).astype(int).T[0])\n```\n\u003cimg width=\"100%\" src=\"images/readme-15.png\"\u003e\n\n#### Visualise permutation feature importance\n``` python\ndef get_avg(x, y):\n    return model.evaluate(f_in(x), y, verbose=0)[1]\n\nimp = xai.feature_importance(x_test, y_test, get_avg)\n\nimp.head()\n```\n\u003cimg width=\"100%\" src=\"images/readme-6.png\"\u003e\n\n#### Identify metric imbalances against all test data\n``` python\n_= xai.metrics_plot(\n        y_test, \n        probabilities)\n```\n\u003cimg width=\"100%\" src=\"images/readme-metrics-plot.jpg\"\u003e\n\n#### Identify metric imbalances across a specific column\n``` python\n_ = xai.metrics_plot(\n    y_test, \n    probabilities, \n    df=x_test_display, \n    cross_cols=[\"gender\"],\n    categorical_cols=categorical_cols)\n```\n\u003cimg width=\"100%\" src=\"images/readme-metrics-column.jpg\"\u003e\n\n#### Identify metric imbalances across multiple columns\n``` python\n_ = xai.metrics_plot(\n    y_test, \n    probabilities, \n    df=x_test_display, \n    cross_cols=[\"gender\", \"ethnicity\"],\n    categorical_cols=categorical_cols)\n```\n\u003cimg width=\"100%\" src=\"images/readme-metrics-multiple.jpg\"\u003e\n\n#### Draw confusion matrix\n``` python\nxai.confusion_matrix_plot(y_test, pred)\n```\n\u003cimg width=\"100%\" src=\"images/readme-confusion-matrix.jpg\"\u003e\n\n#### Visualise the ROC curve against all test data\n``` python\n_ = xai.roc_plot(y_test, probabilities)\n```\n\u003cimg width=\"100%\" src=\"images/readme-9.png\"\u003e\n\n#### Visualise the ROC curves grouped by a protected column\n``` python\nprotected = [\"gender\", \"ethnicity\", \"age\"]\n_ = [xai.roc_plot(\n    y_test, \n    probabilities, \n    df=x_test_display, \n    cross_cols=[p],\n    categorical_cols=categorical_cols) for p in protected]\n```\n\u003cimg width=\"100%\" src=\"images/readme-10.png\"\u003e\n\n#### Visualise accuracy grouped by probability buckets\n``` python\nd = xai.smile_imbalance(\n    y_test, \n    probabilities)\n```\n\u003cimg width=\"100%\" src=\"images/readme-12.png\"\u003e\n\n#### Visualise statistical metrics grouped by probability buckets\n``` python\nd = xai.smile_imbalance(\n    y_test, \n    probabilities,\n    display_breakdown=True)\n```\n\u003cimg width=\"100%\" src=\"images/readme-13.png\"\u003e\n\n#### Visualise benefits of adding manual review on probability thresholds\n``` python\nd = xai.smile_imbalance(\n    y_test, \n    probabilities,\n    bins=9,\n    threshold=0.75,\n    manual_review=0.375,\n    display_breakdown=False)\n```\n\u003cimg width=\"100%\" src=\"images/readme-14.png\"\u003e\n\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethicalml%2Fxai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fethicalml%2Fxai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fethicalml%2Fxai/lists"}