{"id":19548082,"url":"https://github.com/mauroluzzatto/algorithmic-explanations","last_synced_at":"2025-06-16T04:12:24.667Z","repository":{"id":112077663,"uuid":"379045496","full_name":"MauroLuzzatto/algorithmic-explanations","owner":"MauroLuzzatto","description":"This project uses algorithms from Machine Learning Explainability to generate automated text explanations – Work in Progress","archived":false,"fork":false,"pushed_at":"2021-09-09T20:39:20.000Z","size":403,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-08T19:50:16.034Z","etag":null,"topics":["explainy","machine-learning-explainability"],"latest_commit_sha":null,"homepage":"","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/MauroLuzzatto.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":"2021-06-21T19:46:32.000Z","updated_at":"2021-07-18T15:23:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"a155c9e8-53d4-4dcd-95e0-845b6513d5b2","html_url":"https://github.com/MauroLuzzatto/algorithmic-explanations","commit_stats":{"total_commits":24,"total_committers":1,"mean_commits":24.0,"dds":0.0,"last_synced_commit":"4a362ae9576cc68ecf4b61dd6bad2105ff62bf57"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroLuzzatto%2Falgorithmic-explanations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroLuzzatto%2Falgorithmic-explanations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroLuzzatto%2Falgorithmic-explanations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MauroLuzzatto%2Falgorithmic-explanations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MauroLuzzatto","download_url":"https://codeload.github.com/MauroLuzzatto/algorithmic-explanations/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240802632,"owners_count":19860022,"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":["explainy","machine-learning-explainability"],"created_at":"2024-11-11T03:54:39.216Z","updated_at":"2025-02-26T06:22:35.856Z","avatar_url":"https://github.com/MauroLuzzatto.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Algorithmic Explanations (WIP)\n\nThis project generates explanations of the trained machine learning model. The following steps are included:\n- cleaning of data and encoding of the features\n- training and tuning a machine learning model (XGBoost)\n- generating explanations from four machine learning explainability algorithms with a unified API\n- generating different textual and visual explanations for the trained model\n\n\n\n\n## Getting Started \n\nDownload the github repository:\n```bash\ngit clone https://github.com/MauroLuzzatto/algorithmic-explanations\n```\n\ncreate a local environement and install the python requirements:\n```bash\npip install -r requirements.txt\n```\n\n\n## Machine Learning explanability methods\n\nMethod\t\t\t\t| Implemenation \t\t\t\t|Type | Scope | Option|\n--- \t\t\t\t|\t--- \t\t\t\t\t\t| --- | --- | --- | \nPermutation Feature Importance\t|`PermutationExplanation.py`\t| Non-contrastive | global |   sparse and dense |\nShapley Values\t\t|\t`ShapleyExplanation.py`\t\t| Non-contrastive | local |   sparse and dense |\nGlobal Surrogate Model|\t`SurrogateModelExplanation.py`| Contrastive | global |  sparse and dense |\nCounterfactual Example|\t`CounterfactualExplanation.py`| Contrastive | local |  sparse and dense |\n\n\n\n\n\n## Explanations\n\n### Permutation Feature Importance\n\n\nMethod:\n\u003e To help you understand this decision, here are the six features which were most important for how the mechanism made its decision in your specific case:\n\n\nFeatures:\n\u003e In your case, the six features which contributed most to the mechanism’s decision were the features 'Number of extracurricular activities' with an average contribution of 0.41, \n\u003e 'Essay score' with an average contribution of 0.17, 'GPA' with an average contribution of 0.08, 'SAT' with an average contribution of 0.05, 'State of residence' with an average \n\u003e contribution of 0.04 and 'Number of activities with leadership experience' with an average contribution of 0.03.\n\n\n![Permutation Feature Importance](resources/permutation.png)\n\n### Shapley Values\n\nMethod:\n\n\u003e To help you understand this decision, here are the six features which were most important for how the mechanism made its decision in your specific case:\n\nFeatures:\n\n\u003e In your case, the six features which contributed most to the mechanism’s decision were the features 'Number of extracurricular activities' with an average contribution of 0.53, \n\u003e 'Essay score' with an average contribution of -0.09, 'GPA' with an average contribution of 0.07, 'State of residence' with an average contribution of 0.06, 'SAT' with an average \n\u003e contribution of -0.05 and 'College rank - unknown' with an average contribution of -0.04.\n\n![Shapley Values](resources/shapley.png)\n\n### Counterfactual Example\n\nMethod:\n\n\u003e To help you understand this decision, here is an example of another, similar applicant where the mechanism would have decided differently:\n\nFeatures:\n\n\u003e In your case, the mechanism would have awarded you the scholarship, if your 'Grade' was High School Senior (12), if your 'Favorite subjects' was not 'Physical Education (P.E.)', \n\u003e if your 'College rank' was not 'unknown', if your 'Favorite subjects' was Chemistry, if your 'Favorite subjects' was Literature and if your 'Favorite subjects' was History.\n\n![Counterfactual Example](resources/counterfactual.png)\n\n\n### Global Surrogate Model (Decision Tree)\n\n\nMethod:\n\n\u003e To help you understand this decision, here is a decision tree showing you how the mechanism made its decision:\n\nFeatures:\n\n\u003e Applicants received an average score of 2.36 if the value of 'Number of extracurricular activities' is smaller or equal to 3.50 and \u003e 'Number of extracurricular activities' is smaller or equal to 1.50.\n\u003e Applicants received an average score of 2.92 if the value of 'Number of extracurricular activities' is smaller or equal to 3.50 and \u003e 'Number of extracurricular activities' is larger than 1.50.\n\u003e Applicants received an average score of 3.56 if the value of 'Number of extracurricular activities' is larger than 3.50 and 'SAT' is \u003e smaller or equal to 1210.00.\n\u003e Applicants received an average score of 4.29 if the value of 'Number of extracurricular activities' is larger than 3.50 and 'SAT' is \u003e larger than 1210.00.\n\n![alt text](resources/surrogate.png)\n\n## Authors\n* **Mauro Luzzatto** - [Maurol](https://github.com/MauroLuzzatto)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmauroluzzatto%2Falgorithmic-explanations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmauroluzzatto%2Falgorithmic-explanations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmauroluzzatto%2Falgorithmic-explanations/lists"}